--- title: "SAML Migration: Update Your Configuration" description: "Learn how to update your SAML configuration from legacy to the new setup." canonical_url: "https://cobalt-io.brainfish.ai/articles/saml-migration-update-your-configuration-LqzlyEpUSj" md_url: "https://cobalt-io.brainfish.ai/articles/saml-migration-update-your-configuration-LqzlyEpUSj.md" --- # SAML Migration: Update Your Configuration Learn how to update your SAML configuration from legacy to the new setup. :::info On May 10, 2023, we made some changes to our SAML implementation. To avoid any disruptions to authentication, update your SAML configuration. During the transition period, your existing SAML SSO setup will be valid. After the transition period, we'll stop supporting legacy configurations. ::: This page is for [Organization Owners](https://cobalt-io.brainfish.ai/en-us/articles/user-roles-and-permissions-oCij6uRrUR#h-organization-owner) who have set up their SAML SSO configuration **before May 10, 2023**. * If you don’t update your SAML configuration by the end of the transition period, we’ll deprecate your legacy configuration settings. This means you will not be able to sign in to Cobalt. * Make sure to update configurations for each organization where you’re an Organization Owner. * If you don’t have a legacy setup and want to enable SAML, please visit [Configure SAML SSO](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D) for instructions. ## What Has Changed in the SAML Implementation Here is a summary of updates: * Our **Assertion Consumer Service (ACS) URL** is no longer `https://api.cobalt.io/users/saml/auth`, but is now unique per organization. To get your unique ACS URL, go to **Settings** > **Identity & Access** > **Configure SAML** in the Cobalt app. * Example ACS URL: `https://login.app.us.cobalt.io/login/callback?connection=example-org`, where the string after `=`is the organization’s **slug** ( `example-org`). You can also see the slug in **Settings** > **General**. * Our **Audience Restriction** now contains a location subdomain. * Example Audience: `https://api.us.cobalt.io/v2/orgs//saml_metadata` * For EU data center: `https://api.eu.cobalt.io/v2/orgs/test-org-api/saml_metadata` * We no longer require a **RelayState** within the assertion. * Organization Owners can now enable or disable [SSO enforcement](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-enforce-saml-sso). ## How to Update Your SAML Configuration There are two ways to migrate to the new SAML implementation: * **Option 1**: Set up a new SAML configuration and deactivate the old one. * **Option 2**: Update your existing SAML configuration between Cobalt and your IdP. ### Option 1: Set up a New SAML Configuration 1. Create a new SAML app with your preferred identity provider. For instructions, see [how to configure SAML SSO](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D). 2. Test the new configuration. 3. If the test is successful, assign users, and notify them of the new Cobalt SAML app or SSO URL. 4. Deactivate the old SAML app and deprovision users. ### Option 2: Update Your Existing SAML Configuration Before updating your existing configuration, note the following: * To avoid disrupting anyone’s workflows, choose a time when the impact on users is minimal. * Turn off [SAML enforcement](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-enforce-saml-sso) until you’ve successfully tested the new configuration. * You need to copy parameters between two systems, so it’s handy to have both applications open. * You can refer to **instructions for some popular IdPs** below: * Azure AD * Duo * Google * Okta * OneLogin Here’s a general workflow to **update your existing SAML configuration**: 1. In your identity provider: * Update the **==ACS URL==** with the current value from Cobalt. The name of this parameter may differ for different IdPs. To get the ACS URL, in Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**, and copy the ACS URL value. 2. In Cobalt: * Go to **Settings** > **Identity & Access**. * Make sure that the **Enforce SAML** toggle is turned off. You can [enforce SAML](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-enforce-saml-sso) after you complete the configuration. * You can view your legacy configuration under **Legacy SAML Configuration**. It may not match your current setup in the IdP. * Under **Configure SAML**, select **Configure**. * Update the **==IdP Certificate==** with the current value from your identity provider, and select **Save Configuration** to confirm. 3. We no longer require a **==RelayState==** within the assertion. Delete it from the configuration in your IdP. 4. Test the configuration. You should be authenticated to Cobalt. ## Azure AD To update your existing SAML configuration with Azure AD: 1. In Azure AD, go to your SAML application for Cobalt. * **Reply URL (Assertion Consumer Service URL)**: Enter **ACS URL** from Cobalt. * Delete the **Relay State** value. 2. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**. * **IdP Certificate**: Enter **Certificate (Base64)** from Azure AD. If you want to set up a new application, follow this [instruction](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-azure-ad). ## Duo To update your existing SAML configuration with Duo: 1. In Duo, go to your SAML application for Cobalt. * **Assertion Consumer Service (ACS) URL**: Enter **ACS URL** from Cobalt. * Delete the **Default Relay State** value. 2. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**. * **IdP Certificate**: Enter **Certificate** from Duo. If you want to set up a new application, follow this [instruction](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-duo). ## Google We recommend creating a new SAML app with Google. For details, follow this [instruction](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-google). ## Okta ### Non-gallery SAML app To update your existing SAML configuration with Okta for a non-gallery SAML app: 1. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**. * Copy the **ACS URL**. ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=2678a0fc-279a-436d-ad9e-acc99da67ab2) 2. In Okta, go to your SAML application for Cobalt. On the **General** tab, under **SAML Settings**, select **Edit**, then select **Next**. If you don’t see editable **SAML Settings**, we suggest that you [create a new non-gallery app](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-okta). * **Single sign-on URL**: Enter **ACS URL** from Cobalt. * Delete the **Default RelayState** value. * Save the changes. ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=fb5becb4-b588-41da-9362-7a98e548bfd4) 3. In Okta, go to the **Sign On** tab, and select **Edit**. Under **Metadata details**, select **More details**. * Copy the **Sign on URL**. * Download or copy the **Signing Certificate**. ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=ee18e537-198a-4ea7-8a78-e737e9ba81b4 " =482x383") 4. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**. * **IdP SSO URL**: Enter the **Sign on URL** from Okta. * **IdP Certificate**: Enter the **Signing Certificate** from Okta. * Select **Save Configuration**. If you want to set up a new application, follow these [instructions](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-okta). ### OneLogin To update your existing SAML configuration with OneLogin: 1. In OneLogin, go to your SAML application for Cobalt. * **Recipient**, **ACS (Consumer) URL Validator**, and **ACS (Consumer) URL**: Enter **ACS URL** from Cobalt. * Delete the **RelayState** value. 2. In Cobalt, go to **Settings** > **Identity & Access**. Under **Configure SAML**, select **Configure**. * **IdP Certificate**: Enter **X.509 Certificate** from OneLogin. If you want to set up a new application, follow this [instruction](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-onelogin). ## Troubleshooting See our general [troubleshooting tips](https://cobalt-io.brainfish.ai/en-us/articles/configure-saml-sso-oT8Q3qO09D#h-troubleshoot-your-saml-sso-configuration) for SAML configurations. When updating your existing SAML setup, ensure that: * The **ACS URL** and **Entity ID** are correct in the IdP system. * The **Relay State** in the IdP system is blank. We no longer support it in the new SAML implementation. * The organization’s **Slug** is accurate. The slug appears after `=` in the ACS URL. You can also find the slug in **Settings** > **General**. ![](https://cobalt-io.brainfish.ai/api/attachments.redirect?id=22baaa36-b83f-4e89-a020-4d9a134a26ed " =844x72") To get help, contact your Customer Success Manager (CSM) or [support@cobalt.io](mailto:support@cobalt.io).