---
title: "Configure SAML SSO"
description: "Enable SAML SSO for your organization."
canonical_url: "https://cobalt-io.brainfish.ai/articles/configure-saml-sso-oT8Q3qO09D"
md_url: "https://cobalt-io.brainfish.ai/articles/configure-saml-sso-oT8Q3qO09D.md"
---
# Configure SAML SSO

Enable SAML SSO for your organization.


:::info
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)](https://docs.cobalt.io/en-us/articles/glossary-YfTMKeZ1VM#h-security-assertion-markup-language) specifications. Learn more about [SAML SSO](https://docs.cobalt.io/en-us/articles/glossary-YfTMKeZ1VM#h-saml-single-sign-on-sso).

Cobalt supports [identity provider-initiated (IdP-initiated) SSO](https://docs.cobalt.io/en-us/articles/glossary-YfTMKeZ1VM#h-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.    ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=d5cc5664-97c9-4b4e-9bc1-a87e773a3b05)

## **General Configuration Workflow**

As an [Organization Owner](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-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:

* [Organization Owner](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-organization-owner)
* [Organization Member](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-organization-member)
* [Pentest Team Member](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-pentest-team-member)

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**.    ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=3926868a-e9f0-4041-b3a7-2cbc5362c74e)
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/v2/orgs/<your-org's-slug>/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`).


1. Test your SAML configuration.
2. If the test is successful, assign users to the SAML app in the IdP.
3. 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**


:::info
* **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](https://docs.cobalt.io/en-us/articles/glossary-YfTMKeZ1VM#h-saml-single-sign-on-sso). Once the enforcement is on, other authentication methods will no longer work. This affects the following roles:

* [Organization Owner](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-organization-owner)
* [Organization Member](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-organization-member)
* [Pentest Team Member](https://docs.cobalt.io/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-pentest-team-member)

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.    ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=df54d757-d9a8-438e-ae02-27b2ba050742)
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.


:::info
**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
* Duo
* Google
* Okta
* OneLogin


---

### Azure AD

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

#### Click to view instructions.

To configure SAML SSO with Azure Active Directory (Azure AD):


1. In Azure AD, create an enterprise non-gallery application for Cobalt.
   * Select **Enterprise applications**, then select **New application**.
   * Select **Non-gallery application**.
   * Select **Create your own application**.
   * Enter a name for your application, then select **Create**.
   * Wait for the application to load.
2. Enable SSO for the application.
   * On the application page, select **Set up single sign-on**.
   * On the **Select a single sign-on method** screen, select **SAML**.
   * Under **Basic SAML Configuration**, enter:
     * **Identifier (Entity ID)**: `https://api.us.cobalt.io/v2/orgs/<your-org's-slug>/saml_metadata`
       * For EU data center: `https://api.eu.cobalt.io/v2/orgs/test-org-api/saml_metadata`
     * **Reply URL** (Assertion Consumer Service URL): **ACS URL** from Cobalt (unique value for each organization). Copy the value in the Cobalt app in **Settings** > **Identity & Access** > **Configure SAML**.
     * **Sign on URL**: Leave this field blank.
     * **Relay State**: Leave this field blank.
     * **Logout URL**: Leave this field blank.
   * Under **User Attributes & Claims**, add custom attribute mappings to your SAML token attributes configuration.
     * **email**: `user.mail`
     * **name**: `user.userprincipalname`
     * **Unique User Identifier**: `user.userprincipalname`
   * The Cobalt app expects the following attributes to be passed in the SAML response:

| Name | Source Attribute |
|:---|:---|
| email | user.mail |

* Under **SAML Signing Certificate**, download **Certificate (Base 64)**.
* Under **Set up \[Your App\]**, copy **Login URL**.


1. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**.
   * **IdP SSO URL**: Enter **Login URL** from Azure AD.
   * **IdP Certificate**: Enter **Certificate (Base64)** from Azure AD.
2. Test your configuration.
3. If the test is successful, assign users to the application.


---

### Duo

Learn how to configure SAML SSO with Duo as IdP. For more information, refer to Duo [documentation](https://duo.com/docs/sso-generic).

#### Click to view instructions.

To create a SAML app for Cobalt in Duo:


1. In the Duo Admin Panel, go to **Applications**, and select **Protect an Application**. For details, read this [instruction](https://duo.com/docs/sso-generic).
2. Under **Metadata**, copy the following values. You will need to add them to Cobalt in the next step.
   * **Single Sign-On URL**
   * **Certificate**
3. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**.
   * **IdP SSO URL**: Enter **Single Sign-On URL** from Duo.
   * **IdP Certificate**: Enter **Certificate** from Duo.
4. Still in Cobalt, copy the **ACS URL** value, then select **Save Configuration**.
5. Go back to Duo. Under **Service Provider**, enter:
   * **ACS URL**: **ACS URL** from Cobalt.
   * **Entity ID**: `https://api.us.cobalt.io/v2/orgs/<your-org's-slug>/saml_metadata`
     * For EU data center: `https://api.eu.cobalt.io/v2/orgs/test-org-api/saml_metadata`
6. In Duo, complete the **SAML Response** section with:
   * **NameID format**: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
   * **NameID attribute**: `mail`
   * **Signature algorithm**: `SHA256`
   * **Signing options**: Select **Sign response** and **Sign assertion**.
   * **Map attributes**:
     * **IdP Attribute**: `mail`
     * **SAML Response Attribute**: `email`
7. Complete other required steps.
8. Assign users to the application.
9. Test the integration.


---

### Google

Learn how to configure SAML SSO with Google as IdP. For more information, refer to Google [documentation](https://support.google.com/a/answer/6087519?hl=en).

#### Click to view instructions.

To create a SAML app for Cobalt in the Google Admin console:


 1. In the Google Admin console, go to **Menu** > **Apps** > **Web and mobile apps**. Follow this [instruction](https://support.google.com/a/answer/6087519?hl=en) for more details.
 2. Select **Add App** > **Add custom SAML app**.
 3. On the **App Details** page, enter general information for the integration, then select **Continue**.
 4. On the **Google Identity Provider details** page, locate the following values. You will need to add them to Cobalt in the next step.
    * **SSO URL**
    * **Certificate**
 5. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**.
    * **IdP SSO URL**: Enter **SSO URL** from the Google Admin console.
    * **IdP Certificate**: Enter **Certificate** from the Google Admin console.
 6. Still in Cobalt, copy the **ACS URL** value, then select **Save Configuration**.
 7. Go back to the Google Admin console. In the **Service Provider Details** window, enter:
    * **ACS URL**: **ACS URL** from Cobalt
    * **Entity ID**: `https://api.us.cobalt.io/v2/orgs/<your-org's-slug>/saml_metadata`
      * For EU data center: `https://api.eu.cobalt.io/v2/orgs/test-org-api/saml_metadata`
 8. Leave the **Signed Response** option unselected (default).
 9. On the **Attribute Mapping** page, add an attribute `email`, and select **Basic Information** and **Primary Email**.
10. Complete other required steps.
11. Test the integration.
12. If the test is successful, assign users to the application.


---

### Okta

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

For more information on how to create a non-gallery app, refer to the Okta [documentation](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm?cshid=ext_Apps_App_Integration_Wizard-saml).

To create a non-gallery SAML app for Cobalt in Okta:


 1. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**. You will need the following values in the next steps:
    * **ACS URL**
    * **Entity ID**    ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=bafda579-4294-4f1d-ac6d-1742c0b0108e)
 2. In Okta, in the Admin Console, go to **Applications** > **Applications**.
 3. Select **Create App Integration**.
 4. In the overlay that appears, select **SAML 2.0** as the sign-in method, and then select **Next**.
 5. On the **General Settings** tab, enter general information for the integration, then select **Next**.
 6. On the **Configure SAML** tab, under **General**, enter SAML details:
    * **Single sign-on URL**: Enter **ACS URL** from Cobalt.
    * **Audience URI (SP Entity ID)**: Enter `https://api.us.cobalt.io/v2/orgs/<your-org's-slug>/saml_metadata`.
      * For EU data center: `https://api.eu.cobalt.io/v2/orgs/test-org-api/saml_metadata`
    * Leave the **Default RelayState** field blank.
    * For other fields, use default values.    ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=55c4b1c2-6ed9-4edc-828f-a050e3f10c5e)
 7. Still on the **Configure SAML** tab, under **Attribute Statements (optional)**, add the following mapping attribute:
    * **email**: `user.email`

       ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=892032d6-e9b1-4c7c-adef-cb4c6ea2df85 " =626x")
 8. Select **Next**.
 9. On the **Feedback** tab, select **I’m an Okta customer adding an internal app**, and then select **Finish**.
10. Once you’ve created a SAML application, on the **Sign on** tab, under **Metadata details**, click **More details**. You need the following values to complete the configuration in Cobalt:

* **Sign on URL**
* **Signing Certificate**    ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=85e3fd7b-02a0-44f6-94bf-6c1113d72bec)


1. In Cobalt, enter the following values from Okta, and then select **Save Configuration**.

* **IdP SSO URL**: Enter **Sign on URL** from Okta.
* **IdP Certificate**: Enter **Signing Certificate** from Okta.


1. Test the integration.
2. If the test is successful, assign users to the application.


---

### OneLogin

Learn how to configure SAML SSO with OneLogin as IdP. For more information, refer to OneLogin [documentation](https://developers.onelogin.com/saml).

#### Click to view instructions.

To configure SAML SSO with OneLogin:


1. Create a custom application connector for Cobalt. Follow OneLogin instructions to [build a SAML Custom Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=912bb23edbde7810fe39dde7489619de&kb_category=93e869b0db185340d5505eea4b961934).
2. In OneLogin, enter the following values for configuration parameters:
   * **Audience (EntityID)**: `https://api.us.cobalt.io/v2/orgs/<your-org's-slug>/saml_metadata`
     * For EU data center: `https://api.eu.cobalt.io/v2/orgs/test-org-api/saml_metadata`
   * **Recipient**, **ACS (Consumer) URL Validator**, and **ACS (Consumer) URL**: ACS URL (unique value for each organization). Copy the value in the Cobalt app in **Settings** > **Identity & Access** > **Configure SAML**.
   * **SAML initiator**: OneLogin
   * **SAML nameID format**: Email
   * **SAML issuer type**: Specific
   * **SAML signature element**: Assertion
3. In OneLogin, navigate to your application connector. On the **SSO** tab, under **SAML Signature Algorithm**, select **SHA-256**.
4. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**.
   * **IdP SSO URL**: Enter **SAML 2.0 Endpoint (HTTP)** from OneLogin.
   * **IdP Certificate**: Enter **X.509 Certificate** from OneLogin. You can find these parameters in OneLogin on the **SSO** tab of your application connector.
5. Navigate to your application connector in OneLogin. On the **Parameters** tab, select **Add Parameter**.
   * Under **Field name**, enter `email`

     , then select **Include in SAML assertion**, and select **Save**.
   * Under **Value**, select **Email**, and select **Save**.
6. To test your configuration, sign in to OneLogin as your assigned user. You should see a custom application for Cobalt that you configured.
7. Select this application to sign in to Cobalt.
8. If the test is successful, assign users in OneLogin:
   * Go to **Administration**.
   * In the menu, select **Users** > **Users**.
   * Assign users to your application.

## 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](mailto:support@cobalt.io).

| **Troubleshooting Tip** | **Details** |
|:---|:---|
| 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. |