This step-by-step guide explains how to set up Single Sign-On in Contentstack with Azure Active Directory (AD) as your SAML 2.0 Identity Provider (IdP).
In a nutshell, this integration requires four steps:
- Create SSO Name and ACS URL in Contentstack
- Configure Contentstack App in Azure AD
- Configure Azure AD details in Contentstack
Let’s see each of the processes in detail.
Step 1 - Create SSO Name and ACS URL in Contentstack
- Log in to your Contentstack account. Go to the ‘Organization Settings’ page and click on the ‘Single Sign-On’ tab.
- 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 Azure AD.
Keep this window open, as you may need these details for setting up Contentstack app in Azure AD.
Step 2 - Configure Contentstack App in Azure AD
Note: You need to be an Azure AD administrator to complete the below steps.
- To configure the integration of Contentstack into Azure AD, you need to add the Contentstack app. Go to the Azure portal, and click on the ‘Azure Active Directory’ tab on the left navigation panel.
- Click on ‘Enterprise Applications’, and click on ‘+ New application’ on the top.
- Click on ‘Non-gallery application’. This will allow you to create a new application that is not already present in the gallery.
- Provide a name to your app, for example, ‘test-sso’. Click on ‘Add’.
- This will lead you to the ‘Quick start’ page that will lead you to the further steps that you can perform after creating your app. The steps include assigning users to your app, creating a test user for testing your app, configuring our app to use Azure AD as identity provider, and so on.
- Now, click on ‘Properties’ on the left navigation panel. Here, you can enable the application for users to sign in, and provide your application a name and a logo.
You will see the ‘User access URL’ field which holds the Single Sign-On URL that you will need when configuring Azure details in Contentstack.
- Next, you need to enable Azure AD single sign-on in the Azure portal and configure single sign-on in your Contentstack application. Click on ‘Single sign-on’ in the left navigation panel.
- Select ‘Single Sign-on Mode’ as ‘SAML-based Sign-on. This will enable single sign-on.
On the ‘test-sso Domain and URLs’ section, add the details given below:
On the ‘User Attributes’ section, select ‘user.userprincipalname’ for ‘User Identifier’.
- In the ‘Identifier’ textbox, enter the ‘Entity ID’ of Contentstack, i.e., https://app.contentstack.com.
- In the ‘Reply URL’ textbox, enter the ACS URL that we generated in step 2.c.
- Now, you need to add attributes. Click ‘Add attribute’. Enter ‘first_name’ as the ‘Name’ and the select the ‘Value’ as ‘user.givenname’ from the dropdown. Click ‘Ok’. You will see the new attribute in the ‘SAML Token Attributes’ table.
Similarly, add two more attributes, ‘last_name’ and ‘email’. For ‘last_name’ assign ‘Value’ as ‘user.surname’, and for ‘email’ assign the ‘Value’ as ‘user.userprincipalname’.
- Under ‘SAML Signing Certificate’ section, click ‘Certificate (Base64)’ under the ‘DOWNLOAD’ column. This will download the Base64 version of the certificate for your Contentstack app. Save the certificate file on your computer.
- Provide the notification email and click on ‘Save’. Click on the ‘Configure test-sso’ tab that you see at the bottom of the page to open the ‘Configure sign-on’ window where you will find further details that will be useful in setting up your Azure AD details in Contentstack.
Step 3 - Configure Azure AD details in Contentstack
- The ‘Configure sign-on’ window holds data, such as SAML SSO URL, SAML Entity ID, and Sign-Out URL of Azure AD. This data is required when configuring Azure AD details in Contentstack.
- Copy the URL provided in the ‘SAML Single Sign-On’ section of your Contentstack application in Azure AD and paste it into the 'Single Sign-On URL' field in Contentstack IdP configuration section.
- Upload the X.509 certificate that you downloaded from Azure AD into the ‘Certificate’ field in Contentstack SSO Settings.
With this, you are done with setting up the new Contentstack app in Okta. Proceed to configuring the remaining steps in Contentstack SSO.
In Contentstack, save your settings and go to ‘3. User Management’.
Enable Strict Mode if you do not want any users to access the organization without SSO login. Learn More.
Session Timeout lets you define the session duration for a user signed in through SSO. While the default is set to 12 hours, you can modify it as per your requirement. Learn more.
Test & Enable
Go to '4. Test & Enable' in Contentstack.
Click the Test SSO button to check if your SSO settings have been configured properly. It is highly recommended that you test your settings before enabling SSO. Learn more.
To enable SSO for your Contentstack organization, click on Enable SSO. Once this is enabled, users of this organization can access the organization through SSO. You can then disable SSO from the same page when required. Learn more.