SAML SSO setup

## How it works[​](#how-it-works "Direct link to How it works")

### User management with SAML SSO[​](#user-management-with-saml-sso "Direct link to User management with SAML SSO")

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

### Service provider-initiated SSO[​](#service-provider-initiated-sso "Direct link to Service provider-initiated SSO")

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.

### Multi-org SSO[​](#multi-org-sso "Direct link to Multi-org SSO")

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>, submit a support ticket to manually update your SSO settings to remove this behavior.

## Additional information[​](#additional-information "Direct link to Additional information")

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.

## Troubleshooting Common Issues[​](#troubleshooting-common-issues "Direct link to Troubleshooting Common Issues")

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

- [Before you begin](#before-you-begin)- [How to configure your IdP](#how-to-configure-your-idp)
    - [Steps](#steps)- [Access Organization settings](#access-organization-settings)- [Enable SAML single sign-on](#enable-saml-sso)- [Create an application in your identity provider](#create-idp-application)- [Add the metadata URL to your SAML configuration](#add-metadata-url)- [Get domain verification code](#get-domain-verification-code)- [Verify your domain](#verify-your-domain)- [Update default role and session timeout](#update-defaults)- [Configure your admin user](#configure-your-admin-user)- [Remove other authentication methods](#remove-other-auth-methods)- [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)- [How it works](#how-it-works)
      - [User management with SAML SSO](#user-management-with-saml-sso)- [Service provider-initiated SSO](#service-provider-initiated-sso)- [Multi-org SSO](#multi-org-sso)- [Additional information](#additional-information)- [Troubleshooting Common Issues](#troubleshooting-common-issues)

Was this page helpful?