|
| 1 | +--- |
| 2 | +sidebar_label: SAML SSO Setup |
| 3 | +slug: /en/cloud/security/saml-setup |
| 4 | +title: SAML SSO Setup |
| 5 | +description: How to set up SAML SSO with ClickHouse Cloud |
| 6 | +--- |
| 7 | + |
| 8 | +# SAML SSO Setup |
| 9 | + |
| 10 | +:::note |
| 11 | +SAML SSO is in private preview. Please contact [email protected] to see if this is available for your organization. |
| 12 | +::: |
| 13 | + |
| 14 | +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). |
| 15 | + |
| 16 | +We currently support service provider initiated SSO, multiple organizations using separate connections, and just-in-time provisioning. We do not yet support system for cross-domain identity management (SCIM) or attribute mapping. |
| 17 | + |
| 18 | +## Before you begin |
| 19 | + |
| 20 | +You will need Admin permissions in your IdP and the **Admin** role in your ClickHouse Cloud organization. After setting up your connection within your IdP, contact us with the information requested in the procedure below to complete the process. |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +## How to Configure Your IdP |
| 25 | + |
| 26 | +### All IdPs |
| 27 | + |
| 28 | +All setups require your organization ID. To obtain your organization ID: |
| 29 | +1. Sign in to your [ClickHouse Cloud](https://console.clickhouse.cloud) organization. |
| 30 | + |
| 31 | + <img src='https://github.com/ClickHouse/clickhouse-docs/assets/110556185/0cb69e9e-1506-4eb4-957d-f104d8c15f3a' |
| 32 | + class="image" |
| 33 | + alt="Organization ID" |
| 34 | + style={{width: '60%', display: 'inline'}} /> |
| 35 | + |
| 36 | +3. In the lower left corner, click on your organization name under **Organization**. |
| 37 | + |
| 38 | +4. In the pop-up menu, select **Organization details**. |
| 39 | + |
| 40 | +5. Make note of your **Organization ID** to use below. |
| 41 | + |
| 42 | +### Configuring Okta SAML |
| 43 | + |
| 44 | +You will configure two App Integrations in Okta for each ClickHouse organization: one SAML app and one bookmark to house your direct link. |
| 45 | + |
| 46 | +#### Create a group to manage access: |
| 47 | + |
| 48 | +1. Log in to your Okta instance as an **Administrator**. |
| 49 | + |
| 50 | +2. Select **Groups** on the left. |
| 51 | + |
| 52 | +3. Click **Add group**. |
| 53 | + |
| 54 | +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. |
| 55 | + |
| 56 | +5. Click **Save**. |
| 57 | + |
| 58 | +6. Click the name of the group that you created. |
| 59 | + |
| 60 | +7. Click **Assign people** to assign users you would like to have access to this ClickHouse organization. |
| 61 | + |
| 62 | +#### Create a bookmark app to enable users to seamlessly log in: |
| 63 | + |
| 64 | +1. Select **Applications** on the left, then select the **Applications** subheading. |
| 65 | + |
| 66 | +2. Click **Browse App Catalog**. |
| 67 | + |
| 68 | +3. Search for and select **Bookmark App**. |
| 69 | + |
| 70 | +4. Click **Add integration**. |
| 71 | + |
| 72 | +5. Select a label for the app. |
| 73 | + |
| 74 | +6. Enter the URL as `https://console.clickhouse.cloud?connection={organizationid}` |
| 75 | + |
| 76 | +7. Go to the **Assignments** tab and add the group you created above. |
| 77 | + |
| 78 | +#### Create a SAML app to enable the connection: |
| 79 | + |
| 80 | +1. Select **Applications** on the left, then select the **Applications** subheading. |
| 81 | + |
| 82 | +2. Click **Create App Integration**. |
| 83 | + |
| 84 | +3. Select SAML 2.0 and click Next. |
| 85 | + |
| 86 | +4. Enter a name for your application and check the box next to **Do not display application icon to users** then click **Next**. |
| 87 | + |
| 88 | +5. Use the following values to populate the SAML settings screen. |
| 89 | + |
| 90 | + | Field | Value | |
| 91 | + |--------------------------------|-------| |
| 92 | + | Single Sign On URL | https://auth.clickhouse.cloud/login/callback?connection={organizationid} | |
| 93 | + | Audience URI (SP Entity ID) | urn:auth0:ch-production:{organizationid} | |
| 94 | + | Default RelayState | Leave blank | |
| 95 | + | Name ID format | Unspecified | |
| 96 | + | Application username | Email | |
| 97 | + | Update application username on | Create and update | |
| 98 | + |
| 99 | +7. Enter the following Attribute Statement. |
| 100 | + |
| 101 | + | Field | Value | |
| 102 | + |-------------|------------| |
| 103 | + | Name | Basic | |
| 104 | + | Name format | user.email | |
| 105 | + |
| 106 | +8. Click **Next**. |
| 107 | + |
| 108 | +9. Enter the requested information on the Feedback screen and click **Finish**. |
| 109 | + |
| 110 | +10. Go to the **Assignments** tab and add the group you created above. |
| 111 | + |
| 112 | +11. On the **Sign On** tab for your new app, click the **View SAML setup instructions** button. |
| 113 | + |
| 114 | + <img src='https://github.com/ClickHouse/clickhouse-docs/assets/110556185/8d316548-5fb7-4d3a-aad9-5d025c51f158' |
| 115 | + class="image" |
| 116 | + alt="Okta SAML Setup Instructions" |
| 117 | + style={{width: '60%', display: 'inline'}} /> |
| 118 | + |
| 119 | +13. Gather these three items and go to [Submit a Support Case](#submit-a-support-case) below complete the process. |
| 120 | + - Identity Provider Single Sign-On URL |
| 121 | + - Identity Provider Issuer |
| 122 | + - X.509 Certificate |
| 123 | + |
| 124 | +### Configuring Google SAML |
| 125 | + |
| 126 | +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. |
| 127 | + |
| 128 | +1. Go to your Google Admin console (admin.google.com). |
| 129 | + |
| 130 | + <img src='https://github.com/ClickHouse/clickhouse-docs/assets/110556185/b931bd12-2fdf-4e25-b0b5-1170bbd20760' |
| 131 | + class="image" |
| 132 | + alt="Google SAML App" |
| 133 | + style={{width: '60%', display: 'inline'}} /> |
| 134 | + |
| 135 | +2. Click **Apps**, then **Web and mobile apps** on the left. |
| 136 | + |
| 137 | +3. Click **Add app** from the top menu, then select **Add custom SAML app**. |
| 138 | + |
| 139 | +4. Enter a name for the app and click **Continue**. |
| 140 | + |
| 141 | +5. Gather these two items and go to [Submit a Support Case](#submit-a-support-case) below to submit the information to us. NOTE: If you complete the setup before copying this data, click **DOWNLOAD METADATA** from the app's home screen to get the X.509 certificate. |
| 142 | + - SSO URL |
| 143 | + - X.509 Certificate |
| 144 | + |
| 145 | +7. Enter the ACS URL and Entity ID below. |
| 146 | + |
| 147 | + | Field | Value | |
| 148 | + |-----------|-------| |
| 149 | + | ACS URL | https://auth.clickhouse.cloud/login/callback?connection={organizationid} | |
| 150 | + | Entity ID | urn:auth0:ch-production:{organizationid} | |
| 151 | + |
| 152 | +8. Check the box for **Signed response**. |
| 153 | + |
| 154 | +9. Select **EMAIL** for the Name ID Format and leave the Name ID as **Basic Inforamtion > Primary email.** |
| 155 | + |
| 156 | +10. Click **Continue**. |
| 157 | + |
| 158 | +11. Enter the following Attribute mapping: |
| 159 | + |
| 160 | + | Field | Value | |
| 161 | + |-------------------|---------| |
| 162 | + | Basic information | Primary email | |
| 163 | + | App attributes | email | |
| 164 | + |
| 165 | +13. Click **Finish**. |
| 166 | + |
| 167 | +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. |
| 168 | + |
| 169 | +### Configuring Azure (Microsoft) SAML |
| 170 | + |
| 171 | +Azure (Microsoft) SAML may also be referred to as Azure Active Directory (AD) or Microsoft Entra. |
| 172 | + |
| 173 | +You will set up one application integration with a separate sign-on URL for each organization. |
| 174 | + |
| 175 | +1. Log on to the Microsoft Entra admin center. |
| 176 | + |
| 177 | +2. Navigate to **Applications > Enterprise** applications on the left. |
| 178 | + |
| 179 | +3. Click **New application** on the top menu. |
| 180 | + |
| 181 | +4. Click **Create your own application** on the top menu. |
| 182 | + |
| 183 | +5. Enter a name and select **Integrate any other application you don't find in the gallery (Non-gallery)**, then click **Create**. |
| 184 | + |
| 185 | + <img src='https://github.com/ClickHouse/clickhouse-docs/assets/110556185/5577b3ed-56e0-46b9-a9f7-80aa27f9a97a' |
| 186 | + class="image" |
| 187 | + alt="Azure Non-Gallery App" |
| 188 | + style={{width: '60%', display: 'inline'}} /> |
| 189 | + |
| 190 | +6. Click **Users and groups** on the left and assign users. |
| 191 | + |
| 192 | +7. Click **Single sign-on** on the left. |
| 193 | + |
| 194 | +8. Click **SAML**. |
| 195 | + |
| 196 | +9. Use the following settings to populate the Basic SAML Configuration screen. |
| 197 | + |
| 198 | + | Field | Value | |
| 199 | + |---------------------------|-------| |
| 200 | + | Identifier (Entity ID) | urn:auth0:ch-production:{organizationid} | |
| 201 | + | Reply URL (Assertion Consumer Service URL) | https://auth.clickhouse.cloud/login/callback?connection={organizationid} | |
| 202 | + | Sign on URL | https://console.clickhouse.cloud?connection={organizationid} | |
| 203 | + | Relay State | Blank | |
| 204 | + | Logout URL | Blank | |
| 205 | + |
| 206 | +11. Add (A) or update (U) the following under Attributes & Claims: |
| 207 | + |
| 208 | + | Claim name | Format | Source attribute | |
| 209 | + |--------------------------------------|---------------|------------------| |
| 210 | + | (U) Unique User Identifier (Name ID) | Email address | user.mail | |
| 211 | + | (A) email | Basic | user.mail | |
| 212 | + | (U) /identity/claims/name | Omitted | user.mail | |
| 213 | + |
| 214 | + <img src='https://github.com/ClickHouse/clickhouse-docs/assets/110556185/b59af49f-4cdc-47f4-99e0-fe4a7ffbceda' |
| 215 | + class="image" |
| 216 | + alt="Attributes and Claims" |
| 217 | + style={{width: '60%', display: 'inline'}} /> |
| 218 | + |
| 219 | +12. Gather these two items and go to [Submit a Support Case](#submit-a-support-case) below to complete the process: |
| 220 | + - Login URL |
| 221 | + - Certificate (Base64) |
| 222 | + |
| 223 | +### Submit a Support Case |
| 224 | + |
| 225 | +1. Return to the ClickHouse Cloud console. |
| 226 | + |
| 227 | +2. Select **Help** on the left, then the Support submenu. |
| 228 | + |
| 229 | +3. Click **New case**. |
| 230 | + |
| 231 | +4. Enter the subject "SAML SSO Setup". |
| 232 | + |
| 233 | +5. In the description, paste any links gathered from the instructions above and attach the certificate to the ticket. |
| 234 | + |
| 235 | +6. Please also let us know which domains should be allowed for this connection (e.g. domain.com, domain.ai, etc.). |
| 236 | + |
| 237 | +7. Create a new case. |
| 238 | + |
| 239 | +8. We will complete the setup within ClickHouse Cloud and let you know when it's ready to test. |
| 240 | + |
| 241 | +9. Sign in with your original authentication method to assign the Admin role to your new SSO account. |
| 242 | + - For email + password accounts, please use `https://console.clickhouse.cloud?with=email`. |
| 243 | + - For social logins, please click the appropriate button (**Continue with Google** or **Continue with Microsoft**) |
| 244 | + |
| 245 | +## How It Works |
| 246 | + |
| 247 | +### Service Provider Initiated SSO |
| 248 | + |
| 249 | +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. |
| 250 | + |
| 251 | +### Assigning User Roles |
| 252 | + |
| 253 | +Users will appear in your ClickHouse Cloud console after they are assigned to your IdP application and log in for the first time. At least one SSO user should be assigned the Admin role in your organization. Use social login or `https://console.clickhouse.cloud?with=email` to log in with your original authentication method to update your SSO role. |
| 254 | + |
| 255 | +### Removing Non-SSO Users |
| 256 | + |
| 257 | +Once you have SSO users set up and have assigned at least one user the Admin role, the Admin can remove users using other methods (e.g. social authentication or user ID + password). Google authentication will continue to work after SSO is set up. User ID + password users will be automatically redirected to SSO based on their email domain unless users use `https://console.clickhouse.cloud?with=email`. |
| 258 | + |
| 259 | +### Managing Users |
| 260 | + |
| 261 | +ClickHouse Cloud currently implements SAML for SSO. We have not yet implemented SCIM to manage users. This means SSO users must be assigned to the application in your IdP to access your ClickHouse Cloud organization. Users must log in to ClickHouse Cloud once to appear in the **Users** area in the organization. When users are removed in your IdP, they will not be able to log in to ClickHouse Cloud using SSO. However, the SSO user will still show in your organization until and administrator manually removes the user. |
| 262 | + |
| 263 | +### Multi-Org SSO |
| 264 | + |
| 265 | +ClickHouse Cloud supports multi-organization SSO by providing a separate connection for each organization. Use the direct link (`https://console.clickhouse.cloud?organization={organizationid}`) to log in to each respective organziation. Be sure to log out of one organization before logging into another. |
| 266 | + |
| 267 | +## Additional Information |
| 268 | + |
| 269 | +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. |
| 270 | + |
| 271 | +- **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. |
| 272 | + |
| 273 | +- **All users assigned to your app via your IdP must have the same email domain. ** If you have vendors, contractors or consultants you would like to have access to your ClickHouse account, they must have an email address with the same domain (e.g. [email protected]) as your employees. |
| 274 | + |
| 275 | +- **We do not automatically link SSO and non-SSO accounts.** You may see multiple accounts for your users in your ClickHouse user list even if they are using the same email address. |
0 commit comments