> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.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 = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

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 support service provider-initiated SSO, multiple organizations using separate connections, and just-in-time provisioning. We also support [SCIM provisioning](/products/cloud/guides/security/cloud-access-management/scim-setup) in private preview, with support for Okta. We don't yet support 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-it-works">
  How it works
</h2>

Once SAML SSO is configured, users sign in through a service-provider-initiated flow:

1. The user goes to `https://console.clickhouse.cloud` and enters their email address (or uses your organization's direct link).
2. ClickHouse Cloud redirects them to your identity provider to authenticate.
3. On success, the identity provider redirects them back to ClickHouse Cloud.
4. ClickHouse Cloud signs them in, provisioning the account just-in-time on first login and assigning your configured default role.

The rest of this guide covers the one-time configuration.

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

<Steps>
  <Step title="Access Organization settings" id="access-organization-settings">
    Click on your organization name in the lower left corner and select Organization details.
  </Step>

  <Step title="Enable SAML single sign-on" id="enable-saml-sso">
    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-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-self-serve-1.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=2af4318b79cd49c0f5a06d5fd64782fb" size="lg" alt="Start SAML setup" force width="2136" height="1334" data-path="images/cloud/security/saml-self-serve-1.webp" />
  </Step>

  <Step title="Create an application in your identity provider" id="create-idp-application">
    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.

    * [Okta](#okta)
    * [Google](#google)
    * [Azure (Microsoft)](#azure)
    * [Duo](#duo)

    <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-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-self-serve-2.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=f7c06fdce593b1ca0c722cb2d3752d55" size="lg" alt="Create identity provider application" force width="2952" height="1744" data-path="images/cloud/security/saml-self-serve-2.webp" />
  </Step>

  <Step title="Add the metadata URL to your SAML configuration" id="add-metadata-url">
    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-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-self-serve-3.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=672062489d5e16a0b491427ee00a9004" size="lg" alt="Add metadata URL" force width="2962" height="1536" data-path="images/cloud/security/saml-self-serve-3.webp" />
  </Step>

  <Step title="Get domain verification code" id="get-domain-verification-code">
    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-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-self-serve-4.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=75bba9e57d9306bda8287741b85f93e4" size="lg" alt="Add domain to verify" force width="2954" height="1530" data-path="images/cloud/security/saml-self-serve-4.webp" />
  </Step>

  <Step title="Verify your domain" id="verify-your-domain">
    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. The verification value is valid for 48 hours from when it is first generated.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-self-serve-5.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=165803915413f9062183dabe3226fcf6" size="lg" alt="Verify your domain" force width="2962" height="1594" data-path="images/cloud/security/saml-self-serve-5.webp" />
  </Step>

  <Step title="Update default role and session timeout" id="update-defaults">
    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 title="Configure your admin user" id="configure-your-admin-user">
    <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 title="Remove other authentication methods" id="remove-other-auth-methods">
    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-idp">
  Configure your identity provider
</h3>

<Tabs>
  <Tab title="Okta" id="okta">
    You will configure two App Integrations in Okta for each ClickHouse organization: one SAML app and one bookmark to house your direct link.

    <h4 id="okta-create-group">
      Create a group to manage access
    </h4>

    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.

    <h4 id="okta-bookmark-app">
      Create a bookmark app to enable users to seamlessly log in
    </h4>

    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.

    <h4 id="okta-saml-app">
      Create a SAML app to enable the connection
    </h4>

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

  <Tab title="Google" id="google">
    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.

    <h4 id="google-web-app">
      Create a Google web app
    </h4>

    1. Go to your Google Admin console (admin.google.com).

           <Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-google-app.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=1a8582288b074a717e16a4ba4f7119d7" size="md" alt="Google SAML App" force width="1224" height="608" data-path="images/cloud/security/saml-google-app.webp" />

    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         |

    11. Click **Finish**.

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

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

  <Tab title="Azure (Microsoft)" id="azure">
    Azure (Microsoft) SAML may also be referred to as Azure Active Directory (AD) or Microsoft Entra.

    <h4 id="azure-enterprise-app">
      Create an Azure enterprise application
    </h4>

    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-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-azure-app.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=a3eac8489b0b6d7c89c48a2949f48ef6" size="md" alt="Azure Non-Gallery App" force width="980" height="624" data-path="images/cloud/security/saml-azure-app.webp" />

    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-detect-table-modification/qv-kMrZ4A7ARrVOd/images/cloud/security/saml-azure-claims.webp?fit=max&auto=format&n=qv-kMrZ4A7ARrVOd&q=85&s=4acdb07c6e5f0da454ff818eaea6ff72" size="md" alt="Attributes and Claims" force width="1242" height="816" data-path="images/cloud/security/saml-azure-claims.webp" />

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

  <Tab title="Duo" id="duo">
    <h4 id="duo-saml-provider">
      Create a generic SAML service provider for Duo
    </h4>

    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.
  </Tab>
</Tabs>

<h2 id="troubleshooting">
  Troubleshooting
</h2>

<AccordionGroup>
  <Accordion title="There could be a misconfiguration in the system or a service outage">
    **Cause:** identity-provider-initiated login, which isn't supported.

    **Fix:** use 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.
  </Accordion>

  <Accordion title="You're directed to your identity provider, then back to the login page">
    **Cause:** the identity provider doesn't have the email attribute mapping.

    **Fix:** follow the instructions for your identity provider above to configure the user email attribute, then log in again.
  </Accordion>

  <Accordion title="User isn't assigned to this application">
    **Cause:** the user hasn't been assigned to the ClickHouse application in the identity provider.

    **Fix:** assign the user to the application in the identity provider and log in again.
  </Accordion>

  <Accordion title="You always land in the same organization with multiple SAML orgs">
    **Cause:** you're still logged in to the first organization.

    **Fix:** log out, then log in to the other organization.
  </Accordion>

  <Accordion title="The URL briefly shows access denied">
    **Cause:** your email domain doesn't match the domain configured.

    **Fix:** reach out to support for assistance resolving this error.
  </Accordion>
</AccordionGroup>

<h2 id="faq">
  Frequently asked questions
</h2>

<AccordionGroup>
  <Accordion title="Does ClickHouse Cloud support identity-provider-initiated sign-in?">
    No — only service-provider-initiated flows. Users navigate to `https://console.clickhouse.cloud` and enter their email to be redirected to your identity provider. Set up a bookmark or direct link (`https://console.clickhouse.cloud/?connection={organizationid}`) so users don't have to remember the URL.
  </Accordion>

  <Accordion title="How do I use SAML SSO with multiple organizations?">
    ClickHouse Cloud supports multi-organization SSO with a separate connection per organization. Use the direct link (`https://console.clickhouse.cloud/?connection={organizationid}`) to log in to each one, and log out of one organization before logging into another. If you don't want users on your domain routed to an organization automatically when they enter their email at `https://console.clickhouse.cloud`, open a support ticket to remove that behavior.
  </Accordion>

  <Accordion title="Why do I see multiple accounts for the same user?">
    ClickHouse Cloud doesn't automatically link SSO and non-SSO accounts, so a user who has signed in both ways may appear more than once in your user list even with the same email address.
  </Accordion>
</AccordionGroup>

<h2 id="next-steps">
  Next steps
</h2>

* [Manage cloud users](/products/cloud/guides/security/cloud-access-management/manage-cloud-users) — manage permissions and restrict access to SAML connections only.
* [SCIM provisioning](/products/cloud/guides/security/cloud-access-management/scim-setup) — automate user and group provisioning (private preview).
* [Console roles and permissions](/products/cloud/reference/security/console-roles) — the roles you can assign as the default SAML role.