GKE Identity Service diagnostic utility

The GKE Identity Service diagnostic utility helps you to troubleshoot FQDN-based authentication issues. If you're experiencing difficulties authenticating to a cluster using a specific OIDC provider, you can enable the tool and use it to quickly identify configuration issues by simulating sign-in flows with your OIDC provider.

The diagnostic utility is only available on individual clusters running GKE Enterprise 1.32 or higher and only supports OIDC.

Enable the diagnostic utility

The diagnostic utility is disabled by default and must be enabled before you can use it to troubleshoot. To enable it, use these instructions:

Open the ClientConfig custom resource for editing:

 kubectl  
edit  
clientconfig  
default  
 \ 
  
--kubeconfig  
 CLUSTER_KUBECONFIG 
  
-n  
kube-public

The manifest should look similar to the following:

  apiVersion 
 : 
  
 authentication.gke.io/v2alpha1 
 kind 
 : 
  
 ClientConfig 
 metadata 
 : 
  
 name 
 : 
  
 default 
  
 namespace 
 : 
  
 kube-public 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 oidc 
  
 oidc 
 : 
  
 clientID 
 : 
  
 example-client-id 
  
 clientSecret 
 : 
  
 example-client-secret 
  
 cloudConsoleRedirectURI 
 : 
  
 https://console.cloud.google.com/kubernetes/oidc 
  
 extraParams 
 : 
  
 prompt=consent, access_type=offline 
  
 issuerURI 
 : 
  
 https://example.com 
  
 kubectlRedirectURI 
 : 
  
 http://localhost:PORT/callback 
  
 scopes 
 : 
  
 openid,email,offline_access 
  
 userClaim 
 : 
  
 email

As shown in the following example, add an identityServiceOptions section to the ClientConfig manifest to specify the diagnostic utility configuration:

  apiVersion 
 : 
  
 authentication.gke.io/v2alpha1 
  
 kind 
 : 
  
 ClientConfig 
  
 metadata 
 : 
  
 name 
 : 
  
 default 
  
 namespace 
 : 
  
 kube-public 
  
 spec 
 : 
  
  identityServiceOptions 
 : 
  
  diagnosticInterface 
 : 
  
  enabled 
 : 
  
 true 
  
  expirationTime 
 : 
  
  TIMESTAMP 
 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 oidc 
  
 oidc 
 : 
  
 clientID 
 : 
  
 example-client-id 
  
 clientSecret 
 : 
  
 example-client-secret 
  
 cloudConsoleRedirectURI 
 : 
  
 https://console.cloud.google.com/kubernetes/oidc 
  
 extraParams 
 : 
  
 prompt=consent, access_type=offline 
  
 issuerURI 
 : 
  
 https://example.com 
  
 kubectlRedirectURI 
 : 
  
 http://localhost:PORT/callback 
  
 scopes 
 : 
  
 openid,email,offline_access 
  
 userClaim 
 : 
  
 email

Replace TIMESTAMP with an expiration time in RFC 3339 format. For example, 2025-05-01T17:05:00Z . The expiration time determines when the diagnostic utility feature automatically turns off. Since the diagnostic utility is available to anyone with cluster access, setting the expiration time appropriately helps ensure that the utility doesn't remain enabled longer than necessary. When setting the expiration time, it's recommended to set it to 12 hours in the future, although any time in the future is valid.

Save your changes and exit the text editor to apply the manifest to the cluster.

Once the diagnostic utility is enabled, you can simulate a sign-in event and get the corresponding diagnostic information that you can use to troubleshoot issues with a specific provider.

Open the diagnostic page in a browser by navigating to the following URL:
```
  APISERVER-URL 
/diagnose 
```
Replace APISERVER_URL with the fully qualified domain name (FQDN) for your cluster. For example, https://apiserver.example.com .

If you encounter a forbidden error, like the following:
```
 forbidden: user \"system:anonymous\" cannot get path \"/diagnose\" 
```
Append the port number value of :11001 to the APISERVER_URL . For example, https://apiserver.example.com:11001/diagnose .

The diagnostic page displays a list of OIDC providers configured for your cluster.
Select the provider that you want to troubleshoot.
Sign in as usual.

At the end of the sign in process, the utility displays a page with diagnostic information that can help you troubleshoot.

Use the diagnostics page to troubleshoot sign-in problems

The diagnostics page provides an authentication summary, which is divided into three sections:

Status: contains either Success or Failed , depending on whether the authentication has succeeded or not.
Identity Provider: contains details, such as Name , Client ID , and UserClaim , about the provider that was used to sign in.
ID Token: contains information about ID token fetched by GKE Identity Service using the given provider. The ID token is a JSON object containing a set of key-value pairs. Keys might include iss , aud , sub , and email .

Troubleshoot authentication success

If the content of the Statussection indicates that the authentication has succeeded and you're still experiencing issues, missing role-based-access-controls (RBACs) might be the cause. For additional troubleshooting information, see RBACs for groups not working for OIDC providers for further troubleshooting.

Troubleshoot authentication failure

If the content of the Statussection indicates that the authentication has failed, start by looking for inconsistencies between the Identity Providerand ID Tokensections.

Here are a few authentication requirements that you should check:

If the UserClaim field in Identity Provideris empty, then the ID Tokensection must contain a field named sub . A missing sub field is an indication that there's a problem with the ID token.
The UserClaim field value in Identity Providermust be a key in the ID Tokensection. For example, if the UserClaim field is set to email , then there must be a field named email in ID Token.
The GroupsClaim field value in Identity Providermust be a key in ID Token. For example, if the GroupsClaim field is set to groupsList (for a provider that supports groups), then there must be a field named groupsList in ID Token.
The Client ID field value in Identity Providermust be contained within the value of the aud field in ID Tokensection.

If any of the preceding conditions aren't met, see one of the following guides for more details on how to properly configure your clusters with GKE Identity Service:

If you set up GKE Identity Service for individual clusters, see the instructions to configure individual clusters .
If you set up GKE Identity Service at a fleet level, see the instructions to configure a fleet of clusters .

Use logs for further troubleshooting

The GKE Identity Service pod logs contain additional debugging information. To use GKE Identity Service pod logs: