Stay organized with collections
Save and categorize content based on your preferences.
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:
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.
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.
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 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:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[],[],null,["# GKE Identity Service diagnostic utility\n=======================================\n\nThe GKE Identity Service diagnostic utility helps you to troubleshoot\n[FQDN-based authentication](/kubernetes-engine/enterprise/identity/setup/authenticate-fqdn-access)\nissues. If you're experiencing difficulties authenticating to a cluster using a\nspecific OIDC provider, you can enable the tool and use it to quickly identify\nconfiguration issues by simulating sign-in flows with\nyour OIDC provider.\n\nThe diagnostic utility is only available on [individual clusters](/kubernetes-engine/enterprise/identity/setup/per-cluster-overview)\nrunning GKE Enterprise 1.32 or higher and only supports OIDC.\n\nEnable the diagnostic utility\n-----------------------------\n\nThe diagnostic utility is disabled by default and must be enabled before you\ncan use it to troubleshoot. To enable it, use these instructions:\n\n1. Open the ClientConfig custom resource for editing:\n\n kubectl edit clientconfig default \\\n --kubeconfig \u003cvar translate=\"no\"\u003eCLUSTER_KUBECONFIG\u003c/var\u003e -n kube-public\n\n The manifest should look similar to the following: \n\n apiVersion: authentication.gke.io/v2alpha1\n kind: ClientConfig\n metadata:\n name: default\n namespace: kube-public\n spec:\n authentication:\n - name: oidc\n oidc:\n clientID: example-client-id\n clientSecret: example-client-secret\n cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc\n extraParams: prompt=consent, access_type=offline\n issuerURI: https://example.com\n kubectlRedirectURI: http://localhost:PORT/callback\n scopes: openid,email,offline_access\n userClaim: email\n\n2. As shown in the following example, add an `identityServiceOptions` section\n to the ClientConfig manifest to specify the diagnostic utility\n configuration:\n\n apiVersion: authentication.gke.io/v2alpha1\n kind: ClientConfig\n metadata:\n name: default\n namespace: kube-public\n spec:\n identityServiceOptions:\n diagnosticInterface:\n enabled: true\n expirationTime: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eTIMESTAMP\u003c/span\u003e\u003c/var\u003e\n authentication:\n - name: oidc\n oidc:\n clientID: example-client-id\n clientSecret: example-client-secret\n cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc\n extraParams: prompt=consent, access_type=offline\n issuerURI: https://example.com\n kubectlRedirectURI: http://localhost:PORT/callback\n scopes: openid,email,offline_access\n userClaim: email\n\n Replace \u003cvar translate=\"no\"\u003eTIMESTAMP\u003c/var\u003e with an expiration time in\n [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. For\n example, `2025-05-01T17:05:00Z`. The expiration time determines when the\n diagnostic utility feature automatically turns off. Since the diagnostic\n utility is available to anyone with cluster access, setting the expiration\n time appropriately helps ensure that the utility doesn't remain enabled\n longer than necessary. When setting the expiration time, it's recommended\n to set it to 12 hours in the future, although any time in the future is\n valid.\n3. Save your changes and exit the text editor to apply the manifest to the\n cluster.\n\nUse the diagnostic utility to simulate a sign-in\n------------------------------------------------\n\nOnce the diagnostic utility is enabled, you can simulate a sign-in event and get\nthe corresponding diagnostic information that you can use to troubleshoot issues\nwith a specific provider.\n\n1. Open the diagnostic page in a browser by navigating to the following URL:\n\n \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e/diagnose\n\n Replace \u003cvar translate=\"no\"\u003eAPISERVER_URL\u003c/var\u003e with the fully qualified domain\n name (FQDN) for your cluster. For example, `https://apiserver.example.com`.\n\n If you encounter a forbidden error, like the following: \n\n forbidden: user \\\"system:anonymous\\\" cannot get path \\\"/diagnose\\\"\n\n Append the port number value of **`:11001`** to the \u003cvar translate=\"no\"\u003eAPISERVER_URL\u003c/var\u003e. For example, `https://apiserver.example.com:11001/diagnose`.\n\n The diagnostic page displays a list of OIDC providers configured for your\n cluster.\n2. Select the provider that you want to troubleshoot.\n\n3. Sign in as usual.\n\n At the end of the sign in process, the utility displays a page with\n diagnostic information that can help you troubleshoot.\n\nUse the diagnostics page to troubleshoot sign-in problems\n---------------------------------------------------------\n\nThe diagnostics page provides an authentication summary, which is divided into\nthree sections:\n\n- **Status** : contains either `Success` or `Failed`, depending on whether the\n authentication has succeeded or not.\n\n- **Identity Provider** : contains details, such as `Name`, `Client ID`, and\n `UserClaim`, about the provider that was used to sign in.\n\n- **ID Token** : contains information about ID token fetched by\n GKE Identity Service using the given provider. The ID token is a JSON\n object containing a set of key-value pairs. Keys might include `iss`, `aud`,\n `sub`, and `email`.\n\n### Troubleshoot authentication success\n\nIf the content of the **Status** section indicates that the authentication has\nsucceeded and you're still experiencing issues, missing\nrole-based-access-controls (RBACs) might be the cause. For additional\ntroubleshooting information, see [RBACs for groups not working for OIDC\nproviders](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#rbacs_for_groups_not_working_for_oidc_providers)\nfor further troubleshooting.\n\n### Troubleshoot authentication failure\n\nIf the content of the **Status** section indicates that the authentication has\nfailed, start by looking for inconsistencies between the **Identity Provider**\nand **ID Token** sections.\n\nHere are a few authentication requirements that you should check:\n\n- If the `UserClaim` field in **Identity Provider** is empty, then the **ID\n Token** section must contain a field named `sub`. A missing `sub` field is\n an indication that there's a problem with the ID token.\n\n- The `UserClaim` field value in **Identity Provider** must be a key in the\n **ID Token** section. For example, if the `UserClaim` field is set to\n `email`, then there must be a field named `email` in **ID Token**.\n\n- The `GroupsClaim` field value in **Identity Provider** must be a key in **ID\n Token** . For example, if the `GroupsClaim` field is set to `groupsList` (for\n a provider that supports groups), then there must be a field named\n `groupsList` in **ID Token**.\n\n- The `Client ID` field value in **Identity Provider** must be contained\n within the value of the `aud` field in **ID Token** section.\n\nIf any of the preceding conditions aren't met, see one of the following guides\nfor more details on how to properly configure your clusters with\nGKE Identity Service:\n\n- If you set up GKE Identity Service for individual clusters, see the\n [instructions to configure individual\n clusters](/kubernetes-engine/enterprise/identity/setup/per-cluster#configure_clusters).\n\n- If you set up GKE Identity Service at a fleet level, see the\n [instructions to configure a fleet of\n clusters](/kubernetes-engine/enterprise/identity/setup/fleet-cluster#configure_clusters).\n\n### Use logs for further troubleshooting\n\nThe [GKE Identity Service pod\nlogs](/kubernetes-engine/enterprise/identity/setup/ais-pod-troubleshooting)\ncontain additional debugging information. To use GKE Identity Service pod\nlogs:\n\n1. [Enable the GKE Identity Service debug log](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#enable_the_debug_log).\n\n2. [Check the GKE Identity Service container log](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#check_the_container_log)."]]