Version 1.6. This version is no longer supported. For information about how to upgrade to version 1.7, see Upgrading Anthos on bare metal in the 1.7 documentation. For more information about supported and unsupported versions, see the Version history page in the latest documentation.

Identity management with OIDC in Google Distributed Cloud

You can authenticate with Google Distributed Cloud clusters using OpenID Connect (OIDC). OIDC is an authentication layer, built on top of OAuth 2.0, that specifies a RESTful HTTP API, and uses JSON as a data format.

OIDC allows you to use your existing identity provider to manage user and group authentication in Google Distributed Cloud clusters. With OIDC, you can manage access to an Google Distributed Cloud cluster by using the standard procedures in your organization for creating, enabling, and disabling accounts. You can also use your organization's security groups to configure access to a cluster, or to specific services in a cluster. Managed access works on any kind of Google Distributed Cloud cluster: admin, user, hybrid, or standalone.

Google Distributed Cloud supports both on-premises and publicly reachable identity providers. For example, on-premise you might use an Active Directory Federation Services component. You might also use publicly-reachable identity provider services from Google or Okta. In addition, identity provider certificates may be issued by either a well-known public certificate authority (CA), or by a private CA.

There are two OIDC authentication methods available to users:

OIDC authentication through a command line interface (CLI) where users run a gcloud command and are authenticated through a browser-based login/consent page.
OIDC authentication through the Google Google Cloud console UI where users log into a cluster directly from the Kubernetes clusters page. This method requires your cluster to be registered with Google Cloud. Clusters are registered automatically during Google Distributed Cloud cluster installation.

Note that OIDC does not support headless workflows: OIDC requires a browser-based authentication to redirect users to the identity provider web-page, and to prompt users for consent and account login/password.

OIDC and Kubernetes access control

OIDC authentication is often combined with Kubernetes Role-Based Access Control (RBAC). RBAC allows you to create granular authorization policies that define which users or groups can perform specific operations on a given set of cluster resources.

OIDC Authentication overview

A typical OIDC authentication includes the following steps:

A user signs in to an OpenID provider by presenting a username and password.
The OpenID provider issues an ID token for the user.
The token is signed by the provider and is returned through a pre-configured callback URL.
An application, acting on behalf of the user, sends an HTTPS request to the Kubernetes API server. The application includes the user's ID token in the request header.
The Kubernetes API server verifies the ID token by using the provider's certificate, and parses the token to learn the user's identity and, if present, the user's groups.

Usually, there are three personas involved in the OIDC setup and authentication:

The organization administrator, who chooses an OpenID provider and registers client applications with the provider.
A platform administrator, who creates one or more clusters and authentication configuration files for users who use the clusters.
An app operator or developer, who runs workloads on one or more clusters and uses OIDC to authenticate.

You can use any certified OpenID provider (providers are certified by the OpenID Foundation). The specific registration process depends on the provider, but normally includes the following steps:

Learn the provider's issuer URI. This is where the gcloud CLI or Google Cloud Console sends authentication requests.
Give the provider the redirect URLs for the gcloud CLI and Google Cloud console.
Establish a client ID and client secret. The gcloud CLI and Google Cloud console both use this client ID/secret to authenticate to the OpenID provider.
Establish a custom scope and claim for security groups. In general, you should define your cluster RBAC policies based on groups instead of users to make the policies more stable and auditable. Most OIDC providers include group claims in ID tokens if proper scopes have been requested. Specific group claims and scopes differ across OIDC providers, so establishing these provider-specific scopes and claims require customization.

Before installing a new Google Distributed Cloud cluster, the platform administrator normally obtains OIDC configuration from the organization administrator, and configures the relevant OIDC fields in the cluster configuration.

Once cluster installation is complete, the platform administrator obtains the authentication configuration files and shares them with the CLI users. Typically, the platform administrator shares the authentication configuration by hosting the files on a secure host, or by using internal tools to push the configuration files to each user's machine. The CLI users then authenticate the new cluster with the shared configuration files.

The platform administrator can also store the authentication configuration details for multiple clusters within a single authentication configuration file.

Note that Google Cloud console users do not need these configuration files. When users access the Google Cloud console, they can select Authenticate with the Identity Provider configured for the cluster, and then click Login.