SAML SSO setup

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/security/01_cloud_access_management/04_saml-sso-setup.md)

Enterprise plan feature

SAML SSO is available in the Enterprise plan. To upgrade, visit the plans page in the cloud console.

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

## Before you begin[​](#before-you-begin "Direct link to Before you begin")

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.

## How to configure your IdP[​](#how-to-configure-your-idp "Direct link to How to configure your IdP")

### Steps[​](#steps "Direct link to Steps")

Access Organization settings

### Access Organization settings[​](#access-organization-settings "Direct link to Access Organization settings")

Click on your organization name in the lower left corner and select Organization details.

Enable SAML single sign-on

### Enable SAML single sign-on[​](#enable-saml-sso "Direct link to Enable SAML single sign-on")

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.

![Start SAML setup](/docs/assets/ideal-img/saml-self-serve-1.853f431.2048.png)

Create an application in your identity provider

### Create an application in your identity provider[​](#create-idp-application "Direct link to Create an application in your identity provider")

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.

![Create identity provider application](/docs/assets/ideal-img/saml-self-serve-2.be31151.2048.png)

Add the metadata URL to your SAML configuration

### Add the metadata URL to your SAML configuration[​](#add-metadata-url "Direct link to Add the metadata URL to your SAML configuration")

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.

![Add metadata URL](/docs/assets/ideal-img/saml-self-serve-3.b4de217.2048.png)

Get domain verification code

### Get domain verification code[​](#get-domain-verification-code "Direct link to 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.

![Add domain to verify](/docs/assets/ideal-img/saml-self-serve-4.2c0cbec.2048.png)

Verify your domain

### Verify your domain[​](#verify-your-domain "Direct link to 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.

![Verify your domain](/docs/assets/ideal-img/saml-self-serve-5.f37af3a.2048.png)

Update default role and session timeout

### Update default role and session timeout[​](#update-defaults "Direct link to Update default role and session timeout")

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](/docs/cloud/security/console-roles).

Configure your admin user

### Configure your admin user[​](#configure-your-admin-user "Direct link to Configure your admin user")

Note

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

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=%7BorgId%7D) (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

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.

Remove other authentication methods

### Remove other authentication methods[​](#remove-other-auth-methods "Direct link to Remove other authentication 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.

### Configure Okta SAML[​](#configure-okta-saml "Direct link to Configure Okta SAML")

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

 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.

 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.

 3. Create a SAML app to enable the connection