Configure SAML SSO

Enable SAML SSO for your organization.

Cobalt supports identity provider-initiated SAML single sign-on (SSO). As an Organization Owner, you can configure SAML SSO with your preferred identity provider.

SAML SSO Overview

Single sign-on (SSO) is an authentication method that allows users to access multiple independent systems with a single set of credentials. The Cobalt SSO service is based on the Security Assertion Markup Language 2.0 (SAML 2.0) specifications. Learn more about SAML SSO.

Cobalt supports identity provider-initiated (IdP-initiated) SSO, where the authentication workflow starts on the identity provider side. There are a number of identity provider solutions that you can leverage to implement SSO with Cobalt, such as Okta, OneLogin, Microsoft Azure AD, and more.

  • To access Cobalt, users sign in to the identity provider system and select the configured Cobalt app.
  • Cobalt acts as the service provider. When a user attempts to sign in to Cobalt from the IdP system, Cobalt requests the IdP to authenticate the user. Once the authentication is complete, the IdP sends a SAML assertion to Cobalt, and the user is signed in.

Cobalt identity provider-initiated SAML SSO

General Configuration Workflow

As an Organization Owner, you can configure SAML SSO for your organization with your preferred identity provider. Configuration procedures differ for each IdP. See configuration instructions for some popular IdPs below.

Once you’ve enabled SSO, users can sign in to Cobalt through the configured IdP. This affects the following roles:

If SAML SSO enforcement is off and the Identity Provider Domains are not set, users can authenticate in the following ways:

  • Through SAML SSO
  • With their email and password
  • Using Google authentication (OAuth 2.0), if relevant

Here’s a general configuration workflow for SAML SSO:

  1. Create a Cobalt application within the selected identity provider.
    • For each provider, see how configuration parameters map between their platform and Cobalt.
  2. Set up the integration in the Cobalt app.
    • Navigate to Settings > Identity & Access. Under Configure SAML, select Configure.
    • Enter the following values from your identity provider:
      • IdP SSO URL
      • IdP Certificate (Make sure to include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.)
      • Identity Provider Domains (optional)
        • Enter your email domain(s) here if you want your users to be automatically redirected from our sign in form to your IdP (SP-initiated SSO)
        • This will have the same effect as Enforce SAML for any user that signs in with a matching email address
    • Select Save Configuration.
      Configure SAML SSO in the Cobalt app
  3. Complete the configuration in the identity provider system. Enter the following values from Cobalt:
    • ACS URL: (unique value for each organization).
      • Example: https://login.app.us.cobalt.io/login/callback?connection=example-org, where the string after = is the organization’s slug (example-org).
    • Entity ID: https://api.us.cobalt.io/users/saml/metadata
    • Metadata: If your identity provider requires the SAML metadata file, it can be obtained at the following URL.
      • Example: https://login.app.us.cobalt.io/samlp/metadata?connection=example-org, where the string after = is the organization’s slug (example-org).
  4. Test your SAML configuration.
  5. If the test is successful, assign users to the SAML app in the IdP.
  6. Notify users that now they can sign in through the selected identity provider. We don’t send any notifications to users.

We don’t synchronize user datastores, so make sure that all users:

  • Joined your organization in Cobalt, confirmed their email address, and created a password.
  • Are provisioned within your identity provider with the same email address that they use in Cobalt.

If you have problems setting up SAML SSO, see our troubleshooting tips.

Service Provider-initiated SAML SSO

Cobalt now supports SP-initiated SSO. There are two ways you can access SP-initiated SSO once your SAML configuration is set up:

  • Use the following URL format: https://app.us.cobalt.io/users/saml/sign_in?connection=example-org
    • Replace example-org with your organization’s slug
  • Add Identity Provider Domains to your SAML configuration
    • Users with matching email addresses will be automatically redirected from our sign in form to your IdP to complete the authentication flow
    • This will have the same effect as enabling Enforce SAML
    • Note: It is recommended to leave this field blank until after you have tested your SAML connection and confirmed it’s working.

Enforce SAML SSO

SAML SSO enforcement reqiures organization users to sign in to Cobalt only through SAML SSO. Once the enforcement is on, other authentication methods will no longer work. This affects the following roles:

To enforce SAML SSO for your organization:

  1. Navigate to Settings > Identity & Access. You must have SAML SSO configured.
  2. Under SAML Single Sign-on (SSO), turn on the Enforce SAML toggle, and confirm your action.

    Manage SAML enforcement for your organization
  3. Notify users that now they must sign in through the selected identity provider. We don’t send any notifications, so make sure that SAML enforcement doesn’t disrupt your workflows.

Note: It is recommended to leave this turned off until after you have tested your SAML connection and confirmed it’s working.

Configuration Instructions for Specific Identity Providers

You can configure SAML SSO with your preferred identity provider. Here are instructions for some popular IdPs:

Azure AD

Learn how to configure SAML SSO with Azure Active Directory (Azure AD) as IdP.

Click to view instructions.

Duo

Learn how to configure SAML SSO with Duo as IdP. For more information, refer to Duo documentation.

Click to view instructions.

Google

Learn how to configure SAML SSO with Google as IdP. For more information, refer to Google documentation.

Click to view instructions.

Okta

You can set up SAML SSO with Okta in two ways:

Click to view instructions for a non-gallery SAML app.

OneLogin

Learn how to configure SAML SSO with OneLogin as IdP. For more information, refer to OneLogin documentation.

Click to view instructions.

Troubleshoot Your SAML SSO Configuration

If your SAML SSO configuration doesn’t work, you can delete it by selecting Delete Configuration. Then you can configure SAML SSO once again.

To get help, contact your Customer Success Manager (CSM) or support@cobalt.io.

Troubleshooting TipDetails
Ensure that all values match between your identity provider and Cobalt.Mapped parameters in both setups must match.
Ensure that the IdP certificate is accurate.Copy the IdP certificate once again.
- Include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
- Make sure there are no extra whitespaces.
Ensure that you added users to the Cobalt platform.We don’t support user provisioning through an IdP. When leveraging an IdP, make sure that there is an established identity for a user in Cobalt.
To establish an identity in Cobalt, a user needs to create a password and sign in to Cobalt. All subsequent sign-ins (after the user identity is established in Cobalt) are initiated through the organization’s IdP.
Assign users to the Cobalt application in the IdP system.Add users to the new SAML application that you’ve set up.
Try to configure the setup again in a new browser window.There may be a problem with your current session. This may happen if:
- You pressed the Back button in your browser.
- You refreshed the page during the setup process.
- An issue occurred with your browser cookies.
- You opened too many sign-in windows.
- A temporary glitch has occurred.
Last modified November 14, 2024