SAML2 Web Browser based SSO with WSO2 Identity Server

Date: Tue, 13th Jul, 2010 Level: Introductory Reads: 9745 Comments: 10 | Login or register to post comments

Suresh Attanayake Software Engineer WSO2

Single Sign On (SSO) systems have become very popular since it is a very secure and convenient authentication mechanism. WSO2 Stratos and Google Apps can be taken as best examples for Single Sign On systems where users can automatically login to multiple web applications once they are authenticated at a one place using a single credential.

Security Assertian Markup Language (SAML) version 2.0 Profiles Specification defines a web browser based single sign on system. This article briefly explains the SAML 2.0 web browser based SSO profile and guids to build your own SAML 2.0 Assertions Consumer using the OpenSAML 2.2.3 Java library. The demo application provided with this article would help to understand how SAML 2.0 based SSO systems work and how to use WSO2 Identity Server as the Identity Provider in a SSO system.

[Curated on 26th March 2012]

Introduction

In a single sign on system there are basically two roles, Service Providers and Identity Providers (IP). The important characteristic of a single sign on syste is the pre-defined trust relation between the service providers and the identity providesr. Service providers trust the assertions issued by the identity providers and the identity providers issues assertions on the results of authentication and authorization of principles who are willing to access services at service providers.

Following are some of the advantages you can have with SSO:

• Users need only a single username/password pair to access multiple services. So they're off the issue of remembering multiple username/password pairs.
• Users are authenticated only once at the identity provider and then they're automatically logged into all services withing that "trust-domain". That is more convenient to users since they dont have to provide username/password at every service provider.
• Service Providers are off the overhead of managing user identities which is more convenient to them.
• User identities are managed at a central point. This is more secure, less complex and easily manageable.

With the release of WSO2 Identity Server 3.0, it supports the SAML 2.0 web browser based SSO profile. WSO2 Identity Server can act as the identity provider of a single sign on system with minimal configurations. This article guides on how to configure the identity server and how your applications can be deployed in a SAML 2.0 web browser based SSO system.

Applies To

WSO2 Identity Server 3.0.0 or higher.

Table of Contents

• Single Sign On in reality
• SAML 2.0 Web Browser based SSO profile
• A SAML 2.0 SSO Assertion Consumer
• How to create an <AuthnRequest> message using the OpenSAML library
• How to read the <Response> message issued by the WSO2 Identity Server
• Configuring the SAML 2.0 SSO Demo Service Provider
• Configuring the WSO2 Identity Server as a SAML 2.0 SSO Identity Provider
• WSO2 Identity Server SSO feature Demonstration
• Conclusion

Single Sign On in reality

Single Sign On is widely used in web technologies. Google is one of the best examples.

Try this simple exercise,

• Visit www.google.com from your favorite web browser
• Click on the sign in button on the right top of the page
• Once you click on sign in, you will be redirect to www.google.com/accounts/ServiceLogin. There you will be asked to enter your user-name and password. Enter your Google credentials there
• Once you enter your user-name and password, you will be directed back to www.google.com where you started
• Now visit www.igoogle.com , the Google web portal
• See, you are automatically signed in to the portal. You did not entered your user-name password there
• And now visit www.gmail.com , the Google mail server
• Again, you are automatically signed in. you are directly forwarded to your mail In-Box. You did not entered your use-name / password at Gmail.
• Thats not all, now try www.youtube.com
• Click on the “Sign In” button on the top right of the You-Tube home page.
• You will be automatically signed in. You did not entered your user name / password at You Tube.

Tip: did you notice the URL of the web browser? Each time when you are trying to access an application, you will see that you are being redirected to www.google.com/accounts/ServiceLogin and returns immediately to the resource so that you can't even notice it.

That is the beauty of Single Sign On, more secure and more user friendly. You signed in only once but you hvae access to multiple resources without re-entering your username/password.

SAML 2.0 Web Browser based SSO profile

SAML 2.0 Web Browser based SSO profile is defined under the SAML 2.0 Profiles specification. SAML 2.0 provides five main specifications:

• Core
• Binding
• Profile
• Metadata
• Conformance

In a web browser based SSO system, the flow can be started by user either by trying to accessing a service at the service providers or by directly accessing the identity provider itself.

If the user access a service at a service provider :

1. Service provider determines the identity provider (if there are multiple identity providers. SAML identity provider discovery profile may be used)
2. Service provider generates a SAML message and then redirects the web browser to the identity provider along with the message.
3. Identity provider authenticates the user.
4. Identity provider generates a SAML message and then redirects the web browser back to the service provider.
5. . Service provider processes the SAML message and decides to grant or deny access to user.

If the user access the identity provider directly, then only the steps 3,4,5 will be in the flow.

The message MUST contain an element which uniquely identifies the service provider who created the message. Optionally the message may contain elements such as , etc. More informations regarding the message can be found in SAML Core Specification.

The message MUST contain , , , , elements. The message MUST be integrity protecte. More information regarding the message can be found in SAML Core Specification.

Following diagram illustrates the scenario.

SAML 2.0 SSO Assertion Consumers:

Service providers are acting as SAML assertion consumers. They basically do two things :

1. Create messages and redirect users to the identity provider with the created message.
2. Process messages from the identity provider and take decisions upon it.

Following code is a sketch of a sample service provider servlet in a SAML 2.0 Web-Browser based SSO system.

     public class Resource extends HttpServlet {             

             private static SamlConsumer consumer = new SamlConsumer();           

             public void doGet(HttpServletRequest request, HttpServletResponse response) { 
                   requestMessage = consumer.buildRequestMessage();
                   response.sendRedirect(requestMessage);
             }            

             public void doPost(HttpServletRequest request, HttpServletResponse response) { 
                   responseMessage = request.getParameter("SAMLResponse").toString();  
                   result = consumer.processResponseMessage(responseMessage);
             }
     }
 

When a web user try to access the above servlet, it's doGet() method gets called. Inside the doGet() method, it will generates an message and then redirect the user to the Identity Provider.

After authentication is completed by the Identity Provider, it will do a POST call back to the above servlet with a message. Then the doPost() method of the servlet gets called and inside the doPost() method, it will retrieve the message from the request and then the message will be passed to the SamlConsumer instance for processing.

The complete source code can be downloaded from here

How to create an <AuthnRequest> message using the OpenSAML library

It is easy to create and precess SAML messages using the OpenSAML Java library. Add the OpenSAML library to the build path of the project.You can download the open saml jar from here

A sample <AuthnRequest> message can be found here

According to SAML 2.0 specifications, the message must contain an element. Lets create the Issuer element first.

      	     // the issuerUrl is the url of the service provider who generates the  message
             String issuerUrl = "http://localhost:8080/saml2.demo/consumer";
             IssuerBuilder issuerBuilder = new IssuerBuilder();
             Issuer issuer = issuerBuilder.buildObject("urn:oasis:names:tc:SAML:2.0:assertion", "Issuer", "samlp");
             issuer.setValue(issuerUrl);

Lets create the <AutnRequest>

             DateTime issueInstant = new DateTime();
             AuthnRequestBuilder authnRequestBuilder = new AuthnRequestBuilder();
             AuthnRequest authnRequest = authnRequestBuilder.buildObject("urn:oasis:names:tc:SAML:2.0:protocol", "AuthnRequest", "samlp");

             authnRequest.setForceAuthn(new Boolean(false));
             authnRequest.setIsPassive(new Boolean(false));
             authnRequest.setIssueInstant(issueInstant);
             authnRequest.setProtocolBinding("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST");
             authnRequest.setAssertionConsumerServiceURL(issuerUrl);
             authnRequest.setIssuer(issuer);
             authnRequest.setID(aRandomId);
             authnRequest.setVersion(SAMLVersion.VERSION_20); 
 

The message may contain many other elements like , etc. those elements can be created and added to the message in the same way.

Now lets encode the message,

	     Marshaller marshaller = Configuration.getMarshallerFactory().getMarshaller(authnRequest);
	     Element authDOM = marshaller.marshall(authnRequest);

	     StringWriter rspWrt = new StringWriter();
	     XMLHelper.writeNode(authDOM, rspWrt);
             String requestMessage = rspWrt.toString();

	     Deflater deflater = new Deflater(Deflater.DEFLATED, true);
	     ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
	     DeflaterOutputStream deflaterOutputStream = new DeflaterOutputStream(byteArrayOutputStream, deflater);
	     deflaterOutputStream.write(requestMessage.getBytes());
	     deflaterOutputStream.close();

	     /* Encoding the compressed message */
	     String encodedRequestMessage = Base64.encodeBytes(byteArrayOutputStream.toByteArray(), Base64.DONT_BREAK_LINES);
	     String encodedAuthnRequest = URLEncoder.encode(encodedRequestMessage,"UTF-8").trim();

Now we can construct the redirection URL,

	     redirectionUrl = identitypProviderUrl+ "?SAMLRequest=" + encodedRequestMessage;

Now we can redirect the user to the identity provider,

	     response.sendRedirect(redirectionUrl);

How to read the <Response> message issued by the WSO2 Identity Server

A sample <Response> message can be found here

The response message must be fetched from the request,

	     responseMessage = request.getParameter("SAMLResponse").toString(); 

The fetched “responseMessage” has to be unmarshaled and the SAML message must be retrieved,

	     DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance();
             documentBuilderFactory.setNamespaceAware(true);
             DocumentBuilder docBuilder = documentBuilderFactory.newDocumentBuilder();
             Document document = docBuilder.parse(new ByteArrayInputStream(authnReqStr.trim().getBytes()));
       	     Element element = document.getDocumentElement();
             UnmarshallerFactory unmarshallerFactory = Configuration.getUnmarshallerFactory();
       	     Unmarshaller unmarshaller = unmarshallerFactory.getUnmarshaller(element);
       	     Response response = (Response) unmarshaller.unmarshall(element);

The retrieved SAML 2.0 Response message can be easily processed. For example, lets takes the User Name or the Subject's Name Id,

	     String subject = response.getAssertions().get(0).getSubject() .getNameID().getValue();

Or you can retrieve the certificate,

	     String certificate = response.getSignature().getKeyInfo().getX509Datas().get(0).getX509Certificates().get(0).getValue();