This step-by-step guide explains how to set up Single Sign-On in Contentstack with Okta as your SAML 2.0 identity Provider (IdP).
The integration with Okta can be done in four easy steps:
- Create SSO Name and ACS URL in Contentstack
- Configure Contentstack App in Okta
- Configure Okta details in Contentstack
- Manage users access control in Okta
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 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 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 Okta.
Keep this window open, as you may need these details for setting up Contentstack app in Okta.
Step 2 - Configure Contentstack App in Okta
- Log in to your Okta Admin account.
- After logging in, you will see the Okta dashboard. Click on the ‘Application’ tab and select ‘Applications’.
- In the ‘Applications’ page, you will see your already created applications, if any.
- Click on the ‘Add Application’ button to create a new application for Contentstack.
- Set the platform as ‘Web’ and the Sign on method as ‘SAML 2.0’. Click on ‘Create’ to create your application:
- You will be redirected to the ‘General Settings’ page of your application. Provide a name for your application, e.g., ‘Contentstack’, and a logo for your application, and click on ‘Next’ to proceed to configure SAML settings.
- In ‘SAML Settings’, under ‘Configure SAML’, the first field is to set the ‘Single sign-on URL’ field. Here, you need to paste the Assertion Consumer URL that we create in Contentstack in Step 1.c.
In the ‘Audience URI (SP Entity ID)’ field, enter Contentstack’s ‘Entity ID’ that you received in step 1. In most cases, this value would be https://app.contentstack.com. Do not enter any value in the ‘Default RelayState’ field. Select ‘EmailAddress’ in the ‘Name ID format’ field, as we saw in Step 1.d. Choose ‘Email’ in the ‘Application username’ field.
- Click on the Advanced Settings link and in the ‘SAML Issuer ID’, enter the value that you received in ‘Entity ID’ in Contentstack. In most cases, this value would be https://app.contentstack.com.
- Then, in ‘Attribute Statements’, under attribute mapping details, add the attributes received in Step 1.
- Add three attributes: email, first_name, and last_name under ‘Name’, and select ‘user.email’, ‘user.firstname’, and ‘user.lastname’, respectively, under ‘Value’.
- Click ‘Next’ and then ‘Finish’ on the next screen.
Step 3 - Configuring Okta details in Contentstack
- In Okta, click on the ‘Sign On’ tab of the application that you created in Step 2.
- Click on ‘View Setup Instructions’ to get additional settings fields for your Contentstack application. Also, download the X.509 certificate.
- Copy ‘Identity Provider Single Sign-On URL’. Then, in Contentstack SSO settings page, go the ‘2. IdP Configuration’, and paste the URL in the ‘Single Sign-on URL’ field.
- Upload the X.509 certificate that you downloaded in Contentstack in the ‘Certificate’ field.
Now, let’s learn how to assign your Contentstack application to your users in Okta.
Step 4 - Manage users access control in Okta
After setting the necessary configurations in Contentstack, you need to now assign the newly added application to your users.
- Go to the ‘Assignments’ tab of your application and click on ‘People’ in application details section.
- Click on ‘Assign’ to get a list of registered users to whom you need to assign your application.
- Also, you may use multiple applications assignment available in ‘Applications’ > ‘Assign applications’ menu.
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.