> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-1d264819.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO setup

> How to set up SAML SSO with ClickHouse Cloud

export const EnterprisePlanFeatureBadge = ({feature = 'This feature', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Enterprise plan feature
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'are' : 'is'} available in the Enterprise plan. {support ? `Contact support to enable this feature.` : 'To upgrade, visit the plans page in the cloud console.'}</p>
            </div>
        </div>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

ClickHouse Cloud supports single-sign on (SSO) via security assertion markup language (SAML). This enables you to sign in securely to your ClickHouse Cloud organization by authenticating with your identity provider (IdP).

We currently support service provider-initiated SSO, multiple organizations using separate connections, and just-in-time provisioning. We don't yet support a system for cross-domain identity management (SCIM) or attribute mapping.

Customers enabling SAML integrations can also designate the default role that will be assigned to new users and adjust session timeout settings.

<h2 id="before-you-begin">
  Before you begin
</h2>

You will need Admin permissions in your IdP, the ability to add a TXT record to the DNS settings for your domain, the **Admin** role in your ClickHouse Cloud organization. We recommend setting up a **direct link to your organization** in addition to your SAML connection to simplify the login process. Each IdP handles this differently. Read on for how to do this for your IdP.

<h2 id="how-to-configure-your-idp">
  How to configure your IdP
</h2>

<h3 id="steps">
  Steps
</h3>

<Steps>
  <Step>
    <h3 id="access-organization-settings">
      Access Organization settings
    </h3>

    Click on your organization name in the lower left corner and select Organization details.
  </Step>

  <Step>
    <h3 id="enable-saml-sso">
      Enable SAML single sign-on
    </h3>

    Click the toggle next to `Enable SAML single sign-on`. Leave this screen open as you will refer back to it several times during the setup process.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-self-serve-1.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=d3187b4c890625601c5558c2ef7e7b65" size="lg" alt="Start SAML setup" force width="2136" height="1334" data-path="images/cloud/security/saml-self-serve-1.png" />
  </Step>

  <Step>
    <h3 id="create-idp-application">
      Create an application in your identity provider
    </h3>

    Create an application within your identity provider and copy the values on the `Enable SAML single sign-on` screen to your identity provider configuration. For more information on this step, refer to your specific identity provider below.

    * [Configure Okta SAML](#configure-okta-saml)
    * [Configure Google SAML](#configure-google-saml)
    * [Configure Azure (Microsoft) SAML](#configure-azure-microsoft-saml)
    * [Configure Duo SAML](#configure-duo-saml)

    <Tip>
      ClickHouse doesn't support identity provider initiated sign-in. To make it easy for your users to access ClickHouse Cloud, set up a bookmark for your users using this sign-in URL format: `https://console.clickhouse.cloud/?connection={orgId}` where the `{orgID}` is your organization ID on the Organization details page.
    </Tip>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-self-serve-2.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=6cd7587fa870f5f2217af6fbce526b88" size="lg" alt="Create identity provider application" force width="2952" height="1744" data-path="images/cloud/security/saml-self-serve-2.png" />
  </Step>

  <Step>
    <h3 id="add-metadata-url">
      Add the metadata URL to your SAML configuration
    </h3>

    Obtain the `Metadata URL` from your SAML provider. Return to ClickHouse Cloud, click `Next: Provide metadata URL` and paste the URL in the text box.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-self-serve-3.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=90b03dd92584ffbfd75c247157e970b5" size="lg" alt="Add metadata URL" force width="2962" height="1536" data-path="images/cloud/security/saml-self-serve-3.png" />
  </Step>

  <Step>
    <h3 id="get-domain-verification-code">
      Get domain verification code
    </h3>

    Click `Next: Verify your domains`. Enter your domain in the text box and click `Check domain`. The system will generate a random verification code for you to add to a TXT record with your DNS provider.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-self-serve-4.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=a21f5c10808325f147b323f822fc0f4e" size="lg" alt="Add domain to verify" force width="2954" height="1530" data-path="images/cloud/security/saml-self-serve-4.png" />
  </Step>

  <Step>
    <h3 id="verify-your-domain">
      Verify your domain
    </h3>

    Create a TXT record with your DNS provider. Copy the `TXT record name` to the TXT record Name field with your DNS provider. Copy the `Value` to the Content field with your DNS provider. Click `Verify and Finish` to complete the process.

    <Note>
      It may take several minutes for the DNS record to update and be verified. You may leave the setup page and return later to complete the process without restarting.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-self-serve-5.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=d686223a5eed6a9ccd8af64f3e1703d2" size="lg" alt="Verify your domain" force width="2962" height="1594" data-path="images/cloud/security/saml-self-serve-5.png" />
  </Step>

  <Step>
    <h3 id="update-defaults">
      Update default role and session timeout
    </h3>

    Once the SAML setup is complete, you can set the default role(s) all users will be assigned when they log in and also adjust session timeout settings. For a list of available system roles that may be assigned, please review [Console roles and permissions](/products/cloud/reference/security/console-roles).
  </Step>

  <Step>
    <h3 id="configure-your-admin-user">
      Configure your admin user
    </h3>

    <Note>
      Users configured with a different authentication method will be retained until an admin in your organization removes them.
    </Note>

    To assign your first admin user via SAML:

    1. Log out of [ClickHouse Cloud](https://console.clickhouse.cloud).
    2. In your identity provider, assign the admin user to the ClickHouse applications.
    3. Ask the user to log in via [https://console.clickhouse.cloud/?connection=\{orgId}](https://console.clickhouse.cloud/?connection=\{orgId}) (shortcut URL). This may be via a bookmark you created in the prior steps. The user won't appear in ClickHouse Cloud until their first login.
    4. If the default SAML role is anything other than Admin, the user may need to log out and log back in with their original authentication method to update the new SAML user's role.
       * For email + password accounts, please use `https://console.clickhouse.cloud/?with=email`.
       * For social logins, please click the appropriate button (**Continue with Google** or **Continue with Microsoft**)

    <Note>
      `email` in `?with=email` above is the literal parameter value, not a placeholder
    </Note>

    5. Log out one more time and log back in via the shortcut URL to complete the last step below.

    <Tip>
      To reduce steps, you may set your SAML default role to `Admin` initially. When the admin is assigned in your identity provider and logs in for the first time, they can change the default role to a different value.
    </Tip>
  </Step>

  <Step>
    <h3 id="remove-other-auth-methods">
      Remove other authentication methods
    </h3>

    Remove any users that are using a non-SAML method to complete the integration and restrict access to only users originating from your identity provider connection.
  </Step>
</Steps>

<h3 id="configure-okta-saml">
  Configure Okta SAML
</h3>

You will configure two App Integrations in Okta for each ClickHouse organization: one SAML app and one bookmark to house your direct link.

<Accordion title="1. Create a group to manage access">
  1. Log in to your Okta instance as an **Administrator**.

  2. Select **Groups** on the left.

  3. Click **Add group**.

  4. Enter a name and description for the group. This group will be used to keep users consistent between the SAML app and its related bookmark app.

  5. Click **Save**.

  6. Click the name of the group that you created.

  7. Click **Assign people** to assign users you would like to have access to this ClickHouse organization.
</Accordion>

<Accordion title="2. Create a bookmark app to enable users to seamlessly log in">
  1. Select **Applications** on the left, then select the **Applications** subheading.

  2. Click **Browse App Catalog**.

  3. Search for and select **Bookmark App**.

  4. Click **Add integration**.

  5. Select a label for the app.

  6. Enter the URL as `https://console.clickhouse.cloud/?connection={organizationid}`

  7. Go to the **Assignments** tab and add the group you created above.
</Accordion>

<Accordion title="3. Create a SAML app to enable the connection">
  1. Select **Applications** on the left, then select the **Applications** subheading.

  2. Click **Create App Integration**.

  3. Select SAML 2.0 and click Next.

  4. Enter a name for your application and check the box next to **Don't display application icon to users** then click **Next**.

  5. Use the following values to populate the SAML settings screen.

     | Field                          | Value                                                |
     | ------------------------------ | ---------------------------------------------------- |
     | Single Sign On URL             | Copy the Single Sign-On URL from the console         |
     | Audience URI (SP Entity ID)    | Copy the Service Provider Entity ID from the console |
     | Default RelayState             | Leave blank                                          |
     | Name ID format                 | Unspecified                                          |
     | Application username           | Email                                                |
     | Update application username on | Create and update                                    |

  6. Enter the following Attribute Statement.

     | Name  | Name format | Value      |
     | ----- | ----------- | ---------- |
     | email | Basic       | user.email |

  7. Click **Next**.

  8. Enter the requested information on the Feedback screen and click **Finish**.

  9. Go to the **Assignments** tab and add the group you created above.

  10. On the **Sign On** tab for your new app, click the **Copy metadata URL** button.

  11. Return to [Add the metadata URL to your SAML configuration](#add-metadata-url) to continue the process.
</Accordion>

<h3 id="configure-google-saml">
  Configure Google SAML
</h3>

You will configure one SAML app in Google for each organization and must provide your users the direct link (`https://console.clickhouse.cloud/?connection={organizationId}`) to bookmark if using multi-org SSO.

<Accordion title="Create a Google Web App">
  1. Go to your Google Admin console (admin.google.com).

  <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-google-app.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=5c7176b3ec276e3440423ffcfc8b20fe" size="md" alt="Google SAML App" force width="1224" height="608" data-path="images/cloud/security/saml-google-app.png" />

  2. Click **Apps**, then **Web and mobile apps** on the left.

  3. Click **Add app** from the top menu, then select **Add custom SAML app**.

  4. Enter a name for the app and click **Continue**.

  5. Copy the metadata URL and save it somewhere.

  6. Enter the ACS URL and Entity ID below.

     | Field     | Value                                                |
     | --------- | ---------------------------------------------------- |
     | ACS URL   | Copy the Single Sign-On URL from the console         |
     | Entity ID | Copy the Service Provider Entity ID from the console |

  7. Check the box for **Signed response**.

  8. Select **EMAIL** for the Name ID Format and leave the Name ID as **Basic Information > Primary email.**

  9. Click **Continue**.

  10. Enter the following Attribute mapping:

  | Field             | Value         |
  | ----------------- | ------------- |
  | Basic information | Primary email |
  | App attributes    | email         |

  13. Click **Finish**.

  14. To enable the app click **OFF** for everyone and change the setting to **ON** for everyone. Access can also be limited to groups or organizational units by selecting options on the left side of the screen.

  15. Return to [Add the metadata URL to your SAML configuration](#add-metadata-url) to continue the process.
</Accordion>

<h3 id="configure-azure-microsoft-saml">
  Configure Azure (Microsoft) SAML
</h3>

Azure (Microsoft) SAML may also be referred to as Azure Active Directory (AD) or Microsoft Entra.

<Accordion title="Create an Azure Enterprise Application">
  You will set up one application integration with a separate sign-on URL for each organization.

  1. Log on to the Microsoft Entra admin center.

  2. Navigate to **Applications > Enterprise** applications on the left.

  3. Click **New application** on the top menu.

  4. Click **Create your own application** on the top menu.

  5. Enter a name and select **Integrate any other application you don't find in the gallery (Non-gallery)**, then click **Create**.

       <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-azure-app.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=30fa3139f2a7aa26669e78e77f3ffd5e" size="md" alt="Azure Non-Gallery App" force width="980" height="624" data-path="images/cloud/security/saml-azure-app.png" />

  6. Click **Users and groups** on the left and assign users.

  7. Click **Single sign-on** on the left.

  8. Click **SAML**.

  9. Use the following settings to populate the Basic SAML Configuration screen.

     | Field                                      | Value                                                           |
     | ------------------------------------------ | --------------------------------------------------------------- |
     | Identifier (Entity ID)                     | Copy the Service Provider Entity ID from the console            |
     | Reply URL (Assertion Consumer Service URL) | Copy the Single Sign-On URL from the console                    |
     | Sign on URL                                | `https://console.clickhouse.cloud/?connection={organizationid}` |
     | Relay State                                | Blank                                                           |
     | Logout URL                                 | Blank                                                           |

  10. Add (A) or update (U) the following under Attributes & Claims:

      | Claim name                           | Format        | Source attribute |
      | ------------------------------------ | ------------- | ---------------- |
      | (U) Unique User Identifier (Name ID) | Email address | user.mail        |
      | (A) email                            | Basic         | user.mail        |
      | (U) /identity/claims/name            | Omitted       | user.mail        |

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/97BuEWXsPcdQd7-W/images/cloud/security/saml-azure-claims.png?fit=max&auto=format&n=97BuEWXsPcdQd7-W&q=85&s=f137632b8c419616df159d7307d0268e" size="md" alt="Attributes and Claims" force width="1242" height="816" data-path="images/cloud/security/saml-azure-claims.png" />

  11. Copy the metadata URL and return to [Add the metadata URL to your SAML configuration](#add-metadata-url) to continue the process.
</Accordion>

<h3 id="configure-duo-saml">
  Configure Duo SAML
</h3>

<Accordion title="Create a Generic SAML Service Provider for Duo">
  1. Follow the instructions for [Duo Single Sign-On for Generic SAML Service Providers](https://duo.com/docs/sso-generic).

  2. Use the following Bridge Attribute mapping:

     | Bridge Attribute | ClickHouse Attribute |
     | :--------------- | :------------------- |
     | Email Address    | email                |

  3. Use the following values to update your Cloud Application in Duo:

     | Field                                | Value                                                           |
     | :----------------------------------- | :-------------------------------------------------------------- |
     | Entity ID                            | Copy the Service Provider Entity ID from the console            |
     | Assertion Consumer Service (ACS) URL | Copy the Single Sign-On URL from the console                    |
     | Service Provider Login URL           | `https://console.clickhouse.cloud/?connection={organizationid}` |

  4. Copy the metadata URL and return to [Add the metadata URL to your SAML configuration](#add-metadata-url) to continue the process.
</Accordion>

<h2 id="how-it-works">
  How it works
</h2>

<h3 id="user-management-with-saml-sso">
  User management with SAML SSO
</h3>

For more information on managing user permissions and restricting access to only SAML connections, refer to [Manage cloud users](/products/cloud/guides/security/cloud-access-management/manage-cloud-users).

<h3 id="service-provider-initiated-sso">
  Service provider-initiated SSO
</h3>

We only utilize service provider-initiated SSO. This means users go to `https://console.clickhouse.cloud` and enter their email address to be redirected to the IdP for authentication. Users already authenticated via your IdP can use the direct link to automatically log in to your organization without entering their email address at the login page.

<h3 id="multi-org-sso">
  Multi-org SSO
</h3>

ClickHouse Cloud supports multi-organization SSO by providing a separate connection for each organization. Use the direct link (`https://console.clickhouse.cloud/?connection={organizationid}`) to log in to each respective organization. Be sure to log out of one organization before logging into another.

<Note>
  If you do not want users with your company's domain to be directed to an organization when they enter an email address at [https://console.clickhouse.cloud](https://console.clickhouse.cloud), submit a support ticket to manually update your SSO settings to remove this behavior.
</Note>

<h2 id="additional-information">
  Additional information
</h2>

Security is our top priority when it comes to authentication. For this reason, we made a few decisions when implementing SSO that we need you to know.

* **We only process service provider-initiated authentication flows.** Users must navigate to `https://console.clickhouse.cloud` and enter an email address to be redirected to your identity provider. Instructions to add a bookmark application or shortcut are provided for your convenience so your users don't need to remember the URL.

* **We don't automatically link SSO and non-SSO accounts.** You may see multiple accounts for your users in your ClickHouse user list even if they're using the same email address.

<h2 id="troubleshooting-common-issues">
  Troubleshooting Common Issues
</h2>

| Error                                                                                                                                                             | Cause                                                                                | Solution                                                                                                                                                                                                                       |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| There could be a misconfiguration in the system or a service outage                                                                                               | Identity provider initiated login                                                    | To resolve this error try using the direct link `https://console.clickhouse.cloud/?connection={organizationid}`. Follow the instructions for your identity provider above to make this the default login method for your users |
| You're directed to your identity provider, then back to the login page                                                                                            | The identity provider doesn't have the email attribute mapping                       | Follow the instructions for your identity provider above to configure the user email attribute and log in again                                                                                                                |
| User isn't assigned to this application                                                                                                                           | The user hasn't been assigned to the ClickHouse application in the identity provider | Assign the user to the application in the identity provider and log in again                                                                                                                                                   |
| You have multiple ClickHouse organizations integrated with SAML SSO and you're always logged into the same organization, regardless of which link or tile you use | You're still logged in to the first organization                                     | Log out, then log in to the other organization                                                                                                                                                                                 |
| The URL briefly shows `access denied`                                                                                                                             | Your email domain doesn't match the domain we have configured                        | Reach out to support for assistance resolving this error                                                                                                                                                                       |