Set up SSO with Active Directory Federation Services (AD FS)

This step-by-step guide explains how to set up single sign-on (SSO) in Contentstack with AD FS as your SAML 2.0 identity provider (IdP). You create a connection in Contentstack, configure a Relying Party Trust on Windows Server, define claim rules, export the token-signing certificate, and then configure and enable the connection in Contentstack.

You can attach up to five SAML 2.0 IdPs to a single Contentstack organization. Each IdP is a separate connection with its own certificate, session policy, role mapping, and login URL, which is useful when an on-premises AD FS population and a cloud IdP population share one organization. This guide walks through one connection. To add and organize more connections, refer to Configure Multiple Identity Providers.

Note: This guide covers SAML 2.0 SSO setup using Windows Server 2012 R2 Standard (Windows Server 2008 R2 is supported too, but requires additional setup), with AD FS 2.0 as the identity provider.

Prerequisites

• Contentstack account
• AD FS administrator access to a Windows Server
• An AD FS token-signing certificate
• The organization owner role, a security manager role, or a custom role with SSO write permissions in your Contentstack organization

What You Will Learn

• How to create a connection and generate the ACS URL in Contentstack.
• How to configure a Relying Party Trust for Contentstack on Windows Server.
• How to define claim rules and export the token-signing certificate.
• How to configure AD FS details in Contentstack, by metadata XML or manually, and enable the connection.

Steps to Set up SSO with AD FS

1. Create a Connection in Contentstack
2. Configure Windows Server
3. Edit Claim Rules for your AD FS App
4. Configure AD FS details in Contentstack

Let's go into each of the processes in detail.

1. Create a Connection in Contentstack

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

   1. Log 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. It does not affect login URLs. For example, "Acme Corporate AD."
      • SSO ID: The unique identifier for this connection. 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. SSO IDs are unique across all Contentstack organizations, so a name already in use elsewhere is rejected.

      Let's use "sso-test" as the SSO ID.

      

      

   3. Click Create.

      

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

   Note: The ACS URL contains this connection's SSO ID, so every connection in your organization has its own ACS URL. Use the ACS URL of the connection you are configuring, and enter it in the Relying Party Trust for that connection.

   

   Tip: Instead of copying the ACS URL and Entity ID individually, share Contentstack's service provider (SP) metadata with your AD FS administrator in one step. Use Download Metadata XML on the 1. SSO Configuration step. 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. AD FS can import SP metadata from a file when you add the Relying Party Trust. For details, refer to Download Contentstack (SP) Metadata.

2. Configure Windows Server

   1. Open the AD FS Management Console.

      

   2. Define a Relying Party Trust (RPT), which serves as the connection between AD FS and Contentstack. Click Add Relying Party Trust from the Actions sidebar on the right. This opens the Add Relying Party Trust Wizard. Click Start.

      

   3. Select a data source. Choose Enter data about the relying party manually, and click Next.

      Tip: If you downloaded Contentstack's SP metadata in Step 1, choose Import data about the relying party from a file instead, and select the downloaded XML. AD FS fills in the ACS URL and identifier for you.

      

   4. Enter a name for your relying party, for example, "ms-adfs-test."

      Tip: In an organization with more than one connection, name each Relying Party Trust after the Contentstack connection it serves, so the trust-to-connection pairing stays clear.

      

   5. To choose a profile, click AD FS profile. This profile supports relying parties that are interoperable with the SAML 2.0 protocol. Then click Next.

      

   6. You can skip the Configure Certificate step, as it is not required. Click Next.

      

   7. In Configure URL, select Enable support for the SAML 2.0 WebSSO protocol, and enter the Assertion Consumer Service URL generated for this connection in Step 1.c. Click Next.

      Warning: Do not add a slash "/" at the end of the identifier, otherwise this integration will not work.

      

   8. In the Configure Identifiers section, enter the Entity Identifier URL (without a trailing slash) generated in Contentstack, and click Add. After adding it, click Next.

      

   9. Click the I do not want to configure multi-factor authentication settings for this relying party trust at this time radio button in the Configure Multi-factor Authentication Now? section, and click Next.

      

   10. In the Choose Issuance Authorization Rules section, select Permit all users to access this relying party to allow all Active Directory users to sign in to Contentstack, and click Next.

       Note: Permit only the users who authenticate through this connection. In an organization with more than one connection, a user is identified by email address across every IdP, and the same email cannot map to different users in different IdPs.

       

   11. The Ready to Add Trust section displays the configuration you set. Do not change any setting, and click Next.

       

   12. You have successfully configured the Relying Party Trust. Leave the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes option checked to set up the claim rules.

   13. Click Close to close the wizard.

       

   As soon as you have configured Windows Server, the Edit Claim Rules for app_name window opens. Let us see how to set up claim rules in the next step.

3. Edit Claim Rules for your AD FS App

   1. In the Edit Claim Rules for ms-adfs-test window, click Add Rule under the Issuance Transform Rules tab.

      

   2. In the Add Transform Claim Rule Wizard window, select Send LDAP Attributes as Claims as the Claim rule template, and click Next.

      

   3. Enter a name for your claim rule, for example, "email," then set Attribute store to Active Directory.

   4. Enter the LDAP attributes. Enter E-Mail-Addresses twice and set the outgoing types to E-Mail Address and email. Similarly, enter Given-Name twice with outgoing types Given-Name and first_name, and enter Surname twice with outgoing types Surname and last_name.

      Note: Every attribute is entered twice in order to provide a user-specific claim type (that is, email, first_name, and last_name).

      

   5. Click OK when you are done adding the required LDAP attributes.

      Warning: Make sure you select accurate options, because the integration may not work if the variant you select does not match.

      

   6. Add another claim rule. Click Add Rule on the Issuance Transform Rules tab, select Transform an Incoming Claim, and click Next.

      

   7. Enter a claim rule name, for example, Incoming-claim, set Incoming claim type to E-Mail Address, set Outgoing claim type to Name ID, and set Outgoing name ID format to Email.

   8. Select Pass through all claim values and click Finish.

      

   9. In the Edit Claim Rules window, click OK.

   10. Click Service > Certificates, select your token-signing certificate, and click View Certificate… in the Actions pane.

       

   11. Click the Details tab and click Copy to File…. This opens the Certificate Export Wizard. Click Next.

       

       

   12. Select Base-64 encoded X.509 (.CER) as the format of your certificate, and click Next.

       

   13. Click Browse, choose a location to save the certificate file, click Next, and then click Finish and OK.

       

   14. On your AD FS server, click Service > Endpoints, and locate the endpoint URL path for the SAML 2.0 specification. You will use this when configuring AD FS details in Contentstack.

       Tip: If you plan to import IdP metadata into Contentstack instead of entering details by hand, also save your AD FS federation metadata file, which is usually available at https://<your-adfs-server>/FederationMetadata/2007-06/FederationMetadata.xml.

       

4. Configure AD FS details in Contentstack

   Go to 2. IdP Configuration for this connection in Contentstack. You can provide AD FS details in one of the following ways:

   • Metadata XML: Upload the AD FS federation metadata file. This is the recommended path for AD FS, because AD FS endpoints are usually on-premises or firewalled, so the browser cannot reach them directly to fetch a metadata URL.
   • Manual entry: Enter the single sign-on URL and certificate by hand, as described below.

   Tip: Importing metadata auto-populates the Single Sign-On URL, certificate, and related fields, which reduces manual entry and errors. Signature algorithm and SAML encryption are not part of IdP metadata, so you always set those by hand. For the full procedure and error handling, refer to Import IdP Metadata.

   To enter the details manually:

   1. Enter the single sign-on login URL of your AD FS service into the Single Sign-On URL field. This is generally the URL of your AD FS service followed by the suffix "/adfs/ls/".

      

   2. Upload the certificate you exported in Step 3 into the Certificate field.

      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 AD FS server uses. Available options are SHA-1, SHA-256, and SHA-512.

      Note: The Single Sign-On URL must use HTTPS.

   4. (Optional) Turn on SAML encryption to encrypt your SAML attributes. SAML encryption is configured per connection.

   5. Click Save.

   Note: The organization owner can always sign in with Contentstack credentials, regardless of SSO status. If SSO login fails after a certificate update, the owner can sign back in and restore the previous configuration.

Further Steps

User Management

In Contentstack, save your settings and go to 3. User Management for this connection.

• Strict Mode: Enable Strict Mode if you do not want any user to access the organization without SSO login.

Note: Strict mode is set per connection, but it takes effect across the whole organization. If any enabled connection has strict mode on, the entire organization is SSO-only. Because of this, only one connection can hold the strict mode toggle at a time, and enabling strict mode on one connection disables the toggle on the others. 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.

• User Email Whitelists: Lets specified users access APIs even when strict mode is enabled. This setting is organization-scoped and applies only when strict mode is enabled, so the field appears only under the User Management step of the connection that has strict mode 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.

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

• Session Time-Out: Session Time-Out lets you define the session duration for a user signed in through this connection. The default is 12 hours, and you can set any value between 1 and 24 hours. This setting applies per connection, so an AD FS connection can use a different session length from your other connections.

Note: IdP Role Mapping is not yet available for AD FS. To know how it works, refer to IdP Role Mapping.

Test & Enable

Go to 4. Test & Enable for this connection in Contentstack.

Click Test SSO to check that your settings are configured properly. On the Login via SSO page, specify this connection's SSO ID. It is highly recommended that you test your settings before enabling the connection.

To enable SSO for your Contentstack organization, click Enable SSO. Once enabled, users can access the organization through this connection.

You can disable the connection anytime from the same page.

For the full set of connection actions, refer to Manage SSO Connections.

Additional Resource: To add more identity providers, refer to Configure Multiple Identity Providers. To upload your AD FS federation metadata instead of entering details by hand, refer to Import IdP Metadata.