Skip to main content

Integrate with an identity provider and log in with SAML SSO

Configure SAML SSO to let your team log in to Intercom using your identity provider like Okta or OneLogin.

Written by Eric Fitzgerald
Updated over a week ago

Integrating Intercom with your identity provider (IdP) makes logging in simple and secure for your team.

Follow the steps in this article to configure your identity provider, to require SAML SSO (Single Sign On) from all your teammates, or to offer it as one of your sign in options. Once configured, SAML SSO will also work with the Intercom Conversations app.

Before you start

Important:

  • SAML SSO is only available on certain Intercom plans. Check our plans and pricing to see if this is included in your subscription.

  • You must have permissions to access Settings > Workspace > Security in Intercom, as well as administrative access to your identity provider.

Step 1: Enable SAML SSO in Intercom

First, you need to enable SAML SSO in your Intercom workspace to get the URLs for your identity provider.

  1. Go to Settings > Workspace > Security > Authentication methods

  2. Toggle on SAML SSO.

  3. Once toggled on, the SAML SSO configuration section will appear.

  4. The first thing you’ll see is the unique SAML URL for your workspace. Keep this page open; you will need this URL for the next step.

Step 2: Configure your identity provider

In your identity provider's settings (like Okta or OneLogin), you will need to add Intercom as an application. You will need the SAML URL from Step 1.

Use the following parameters in your IdP's configuration:

  • Single Sign-On URL: <SAML URL>/consume

  • Recipient URL: <SAML URL>/consume

  • Audience restriction/Entity ID: <SAML URL>

  • NameID: Email address

  • Signed Assertions: Yes

  • Mapped Attributes:

    • firstName (User's first name)

    • lastName (User's last name)

  • Encryption: AES256_CBC with this certificate:

-----BEGIN CERTIFICATE-----
MIIDYzCCAkugAwIBAgIUS9LFUH5IWanIgQ78d/qyKOdojAYwDQYJKoZIhvcNAQEL
BQAwQTERMA8GA1UECgwISW50ZXJjb20xETAPBgNVBAsMCFBsYXRmb3JtMRkwFwYD
VQQDDBBTQU1MIENlcnRpZmljYXRlMB4XDTI2MDExMjE3NTIzN1oXDTM2MDExMDE3
NTIzN1owQTERMA8GA1UECgwISW50ZXJjb20xETAPBgNVBAsMCFBsYXRmb3JtMRkw
FwYDVQQDDBBTQU1MIENlcnRpZmljYXRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
MIIBCgKCAQEA2LVcYLNwR0t1Co/FBNSFUEdpOJTM87X0//NPisUgQJ71l11Dohg9
Yg1aAraqOsQ9EPR9prdQjP50lhOmogjvPDClPlXtoHdRCJ81U/3duXoBdGS02NN3
2DetudNnyjeUefkcnPWsQ+FNZasnP9ODU8dtPKxMcLP3AmcUYOAaKp1r3WBuFDcT
woMtbrWUoxTfBeYx6nQ9TfzJOGQFZCYs30Sx1j5LVio5DoM3oynTTh0qOzJS+KpU
iIIqby8szpqWMfdPNTdBd7XQK2SkHmBgkgSDfQIII93kkXCP1bCOuo4rC+lIeXlF
gIi2Z4iMxuKceBeLBgFTovG7dVDeGmTucQIDAQABo1MwUTAdBgNVHQ4EFgQUgZdt
wisFHetsCww03EXQGt8Oq24wHwYDVR0jBBgwFoAUgZdtwisFHetsCww03EXQGt8O
q24wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAiL3wXWof5x+k
thOn2tAspFR/IH5NQHPLocV605FcRjt1JS1z0cBjtBroTKFarXo6T1NKQN5Lhjsu
wrvu1J/YQcGnSmChar8OJSIbxPhHrbpA6Gg2mtkH4BTnnXY3LBgVFfCl5oiFxZqB
ELkm6iBZmReot+MPWvE0Ypx7hQLI/3qLc5yYEw7ZNKWq/lRbbT4DLgKeHH89fSrm
cpDa9ZHF2e6rlx95LCbZUWyEE6pPFeq+6CyQt+FkwLl1e+ZIJTknWgD/bzPsZ6CF
XfF2fS2ObaUISKYEZMZx5o+JZnnYGr1U614lhniha+Rpykzoa+SsOdwvI0xl5ZRr
aqD3fI3jqA==
-----END CERTIFICATE-----

Note: If your identity provider supports it, you can define a session duration in your IdP's configuration. This sets the length of time before a teammate's session expires and they must log in to Intercom again. If this is not set, the default duration is 3.5 days.

Step 3: Configure Intercom with your IdP's details

After configuring your IdP, you must add its details back into Intercom.

  1. Return to your Intercom SAML SSO settings page (Settings > Workspace > Security).

  2. Add the following information from your identity provider:

    • Identity provider Single Sign-On URL: This is the URL used to start the login process.

    • Public certificate: This allows Intercom to validate SAML requests from your IdP. It must be an X.509 certificate.

Step 4: Add and verify your allowed domains

You must specify which domains are allowed to authenticate with SAML SSO.

  1. Enter a domain under "Allowed domains" and click Add domain.

  2. You must verify that you own the domain by adding a TXT record in your DNS settings with the provided values.

  3. After adding the TXT record, click Verify DNS record.

  4. Once verified, you’ll see a success message and the domain will be added. Repeat this process if you need to add more than one domain.

Note: If you have just created the DNS record, it may still be propagating. If you see a warning message ("Unable to verify DNS record. Please try again later."), wait a few minutes (or up to a few hours) and try again.

To uncheck this option and enforce SAML SSO as the required login method, you must be logged in with SAML SSO. You can do this after saving your settings.

Step 5: Test and enforce SAML SSO

Before enforcing SAML for all teammates, you must test the configuration.

  1. Test your setup: To ensure all teammates can log in successfully with SAML SSO before disabling other methods, leave the Google Sign-On and Email and password options toggled on.

  2. Save your settings at the bottom of the page.

  3. Log out and attempt to log back in using the Sign in with SAML SSO option to test your configuration.

  4. Enforce SAML SSO (Optional): Once you have successfully logged in and confirmed the setup works, you can return to the settings and uncheck the other login methods.

Note:

  • To uncheck the other login options and enforce SAML SSO as the only login method, you must be logged in with SAML SSO yourself.

  • Once your workspace has SAML SSO enabled, teammates will be unable to edit their own email address from their Account security page. The email field will be read-only.

How SAML SSO works for your team

How teammates log in

Once SAML SSO is enabled, teammates will see a Sign in with SAML SSO button on the login page. The login experience will vary based on their email address:

  • Email not registered: If the email entered doesn't match a teammate in a workspace with SAML enabled, they will see an error message.

  • Email registered for one SAML workspace: The teammate is redirected to the identity provider to log in.

  • Email registered for multiple SAML workspaces: The teammate is shown the workspace selector. After selecting a workspace, they are redirected to the correct identity provider for that workspace.

Depending on the identity provider the teammate has for each workspace, the teammate is redirected to the right identity provider's login experience. After performing the log in, the user is brought back to the correct workspace and logged in.

Switching between workspaces

SAML SSO is supported when switching between workspaces:

  • If a teammate is logged into two workspaces that use the same SAML SSO provider, they can switch between them without needing to re-authenticate.

  • If the teammate has access to a third workspace that uses email/password, and they aren't logged in, they will be redirected to the workspace switcher to log in with their password.

Logging in on the mobile app (Intercom Conversations app)

SAML SSO is supported on the iOS and Android Intercom Conversations app.

  1. Navigate to the log in screen and tap the Sign in with SAML SSO button.

  2. Enter your work email and tap Continue.

  3. If you have access to multiple workspaces, you will see a list to choose from. (If you only have one, this screen is skipped).

  4. Selecting a workspace will open a web view to log in to your SAML provider.

  5. Once you sign in, you will be logged into the app.

If you don’t have SAML SSO set up for your account and try to log in with SAML SSO, you'll see an error message.

Workspace invites

SAML SSO is compatible with workspace invites. When a teammate redeems an invite, the invite email must match the email returned by the identity provider, or the invite will fail.

How to change the email addresses of teammate/admin profiles if the Workspace has SAML SSO enabled

1. Admin should enables "Email and password" as a login method, if not already enabled.

2. All teammates set/reset their Intercom password and confirm they can log in with their old email + password.

3. Admin disables SAML SSO on the workspace (this makes the email field editable for teammates).

4. Each teammate logs in with their old email + password and individually updates their own login email to the new domain.

5. Admin updates users' emails in the IdP to the new domain.

6. Admin re-enables SAML SSO on the workspace.

7. SSO now works with the new emails. Admin may optionally re-enforce SSO-only login.

IdP-specific guides and troubleshooting

Troubleshooting Google Workspace

If you are using Google Workspace as your SSO provider and see an access error, you can turn on "remediation messages" in your Google Admin console to understand the reason for the error. Once enabled, you'll see more detailed information in the error message (e.g., "the device... is not managed by Google endpoint management").

Once enabled, you'll be able to see more detailed information in the error message.

For example, the following error could indicate that the device which is being used is not managed by Google endpoint management:

Choose to enable Just-in-Time (JIT) provisioning

Just-in-Time provisioning will automatically add teammates to your Intercom workspace the first time they sign in with SAML SSO, if they don’t already have an Intercom account.

To enable this, go to Settings > Workspace > Security, make sure SAML SSO is toggled on, and click on Provisioning:

Then, define which permissions new teammates should have when added by JIT provisioning:

Note: New teammates will only be added if you have available seats.

Finally, save your settings, and test your configuration by authenticating with your identity provider:

Once your workspace has SAML SSO enabled with any provider, teammates will be unable to edit their own email address from their Account security page. The email field will be read-only.

Configuring SAML with OneLogin

You can use the "Intercom SAML 2.0" app in the OneLogin store.

  1. In your OneLogin admin page, go to Applications and click Add App.

  2. Search for and add the Intercom SAML 2.0 app.

  3. Open the Configuration tab and enter the SAML name for your workspace.

  4. On the SSO tab, copy the "SAML 2.0 Endpoint" URL and paste it into your Intercom workspace's SAML settings.

  5. Click View Details under the certificate, copy the certificate, and paste it into Intercom's Public certificate field.

  6. Save your settings in Intercom and test the connection.

Note: If your workspace is hosted in the EU or AU, reach out to the OneLogin team to make sure your integration is supported.

Configuring SAML with Okta

You can use the "Intercom" app from the Okta App Store.

  1. In Okta:

    • Open the Okta admin dashboard and add the Intercom app.

    • Proceed to the Sign-On Options.

    • Download the Signing Certificate and copy the Sign on URL provided by Okta.

  2. In Intercom:

    • Go to Settings > Workspace > Security and toggle on SAML SSO.

    • Make note of your SAML URL (at the top of the SAML settings).

    • Enter the following details from Okta:

      • Identity Provider Sign-On URL: (The Sign on URL from Okta)

      • Public Certificate: (Paste the full certificate downloaded from Okta)

    • Under "Allowed Domains", enter your company’s domain (e.g., acme.com).

    • Do not click Save yet.

  3. Back in Okta:

    • Return to your Okta Intercom app's Sign-On Options.

    • Under Encryption Certificate, upload the following certificate as intercom.pem:

      -----BEGIN CERTIFICATE-----
      MIIDYzCCAkugAwIBAgIUS9LFUH5IWanIgQ78d/qyKOdojAYwDQYJKoZIhvcNAQEL
      BQAwQTERMA8GA1UECgwISW50ZXJjb20xETAPBgNVBAsMCFBsYXRmb3JtMRkwFwYD
      VQQDDBBTQU1MIENlcnRpZmljYXRlMB4XDTI2MDExMjE3NTIzN1oXDTM2MDExMDE3
      NTIzN1owQTERMA8GA1UECgwISW50ZXJjb20xETAPBgNVBAsMCFBsYXRmb3JtMRkw
      FwYDVQQDDBBTQU1MIENlcnRpZmljYXRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
      MIIBCgKCAQEA2LVcYLNwR0t1Co/FBNSFUEdpOJTM87X0//NPisUgQJ71l11Dohg9
      Yg1aAraqOsQ9EPR9prdQjP50lhOmogjvPDClPlXtoHdRCJ81U/3duXoBdGS02NN3
      2DetudNnyjeUefkcnPWsQ+FNZasnP9ODU8dtPKxMcLP3AmcUYOAaKp1r3WBuFDcT
      woMtbrWUoxTfBeYx6nQ9TfzJOGQFZCYs30Sx1j5LVio5DoM3oynTTh0qOzJS+KpU
      iIIqby8szpqWMfdPNTdBd7XQK2SkHmBgkgSDfQIII93kkXCP1bCOuo4rC+lIeXlF
      gIi2Z4iMxuKceBeLBgFTovG7dVDeGmTucQIDAQABo1MwUTAdBgNVHQ4EFgQUgZdt
      wisFHetsCww03EXQGt8Oq24wHwYDVR0jBBgwFoAUgZdtwisFHetsCww03EXQGt8O
      q24wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAiL3wXWof5x+k
      thOn2tAspFR/IH5NQHPLocV605FcRjt1JS1z0cBjtBroTKFarXo6T1NKQN5Lhjsu
      wrvu1J/YQcGnSmChar8OJSIbxPhHrbpA6Gg2mtkH4BTnnXY3LBgVFfCl5oiFxZqB
      ELkm6iBZmReot+MPWvE0Ypx7hQLI/3qLc5yYEw7ZNKWq/lRbbT4DLgKeHH89fSrm
      cpDa9ZHF2e6rlx95LCbZUWyEE6pPFeq+6CyQt+FkwLl1e+ZIJTknWgD/bzPsZ6CF
      XfF2fS2ObaUISKYEZMZx5o+JZnnYGr1U614lhniha+Rpykzoa+SsOdwvI0xl5ZRr
      aqD3fI3jqA==
      -----END CERTIFICATE-----

    • Under "Advanced Sign-On Settings", paste your SAML Base URL from Intercom.

    • Click Save.

  4. Test and Activate:

    • Go back to your Intercom workspace's SAML settings and click Save.

    • Test your SAML configuration by logging out and logging back in with SAML.

    • Once confirmed, you can return to settings and uncheck the email/password or Google sign-on options to enforce SAML.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Related Articles
System for Cross-domain Identity Management (SCIM) Provisioning
Accept an invite to an Intercom workspace
Did this answer your question?