How to set up single sign-on (SSO)

Introduction

The Sublime Platform supports single sign-on SSO through both SAML (Security Assertion Markup Language) and OIDC (OpenID Connect), allowing you to authenticate with Sublime via Okta, OneLogin, Azure Active Directory, or any other SAML or OIDC provider.

πŸ“˜

Managing users with SCIM

Sublime also supports the SCIM (System for Cross-domain Identity Management) standard, which makes it easy to provision, update, and de-provision users from your identity provider. Learn more here.

Integrating with SAML

Below are the steps for setting up SAML with Okta. If you need help setting up SAML for another identity provider, drop us a message.

Okta

Get your Sublime SAML signon URL

  1. Sign into Sublime
  2. Go to Admin > Account
  3. Under Authentication, click the button next to SAML
  4. Copy and hold onto the URL under Single sign-on URL

Create a custom SAML app

  1. Sign into your Okta admin console
  2. Go to Applications > Applications
  3. Click Create App Integration
  4. In the modal that opens, select Sign-in method of SAML 2.0
  5. Click Next
  6. Provide an App name, such as "Sublime Platform"
  7. Optionally add a logo. You can download the Sublime logo here.
  8. Click Next
  9. For Single sign-on URL, paste the SAML signon URL you copied from the Sublime dashboard
  10. Be sure Use this for Recipient URL and Destination URL is checked
  11. For Audience URI (SP Entity ID), also paste the SAML signon URL you copied from the Sublime dashboard
  12. For Name ID format, select Email Address
  13. For Update application username on, select Create and update
  14. Leave all other settings as their defaults
  15. Click Next
  16. Click Finish
  17. Click the Sign On tab of the new Okta app
  18. Copy the Metadata URL

Update your SAML settings in Sublime:

  1. In Sublime, go to Admin > Account
  2. Under Authentication, click the button next to SAML
  3. Under Metadata URL, paste the metadata URL you copied from Okta
  4. Click Save

Test SAML

πŸ“˜

Matching user required

For a user to successfully sign into Sublime with your SAML identity provider, there must already be a matching user with the same email address in Sublime. We recommend provisioning users through SCIM.

  1. In Sublime, go to Admin > Account
  2. Under Authentication, verify Allowed methods is set to either Any method or SAML only, or update accordingly
  3. While signed into Okta as the provisioned user, navigate to the SAML signon URL you copied from the Sublime dashboard

You should be signed into the Sublime dashboard. You're in business!

Integrating with OIDC

There are two high-level steps to integrating the Sublime Platform with OpenID Connect:

  1. Obtain a set of OIDC settings, consisting of an issuer URL, a client ID, and a client secret
  2. Add these settings to Sublime

1. Obtain OIDC settings

The process for obtaining OIDC settings varies between OIDC identity providers, but typically involves creating an application that includes an OAuth 2.0 client ID and client secret, and configuring the appropriate redirect URI.

Okta

Below are the steps for obtaining OIDC settings via Okta.

Open the OIDC settings modal in Sublime:

  1. Log into the Sublime Platform
  2. Go to Admin > Account
  3. Under Authentication, click the button next to Open ID Connect
  4. Keep this page open, as you'll use the Initiate login URL and Redirect URI to set up an application in Okta

Create the application in Okta:

  1. Sign into your Okta admin console
  2. Go to Applications > Applications
  3. Click Create App Integration
  4. In the modal that opens, select Sign-in method of OIDC - OpenID Connect
  5. Then select Application type of Web Application
  6. Click the Next button
  7. Provide an App integration name, such as "Sublime Platform"
  8. Optionally add a logo. You can download the Sublime logo here.
  9. In the Grant type section, check Implicit (Hybrid)
  10. In Sign-in redirect URIs, paste the Redirect URI from Sublime
  11. Remove the default entry in Sign-out redirect URIs
  12. In the Controlled access section, select your preferred option
  13. Click the Save button
  14. Click the Edit button in the General Settings section
  15. In Login initiated by, select Either Okta or App
  16. In Initiate login URI, paste the Initiate login URL from Sublime
  17. Next to Application visibility, check Display application icon to users and optionally check Display application icon in the Okta Mobile app
  18. Click the Save button
  19. Note the Client ID and Client secret from the current page
  20. Click the Sign On tab
  21. Note the Issuer URL under OpenID Connect ID Token

You'll use the client ID, client secret, and issuer URL you noted in the next section

Azure Active Directory

To use Azure Active Directory as your SSO provider for Sublime, you'll need to create an Azure application. Note that you have the option of using the same application you created when setting up a Microsoft 365 message source.

🚧

You must use an Azure AD tenant you control

You must create your Azure application for Sublime SSO in a tenant you wholly control to ensure no third party can impersonate your users.

First, get the Redirect URI for your Sublime organization:

  1. Log into the Sublime Platform
  2. Go to Admin > Account
  3. Under Authentication, click the button next to Open ID Connect
  4. Note the Redirect URI, as you'll use it to set up an application in Azure

To create the application in Azure, follow the steps below. If you're using an existing Azure app for SSO, jump to step 7.

  1. Sign into portal.azure.com
  2. Click App Registrations
  3. Click New Registration
  4. Give your application a name, such as "Sublime Platform"
  5. Under Supported account types select Accounts in this organizational directory only if it's not already selected by default
  6. Click Register (skip the Redirect URI section)
  7. In the Overview section of the application's settings, note the Application (client) ID and the Directory (tenant) ID. You'll use these IDs later.
  8. Go to the Authentication settings page
  9. Click Add a platform
  10. In the panel that opens, click Web
  11. Under Redirect URIs, paste the Redirect URI from Sublime
  12. Under Implicit grant and hybrid flows, check ID tokens
  13. Click Configure
  14. Go to the Certificates & secrets settings page
  15. Click New client secret
  16. Give the client secret a name like "Sublime SSO" and select an expiration of "24 months"
  17. Click Add
  18. Note the value of the new client secret

Now that you've configure your Azure application, you'll use the following values in the next section of this guide:

  • Your issuer URL is https://login.microsoftonline.com/TENANT_ID/v2.0, with TENANT_ID being the Directory (tenant) ID you noted earlier
  • Your client ID is the Application (client) ID you noted earlier
  • Your client secret is the client secret you just created

Google

In order to use Google's OpenID Connect feature, you'll need to create a Google Cloud Platform project with an OAuth app restricted to your organization, then create a client ID/secret pair to use to set up OIDC in Sublime.

Here's a video recording showing the steps to configure the app and create the client ID/secret pair.

  • Note that the GCP settings not configured in the recording are optional.
  • Add the Redirect URI provided in the "Configure OpenID Connect" modal in Sublime to the "authorized redirect URIs" in GCP.
  • Add the client ID and client secret from Google to your OIDC settings in Sublime, using https://accounts.google.com as the "Issuer URL".

2. Add OIDC settings to Sublime

  1. Log into the Sublime Platform
  2. Go to Admin > Account
  3. Under Authentication, click the button next to Open ID Connect
  4. Enter your OIDC issuer URL, client ID, and client secret
  5. Click the Save button

Test the integration

You should now be able to sign into Sublime with your OIDC identity provider. You can verify the integration is working by either selecting the Sublime Platform application in your provider (for example, Okta), or by loading the Initiate login URL from your OIDC settings in Sublime.

πŸ“˜

Matching user required

For a user to successfully sign into Sublime with your OIDC identity provider, there must already be a matching user with the same email address in Sublime.

Managing allowed authentication methods

Once you set up SAML or OIDC, you can optionally restrict user signin to only SAML or only OIDC. If you'd like to use this option:

  1. Sign out of Sublime and verify signin via OpenID Connect is working
  2. Go to Admin > Account
  3. Under Authentication, click the button next to Allowed methods
  4. Select Users must log in with OpenID Connect SSO or Users must log in with SAML SSO
  5. Click Save