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 checked out 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 &ltAuthnRequest&gt 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 = "https://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 &ltAutnRequest&gt

             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();

Likewise the message from the WSO2 Identity Server can be read easily.

Configuring the SAML 2.0 SSO Demonstration

• Download the SAML2 SSO sample service provider .war file from here.
• Extract the saml2-demo.war file to your Apache-Tomcat server's webapps folder.
• Open the web.xml file which can be found in the path [tomcat-home]/webapps/saml2.demo/WEB-INF/web.xml

• Given configurations are valid for default configurations of the WSO2 Identity Server and Apache Tomcat Server
• (1) Issuer : This is a unique name given for this Service Provider
• (2) IdpUrl : The URL of the WSO2 Identity Server SAML SSO Provider. This has the pattern https://{is-host-name}:{is-https-port}/samlsso
• (3) ConsumerUrl : The URL of the SAML2ConsumerServlet of this webapp. This has the pattern https://{tomcat-host-name}:{tomcat-http-port}/saml2.demo/consumer

Configuring the WSO2 Identity Server as a SAML 2.0 SSO Identity Provider

• Start the WSO2 Identity Server and sign in as the admin. Go to the “SAML SSO” page which is under the “Manage” menu in the left pane.

• Do the following configurations. Use exactly the same values we used to configure the webapp
• Issuer : saml2.demo
• Assertion Consumer URL : https://localhost:8080/saml2.demo/consumer

• Thats all about the configuring the WSO2 Identity Server.

WSO2 Identity Server SSO feature Demonstration

• Now, start Apache-tomcat and visit https://localhost:8080/saml2.demo/.
  
• Click on SingIn. Now you will be redirected to the WSO2 Identity Server. Enter the User name/Password.

• After successful authentication you will be logged into the service provider.

• When you try to access the above resource you will be always redirected to the WSO2 Identity Server. If you are already authenticated then the Identity Server will immediately direct you back to the resource. If you are not authenticated, after the successful authentication you will be returned back to the resource

Conclusion

SSO systems are more secure and more convenient for users. A SAML 2.0 web browser based SSO system can be easily implimented with the WSO2 Identity Server with only few confgurations. OpenSAML Java library can be used to create Consumer Modules to interat with the WSO2 Identity Server in implimenting SSO systems.

Author

Suresh Attanayake, Software Engineer at WSO2 , [email protected]