Keycloak single sign-on

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.

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.
  5. Configure the following settings for the client:

    1. Client ID: google.com
    2. Client Protocol: saml
    3. Client SAML Endpoint: leave blank
  6. Click Save.

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

    1. Name: Enter a name such as Google Cloud
    2. Sign Assertions: on
    3. Client Signature Required: off
    4. Force Name ID Format: on
    5. Name ID Format: email
    6. 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 token-signing certificate from Keycloak:

  1. In the menu, select Realm settings.
  2. Select the Keys tab.
  3. In the RS256 row, select Certificate.

A dialog that contains a base64-encoded certificate appears.

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

Converting the signing certificate

Before you can use the certificate, you must decode it.

Windows

  1. Open a text editor such as Notepad.
  2. Paste the base64-encoded certificate from the clipboard.
  3. Save the file to a location where you can find it later.
  4. Open a command prompt.
  5. Decode the certificate and save the results in a new file:

     certutil -decode INPUT-FILE OUTPUT-FILE

    Example:

    certutil -decode keycloak.txt keycloak.cer

Linux or macOS

  1. Open a text editor
  2. Paste the base64-encoded certificate from the clipboard.
  3. Save the file to a location where you can find it later.
  4. Open a Terminal window and create the file:

    cat INPUT-FILE | base64 -d > OUTPUT-FILE

    Example:

    cat keycloak.txt | base64 -d > keycloak.cer

Configuring Cloud Identity

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

  1. In the Admin console, click Security > Settings.
  2. Click Set up single sign-on (SSO) with a third party IdP.
  3. Ensure that Setup SSO with third party identity provider is enabled.
  4. Enter the following settings:

    • Sign-in page URL: https://KEYCLOAK/auth/realms/REALM/protocol/saml
    • Sign-out page URL: https://KEYCLOAK/auth/realms/REALM/protocol/openid-connect/logout?redirect_uri=https%3A%2F%2Fwww.google.com%2F
    • Use a domain specific issuer: clear
    • Change password URL: 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
  5. Under Verification certificate, click Choose file, and then pick the decoded token-signing certificate that you created previously.

  6. Click Save.

  7. On the next page, confirm that you intend to enable single sign-on, and if you agree to the terms, click I understand and agree.

  8. To sign out of the Admin console, click the avatar, and then click Sign out.

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.

    Google Sign in page.

    You are redirected to Keycloak.

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

    After successful authentication, Keycloak redirects you back to the 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 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