Version 1.13. This version is no longer supported. For information about how to upgrade to version 1.14, see Upgrading Anthos on bare metal in the 1.14 documentation. For more information about supported and unsupported versions, see the Version history page in the latest documentation.
This page shows you how to identify and resolve OpenID Connect (OIDC) issues
with Google Distributed Cloud.
Identify OIDC issues
When OIDC is not working for Google Distributed Cloud, typically the OIDC
specification within the cluster config file has been improperly configured.
This section provides instructions for reviewing logs and the OIDC specification
to help identify the cause of an OIDC problem.
Review the GKE Identity Service logs
GKE Identity Service supports OIDC in Google Distributed Cloud.
Use kubectl logs to print the GKE Identity Service logs:
Review the logs for errors that can help you diagnose OIDC problems.
If you are unable to authenticate with OIDC, GKE Identity Service logs
provide the most relevant and useful information for debugging the problem.
For example, if the OIDC specification (in the cluster config file) has a
typo in the issuerURL field, such as htps://accounts.google.com (missing
a "t" in https), the GKE Identity Service logs will contain an entry
like this:
OIDC (htps://accounts.google.com) - Unable to fetch JWKs needed to validate OIDC ID token.
If you have identified a configuration issue in the logs, proceed to
Reconfiguring OIDC.
Cloud Customer Care will need the GKE Identity Service
logs and the OIDC specification to diagnose and resolve
OIDC problems.
Reconfigure OIDC
If you identified problems in either the GKE Identity Service logs or the
the clientconfig object, you can reconfigure OIDC in your cluster (without
re-creating the cluster) to address them. To reconfigure OIDC, edit the KRM
default object of type clientconfig in thekube-public namespace:
Details from the ClientConfig CRD are used to configure OIDC for both
the Google Cloud console and the Authentication plugin for GKE Enterprise. For details about the OIDC
Information included in the ClientConfig CRD, see the following YAML and
associated table of field descriptions.
The following table describes the fields of the ClientConfig CRD oidc object.
Field
Required
Description
Format
name
Yes
The name of the OIDC configuration to create.
String
certificateAuthorityData
No
A base64-encoded
PEM-encoded certificate for the OIDC provider. To create the string,
encode the certificate, including headers, into base64. Include the resulting
string in certificateAuthorityData as a single line.
ID for the client application that makes authentication requests to the
OpenID provider.
String
clientSecret
No
Shared secret between the OIDC client application and the OIDC provider.
String
extraParams
No
Additional key-value parameters to send to the OpenID provider. If you are
authorizing a group, pass in resource=token-groups-claim.
If your authorization server prompts for consent for authentication with
Microsoft Azure and Okta, set extraParams to
prompt=consent. For Cloud Identity, set
extraParams to
prompt=consent,access_type=offline.
Comma-delimited list
groupsClaim
No
JWT claim that the
provider uses to return your security groups.
String
groupPrefix
No
Prefix prepended to group claims to prevent clashes with existing names.
For example, if you have two groups named foobar, add a prefix
gid-. The resulting group is gid-foobar.
String
issuerURI
Yes
URL where authorization requests are sent to your OpenID, such as
https://example.com/adfs. The Kubernetes API server uses this URL
to discover public keys for verifying tokens. The URI must use HTTPS.
URL String
kubectlRedirectURI
Yes
The redirect URL that kubectl uses for authorization.
URL String
scopes
Yes
Additional scopes to send to the OpenID provider. Microsoft Azure and Okta
require the offline_access scope.
Comma-delimited list
userClaim
No
JWT claim to use as the username. You can choose other claims, such
as email or name, depending on the OpenID provider. However, claims other than
email are prefixed with the issuer URL to prevent naming clashes.
String
userPrefix
No
Prefix prepended to username claims to prevent clashes with existing names.
String
proxy
No
Proxy server to use for the auth method, if applicable.
For example: http://user:password@10.10.10.10:8888.
[[["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-09-04 UTC."],[[["\u003cp\u003eThis page guides users through identifying and resolving OpenID Connect (OIDC) issues in Google Distributed Cloud, which often stem from incorrect configurations within the cluster config file.\u003c/p\u003e\n"],["\u003cp\u003eGKE Identity Service logs, accessible via \u003ccode\u003ekubectl logs\u003c/code\u003e, are the primary resource for diagnosing OIDC problems, and these logs should be reviewed for errors like incorrect \u003ccode\u003eissuerURL\u003c/code\u003e entries.\u003c/p\u003e\n"],["\u003cp\u003eThe OIDC specification, found in the \u003ccode\u003eclientconfig\u003c/code\u003e object within the \u003ccode\u003ekube-public\u003c/code\u003e namespace, should be checked using \u003ccode\u003ekubectl get\u003c/code\u003e to ensure its values align with the OIDC provider's requirements.\u003c/p\u003e\n"],["\u003cp\u003eOIDC can be reconfigured without recreating the cluster by editing the KRM default object of type \u003ccode\u003eclientconfig\u003c/code\u003e using \u003ccode\u003ekubectl edit\u003c/code\u003e, allowing for corrections to identified issues in the logs or specification.\u003c/p\u003e\n"],["\u003cp\u003eThe clientconfig CRD contains specific fields that are required, such as clientID, issuerURI, and kubectlRedirectURI, which if configured improperly will cause authentication issues.\u003c/p\u003e\n"]]],[],null,["# Troubleshoot OIDC in Google Distributed Cloud\n\n\u003cbr /\u003e\n\nThis page shows you how to identify and resolve OpenID Connect (OIDC) issues\nwith Google Distributed Cloud.\n\nIdentify OIDC issues\n--------------------\n\nWhen OIDC is not working for Google Distributed Cloud, typically the OIDC\nspecification within the cluster config file has been improperly configured.\nThis section provides instructions for reviewing logs and the OIDC specification\nto help identify the cause of an OIDC problem.\n\n### Review the GKE Identity Service logs\n\nGKE Identity Service supports OIDC in Google Distributed Cloud.\n\n1. Use `kubectl logs` to print the GKE Identity Service logs:\n\n kubectl --kubeconfig \u003cvar translate=\"no\"\u003eCLUSTER_KUBECONFIG\u003c/var\u003e -n anthos-identity-service logs \\\n deployment/ais --all-containers=true\n\n2. Review the logs for errors that can help you diagnose OIDC problems.\n\n If you are unable to authenticate with OIDC, GKE Identity Service logs\n provide the most relevant and useful information for debugging the problem.\n\n For example, if the OIDC specification (in the cluster config file) has a\n typo in the `issuerURL` field, such as `htps://accounts.google.com` (missing\n a \"t\" in https), the GKE Identity Service logs will contain an entry\n like this: \n\n OIDC (htps://accounts.google.com) - Unable to fetch JWKs needed to validate OIDC ID token.\n\n3. If you have identified a configuration issue in the logs, proceed to\n [Reconfiguring OIDC](#reconfiguring_oidc).\n\n4. If you are unable to diagnose and resolve the problem yourself, [engage with\n Cloud Customer Care](/anthos/clusters/docs/bare-metal/1.13/getting-support).\n\n Cloud Customer Care will need the GKE Identity Service logs and the [OIDC\n specification](#checking_the_oidc_specification_in_your_cluster) to diagnose\n and resolve OIDC problems.\n\n### Check the OIDC specification in your cluster\n\nThe OIDC information for your cluster is specified in the `clientconfig` object\nin the `kube-public` namespace.\n\n1. Use `kubectl get` to print the OIDC resource for your cluster:\n\n kubectl --kubeconfig \u003cvar translate=\"no\"\u003eCLUSTER_KUBECONFIG\u003c/var\u003e -n kube-public get \\\n clientconfig.authentication.gke.io default -o yaml\n\n | **Note:** The `clientconfig` spec may differ slightly from the OIDC spec in your cluster config file. For example, the OIDC provider URL is specified with the `issuerURL` field in the cluster config file, but the `clientconfig` object returns this information in the `issuerURI` field.\n2. Review the field values to confirm the specification is configured correctly\n for your OIDC provider.\n\n3. If you have identified a configuration issue in the specification, proceed to\n [Reconfiguring OIDC](#reconfiguring_oidc).\n\n4. If you are unable to diagnose and resolve the problem yourself, [engage with\n Cloud Customer Care](/anthos/clusters/docs/bare-metal/1.13/getting-support).\n\n Cloud Customer Care will need the [GKE Identity Service\n logs](#reviewing_the_logs) and the OIDC specification to diagnose and resolve\n OIDC problems.\n\nReconfigure OIDC\n----------------\n\nIf you identified problems in either the GKE Identity Service logs or the\nthe `clientconfig` object, you can reconfigure OIDC in your cluster (without\nre-creating the cluster) to address them. To reconfigure OIDC, edit the KRM\ndefault object of type `clientconfig` in the`kube-public` namespace: \n\n```yaml\nkubectl --kubeconfig CLUSTER_KUBECONFIG -n kube-public edit clientconfig default\n```\n\nDetails from the ClientConfig CRD are used to configure OIDC for both\nthe Google Cloud console and the Authentication plugin for GKE Enterprise. For details about the OIDC\nInformation included in the ClientConfig CRD, see the following YAML and\nassociated table of field descriptions.\n**Note:** Some field names in this CRD may differ slightly from the field names used in the OIDC specification in the cluster configuration file for Google Distributed Cloud. For example, `issuerURI` versus `issuerURL`. \n\n```yaml\nauthentication:\n - name: oidc\n oidc:\n certificateAuthorityData: CERTIFICATE_STRING\n clientID: CLIENT_ID\n clientSecret: CLIENT_SECRET\n cloudConsoleRedirectURI: \"http://console.cloud.google.com/kubernetes/oidc\"\n deployCloudConsoleProxy: PROXY_BOOLEAN\n extraParams: EXTRA_PARAMS\n groupsClaim: GROUPS_CLAIM\n groupPrefix: GROUP_PREFIX\n issuerURI: ISSUER_URI\n kubectlRedirectURI: KUBECTL_REDIRECT_URI\n scopes: SCOPES\n userClaim: USER_CLAIM\n userPrefix: USER_PREFIX\n proxy: PROXY_URL\n```\n\nThe following table describes the fields of the ClientConfig CRD `oidc` object."]]
