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 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. The way to enable the utility depends on how you set up your cluster with GKE Identity Service.

Fleet setup (console)

If you used the Google Cloud console to set up clusters with GKE Identity Service at a fleet level, use these instructions.

  1. Create a YAML ClientConfig manifest file as outlined in Create a config file.

    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

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

  3. Next, apply the file to your cluster by running:

    gcloud container fleet identity-service apply \
    --membership=CLUSTER_NAME \
    --config=MANIFEST_FILE_PATH

    Replace the following:

    • CLUSTER_NAME: the unique name of the cluster within your fleet.

    • MANIFEST_FILE_PATH: path of the YAML ClientConfig manifest file.

Fleet setup (gcloud)

If you used the Google Cloud CLI to set up clusters with GKE Identity Service at a fleet level, use these instructions:

  1. Open the ClientConfig manifest file that was created when you set up your cluster with GKE Identity Service.

    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

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

  3. Next, apply the file to your cluster by running:

    gcloud container fleet identity-service apply \
    --membership=CLUSTER_NAME \
    --config=MANIFEST_FILE_PATH

    Replace the following:

    • CLUSTER_NAME: the unique name of the cluster within your fleet.

    • MANIFEST_FILE_PATH: path of the YAML ClientConfig manifest file.

Individual cluster setup

If you set up GKE Identity Service for individual clusters, use these instructions:

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

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

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

Use the diagnostic utility to simulate a sign-in

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.

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

    The diagnostic page displays a list of OIDC providers configured for your cluster.

  2. Select the provider that you want to troubleshoot.

  3. 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 Status section 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 Status section indicates that the authentication has failed, start by looking for inconsistencies between the Identity Provider and ID Token sections.

Here are a few authentication requirements that you should check:

  • If the UserClaim field in Identity Provider is empty, then the ID Token section 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 Provider must be a key in the ID Token section. 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 Provider must 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 Provider must be contained within the value of the aud field in ID Token section.

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:

Use logs for further troubleshooting

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

  1. Enable the GKE Identity Service debug log.

  2. Check the GKE Identity Service container log.