Single Sign-On (SSO)

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.

Overview

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.

how_sso_works_with_contentstack.jpeg

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. 

Prerequisites

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

  1. 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.
    01.png
  2. Enter an SSO name of your choice, and click Create. For example, if you're 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 (-).
    02.png
    Let's use 'test-sso' as the SSO Name.
  3. 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.
    03.png
    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

  1. Login to your IdP admin account.
  2. Create a new application (also known as app or connector in some IdPs) with application name preferably as ‘Contentstack’.
  3. 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.
  4. 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.
    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

  1. Go to 2. IdP Configuration in Contentstack.
  2. In the Single Sign-On URL field, paste the IdP Single Sign-On URL that you received from IdP in Step 2.
  3. In the Certificate field in Contentstack, upload the X.509 or Public Key Certificate that you received from your IdP.
  4. Select relevant algorithm from the options given under the Signature Algorithm field.
  5. Click Save to save IdP configuration.

04.png

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.

Strict Mode

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: 

  1. Disable Strict Mode in the User Management step in SSO settings.
  2. Go to Users in Organization settings. 
  3. Click on Invite User. On the modal that appears, check Allow Access Without SSO, and enter user details.
  4. Click Invite.

Session Timeout

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

05.png

Step 5 - Test and Enable SSO

Test SSO

Before enabling SSO, it is recommended that you test the SSO settings configured so far. Clicking on the Test link 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. If you are able to sign in to your IdP, you test is successful. You can then enable SSO for your organization.

06.png

Enable SSO

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.

07.png

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.

08.png

Note: Only the users invited to the SSO-enabled organization can access the organization. Your IdP users cannot directly access the organization if they have not been invited to this organization.

Disable SSO

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.

09.png

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 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 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.

Common Questions

  • 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.
  • 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 ccess 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 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 user’s email address. The user needs to follow the instruction in the email and login to their Contentstack account.
Was this article helpful?
top-arrow