Jahia DX & SAML 2.0

Single Sign On (SSO) is a common requirement for enterprise customers.  Most enterprise customers tend to have multiple web applications running, possibly connected to a common LDAP to manage users.  Even though users can authenticate using the same credentials on each web app, this approach does not provide the best user experience or can possibly be a security risk.  SSO is the solution that reduces the number of times a user has to login in a multi application environment.

There are two popular approaches when it comes to SSO.  One approach is Security Assertion Markup Language (SAML) which has been in the industry since the early 2000.  The other approach is OAuth.  OAuth’s inception was due to the rise of mobile devices.  Most people have encountered OAuth though the use of Facebook, Twitter, or LinkedIn connect to login.  As for native apps, they exclusively use OAuth for SSO since SAML communicates with systems using request and response headers which is not available in native apps.  At this time, we will cover SAML and its integration with Jahia DX.

Anatomy of SAML 2.0

It is important to know the parts that make up the SAML specification.  I will briefly go over these concepts so that there is better context for understanding.  For deep dives on any of these concepts, you can search the internet or check out any SAML books.

Assertions

Assertion consists of one or more statements.  The first statement is the authentication which is typically generated by an Identity Provider (IdP).  Next is the attribute statement which consists of information about the user.  Last, the authorization statement provides instructions on whether the user has access to the specified resource.  In Jahia DX, authorization is handled through ACL built into the system so authorization statements are not needed in the Assertions.

Protocol

The protocol defines the element packaging within a SAML request and response assertions.  It also provides consuming and producing processing rules that must be followed by SAML entities.  An example of a protocol request is a query.

Bindings

Bindings describes how protocol messages are mapped to a messaging format such as SOAP.  The bindings provide instructions on posting, redirections, and more.  To get more detail, please refer to SAML resources.

Profiles

A profile is how assertions, protocols, and bindings are combined.  A most common SAML profile is a Web Browser SSO profile.  There is also Single Logout Profile and more.

Communication

Communication between a user and an Identity provider (IdP) or Service Provider (SP) is executed through the uses of request and response SOAP messages.  The user kicks off this process either with a request for a secured resource or a request to login.

Request

The example below is a SOAP request message generated by the Service Provider (SP).  The request message is POSTed to the Identity provider to start the login process.

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest AssertionConsumerServiceURL="https://jahia.local:8443/cms/login.SAML.incoming">
   <saml2:Issuer>https://sp.jahia.org/shibboleth-sp</saml2:Issuer>
   <saml2p:NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
</saml2p:AuthnRequest>

Response

Once the Identity Provider (IdP) confirms the user's credentials, the below SOAP is sent to the user in a form.  The form is automatically posted to the  Service Provider to complete the login process.  This message is set in the header of a request object.  This example provides the user unique id as well as other user properties.

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response Destination="https://jahia.local:8443/cms/login.SAML.incoming">
    <saml2:Assertion>
        <saml2:Issuer>https://192.168.33.99:8443/idp/shibboleth</saml2:Issuer>
        <saml2:Subject>
            <saml2:NameID SPNameQualifier="https://sp.jahia.org/shibboleth-sp">
                ...
            </saml2:NameID>
        </saml2:Subject>
        <saml2:AttributeStatement>
            <saml2:Attribute FriendlyName="uid">
                <saml2:AttributeValue>smomin</saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>

Shibboleth

There are many SSO products that are available in the industry.  Some of the more popular ones are Shibboleth, Ping Federate, and OneLogin.  Shibboleth was chosen for this integration with Jahia DX.

Shibboleth is an open source project that adheres to the OASIS standard.  In addition to being a project, it’s an implementation and a specification. Shibboleth provides an Identity provider (IdP) to authenticate users and a Services Provider (SP) to authorize access to protected resources, such as a directory or a file.  The technologies used by both products are XML, HTTP, and SOAP.  

The Identity Provider (IdP) is a J2EE web app that can be deployed to Tomcat or Jetty.  The Service Provider (SP) is a Apache HTTPd modules that is written in C++.  There is a NGINX workaround.

Jahia Digital Experience Manager (DX)

Jahia DX is a popular enterprise User Experience Platform.  It provides a content management system for building and managing sites, a portal for application aggregation, and a document manager to manage digital assets.  Jahia DX provides a powerful system to manage secured resources such as a site, pages, content, or digital assets.  These are managed through easy to use interfaces that makes DX an ideal candidate to be a Service Provider (SP).

Jahia DX & Shibboleth

So let’s discuss how these two platforms can be integrated to provide a solution for customers with SSO needs.

Configuration

Before we can integrate Shibboleth (IdP) to Jahia DX (SP), we have to properly configure the Identity provider.  The following files were configured for Shibboleth (IdP) web application to integrate with a LDAP and Jahia DX.

• Access-control.xml, ability to control access through the use of ip addresses
• Attribute-filter.xml, create a list with attributes that will be exposed to a Service Provider
• Attribute-resolver.xml, map attributes from source, i.e. LDAP to IDP attributes
• Metadata-providers.xml, definition on registering a Service Provider
• Relying-party.xml, configures SAML profiles and allows for additional configuration based on the relying party id
• Ldap.properties, configure LDAP to IdP
• Logback.xml, controlling the logging levels

Users

It is important that both Jahia DX (SP) and Shibboleth (IdP) use a common users repository. Using a LDAP product such as OpenLDAP can be a central location where users are managed.  Configuring Shibboleth (IdP) with a common LDAP allows for authentication of users and mapping of LDAP properties to IdP attributes.  These attributes are sent to Jahia DX (SP) in the response SOAP message.  For Jahia DX (SP), LDAP is configured to allow authors to permission users to a site, pages, content, or files.

Registration

In Shibboleth (IdP), Jahia DX has to register as a Service Provider (SP).  This process requires an XML document that provides metadata about the Service Provider (SP).  This metadata consists of a Service Provider ID for identification, encryption and signing certificates to secure the request & response SOAP messages, and a redirect location url to complete the authentication process.  The diagram below illustrates this registration.

This registration is important in the login process.  Shibboleth (IdP) will use the Service Provider ID in the request SOAP message and validate this ID against the registered Service Providers.  If the Service Provider is registered, the login process continues, otherwise Shibboleth IdP will halt the login process.

Integration

When SSO is implemented, there are human and system actors that make up the process.  The user (human) initiates the process by requesting a secured resource or requesting a login.  For starting the login process on a secured resource request, the 401 status code can be utlizied.  Jahia DX (SP) 401 error page can initiate the login process transparently so manually steps from a user is not required.  This process will create an authentication request SOAP message that is auto posted to Shibboleth (IdP).  The below diagram presents the steps on how these actors interact.

Steps

1. Secured Resource requested
2. Jahia DX generates a HTML Form with SAML Auth Request value in a form input. This HTML form is in the response to the end user. The Javascript added with the HTML form response to auto post the form to the Shibboleth (IdP).
3. SAML with Authn Request POSTed
4. IdP Login Form displayed
5. Username/Password submitted
6. Retrieve user for authentication
7. Redirect with a Form and SAML response as input
8. SAML response is auto POSTed to Jahia DX
9. Retrieve user to be placed in session
10. Give access to secured resource

SAML Authentication Valve

In Jahia DX (SP), the SAML Authentication Valve manages the SAML interactions.  This valve uses the SAML client service to generate a request SOAP message.  The client service then sets the request SOAP message as an input in a generated HTML form.  This form is returned to the user and is auto POSTed using JavaScript to Shibboleth (IdP).  The IdP processes the request SOAP message for validity before displaying the login form.  Upon credential submission and successful authentication, the IdP sends the user a POST redirect with the response SOAP message.  This response SOAP message is posted to the redirect url provided in the Jahia DX metadata.  The redirect url is handled by the SAML Authentication Valve with the consumption of the response SOAP message.  The valve finishes the process by using the User Manager to get the User,  The user is placed into session and is allowed to access the secured resource.  This sequence diagram below illustrates the services involved in Jahia DX (SP).  

Steps

1. /cms/login.SAML
2. Send Request to IdP
3. Generated HTML Form with Authn Request SOAP Message.  The SAML Client provides a utility that places a generated form in the response.
4. Auto POST Authn Request SOAP Message
5. Display Login Form
6. Username/password submitted
7. Response SOAP Message ready for POST
8. /cms/login.incoming, POST Response Message
9. Retrieve User
10. Return User
11. User is logged in or given access to the secured resource

With Configuration, Registration, and Integration, Jahia DX (SP) is properly set up to communicate with Shibboleth (IdP) for SSO logins.

Conclusion

With Jahia DX platform, an enterprise customer is capable of integrating with any Identity Provider (IdP). This demonstration can be used as a foundation to achieve success. Below are resource used to demonstrate this integration of Jahia DX and Shibboleth.

Resources

• https://github.com/Jahia/jahia-development-environment, this development environment will set up Jahia DX, Shibboleth, and OpenLDAP.
• https://github.com/Jahia/saml-authentication-valve, this Jahia DX authentication value interacts with the IdP.  It provides a MetaData Action to generate the metadata to register.  If you are using the development environment, you will not need to worry about the registration.  SAML authentication valve will need to be set up for any Jahia DX site.  Setting values are provided in the development environment instructions.
• https://github.com/Jahia/LDAP-provider, this Jahia DX module allows connecting to an LDAP platform.
• http://saml.xml.org/, for all things SAML.
• http://shibboleth.net/, for all things Shibboleth.