Configure SAML SSO

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 must 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.
• SAML SSO authentication from the Cobalt sign-in page (SP-initiated SSO) is not possible.
  
  

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, 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-----.)
   • 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.cobalt.io/login/callback?connection=example-org, where the string after = is the organization’s slug (example-org).
   • Entity ID: https://api.cobalt.io/users/saml/metadata
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.

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.

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

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

1. In Azure AD, create an enterprise non-gallery application for Cobalt.
2. Enable SSO for the application. If available, follow the instructions that you see in the UI.
   • Verify that the single sign-on method for your application is SAML.
   • Under Basic SAML Configuration, enter:
     • Identifier (Entity ID): https://api.cobalt.io/users/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.
     • Logout URL: Leave this field blank.
   • Under User Attributes & Claims, add custom attribute mappings to your SAML token attributes configuration.
     • givenname: user.givenname
     • surname: user.surname
     • emailaddress: 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
     Mail	user.mail
     Othermail	user.othermail

   • 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

To set up SAML SSO with Duo, read their documentation.

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

Google

For instructions on how to enable SAML SSO with Google, read their guide.

In the Google Admin console, configure the following:

• On the Service Provider Details page, leave the Signed Response option unselected (default).
• On the Attribute Mapping page, add an attribute email, and select Basic Information and Primary Email.

Once you’ve completed the setup, your application for Cobalt appears in the Google Workspace.

Okta

We recommend creating a non-gallery SAML application for Cobalt manually. For details, read Okta’s documentation.

In Okta:

• Leave the Default RelayState field empty.
• In Attribute Statements, add the following mapping attribute:
  • email: user.email
    
    

OneLogin

For more information about setting up SAML SSO with OneLogin, refer to their 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). Enter the following values for configuration parameters in OneLogin:
   • Audience (EntityID): https://api.cobalt.io/users/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
2. In OneLogin, navigate to your application connector. On the SSO tab, under SAML Signature Algorithm, select SHA-256.
3. Configure parameters in the Cobalt app in Settings > Identity & Access > Configure SAML. Enter the following values from OneLogin. You can find them on the SSO tab of your application connector.
   • IdP SSO URL: SAML 2.0 Endpoint (HTTP)
   • IdP Certificate: X.509 Certificate
4. Navigate to your application connector in OneLogin.
5. 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. Select this application to sign in to Cobalt.
7. 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.