Set Up SSO in Contentstack

This guide explains how to set up single sign-on (SSO) in Contentstack with any Security Assertion Markup Language 2.0 (SAML 2.0) identity provider (IdP).

Note: SSO can be configured by the organization owner, a security manager, or a user with a custom role that has SSO write permissions.

You can attach more than one IdP to an organization. Each IdP is a separate connection with its own configuration, and you can add up to five. This guide walks through a single connection. To add and organize multiple connections, refer to Configure Multiple Identity Providers.

Prerequisites

To enable SSO for your organization, you need the following:

• Access to your identity provider's configuration settings.
• The organization owner role, a security manager role, or a custom role with SSO write permissions in your Contentstack organization.

Overview

Setting up SSO takes five steps:

1. Create a connection in Contentstack
2. Set up the Contentstack app in your IdP
3. Configure IdP details in Contentstack
4. Manage users in Contentstack
5. Test and enable SSO

Step 1: Create a Connection in Contentstack

1. Sign in to your Contentstack account, open the App Switcher, go to Administration, and then click Single Sign-On.

   

2. Add a connection to open the New Connection dialog, and enter the following details:

   • Connection Name: A friendly name shown across SSO surfaces, up to 128 characters. It does not affect login URLs. For example, "Acme Employees."
   • SSO ID: The unique identifier for your SSO-enabled organization. Contentstack auto-generates it from the connection name, and you can edit it before you create the connection. Users enter it as one of the login parameters once SSO is enabled.
   • Description (optional): Context about this connection, up to 400 characters.

   Note: The SSO ID can contain only lowercase letters, numbers (0-9), and hyphens (-). You cannot change the SSO ID after you create the connection.

   

3. Click Create.

Contentstack opens the connection at 1. SSO Configuration and generates the Assertion Consumer Service (ACS) URL, along with other read-only details such as Entity ID, SAML Version, Attributes, and NameID Format. You need these details in Step 2. Keep this window open.

Tip: Instead of copying the ACS URL and Entity ID individually, share Contentstack's service provider (SP) metadata with your IdP team in one step. Use Download Metadata XML. If you enable SAML encryption on this connection, the downloaded metadata also carries the public certificate your IdP uses to encrypt assertions. You can download that certificate on its own from the Contentstack public certificate link. For details, refer to Download Contentstack (SP) Metadata.

Step 2: Set Up the Contentstack App in Your IdP

1. Sign in to your IdP admin account.

2. Create a new application (also called an app or connector in some IdPs). Name it "Contentstack."

3. In the SAML settings, enter the SSO configuration details from Step 1:

   • Single Sign-On URL: The ACS URL generated for your organization in Contentstack.
   • Audience URI, SP Entity ID, or SAML Issuer ID: Contentstack's Entity ID from Step 1.
   • NameID Format: Select or enter EmailAddress. This defines the parameter your IdP uses to identify Contentstack users.
   • (Optional) To encrypt SAML attributes, enable SAML encryption in your IdP and upload the Contentstack public certificate.

   Tip: If your IdP supports importing SP metadata, import the Contentstack metadata URL or XML file instead of entering these fields by hand. Refer to Download Contentstack (SP) Metadata.

4. Under Attribute Mapping or Attribute Statements, add three attributes, email, first_name, and last_name, and map them to the corresponding IdP values.

   Note: The name format for these attributes must be "Basic." The Unspecified format and other formats do not work.

5. (Optional) To map IdP groups or roles to Contentstack roles, add a roles attribute under Attribute Mapping that returns your IdP users' roles or groups.

   Note: Perform this step only if IdP Role Mapping is part of your Contentstack plan.

6. Save your settings. Your IdP returns an IdP Single Sign-On URL and an X.509 certificate. You need these in Step 3.

Step 3: Configure IdP Details in Contentstack

Go to 2. IdP Configuration in Contentstack. You can provide your IdP's details in one of three ways. Choose the one that matches your IdP's capabilities and your network environment:

• Metadata URL: Enter your IdP's metadata endpoint and click Fetch. Contentstack retrieves and parses the details. This is the fastest path for IdPs that expose a live metadata URL, such as Okta, Microsoft Entra ID, OneLogin, and Ping Identity.
• Metadata XML: Upload your IdP's metadata file. Use this for IdPs that do not expose a URL, such as on-premises Active Directory Federation Services (AD FS) and some legacy IdPs, or when network rules prevent Contentstack from reaching the URL.
• Manual entry: Enter each field by hand. Use this for IdPs that do not provide structured metadata.

Tip: Importing metadata auto-populates the Single Sign-On URL, certificate, and related fields, which reduces manual entry and errors. For the full procedure and error handling, refer to Import IdP Metadata.

To enter the details manually:

1. In the Single Sign-On URL field, paste the IdP Single Sign-On URL from Step 2. The URL must use HTTPS.

2. In the Certificate field, upload the X.509 certificate from Step 2.

   Warning: A connection stores one signing certificate. Contentstack shows its expiry date next to the field. When your IdP switches to a new signing certificate, every SAML assertion arrives signed by a certificate Contentstack does not recognize, and sign-in through this connection fails until you upload the new certificate here. Coordinate the replacement with the switch on the IdP side rather than waiting for the current certificate to expire.

3. Under Signature Algorithm, select the algorithm your IdP uses. Available options are, SHA-1, SHA-256, and SHA-512.

4. (Optional) Turn on SAML encryption to encrypt your SAML attributes.

5. Click Save.

Tip: In some IdPs, you assign the new Contentstack application to your users. You find these settings under the Users section in your IdP.

Note: The organization owner can always sign in with Contentstack credentials, regardless of SSO status (enabled, disabled, misconfigured, or strict mode). If SSO login fails after a certificate update, the owner can sign back in and restore the previous configuration.

Step 4: Manage Users in Contentstack

Go to 3. User Management to define how users access your SSO-enabled organization. This step covers Strict Mode, User Email Whitelists, Session Time-Out, and Advanced Settings.

Strict Mode

Strict mode controls whether users who are not in your IdP can access the organization.

• Enabled: Users can access the organization only through SSO. Users who are not in your IdP cannot sign in.
• Disabled: Users marked Allow access without SSO in the organization's user settings can sign in with Contentstack credentials. This works like an exception list.

Note: In an organization with multiple connections, strict mode is set per connection but takes effect across the whole organization. If any enabled connection has strict mode on, the entire organization is SSO-only. Disabling a connection that has strict mode on removes strict mode for the organization, because a disabled connection does not contribute to the organization's strict state.

To let specific users sign in without SSO:

1. Disable Strict Mode in the User Management step.
2. Go to Users in your organization settings.
3. Click Invite User, select Allow Access Without SSO, and enter the user's details.
4. Click Invite.

User Email Whitelists

The User Email Whitelists setting lets specified users access APIs even when strict mode is enabled. It is organization-scoped, not connection-scoped, and applies only when strict mode is enabled. Enter up to 100 email addresses, separated by commas (for example, user1@example.com, user2@example.com). Each address must belong to an accepted, non-owner member of the organization.

In a multi-connection organization, this field appears only under the User Management tab of the connection that has strict mode enabled. It does not appear on the other connections.

Note: Because any one strict connection makes the whole organization SSO-only, only one connection can hold the strict mode toggle at a time. Enabling strict mode on one connection automatically disables the strict mode toggle on every other connection.

Note: This is a plan-based feature. For access, contact our support team.

Session Time-Out

Set how long an SSO session lasts. The default is 12 hours, and you can set any value between 1 and 24 hours. The session begins when the user signs in through SSO and ends when the timeout period elapses.

Advanced Settings

Advanced Settings contains IdP Role Mapping, which assigns Contentstack roles to the users of a group or role in your IdP.

Note: IdP Role Mapping is available only if it is part of your Contentstack plan. The Role Mapping section appears under Advanced Settings only when the feature is included. To add it to your plan, contact our Support team.

Before you add role mappings, add the roles attribute in your IdP, as described in Step 2.

To add a role mapping, click Add Role Mapping, and enter the following:

• IdP Role Identifier: The name or UID of the IdP group you want to map. For example, "Contentstack Developers."
• Assign Product Roles: Assign Contentstack roles per product. For each product, such as CMS, Personalize, Agent OS, and Administration, click Manage Roles and select the roles this IdP group receives.

For the Administration product, at least one role is required. The Member role is selected by default and grants read-only access to organization information. Change it only when the group needs elevated access. The Administration roles include:

• Admin: Full administrative access across the organization, including users, roles, and settings.
• Security Manager: Manages organization security settings, SSO, System for Cross-domain Identity Management (SCIM), user access, and related configuration.
• Product Analytics Viewer: Access to the Analytics application.
• Member: Read-only access to organization information.

Note: The available products and roles depend on your Contentstack plan and the applications enabled for your organization, so your list may differ from these examples.

Next, set the following and save:

• Role Delimiter: The character your IdP uses to separate roles in the assertion, such as a comma, semicolon, or space.
• Enable IdP Role Mapping: Select this checkbox to turn on the feature.

Warning: Once IdP Role Mapping is on, a user whose assertion carries no role matching any mapping is denied sign-in through this connection. Organization owners are exempt, so a successful test as the owner does not prove that other users can sign in. Before you enable it, confirm that every group you expect to sign in has a matching mapping and that the Role Delimiter matches what your IdP sends.

A connection holds up to 200 role mappings.

Note: After you enable IdP Role Mapping, role management for your IdP users is handled from your IdP, not from Contentstack. In an organization with multiple connections, role mapping is configured per connection, and the roles applied come from the connection the user signs in through. For how IdP Role Mapping interacts with SCIM provisioning, refer to IdP Role Mapping.

Step 5: Test and Enable SSO

In this final step, you verify the connection works and then turn SSO on for your organization. You can also disable SSO here later.

Test SSO

Test the connection before you enable it:

1. Click Test SSO. Contentstack opens the Login via SSO page.
2. Enter your organization's SSO ID, and click Continue to open your IdP sign-in page.
3. Sign in. If you reach your IdP and sign in, the test succeeds and Contentstack shows a success message.

[Screenshot: A successful SSO test]

If IdP Role Mapping is enabled, the result page also shows:

• SSO connection established successfully: A success message.
• IdP Roles received: The roles assigned to you in your IdP.
• Contentstack-IdP role mapping details: The Contentstack roles mapped to your IdP roles.

Note: When you test with IdP Role Mapping enabled, the test evaluates only the IdP roles of the user performing the test.

Enable SSO

Click Enable SSO. Once enabled, users can access the organization through SSO. You can disable SSO from the same page at any time.

[Screenshot: The Enable SSO confirmation]

After you enable SSO, the SSO One-Click URL appears at the top of the SSO page. Bookmark it to go straight to your organization's SSO login page.

Note: If you are already signed in to your IdP, the trigger_sso_flow=<sso_id> query parameter signs you in to Contentstack through SSO and skips the Contentstack login page.

Note: If IdP Role Mapping is disabled, only users invited to the organization can access it. IdP users who have not been invited cannot sign in.

Disable SSO

After you enable SSO, the 4. Test & Enable SSO tab becomes 4. Disable SSO. Click Disable to turn SSO off.

Once SSO is disabled, existing users sign in with Contentstack credentials. A user without Contentstack credentials uses the Forgot password link on the login page to set a password.

Additional Resource: To add more identity providers, refer to Configure Multiple Identity Providers. To manage connections from the Connections list, refer to Manage SSO Connections.