Keycloak single sign-on

Last reviewed 2023-02-27 UTC

---

This guide shows how to set up single sign-on (SSO) between Keycloak and your Cloud Identity or Google Workspace account by using SAML federation. The document assumes you have installed and are using Keycloak.

Note: Keycloak does not provide built-in integration for automatically provisioning users and groups to Cloud Identity or Google Workspace. To automate user and group provisioning, you must combine Keycloak with a provisioning tool such as Google Cloud Directory Sync, which lets you provision users and groups from an LDAP server.

Note: This article uses classic organizational SSO profiles instead of SAML profiles to set up single sign-on. Organizational SSO profiles let you choose whether to apply additional authentication challenges to users, which is not supported for SAML profiles.

Objectives

• Configure your Keycloak server so that it can be used as an identity provider (IdP) by Cloud Identity or Google Workspace.
• Configure your Cloud Identity or Google Workspace account so that it uses Keycloak for SSO.

Before you begin

1. If you don't have a Cloud Identity account, sign up for an account.
2. Make sure your Cloud Identity account has super-admin privileges.
3. If your Keycloak server is used to manage more than one realm, decide which realm you want to use for the federation.
4. Ensure that you have admin access to the selected realm.

Configuring Keycloak

Before enabling SSO in Cloud Identity or Google Workspace, you must configure your Keycloak server by creating a client.

Creating a client

You start by creating a client in Keycloak:

1. Log in to Keycloak and open the administration console.
2. Select the realm that you want to use for federation.
3. In the menu, select Clients.
4. Click Create client.

5. Configure the following settings for the client:

   KeyCloak 19 or later

   • Client type: SAML
   • Client ID: google.com
   • Name: Google Cloud

   KeyCloak 18 or earlier

   • Client ID: google.com
   • Client Protocol: saml
   • Client SAML Endpoint: leave blank
   Note: For SAML federation to work, Client ID must be google.com.

6. Click Save.

7. Specify the details for the google.com client by configuring the following settings:

   KeyCloak 19 or later

   On the Settings tab:

   • Valid Redirect URIs: https://www.google.com/*
   • Name ID Format: email
   • Force Name ID Format: on
   • Sign documents: off
   • Sign Assertions: on

   On the Keys tab:

   • Client Signature Required: off

   KeyCloak 18 or earlier

   • Name: A name such as Google Cloud
   • Sign Assertions: on
   • Client Signature Required: off
   • Force Name ID Format: on
   • Name ID Format: email
   • Valid Redirect URIs: https://www.google.com/*

   Keep the default values for all other settings.

8. Click Save.

Exporting the signing certificate

After Keycloak authenticates a user, it passes a SAML assertion to Cloud Identity or Google Workspace. To enable Cloud Identity and Google Workspace to verify the integrity and authenticity of that assertion, Keycloak signs the assertion with a special token-signing key and provides a certificate that enables Cloud Identity or Google Workspace to check the signature.

You now export the signing certificate from Keycloak:

1. In the menu, select Realm settings.
2. Select the Keys tab.

3. Find the row for Algorithm: RS256 and Use: SIG and select Certificate.

   A dialog that contains a base64-encoded certificate appears.

4. Copy the base64-encoded certificate value to the clipboard.

Converting the signing certificate

Before you can use the signing certificate, you must convert it into PEM format by adding a header and footer.

1. Open a text editor such as Notepad or vim.

2. Paste the following header, followed by a newline:

   -----BEGIN CERTIFICATE-----
   

3. Paste the base64-encoded certificate from the clipboard.

4. Add a newline and paste the following footer:

   -----END CERTIFICATE-----
   

   The output is similar to the following:

   -----BEGIN CERTIFICATE-----
   MIICmzCCAYMCBgF7v8/V1TANBgkq...
   -----END CERTIFICATE-----
   

5. Save the file to a temporary location on your computer.

Configuring Cloud Identity

You now configure single sign-on in Cloud Identity or Google Workspace.

1. Open the Admin Console and log in using a super-admin user.
2. In the menu, click Show more and go to Security > Authentication > SSO with third-party IdP.

3. Click Add SSO profile.

   Note: Don't use the Add SAML profile button.

4. Set Setup SSO with third party identity provider to enabled.

5. Enter the following settings:

   • Sign-in page URL:

     KeyCloak 17 or later

     https://KEYCLOAK/realms/REALM/protocol/saml
     

     KeyCloak 16 or earlier

     https://KEYCLOAK/auth/realms/REALM/protocol/saml
     

   • Sign-out page URL:

     KeyCloak 17 or later

     https://KEYCLOAK/realms/REALM/protocol/openid-connect/logout
     

     KeyCloak 16 or earlier

     https://KEYCLOAK/auth/realms/REALM/protocol/openid-connect/logout?redirect_uri=https://KEYCLOAK/auth/realms/REALM/account/
     

   • Use a domain specific issuer: clear

   • Change password URL:

     KeyCloak 17 or later

     https://KEYCLOAK/realms/REALM/account
     

     KeyCloak 16 or earlier

     https://KEYCLOAK/auth/realms/REALM/account
     

   In all URLs, replace the following:

   • KEYCLOAK: the fully qualified domain name of your Keycloak server
   • REALM: the name of your selected realm

6. Under Verification certificate, click Upload certificate, and then pick the token signing certificate that you downloaded previously.

7. Click Save.

8. Sign out of the Admin Console.

Testing single sign-on

You've completed the single sign-on configuration. You can now check whether SSO works as intended.

1. Choose a Keycloak user that satisfies the following criteria:

   • The user has an email address.
   • The email address corresponds to the primary email address of an existing user in your Cloud Identity or Google Workspace account.

   • The Cloud Identity user does not have super-admin privileges.

     User accounts that have super-admin privileges must always sign in by using Google credentials, so they aren't suitable for testing single sign-on.

2. Open a new browser window and go to the Google Cloud console.

3. On the Google sign-in page, enter the email address of the user account, and then click Next.

   

   You are redirected to Keycloak.

4. Enter your Keycloak credentials, and then click Log in.

   After successful authentication, Keycloak redirects you back to the Google Cloud console. Because this is the first login for this user, you're asked to accept the Google terms of service and privacy policy.

5. If you agree to the terms, click Accept.

6. You are redirected to the Google Cloud console, which asks you to confirm preferences and accept the Google Cloud terms of service. If you agree to the terms, click Yes, and then click Agree and Continue.

7. Click the avatar icon, and then click Sign out.

   You are redirected to Keycloak, logged out, and redirected to www.google.com.

If you have trouble signing in, keep in mind that user accounts with super-admin privileges can bypass SSO, so you can still use the Admin console to verify or change settings.

What's next

• Learn more about Identity and Access Management (IAM).
• Review the best practices for managing identity and access.