Contentstack supports Single Sign-On (SSO). If your Contentstack organization is SSO-enabled, users can access the organization through your corporate identity provider credentials, instead of Contentstack account credentials. This eliminates the normal login process and enables faster and secure access to your apps.
Single Sign-On is a method that enables a particular system (usually the concerned organization’s identity provider) to authenticate users and subsequently inform Contentstack that the users have been authenticated. The users are then allowed to access their resources in Contentstack without having to sign in using Contentstack credentials.
Contentstack uses the most-commonly adopted SSO standard, i.e., Security Assertion Markup Language 2.0 (SAML 2.0). Consequently, our SSO implementation can be integrated with any well-known identity provider (IdP) that supports SAML 2.0.
How SSO works with Contentstack
Authentication to your SSO-enabled organization will be handled by your IdP. If any of your users want to sign in to Contentstack via SSO, they will be redirected to your IdP.
If users are not logged in to your IdP, they will be redirected to the IdP sign-in page, where they are required to authenticate themselves. However, if the users are already signed in to your IdP while signing into Contentstack via SSO, they will not be asked to log in again and will be redirected to the Contentstack dashboard or the requested page.
However, in order to access and manage content in Contentstack, users need to be assigned specific roles in their respective IdPs and these roles need to be mapped to Contentstack roles.
Let’s see how this IdP Role Mapping works in detail.
IdP Role Mapping
IdP Role Mapping allows you to assign Contentstack roles to the users of a group/role in your IdP. Subsequently, users of such groups can directly log in to your SSO-enabled organization (without invitation) with the assigned permissions.
This is an alternate way of managing users and permissions of your SSO-enabled organization (the other way being invitation-based users and roles management).
To use this feature, you need to map your IdP roles to Contentstack roles, while configuring SSO for your organization. Learn how to map IdP roles.
Note: After enabling IdP Role Mapping, the role management (in Contentstack) for the users of your IdP will be handled from your IdP, instead of from Contentstack. Learn more.
Currently, IdP Role Mapping is supported only for Okta and OneLogin.
Supported Identity Providers
Contentstack SSO can be integrated with all the identity providers (IdP) that support SAML 2.0 protocol. This includes all major IdPs such as Okta, OneLogin, Azure AD, AD FS, Google G-Suite, Ping Identity, Ping Federate, Auth0, LastPass, Clear Login, Centrify, and more.
We have step-by-step SSO setup guides for some of the popular IdPs. The details can be found in the corresponding articles given in the list below. Or you can refer to our general guide on setting up SSO with any IdP.
Guides for setting up SSO with specific IdPs
Guide for setting up SSO with other SAML 2.0 IdPs
Set up SSO in Contentstack
This is a general step-by-step guide explaining the process of setting up single sign-on in Contentstack with your SAML 2.0 Identity Provider.
In order to enable SSO for your organization, you would need the following:
- Access to your identity provider’s configuration settings
- Owner role in your Contentstack organization
Steps to enable SSO in Contentstack
In order to set up SSO for your Contentstack organization with any IdP, you need to proceed according to steps given below.
Let’s go through each of these steps in detail.
Step 1 - Create SSO Name and ACS URL in Contentstack
- Log in to your Contentstack account. Go to the Organization Settings page of your organization and click on the Single Sign-On tab on the left.
- Enter an SSO name of your choice, and click Create. For example, if your company name is 'Acme, Inc.' enter 'acme' here. This name will be used as one of the login credentials by the organization users while signing in.
Note: The SSO Name can contain only alphabets (in lowercase), numbers (0-9), and/or hyphens (-).
Let's use 'test-sso' as the SSO Name.
- This will generate the Assertion Consumer Service (ACS) URL and other details such as Entity ID, Attributes and NameID Format. These details will be used in Step 2 for configuring Contentstack app in your Identity Provider.
Keep this window open, as you may need these details for setting up Contentstack app in your IdP in the next step.
Step 2 - Setup Contentstack app in your IdP
- Login to your IdP admin account.
- Create a new application (also known as app or connector in some IdPs) with application name preferably as ‘Contentstack’.
- In SAML settings, you need to provide the ‘SSO Configuration’ details that you received from Contentstack in Step 1.
In your IdP, in the Single Sign-on URL field, provide the ACS URL that was generated for your organization in Contentstack. Then, use Contentstack’s Entity ID (generated in Step 1) in your IdP in ‘Audience URI’, ‘SP Entity ID’, ‘SAML Issuer ID’, or fields similar to these. In the NameID Format, select or enter EmailAddress. This defines the parameter that your IdP should use to identify Contentstack users.
- Under ‘Attribute Mapping’ or ‘Attribute Statements’, add three attributes, i.e., email, first_name, and last_name, and map corresponding IdP values, such as email, firstname, and lastname.
- [Optional Step] If you want to map IdP groups/roles to Contentstack roles, you need to add a new attribute called ‘roles’ under ‘Attribute Mapping’, and return your IdP users’ roles or groups.
Note: Perform this step only if IdP Role Mapping is part of your Contentstack plan.
- Once you enter all the details and save your settings in IdP, you should receive IdP Single Sign-On URL and X.509 certificate. Use these details in Step 3.
Step 3 - Configure IdP Details in Contentstack
- Go to 2. IdP Configuration in Contentstack.
- In the Single Sign-On URL field, paste the IdP Single Sign-On URL that you received from IdP in Step 2.
- In the Certificate field in Contentstack, upload the X.509 or Public Key Certificate that you received from your IdP.
- Select the relevant algorithm from the options given under the Signature Algorithm field.
- Click Save to save IdP configuration.
Note: In some IdPs, you may have to assign the newly-created Contentstack application to the existing users of your IdP. These settings can be found under the ‘Users’ section in IdP.
With this step, you have completed SSO settings in your IdP. However, you need to configure two more steps in Contentstack.
Step 4 - User Management in Contentstack
In Contentstack, go to 3. User Management. Here, you need to define important settings related to your users in your SSO-enabled organization. These settings include Strict Mode, Session Timeout, and Advanced Settings.
Strict Mode lets you decide if you want to allow any non-IdP users (i.e., users that are not available in your IdP) to access the SSO-enabled organization in Contentstack.
- Enable ‘Strict Mode’
If you enable Strict Mode, users that are not added to your IdP will not be able to access the Contentstack organization. This means that users can access the organization only through SSO, without any exceptions.
- Disable ‘Strict Mode’
If you disable Strict Mode, users with special permission (i.e., users marked as ‘Allow access without SSO’ in Organization User settings) can access this organization using Contentstack credentials, instead of through SSO (IdP credentials). It’s similar to creating an exception list of users.
Invite users to access organization without SSO
To allow users to access your SSO-enabled organization without SSO login (using Contentstack credentials), perform the following steps:
- Disable Strict Mode in the User Management step in SSO settings.
- Go to Users in Organization settings.
- Click on Invite User. On the modal that appears, check Allow Access Without SSO, and enter user details.
- Click Invite.
You can define the session duration of user signed in through SSO. By default, this is set to 12 hours. However, it can be set anywhere between 1 hour and 24 hours. The session begins when the user logs in to Contentstack via SSO and will timeout after 12 hours (or the time period that you specify here).
Under Advanced settings, you will find more advanced settings related to user management, which includes IdP Role Mapping.
Note: The IdP Role Mapping feature is available only if it is part of your Contentstack plan. You will find the Role Mapping section only if it's part of your plan. If you want to include this feature in your plan, contact firstname.lastname@example.org.
Configuring IdP Role Mapping
IdP Role Mapping allows you to assign Contentstack roles to the users of a group/role in your IdP. Learn more about this feature.
Before you add new role mappings, you must add the ‘roles’ attributes in the ‘Attribute Mappings’ section in your IdP. The steps are covered in Step 2 above.
To add new IdP role mapping, click on the + ADD ROLE MAPPING link. Enter the following details:
- IdP Role Identifier: Role identifier is the name or UID (by which it is uniquely identified in IdP) of the IdP group that you want to map. For example, ‘Contentstack Developers’ or ‘Contentstack Project Managers’.
- Organization Role: Assign an organization-level Contentstack role (i.e., either ‘Admin’ or ‘Member’) to the IdP group/role that you are mapping.
- Stack Roles: Assign stacks as well as corresponding stack-level roles to this IdP role.
On the IdP side, you need to add ‘Group Mapping’ or ‘Group Attributes’ to map the roles. Read more.
Likewise, you can add more role mappings for your Contentstack organization.
In the Role Delimiter section, mention the character that serves as the delimiter for the roles. Depending on the IdP selected, the delimiter can be a space, comma (','), semicolon (;), or something else.
Finally, select the Enable IdP Role Mapping checkbox to enable this feature.
Note: After enabling IdP Role Mapping, the role management (in Contentstack) for the users of your IdP will be handled from your IdP, instead of from Contentstack. Learn more.
Step 5 - Test and Enable SSO
Before enabling SSO, it is recommended that you test it. Clicking on the Test SSO button will take you to Contentstack’s Login Via SSO page, where you need to specify your organization SSO name. Then, click on Continue to go your IdP sign in page. Sign in to your account. If you are able to sign in to your IdP, your test is successful.
On successful connection, you will see a success message as follows:
But, if you have enabled IdP Role Mapping, you’ll find the following details in a new page:
- SSO connection established successfully - A success message is displayed.
- IdP Roles received - The list of all the roles assigned to you in your IdP.
- Contentstack-IdP role mapping details - The details of all the Contentstack Organization-specific and Stack-specific roles mapped to your IdP roles.
Click on the Close button. Now, you can safely enable SSO for your organization.
Note: While testing SSO setting with IdP Role Mapping enabled, the test will be performed only for the IdP roles of the currently logged-in user (i.e., the user performing the test).
Click on ‘Enable SSO’ to enable SSO for your Contentstack organization. Once this is enabled, users of this organization can access the organization through SSO login. You can disable SSO from the same page when required.
After enabling SSO, you will see ‘SSO One-click URL’ at the top of the SSO page. You can use this URL to directly go to Contentstack’s SSO login page. Bookmark this URL to skip multiple steps while logging in.
Note: Only the users invited to the SSO-enabled organization can access the organization if IdP Role Mapping is disabled. Your IdP users cannot directly access the organization if they have not been invited to this organization.
After enabling SSO, you will notice that 4. Test & Enable SSO changes to 4. Disable SSO in your SSO settings page. You can disable SSO for your organization anytime by clicking the Disable button.
Once disabled, the existing users of your organization will have to use Contentstack credentials to sign in. In case the existing user does not have Contentstack credentials, the user will have to use the Forgot password link on the login page in Contentstack to create a new password for login.
REST API Usage
Enabling SSO for an organization may affect your REST API integrations, particularly the ones using Content Management APIs. It is therefore recommended that you read this section carefully.
Content Delivery API
For an SSO-enabled organization, Content Delivery APIs work as expected. The Content Delivery API requests are GET calls and they use the stack’s delivery tokens to fetch content. No changes are required.
Content Management API
Any user who accesses the SSO-enabled organization through IdP login cannot make Content Management API requests since it requires a user authtoken. Below we will explain a couple of options on how to utilize the Content Management API for specific users when SSO is enabled.
Since the owner of an organization can access an SSO-enabled organization through Contentstack credentials as well, he/she has a user authtoken. The owner can use this authtoken (received in the response of the ‘Login’ request) to make Content Management API requests.
Similarly, if Strict Mode is disabled for an SSO-enabled organization, and if a few users have been given permission to access the organization through Contentstack credentials (by enabling the Allow Access Without SSO option in Organization > Users), then these users can use the authtoken to make Content Management API requests.
How do I enable SSO for an organization?
To enable SSO for an organization in Contentstack, you must be the owner of the organization and SSO must be part of your Contentstack plan. If you meet these two conditions, you can set up SSO for your organization. Read how to set up SSO in Contentstack.
How can a user, who always logged in to his/her SSO-enabled Contentstack account via SSO (and does not have normal login credentials), access the same organization after SSO has been disabled for the organization?
When a user is included in an SSO-enabled Organization, he/she accesses the Organization through SSO using their IdP credentials instead of their Contentstack credentials (which they might not have created). If, later on, SSO is disabled for the Organization, the user will not be able to log in to Contentstack through IdP. However, the user is still part of the Organization.
To access the same organization, the user will have to reset his/her password in order to log in to Contentstack. To do so, open the login page of Contentstack UI, click on the ‘Forgot password’ underneath, enter your email address, and click on ‘SEND INSTRUCTIONS’. This will send password reset instructions to the user’s email address. The user needs to follow the instruction in the email and login to their Contentstack account.
If the Identity Provider (IdP) experiences a system failure, how can we make changes to our content?
An organization owner can always use his Contentstack credentials to log in to Contentstack and make relevant changes, irrespective of whether SSO has been enabled or not.
If the IdP experiences system failure, then an owner can log in using his credentials, disable Strict Mode, and grant access to the required user(s) by checking the 'Allow access without SSO' option in their Organization User settings. These users will now be able to access the organization using their Contentstack credentials, instead of through SSO (IdP credentials).
However, if the user does not have a Contentstack account, he/she will receive an email with the account setup instructions that they need to follow in order to create an account in Contentstack. Post setting up their account, they will be able to access the Organization content.
As a user, how do I sign in to an SSO-enabled organization in Contentstack?
Log on to Contentstack, and click the ‘Login via SSO’ link located at the bottom of the page. On the next screen that appears, enter your organization SSO Name. You must have received the SSO name in your stack or organization invitation email. If you do not know your organization SSO Name, contact your organization owner or admin. Hit the ‘Continue’ button after entering the SSO Name, and you will be redirected to your corporate IdP login page. Enter your IdP login details to sign in to your Contentstack account.
As an owner/admin, how do I invite users that are not in my corporate IdP to my SSO-enabled organization?
To invite users that are not in your IdP, you first need to disable ‘Strict Mode’ in the ‘User Management’ step in your SSO settings page. Then, go to Organization > Users, and invite users as you normally do. While inviting, select the checkbox ‘Allow Access Without SSO’. This will allow the invited user to access the SSO-enabled organization through Contentstack credentials.
Will I need to resend an invite to my existing organization users if I enable SSO?
No. You do not have to send an invitation again since the existing users continue to remain part of the organization, even after SSO is enabled. Nothing changes for the existing users, except that they are required to sign in using SSO, instead of normal Contentstack username/password login. However, if any existing user is not part of your identity provider, you may have to disable 'Strict Mode' and update the user in Contentstack by assigning permission to ‘Allow Access Without SSO’. Learn more about Strict Mode
How do I invite new users when IdP Role Mapping is enabled for my SSO-enabled organization?
To add new IdP users to your SSO enabled organization, just add them to any of your IdP group or role (in your IdP settings) that is mapped with Contentstack roles. They can then directly login to Contentstack (via SSO) with the corresponding permissions.
If you want to provide a different set of permissions to some users, create a new group/role in your IdP, and add users to this group. Subsequently, add the mapping for this group in Contentstack SSO user settings.
To invite external users, disable Strict Mode and invite them as usual from Contentstack from Organization Settings. Remember to select the Allow login without SSO checkbox.
If SSO is already enabled for my organization, does enabling IdP Role Mapping cause any change?
Yes. Only the roles received from your IdP for the users will be honored. This means that, on enabling IdP Role Mapping, the existing roles assigned to the users will be overridden by the roles assigned to IdP groups. This, however, is not applicable for external users (i.e., users who log in without SSO to your SSO-enabled organization).
Please note that there is no way to revert the changes that were overridden by your IdP roles. The roles that were assigned to users prior to enabling IdP Role Mapping are erased.
What happens to user roles when I disable IdP Role Mapping for my SSO-enabled organization?
If IdP Role Mapping is disabled, Contentstack no longer honors roles (and permissions) returned by your IdP. There are, however, no changes to the existing permissions of the users in Contentstack. Users continue to maintain the permissions that they had.
However, subsequent to disabling IdP Role Mapping, role management can be done only through Contentsatack’s Users and Roles settings.