Configure SAML SSO

Enable SAML SSO for your organization.

:::info Cobalt supports 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.

  

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:

• Organization Owner

• Organization Member

• 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.

     

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).

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.

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

Service Provider-initiated SAML SSO

Once your SAML configuration is set up, you can optionally configure SP-initiated SSO to allow your users to sign in with SAML directly from the Cobalt login page:

• Use the following URL format: https://app.us.cobalt.io/users/saml/sign_in?connection=example-org

  • Replace example-orgwith 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. Once the enforcement is on, other authentication methods will no longer work. This affects the following roles:

• Organization Owner

• Organization Member

• 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.

   

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.

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.

3. 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.
4. Test your configuration.
5. 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.

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.

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.

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 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

For more information on how to create a non-gallery app, refer to the Okta documentation.

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

     

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.

     

7. Still on the Configure SAML tab, under Attribute Statements (optional), add the following mapping attribute:

   • email: user.email

     

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

    

11. 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.

12. Test the integration.
13. 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.

To configure SAML SSO with OneLogin:

1. Create a custom application connector for Cobalt. Follow OneLogin instructions to build a SAML Custom Connector (Advanced).

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.

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.
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.

Troubleshoot user access

If you've configured SAML successfully but users are unable to access your Org when signing in through your IdP, they may need to accept an email invitation:

• New users (not yet part of any Cobalt org) provisioned via IDP will have their Cobalt account created automatically — no invitation acceptance required.
• Existing users being added to an additional org via IDP will still receive an invitation email and must accept it before gaining access.