Configure OIDC providers for GKE Identity Service

This document is for platform administrators, or whoever manages identity setup in your organization. It explains how to configure your chosen OpenID Connect (OIDC) identity provider for GKE Identity Service.

Register GKE Identity Service with your provider

GKE Identity Service setup requires a single client ID and secret from your identity provider. This ID and secret are used by GKE Identity Service when connecting to the provider as part of the authentication flow for users. To get these, you need to register GKE Identity Service with your provider as a client application, following the standard procedure for your chosen provider. You can find some specific registration details for popular providers in the next section.

For redirect URLs, specify the following values:

  • https://console.cloud.google.com/kubernetes/oidc is the redirect URL for the Google Cloud console.
  • http://localhost:PORT/callback is the redirect URL for the gcloud CLI. You can specify any port number that is higher than 1024.
  • APISERVER-URL:11001/finish-login is the redirect URL if you choose to authenticate using FQDN access. Replace APISERVER-URL with the FQDN of the cluster's Kubernetes API server. For example, if the APISERVER-URL is https://apiserver.company.com, then the redirect_uri should be https://apiserver.company.com:11001/finish-login.

Save the client ID and secret you get from the registration step. Share these details with cluster administrators who need to set up the GKE Identity Service.

Identity provider setup information

This section provides additional provider-specific information for registering GKE Identity Service. If your provider is listed here, register GKE Identity Service with your provider as a client application using the following instructions.

Microsoft AD FS

Use a set of AD FS management wizards to configure your AD FS server and AD user database.

  1. Open the AD FS management pane.

  2. Select Application Groups > Actions > Add an Application Group.

  3. Select Server Application. Enter a name and description of your choice. Click Next.

  4. Enter your two redirect URLs, as specified above. You are given a client ID. This is how the AD FS server identifies GKE Identity Service. Save the client ID for later.

  5. Select Generate a shared secret. GKE Identity Service uses this secret to authenticate to the AD FS server. Save the secret for later.

Configuring security groups (optional)

  1. In AD FS management, select Relying party trusts > Add a new relying party trust.

  2. Select Claims aware, and click Start.

  3. Select Enter data about relying party manually.

  4. Enter a display name.

  5. Skip the next two steps.

  6. Enter a Relying party trust identifier. Suggestion: token-groups-claim.

  7. For Access control policy, select Permit everyone. This means that all users share their security group information with the gcloud CLI and Google Cloud console.

  8. Click Finish.

Mapping LDAP attributes to claim names

  1. In AD FS management, select Relying party trusts > Edit claim issuance policy.

  2. Select Send LDAP Attributes as Claims, and click Next.

  3. For Claim rule name, enter groups.

  4. For Attribute store, select Active Directory.

  5. In the table, for LDAP Attribute, select:

    • AD FS version 5.0 and later: Token-Groups Qualified by Domain name
    • AD FS versions before 5.0: Token Groups - Qualified Names

  6. For Outgoing Claim Type, select:

    • AD FS version 5.0 and later: Group
    • AD FS versions before 5.0: groups

  7. Click Finish, and click Apply.

Registering GKE Identity Service with AD FS

Open a PowerShell window in Administrator mode, and enter this command:

Grant-AD FSApplicationPermission `
  -ClientRoleIdentifier "[CLIENT_ID]" `
 -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] `
  -ScopeName "allatclaims", "openid"

Replace the following:

  • [CLIENT_ID] is the client ID that you obtained previously.

  • [SERVER_ROLE_IDENTIFIER] is the claim identifier you entered previously. Recall that the suggested identifier was token-groups-claim.

Azure AD

Register an OAuth client with Azure

To register an OAuth client with Azure, complete the steps at the following links:

  1. If you haven't done so already, Set up a tenant on Azure Active Directory.

  2. Register an application with the Microsoft identity platform.

  3. Open the App registrations page on the Azure Portal and select your application by name.

  4. Create a Client Secret.

    1. Click Add a certificate or secret under Essentials. A list of certificates and a list of secrets appears.

    2. Click New client secret. Name your secret and click Add.

    3. Save the Value* of the secret in a secure location. You will not be able to retrieve it after you close or refresh the page.

  5. Add redirect URIs.

    1. Return to the application page.

    2. Select Add a Redirect URI under Essentials. The Authentication page appears.

    3. Choose Add a platform, and panel named Configure platforms appears on the right.

    4. Choose Web. Under Redirect URIs, enter http://localhost:PORT/callback for the gcloud CLI login flow. Pick a PORT greater than 1024. Click the Configure button.

    5. Click the Add URI button to add another URI, https://console.cloud.google.com/kubernetes/oidc, for the Google Cloud console login.

    6. Click the Save button on the top.

Now your client registration is complete. You should have the following info to share with your cluster administrator:

  • Issuer URI: https://login.microsoftonline.com/TENANT_ID/v2.0. The tenant ID is displayed as the Directory (tenant) ID on the Application page on Azure portal.

  • Client ID: The client ID is displayed as the Application (client) ID on the Application page on Azure portal.

  • Client Secret: You were given this in the last step. You won't be able to retrieve this if you close the page upon secret creation. Make sure to save the value in a secure location (or generate a new secret if you lose track of the previous one).

Advanced setup for Azure AD

Consider using this advanced setup only when you want to set up clusters with Azure AD group-based authorization policies where users of the clusters belong to more than 200 Azure AD groups. The advanced setup for Azure AD supports the following platforms:

  • On-premises GKE clusters (both VMware and bare metal): From GKE Enterprise 1.14
  • Anthos clusters on AWS: From GKE Enterprise 1.14 (Kubernetes version of 1.25 or later)
  • Anthos clusters on Azure: From GKE Enterprise 1.14 (Kubernetes version of 1.25 or later)
  • Anthos clusters on AWS (previous generation): From GKE Enterprise 1.14

Before you begin, make sure that each user has an associated email address configured as their identifier in Azure AD. GKE Identity Service uses the user's email to assert the user's identity and authenticate the request.

You need to ensure that the client you registered in the previous section has delegated permissions to get user and group information from the Microsoft Graph API. These permissions let the GKE Identity Service plugin access the Microsoft Graph API endpoints from which group information is fetched. Without this step, GKE Identity Service cannot list the user’s groups, and RBAC authorization policies based on groups will not work as expected.

You need to have global admin or organization admin permissions to perform this setup step.

  1. Sign in to the Azure portal.
  2. If you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant containing your client app's registration.
  3. Select Azure Active Directory - App registrations, and then select your client application.
  4. Select API permissions - Add a permission - Microsoft Graph - Delegated permissions.
  5. Under the Group tab, check Group.Read.All. Under the User tab, check User.Read.All.
  6. Click Add permissions to complete the process.
  7. Grant consent on behalf of all users by clicking the Grant admin consent for... button. You can find more about granting admin consent in More on API permissions and admin consent.

Share the identity provider details

Share the following provider information with your cluster administrator for cluster setup:

  • The provider's issuer URI
  • The client secret
  • The client ID
  • The redirect URI and port you specified for the gcloud CLI
  • The user name field (claim) that your provider uses to identify users in its tokens (the assumed default when configuring clusters is sub)
  • The group name field (claim) that your provider uses to return security groups, if any.
  • Any additional scopes or parameters that are specific to your provider, as described in the previous section. For example, if your authorization server prompts for consent for authentication with Microsoft Azure and Okta, the cluster admin needs to specify prompt=consent as a parameter. If you have configured ADFS to provide security group information, the relevant additional parameter is resource=token-groups-claim (or whatever you chose as your relying party trust identifier).
  • (Optional) If your provider is not using a certificate signed by a public certificate authority (for example if you are using self-signed certificates), then you will need a certificate (or certificate chain) of the identity provider. The certificate (or certificate chain) needs to contain the root certificate at a minimum (partial chains are accepted, as long as the chain is contiguous back to the root certificate). When providing this value in ClientConfig, it needs to be formatted as a base64 encoded string. To create the string, concatenate the complete PEM-encoded certificate(s) into a single string and then base64 encode it.

You can see a complete list of GKE Identity Service configuration parameters in Configure clusters.

What's next

Your cluster administrator can set up GKE Identity Service for individual clusters or a fleet.