SAML2 Web Browser based SSO with WSO2 Identity Server

If you are willing to implement a SAML 2.0 assertion consumer module for a web browser based Single Sign On system with the WSO2 Identity Server, then this article is for you. This article will be guiding you to implement a SAML 2.0 consumer module using the OpenSAML library which is Java based. Date: Tue, 13th Jul, 2010 Level: Introductory Reads: 7942 Comments: 7 | Login or register to post comments Printer-friendly version Send to friend PDF version Post to twitter

Suresh Attanayake Intern WSO2

Introduction

The WSO2 Identity Server can act as an Identity provider for SAML 2.0 Web Browser based Single Sign On systems. This article will be guiding to implement a Java based SAML 2.0 consumer module and to configure the WSO2 Identity Server as the Identity Provider for a Single Sign On system. You can experience the SAML 2.0 Web-Browser based Single Sing On feature of the WSO2 Identity Server with a sample SAML 2.0 consumer module which is a simple .war file that can be run on your Apache Tomcat Server.

With the release of the WSO2 Identity Server 3.0, it provides SAML 2.0 Web-Browser based Single Sign On service. It can act as an Identity Provider for SAML 2.0 Web Browser based Single Sign On systems.

In a Single Sign On system, service providers trust the identity provider or in other words, service providers acts as assertion consumers. Web users who are trying to access those service providers will be redirected to the Identity Provider. Once a user is authenticated by the Identity Provider, the user can access any of those service providers without providing the user-name / password pair again. following are some of the advantages you can have with SSO:

• Users do not have to remember several user-name/password pairs. users just need to use single user name / password pair to login to the Identity Server. So users do not have to keep several user name and passwords in mind
• Users do not have to provide the user name/password pair at multiple places, but only at the identity provider which is more secure (reduces phising success)
• Users can access any of those services providers in need without re-entering user name / password pair which is more convenient to the user
• User's applications can use the user's SAML token on behalf of the user to access SAML secured resources
• Since authentication is handled at a single place, your system is more secured and less complex.

Additionally, all the WSO2 products will be able to act as SAML assertion consumers in near future, therefor implementing Single Sign On systems with the WSO2 Identity Server will be extremely easy.

Applies To

WSO2 Identity Server : 3.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 on the URL bar of the web browser? Each time when you are trying to access a resource, you will see that you are redirecting 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 user friendly and more secure. You signed in only once but you can access multiple resources withing the same domain without re-entering your user name /password.

SAML 2.0 Web Browser based SSO profile

SAML 2.0 Web Browser based SSO profile is yet another profile under Security Assertion Markup Language specifications. SAML provides five main specification documents:

1. Core
2. Binding
3. Profile
4. Metadata
5. Conformance

The SAML Web Browser based Single Sign On profile is defined in the Profile specifications.

In this scenario all the service providers trust the Identity Provider. A web user tries to access a SAML secured resource at a service provider or access the identity provider directly. In the previous case the service provider will redirects the user to the identity provider for authentication with a SAML 2.0 <AuthenRequest> message. This <AuthenRequest> message is generated by the service provider itself. The <AuthnRequest> message contains informations like <Issuer> (the location of the service provider) etc to be processed by the Identity provider. More informations regarding the <AuthRequest> message can be found in SAML Core Specification.

Then the identity provider process the <AuthenRequest> message and does the authentication of the user and then response with an authentication assertion message so called the <Response> message. The SAML 2.0 <Response> message basically contains information like the <Signature>, <Status> <Assertion> etc. This <Response> message will be delivered to the service provider and it will consume the assertion to establish a security context for the web user. More information regarding the <Response> message can be found in SAML Core Specification.

Following diagram illustrates the scenario.

 

SAML 2.0 SSO Assertion Consumers:

Service providers in a SAML 2.0 SSO system act as SAML SSO Assertion Consumers. They basically do two things:

1. Generating <AuthenRequest> messages to be redirected with the user to the identity provider.
2. Consuming <Response> message from the Identity provider and taking decisions regarding the principle based on the content of the <Response> message.

• Generating the <AuthnRequest> message: The SAML 2.0 <AuthenRequest> message must contain <Issuer> element and must contain the unique identifier of the requesting service provider. A sample <AuthRequest> message can be find here.

• Consuming the <Response> message : The SAML 2.0 <Response> message basically contains following three tags
  • <Signature> - contains the certificate given by the identity provider. This can be used to validation of the SAML 2.0 token.
  • <Status> - contains information like the status of the authentication (Success/Failed) etc.
  • <Assertion> - contains information like the subject of the assertion etc.

A sample <Response> message can be found here.

For further information please refer Security Assertion Markup Language 2.0 specifications.

SAML 2.0 web-browser based Single Sign On can be achieved in 3 different bindings:

• HTTP Redirect binding
• HTTP POST binding
• SAML SOAP binding or Artifact binding

In our scenario HTTP Redirect binding is used. More informations regarding the SAML message bindings can be found in the SAML Bindings Specification. A sample Java Assertion Consumer class which generates above <AuthnRequest> message and process above <Response> message can be found here.

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

           }

      }
 

• The SamlConsumer class does the generating the <AuthnRequest> message and processing the <Response> message.
• When a web user try to access the above servlet, it's doGet() method get called. Inside the doGet() method, it will generates an <AuthRequest> message and redirect the user to the Identity Provider.

• After the process of authentication is completed my the Identity Provider, it will do a POST call to the above servlet with a <Response> message. Then the doPost() method of the servlet will get called. Inside the doPost() method, it will retrieve the <Response> message from the request object and the <Response> message will be passed to the SamlConsumer instance for processing.

The complete code can be checked out here

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

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

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

       // the issuerUrl is the url of the service provider who generates the <authnRequest> message

         String issuerUrl = "http://localhost:8080/saml-demo/resource";

         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 authRequestBuilder = new AuthnRequestBuilder();

             AuthnRequest authRequest = authRequestBuilder.buildObject("urn:oasis:names:tc:SAML:2.0:protocol", "AuthnRequest", "samlp");

             authRequest.setForceAuthn(new Boolean(false));

             authRequest.setIsPassive(new Boolean(false));

             authRequest.setIssueInstant(issueInstant);

             authRequest.setProtocolBinding("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST");

             authRequest.setAssertionConsumerServiceURL(issuerUrl);

             authRequest.setIssuer(issuer);

             authRequest.setID(aRandomId);

             authRequest.setVersion(SAMLVersion.VERSION_20);
 

• The <authnRequest> message may contain many other elements like <NameIDPolicy>, <RequestedAuthnContext> etc. those elements can be created and added to the <authRequest> message in the same way.
• The generated <authenRequest> message must be marshaled using the “org.opensaml.xml.io.Marshaller” and must be Base64 encoded to the URL using the org.opensaml.xml.util.Base64;

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

• The response message must be fetched. For example if you are using a Servlet, you can fetch the response message from the “HttpServletRequest” like this,    responseMessage = request.getParameter("SAMLResponse").toString(); // request is the HttpServletRequest object.

• The fetched “responseMessage” has to be unmarshaled and the SAML <Response> message must be retrieved.

  DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance();

              documentBuilderFactory.setNamespaceAware(true);

              DocumentBuilder docBuilder = documentBuilderFactory.newDocumentBuilder();

              Document document = docBuilder.parse(new ByteArrayInputStream(authReqStr.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 <Response> message from the WSO2 Identity Server can be read easily.

Configuring the SAML 2.0 SSO Demo Service Provider 

• Check Out the SAML2 SSO sample service provider .war file from here.

• Extract the saml2-demo-webapp.war file to your Apache-Tomcat installation's webapps folder.

• Service Provider Configurations:

• Set the redirect URL (the URL of the Identity Provider ) at the config.xml file in “saml2-demo-webapp.war/WEB-INF/classes/my/test/saml/apps”
  (https://identity_server_host:identity_server_port/samlsso)

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.
• Set only the following values:
  • Issuer : http://tomcathost:port/saml2-demo-webapp/resource
  • Assertion Consumer URL : http://tomcathost:port/saml2-demo-webapp/resource
  • Thats all about the configuring the WSO2 Identity Server.

WSO2 Identity Server SSO feature Demonstration

• Now, start Apache-tomcat and visit http://tomcathost:port/saml2-demo-webapp/resource You will be redirected to the WSO2 Identity Server. Enter the User name / password.

  

• After successful authentication you will be able to access the resource.

 

• 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, an intern at WSO2 , suresh@wso2.com

Attachment	Size
isconfig.png	37.57 KB
resource.png	69.04 KB
saml-diag.png	39.5 KB
signin.png	18.63 KB
AuthRequest.xml	938 bytes
Response.xml	3.5 KB
saml-demos-final.zip	1.57 MB