SAML SSO setup

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

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.

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.

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 to continue the process.

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.

Create a Google web app

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

   

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 to continue the process.

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

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.

   

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

    

11. Copy the metadata URL and return to Add the metadata URL to your SAML configuration to continue the process.

Create a generic SAML service provider for Duo

1. Follow the instructions for Duo Single Sign-On for Generic SAML Service Providers.

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 to continue the process.