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)
Okta
PingOne
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:

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.
In Manage Platform, select Platform Settings.
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.
Certificate: A PEM formatted certificate that will be used to sign SAML communicate with 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. The value of this field must be lower case in the SAML assert.
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.

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 :

In Manage Platfrom, 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 decrypts 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
Field Value: 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.

The name property is used as the default display name for users within the CMS, so this is often a good one to map to. For SAML, nameID will often work as a unique identifier, or you could use another mapped field from your SSO system. Note that names must conform to the platform username policy, which by default requires all characters to be lowercase.

Group Mappings

Cloud CMS automatically picks off groups from your JWT payloads or SAML Assertions. Groups are simply names that identify which "groups" a user should belong to. These groups can be acted upon using Group Mappings.

A user's group is identified via a field on the JWT payload or the SAML Assertion. The field name should be either groups or member. The value of this field can either be an array of strings or a string with comma-delimited values.

For example, here is a JWT payload that describes a user (Joe Smith) who is a member of the employees and editors groups:

{
  "iss": "test",
  "name": "Joe Smith",    
  "email": "joe@smith.com",
  "groups": ["employees", "editors"]
}

Or perhaps:

{
  "iss": "test",
  "name": "Joe Smith",    
  "email": "joe@smith.com",
  "member": "employees,editors"
}

When a user is identified as belonging to a specific group, via a group mapping, 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.

Setting up the App User

For user synchronization rules to work, you will first need to make sure that the application server's appuser account has Manager rights to the domain where users are stored.

The easiest way to do this is to add the appuser to a team for the platform that grants the Manager role.

To do this:

Log in to the Administration Console
Click on Teams
Create a Team called sso (with the team key sso) and make sure it grants the Manager role.
Click into your sso team.
Under Manage Memberships, click on Query.
Uncheck the box for Only display group members.
Under Domain, select Primary Domain.
Click on Query on the right bottom corner.
Find the row with your appuser and click Add.

Once this is done, your appuser will have rights to modify users in the domain. This will allow SSO user and group synchronization to work as intended for not only new users and groups but also existing users and groups.

If your App User doesn't have sufficient access rights, you may see an error like this:

The principal: 0f4fdc4f04f5bf8da4bc with name: appuser-bffcd138f66980156e99 requires ACL permission: MODIFY_PERMISSIONS against 9873f7069bc9e3aff8d7 of type: DomainUserImpl to complete the operation

If you see a similar error when trying to log in via SSO, this means that a user sync operation failed. Please follow the steps above to give the App User sufficient privileges.

Rules

Add To Project

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

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

Examples:

addToPlatformTeam("managers")

Add to Platform Teams

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.

Examples

We provide a couple of examples here of how to set up Cloud CMS. The following are available: