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 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:
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:
- Create a Cobalt application within the selected identity provider.
- For each provider, see how configuration parameters map between their platform and Cobalt.
- 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.
- 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
- Test your SAML configuration.
- If the test is successful, assign users to the SAML app in the IdP.
- 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:
To enforce SAML SSO for your organization:
- Navigate to Settings > Identity & Access. You must have SAML SSO configured.
- Under SAML Single Sign-on (SSO), turn on the Enforce SAML toggle, and confirm your action.
- 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
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):
- 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.
- 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/users/saml/metadata
- For EU data center:
https://api.eu.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 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.
- 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.
- Test your configuration.
- 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.
Click to view instructions.
To create a SAML app for Cobalt in Duo:
- In the Duo Admin Panel, go to Applications, and select Protect an Application. For details, read this instruction.
- Under Metadata, copy the following values. You will need to add them to Cobalt in the next step.
- Single Sign-On URL
- Certificate
- 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.
- Still in Cobalt, copy the ACS URL value, then select Save Configuration.
- Go back to Duo. Under Service Provider, enter:
- ACS URL: ACS URL from Cobalt.
- Entity ID:
https://api.us.cobalt.io/users/saml/metadata
- For EU data center:
https://api.eu.cobalt.io/users/saml/metadata
- 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
- Complete other required steps.
- Assign users to the application.
- Test the integration.
Google
Learn how to configure SAML SSO with Google as IdP. For more information, refer to Google documentation.
Click to view instructions.
To create a SAML app for Cobalt in the Google Admin console:
- In the Google Admin console, go to Menu > Apps > Web and mobile apps. Follow this instruction for more details.
- Select Add App > Add custom SAML app.
- On the App Details page, enter general information for the integration, then select Continue.
- On the Google Identity Provider details page, locate the following values. You will need to add them to Cobalt in the next step.
- 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.
- Still in Cobalt, copy the ACS URL value, then select Save Configuration.
- 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/users/saml/metadata
- For EU data center:
https://api.eu.cobalt.io/users/saml/metadata
- Leave the Signed Response option unselected (default).
- On the Attribute Mapping page, add an attribute
email, and select Basic Information and Primary Email.
- Complete other required steps.
- Test the integration.
- If the test is successful, assign users to the application.
Okta
You can set up SAML SSO with Okta in two ways:
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.
To create a non-gallery SAML app for Cobalt in Okta:
- 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
- In Okta, in the Admin Console, go to Applications > Applications.
- Select Create App Integration.
- In the overlay that appears, select SAML 2.0 as the sign-in method, and then select Next.
- On the General Settings tab, enter general information for the integration, then select Next.
- 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/users/saml/metadata.
- For EU data center:
https://api.eu.cobalt.io/users/saml/metadata
- Leave the Default RelayState field blank.
- For other fields, use default values.
- Still on the Configure SAML tab, under Attribute Statements (optional), add the following mapping attribute:
- email:
user.email
- Select Next.
- On the Feedback tab, select I’m an Okta customer adding an internal app, and then select Finish.
- 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
- 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.
- Test the integration.
- 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.
Click to view instructions.
To configure SAML SSO with OneLogin:
- Create a custom application connector for Cobalt. Follow OneLogin instructions to build a SAML Custom Connector (Advanced).
- In OneLogin, enter the following values for configuration parameters:
- Audience (EntityID):
https://api.us.cobalt.io/users/saml/metadata
- For EU data center:
https://api.eu.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
- In OneLogin, navigate to your application connector. On the SSO tab, under SAML Signature Algorithm, select SHA-256.
- 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.
- 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.
- 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.
- 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. |
| 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. |
Learn how to update your SAML configuration from legacy to the new setup.
Configure SAML with Okta using their gallery app for Cobalt.
Last modified September.09.2023