Configure OIDC providers for GKE Identity Service

This document explains how to configure your chosen OpenID Connect (OIDC) identity provider for GKE Identity Service. To find out more about GKE Identity Service, see the overview.

This document is for platform administrators, or whoever manages identity setup in your organization. If you are a cluster administrator or application operator, ask your platform administrator to follow this section before you start Configure your clusters for fleet-level GKE Identity Service or Configure clusters for GKE Identity Service with OIDC.

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.

Register your provider through an alternative authentication process

An alternative process to register your provider is to authenticate directly through the GKE Identity Service server. If you're using an OIDC or Azure AD provider, you must update your redirect_uri according to the format of your cluster URL. The redirect_uri has the following format:

      https://CLUSTER-SERVER-FQDN.com:8443/finish-login

Replace CLUSTER-SERVER-FQDN with the name of the cluster server.

For example, if the cluster URL is https://cluster.company.com, then the redirect_uri should be https://cluster.company.com:8443/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. You must ensure that you have done the following:

  • Configure your domain name service (DNS) to resolve CLUSTER-SERVER-FQDN to the control plane VIPs (virtual IP addresses). Users can access the cluster using this domain name.
  • Use a Server Name Indication (SNI) certificate issued by your trusted enterprise Certificate Authority (CA). This certificate specifically mentions CLUSTER-SERVER-FQDN as a valid domain, eliminating potential certificate warnings for users. You can provide the SNI certificate during cluster creation. For more information on authentication using SNI certificates, see SNI certificate authentication.
  • If SNI certificates are not feasible, configure all user devices to trust the cluster-CA certificate. This avoids certificate warnings but requires distributing the cluster-CA certificate to all users.

For more information on user login access using these certificates, see Set up a user login access through an alternative authentication process

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 provider details

Ensure the cluster administrator has the following required information for cluster configuration:

  • 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.