Single Sign On (SSO)

Cloud CMS offers Single Sign On (SSO) Enterprise support that provides ways for users to log in using their existing business accounts. It makes it possible for your users to authenticate to Cloud CMS without having to remember or type in their credentials every time.

Cloud CMS offers two Enterprise SSO features - SAML 2.0 and JWT. These are two popular SSO mechanisms that work with many commercial and open-source identity providers including:

  • Microsoft Active Directory Federation Services (ADFS)
  • JBoss Keycloak,
  • Oracle Identity Federation,
  • SecureAuth,
  • IBM Tivoli Federated Identity Manager

Using SAML 2.0 and JWT, Cloud CMS can be easily integrated with your corporate security infrastructure.

SAML 2.0

Security Assertion Markup Language (SAML) is a standard for logging users into applications based on their sessions in another context. SAML 2.0 creates a two-way agreement between two vendors asserting that the information provided is valid. It provides a standard framework to share this information so you do not have to recreate the configuration for every vendor you want to share information.

Cloud CMS uses SAML 2.0 to connect briefly to a SAML 2.0-compatible Identity Provider (IdP). There are many identity provider products on the market, a few of which are listed above. Some identity providers are commercial products, others are open source and still others are home-grown. SAML 2.0 is a specification that many identity providers implement and therefore Cloud CMS integrates seamlessly with these.

For example, Microsoft provides its self-hosted Active Directory Federation Services (ADFS) server. ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials. Most organizations already know the identity of users because they are logged in to their Active Directory domain or intranet. It makes sense to use this information to log users in to other applications, such as web-based applications. One of the more elegant ways of doing this is by using SAML.

When SAML 2.0 is enabled, unauthenticated requests coming into Cloud CMS are redirected to the SAML 2.0 identity provider. The identity sits at a different URL and communicates 1-1 with the user to let them sign on. Thus, the username and password information flows between the user and the identity provider. Cloud CMS never sees the username and password.

Instead, once the user has given a valid username and password to the identity provider, the identity provider either does a Redirect or a POST back to Cloud CMS to assert that the user logged in successfully. This is known as a SAML Assertion. The identity provider asserts that the user is valid and also provides some information about the valid user.

The URL for redirection (or POST) is known as the Cloud CMS Assertion Consumer Service. It is available here:

https://<your-domain>.cloudcms.net/saml

The SAML Assertion must contain, at a minimum, a "user identifier" field which is used as a primary key into the user. Usually, this is the nameID field and it corresponds to the user's email address.

The SAML Assertion may contain other fields which can be mapped to user properties (such as firstName and lastName). In this way, user profile properties are kept in sync between Cloud CMS and your enterprise directory.

Cloud CMS receives this assertion and then proceeds. If the user already has an account with Cloud CMS, they will be logged in. Note that if the user had already logged in to the identity provider, this entire sequence will happen instantaneously. The end user will just see Cloud CMS come up and they will already be logged in.

If the user doesn't yet have an account with Cloud CMS, one will be created for them. Further, whether an account already exists or one is created, the user will be updated with the contents of the SAML Assertion. Cloud CMS lets you configure SSO user properties that will be mapped from the assertion onto the user. Cloud CMS also lets you inspect SAML asserted groups and automatically assign users to Cloud CMS Projects, Teams and Roles.

Configuring Cloud CMS to use SAML 2.0

You can configure SSO using SAML 2.0 right from the user interface. To do so, please follow these steps:

  1. Log into Cloud CMS as a user who has Manager rights over the platform. Usually this is the administrator of the platform or someone on the DevOps/IT side.

  2. On the left-side, select Platform Settings.

  3. On the sub-menu, select SSO.

By default, SSO is turned off. All authentication is explicitly done via username and password entry. You can now choose to enable SSO using SAML 2.0 by selecting "SAML 2.0" from the selection list:

The configuration screen looks like this:

The following properties are required:

  • SAML SSO URL : This is the URL that Cloud CMS will invoke to redirect users to your Identity Provider (IdP).
  • SAML Issuer : This is the issuer or client ID that will be sent to your Identity Provider.

The following properties are optional:

  • SAML Failure URL: This is a URL that Cloud CMS will direct users to in the event that something unforeseen happens during the login or account synchronization process. This should either be a custom error page or a standard error page provided by your Identity Provider. The Identity Provider may, for example, choose to log you out or redirect for another login.
  • User Primary Identifier Field: Use this to specify the field from the SAML assertion response that serves as the primary key for the user. By default, the nameID field serves as the primary field.
  • Mandatory Groups: A comma-delimited listed of group names. A user must belong to at least one of these groups in order to be permitted to log in to Cloud CMS. If a user does not belong to at least one of these groups, they will be redirected to a failure page. You can customize this failure page by setting the User Sync Error Redirect URL value on the Platform Settings > Settings page.
  • Certificate: A PEM formatted certificate that will be used to communicate with your Identity Provider.

SAML 2.0 merely describes the redirection of the browser to the identity provider, the login and the POST back to Cloud CMS of the assertion. Once Cloud CMS receives the assertion, it will sync the user and then authenticate as that user (through its own means).

SAML 2.0 ends at that point. There is no SSO token and SAML 2.0 itself has nothing to say about HTTP request state (cookies, tokens or otherwise).

JWT (JSON Web Token)

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA. JWT can be used for Authentication and Information Exchange.

To configure Cloud CMS to use JWT :

  • Go to Platform Settings > SSO.

  • Select JWT from the list as below:

With JWT configured, requests coming into Cloud CMS are expected to have a header or a cookie that contains a JWT token. A JWT token serves as an SSO token in that its presence asserts who the user is as well as some of their properties.

Cloud CMS receives the token and unencrypts it using a shared secret that is only known by the JWT token issuer and Cloud CMS. The contents of the token are then used to establish who the user is (as well as any properties the user may have).

Once the user is identified and its properties are understood, Cloud CMS will either create the user or update the user using the information extracted from the JWT token. In this way, Cloud CMS user accounts are automatically created and kept in sync with your enterprise architecture. The expectation is that an upstream server will have provisioned this JWT token - as such, it should be available with every request.

The JWT token should contain within it, at a minimum, a "user identifier" field which is used as a primary key into the user. Usually, this is the email field and it corresponds to the user's email address.

The JWT token may contain other fields which can be mapped to user properties (such as firstName and lastName). In this way, user profile properties are kept in sync between Cloud CMS and your enterprise directory.

The configuration screens look like this:

The configurable properties are:

  • Token Type (header or cookie) : Select whether the incoming JWT token is stored as an HTTP header or an HTTP cookie.
  • Token Name : The name of the HTTP header or HTTP cookie storing the JWT token.
  • Shared Secret : This value should be kept secret between you and Cloud CMS. It is used to verify the incoming JWT token.
  • Algorithms : Choose the algorithm to use to sign and encrypt the JWT token
    • HS256 (HMAC + SHA256))
    • HS384 (HMAC + SHA384)
    • HS512 (HMAC + SHA512)
  • Issuer : Give the issuer of the JWT token
  • User Primary Identifier Field : Generally e-mail address of the user.

Once, we configure the Cloud CMS to use JWT:

  • Log out of your current Cloud CMS account
  • Log back in

While logging in again, the system will check if the JWT token is found and is valid. If not the Remote Login URL setting lets you specify where the request should be redirected. Usually, this is a corporate login service. Once the user logs in there, they will be redirected back to Cloud CMS (through means controlled by the corporate login service). In that process, the JWT token will be placed into the request so that when it arrives to Cloud CMS, it can be utilized for SSO. If the token is found and is valid, it automatically logs in as that User.

User Field Mappings

Cloud CMS supports mapping custom fields from either JWT payloads or SAML Assertions into your users. This lets you synchronize user properties from our identity provider into Cloud CMS. This may be simple fields like First Name or Email but also may include custom properties of any sort.

To add a User Field Mapping, go to the User Field Mappings section and click on the [+] icon. Each mapping must define

  • User Property: the name of the field on the Cloud CMS user object
  • Source Field: the name of the field on the JWT payload or SAML Assertion.

Values will be mapped directly and will be applied whenever a user logs in. Users must sign out and sign back in for synchronization to run again.

Group Mappings

Cloud CMS automatically picks off groups from your JWT payloads or SAML Assertions. Groups are simply names that identifiy which "groups" a user should belong to. These groups can be acted upon using Group Mappings. If a user belongs to a specific group, you can have the following occur:

  • Add them to a Project
  • Add them to a Project Team
  • Add them to a Platform Team

To add a Group Mapping, go the Group Mappings section and click on the [+] icon. Each mapping defines a group name and a series of rules to execute if the user belongs to that group.

Rules are simply strings that invoke functions to do things with the user.

The following rules are supported:

Add To Project

Usage: addToProject(projectId, teamKeys)

This rule adds a user to a project. It also lets you specify teams within the project that the user should be placed into. If the user is already a member of the project or if the user is already a member of the specified team, no action is taken.

Examples:

addToProject("518f055f88ef59fa8c77")
addToProject("518f055f88ef59fa8c77", "myteam")
addToProject("518f055f88ef59fa8c77", ["myteam1", "myteam2", "myteam3"])

Add To Platform Team

Usage: addToPlatformTeam(teamKey)

This rule adds a user to a platform team. If the uesr is already a member of the platform team, no action is taken.

Examples:

addToPlatformTeam("managers")

Add to Platform Teams

Usage: addToPlatformTeams(teamKeys)

This is very similar to Add a Platform Team above but lets you specify an array of team keys.

Examples:

addToPlatformTeams(["managers", "content-publishers", "authors"])

Tips and Tricks

When SSO is configured, the default login process will go down the path of the configured SSO mechanism. If SAML is enabled, unauthenticated users are redirected to the Identity Provider. If JWT is provided, unauthenticated requests are resolved and authenticated by considering the encrypted JWT token.

Either way, users who log in this way will have user accounts automatically created and synchronized within Cloud CMS. These "synchronized" Cloud CMS user accounts will not have password information stored within Cloud CMS. In fact, Cloud CMS never comes in contact with the password since that username/password sign on happens somewhere else.

As such, the only way these "synchronized" users can log in is to use the SSO mechanism.

That said, you may have users in Cloud CMS who are non-SSO users. These may be administrative users, tenant owners or other test users that you need access to. These users do have their passwords stored within Cloud CMS and so you can log in as those users directly by going to:

https://<your-domain>.cloudcms.net/login

Further, once you're logged in as any user, you can force a logout by going to:

https://<your-domain>.cloudcms.net/logout

Logging out will end the session with the Cloud CMS user interface. If you want to specify a redirect URL where users should be routed to once the logout has completed, you can set this on the Platform Settings > Settings page using the Remote Logout URL setting.

Example: KeyCloak

In this section, we look at a few examples of configuring Identity Providers to work with SAML 2.0. This is not intended to be an exhaustive guide but simply to provide readers with a general idea.

Keycloak is a software product from JBoss to allow single sign-on and Identity Management. Keycloak is an open source Identity and Access Management solution aimed at modern applications and services. From a conceptual perspective the tools intent is to make it easy to secure applications and services with little to no coding.

Users authenticate with Keycloak rather than individual applications. This means that your applications don't have to deal with login forms, authenticating users, and storing users. Once logged-in to Keycloak, users don't have to login again to access a different application.

You can learn a whole lot more about Keycloak here:

http://www.keycloak.org/about.html

Before configuring the Cloud CMS Single Sign-On, you’ll need to set up a few things on Keycloak Single-Sign On:

Log in to the Keycloak Administration Console

Keycloak offers an Administration Console that is generally available at:

http://localhost:9090/auth/admin/.

Enter the username and password you created on the Welcome Page or the add-user-keycloak script. If you're using a standard configuration, then this may simply be admin / admin.

Once you have logged in, you can see the Admin Console with a Master realm already present.

Create a SAML 2.0 client

Go to Clients in the left menu bar. Click on the Create button the right hand side of the page.

You will see a form like this:

Enter in the Client ID of the client. This can be any name but we recommend myapp.

Select saml in the Client Protocol drop down box.

Click Save. This will create the client and bring you to the client Settings tab as below:

Customize your client

By default, Keycloak sets up your client to require an SSL Certificate for communication with it. This means that Cloud CMS must know about your Identity Provider's certificate (you would have to provide it, see the SAML 2.0 section above). However, if you're just running in development and do not have a certificate, you should disable the Client Signature Required option.

You now need to tell your Keycloak client about any Redirect URIs that it should allow. When Cloud CMS redirects to your Identity Provider for login, it will let the Identity Provider know where to redirect back. This URL will be:

https://<your-domain>.cloudcms.net/saml

In order for Keycloak to respect the wishes of Cloud CMS, you should set the Redirect URIs field to include:

https://<your-domain>.cloudcms.net*

For developers running Cloud CMS on-premise, you may choose to use this for local testing:

http://localhost*

There are a lot of other options available. For more information on these options, please check out:

http://www.keycloak.org/docs/2.5/server_admin/topics/clients/client-saml.html

Add Mappers

Applications that receive ID Tokens, Access Tokens, or SAML assertions may need or want different user metadata and roles. Keycloak allows you to define what exactly is transferred.Each client has several built-in mappers that are created for it by default. They map things like, for example, email address to a specific claim in the identity and access token. Their function should each be self explanatory from their name. You can create various mappers like First Name, Last Name, E-mail etc.

To create a Mapper, go to Clients in the left menu bar.

Select the client for which you want to add Mappers.

Then, go to Mappers tab and Click on Create button present on the right side of the Mappers tab and start creating a mapper.

An example of creating a Mapper "First Name" is:

Create a new User

Go to Users in the left menu bar. Then, on the right side of the empty user list, you should see an Add User button.

Click that to start creating your new user.

The only required field is Username. Click Save. This will bring you to the management page for your new user.

Once the User is created, go to the Credentials tab and add a Password for the User which will be used to login.

Verify it works

You can now verify that Cloud CMS is configured to use SAML 2.0:

  • Log out of your current Cloud CMS account
  • Log back in
  • While Logging in again, you will be re-directed to Keycloak Admin Console.
  • Enter the username and password of the SAML User you created.
  • If the credentials match, you will be redirected back to Cloud CMS.
  • Cloud CMS will automatically log you in and create your user if it doesn't yet exist.
  • Proceed and be merry.

Example: Azure Active Directory

Azure Active Directory is a Microsoft Azure service which provides identity and access management. Cloud CMS supports single sign on with Azure AD using SAML 2.0.

Before configuring the Cloud CMS Single Sign-On, you’ll need to set up a few things on Microsoft Azure Active Directory:

Create an Azure Account

If not already present, create an Azure Account using the Azure portal. Log into the portal and go to Azure Active Directory.

Register your App

Go to the App Registrations tab in your directory to create a new application. Click New application registration button at the top panel.

Enter the Name for the application and Sign on URL. Click on Create.

Configure your App

Once the Application is created, Choose the application you created from the list of All apps. Go to Setting tab and Enter the reply URL as : "http://localhost/saml/consume".

Configure Cloud CMS

To find the Client SAML Endpoint URL, Go to App Registrations panel and click on Endpoints button on the top panel.

From the Endpoints screen, copy the URL at the SAML-P SIGN-ON ENDPOINT field.

Now, to configure Cloud CMS:

  • Go to Platform Settings > SSO.
  • Select SAML 2.0 from the list as below:
  • In the SAML SSO URL field, paste the URL copied above.
  • In the SAML Issuer field, enter the Application ID of the application created.

All the other fields can be filled as explained in section 1.

Below is a screenshot of how the settings page would look like:

Save the settings.

Verify it works

You can now verify that Cloud CMS is configured to use SAML 2.0:

  • Log out of your current Cloud CMS account
  • Log back in
  • While Logging in again, you will be re-directed to Microsoft Azure portal.
  • Enter the username and password of your account.
  • If the credentials match, you will be redirected back to Cloud CMS.
  • Cloud CMS will automatically log you in and create your user if it doesn't yet exist.
  • Proceed and may the force be with you.