Stay organized with collections Save and categorize content based on your preferences.

Configure clusters for fleet-level Anthos Identity Service

This document is for cluster administrators or application operators setting up Anthos Identity Service on their clusters. It tells you how to set up Anthos Identity Service at the fleet level on your clusters with your preferred OpenID Connect (OIDC) identity provider. The instructions in this document assume that Anthos Identity Service has already been registered with your identity provider as a client application.

To find out more about Anthos Identity Service and other setup options, see the overview. To learn how to access a cluster using this service as a developer or other cluster user, see Accessing clusters with Anthos Identity Service.

Before you begin

  • Ensure that your platform administrator has given you all the necessary information from Configuring OIDC providers for Anthos Identity Service before you start setup, including the client ID and secret for Anthos Identity Service.
  • Ensure that the clusters you want to configure meet the prerequisites for fleet-level setup. For other cluster types and environments, see the Anthos Identity Service Overview.
  • Ensure that you have the following command line tools installed:

    • The latest version of the Google Cloud CLI, which includes gcloud, the command line tool for interacting with Google Cloud. If you need to install the Google Cloud CLI, see the installation guide.
    • kubectl for running commands against Kubernetes clusters. If you need to install kubectl, see the installation guide.

    If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.

  • Ensure that you have initialized the gcloud CLI for use with the project where the clusters are registered.

  • If you are not the project owner, you need the GKE Hub Admin role in the project where the clusters are registered to complete the configuration steps.

Enable APIs

Console

  1. Ensure that the project where the clusters are registered is selected.
  2. Enable the GKE Hub and Kubernetes Engine APIs.

    Enable the APIs

gcloud

Run the following command to enable the required APIs for setup:

gcloud services enable \
gkehub.googleapis.com \
container.googleapis.com

Configure clusters

To configure your clusters to use your chosen provider, Anthos Identity Service needs you to specify details about the identity provider, the information in the JWT tokens it provides for user identification, and other information provided when registering Anthos Identity Service as a client application.

So, for example, if your provider creates identity tokens with the following fields (among others), where iss is the identity provider URI, sub identifies the user, and groupList lists the security groups that the user belongs to:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

...your configuration will have the following corresponding fields:

issueruri: 'https://server.example.com'
username: 'sub'
group: 'groupList'
...

Your platform adminstrator, or whoever manages identity in your organization, should provide you with most of the information you need to create the configuration.

Anthos Identity Service lets you create or update and apply this configuration from the Google Cloud console or using the Google Cloud CLI.

Console

Enable Anthos Identity Service

  1. In the Google Cloud console, go to the Anthos Features page.

    Go to Anthos Features

  2. In the Features table, click Enable in the Anthos Identity Service row, then click Enable again in the pane that displays. This creates a new Anthos Identity Service controller instance to manage the lifecycle of Anthos Identity Service in your fleet's clusters.

Select clusters

  1. Back in the Features table, click Details in the Anthos Identity Service row to open the details pane for the service. This displays your project's clusters and their fleet-level Anthos Identity Service status.
  2. Click Update identity service to open the setup pane.
  3. Select the clusters you want to configure. Only supported cluster types can be selected. You can choose individual clusters, or specify that you want all clusters to be configured with the same identity configuration.
  4. In the Identity provider drop-down, choose how you want to configure the cluster(s). New OpenID Connect lets you create a new configuration. If the cluster has an existing Anthos Identity Service configuration, you can choose to update it. If an existing registered cluster has an Anthos Identity Service configuration you'd like to use, you can choose to copy that configuration to your selected cluster(s).

Set provider details

  1. Specify the name you want to use to identify this configuration in the Provider name field, typically the identity provider name. This name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen. You cannot edit this name once you've created a configuration.
  2. Specify the client ID returned when registering Anthos Identity Service with your provider in the Client ID field.
  3. Specify the client secret that must be shared between the client application and the identity provider in the Client Secret field.
  4. Specify the URI where authorization requests are made to your identity provider in the Issuer URL field.
  5. Click Next.

Set attributes

Most of the attributes in this section are optional. The attributes you need to add depend on your identity provider and the setup options chosen by your platform admin when configuring the provider for Anthos Identity Service.

  1. Fill in the configuration attributes:

    • kubectl redirect URI: The redirect URL and port used by the gcloud CLI and specified by your platform admin at registration, typically in the form http://localhost:PORT/callback.
    • Certificate Authority (Optional): If provided by your platform administrator, a PEM-encoded certificate string for the identity provider.
    • Group Claim (Optional): The JWT claim (field name) that your provider uses to return an account's security groups.
    • Group Prefix (Optional): The prefix you want to prepend to security group names to avoid clashes with existing names in your access control rules if you have configurations for multiple identity providers (typically the provider name).
    • Proxy (Optional): Proxy server address to use to connect to the identity provider, if applicable. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. For example: http://user:password@10.10.10.10:8888.
    • Scopes (Optional): Any additional scopes required by your identity provider. Microsoft Azure and Okta require the offline_access scope. Click Add scope to add more scopes if necessary.
    • User Claim (Optional): The JWT claim (field name) that your provider uses to identify an account. If you don't specify a value here, Anthos Identity Service uses "sub", which is the user ID claim used by many providers. You can choose other claims, such as "email" or "name", depending on the OpenID provider. Claims other than "email" are prefixed with the issuer URL to prevent naming clashes.
    • User Prefix (Optional): The prefix you want prepended to user claims to prevent clashes with existing names, if you don't want to use the default prefix.
    • Extra Params (Optional): Any extra parameters required for your configuration, specified as the parameter Key and Value. Click Add param to add more parameters if needed.
    • Enable access token (Optional): If enabled, it allows group support for OIDC providers such as Okta.
    • Deploy Google Cloud console proxy (Optional): If enabled, a proxy is deployed that lets the Google Cloud console connect to an on-premises identity provider that is not publicly accessible over the internet.

Add identity provider

  • If you have additional identity providers that you'd like to configure for your fleet, you have the option to add the providers here. Follow the steps to specify additional identity providers and configuration parameters.

Update configuration

  • Click Update configuration. This installs Anthos Identity Service if necessary (EKS clusters only, Anthos clusters already have Anthos Identity Service installed by default) and applies the client configuration on your selected clusters.

gcloud

Enable Anthos Identity Service

To enable the Anthos Identity Service feature for your project, run the following command:

gcloud container fleet identity-service enable

This creates a new Anthos Identity Service controller instance to manage the lifecycle of Anthos Identity Service in your fleet's clusters. You only need to run this command once per project to use Anthos Identity Service with all supported clusters registered to your project fleet.

Create the configuration file

Anthos Identity Service uses a Kubernetes custom resource type (CRD) called ClientConfig for cluster configuration, with fields for all the information Anthos Identity Service needs to interact with the identity provider. Create a file called auth-config.yaml with your configuration:

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
    proxy: PROXY_URL

If you have configured more than one identity provider, you can list multiple authentication configurations in the auth-config.yaml file under the authentication anchor in the same format as you see above.

The following table describes the fields of the ClientConfig oidc object. Most of the fields are optional. The fields you need to add depend on your identity provider and the setup options chosen by your platform admin when configuring the provider for Anthos Identity Service.

Field Required Description Format
name yes The name you want to use to identify this configuration, typically the identity provider name. A configuration name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen. String
certificateAuthorityData No If provided by your platform administrator, a PEM-encoded certificate string for the identity provider. Include the resulting string in certificateAuthorityData as a single line. String
clientID Yes The client ID returned when registering Anthos Identity Service with your provider. String
clientSecret Yes The client secret returned when registering Anthos Identity Service with your provider. String
deployCloudConsoleProxy No Specifies whether a proxy is deployed that lets the Google Cloud console connect to an on-premises identity provider that is not publicly accessible over the internet. By default this is set to false. Boolean
extraParams No Additional key=value parameters to send to the identity provider, specified as a comma-separated list—for example `prompt=consent,access_type=offline`. Comma-delimited list
enableAccessToken No If enabled, Anthos Identity Service can use the identity provider's userinfo endpoint to get groups information when a user logs in from the command line. This lets you use security groups for authorization if you have a provider (such as Okta) that provides group claims from this endpoint. If not set, this is considered to be false. Boolean
groupsClaim No The JWT claim (field name) that your provider uses to return an account's security groups. String
groupPrefix No The prefix you want to prepend to security group names to avoid clashes with existing names in your access control rules if you have configurations for multiple identity providers (typically the provider name). String
issuerURI Yes The URI where authorization requests are made to your identity provider. The URI must use HTTPS. URL String
kubectlRedirectURI Yes The redirect URL and port used by the gcloud CLI and specified by your platform admin at registration, typically in the form `http://localhost:PORT/callback`. URL String
scopes Yes Additional scopes to send to the OpenID provider. For example, Microsoft Azure and Okta require the offline_access scope. Comma-delimited list
userClaim No The JWT claim (field name) that your provider uses to identify a user account. If you don't specify a value here, Anthos Identity Service uses "sub", which is the user ID claim used by many providers. You can choose other claims, such as "email" or "name", depending on the OpenID provider. Claims other than "email" are prefixed with the issuer URL to prevent naming clashes. String
userPrefix No The prefix you want prepended to user claims to prevent clashes with existing names, if you don't want to use the default prefix. String
proxy No Proxy server address to use to connect to the identity provider, if applicable. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. For example: http://user:password@10.10.10.10:8888. String

Apply the configuration

To install Anthos Identity Service if necessary (EKS clusters only, Anthos clusters already have Anthos Identity Service installed by default) and apply the configuration to a cluster, run the following command:

gcloud container fleet identity-service apply \
--membership=CLUSTER_NAME \
--config=/path/to/auth-config.yaml

...where CLUSTER_NAME is your cluster's unique membership name within the fleet.

Once applied, this configuration is managed by the Anthos Identity Service controller and is considered the "source of truth". Any local changes made to Anthos Identity Service client configuration will be reconciled back by the controller to the configuration specified in this setup.

Additionally, the Anthos Identity Service client configuration for a cluster can now be configured with a new authentication method that enables Connect gateway to support Google Groups authorization policies. For some cluster versions, applying your fleet-level configuration also by default adds an additional authentication method to your clusters. This method allows Anthos Identity Service retrieve Google Groups information for user accounts logging in with their Google ID. This configuration is applicable to Anthos clusters on VMware and Anthos on bare metal from the Anthos 1.13 version onwards. To know more about the Google Groups feature, see Set up the Connect gateway with Google Groups.

Be aware that if you have an existing configuration on your cluster for any authentication options, such as LDAP configuration, the following apply:

  • If you have existing cluster-level configurations for OIDC providers, applying fleet-level Anthos Identity Service control to the cluster will overwrite all your existing authentication specifications.
  • If you have existing cluster-level configurations for providers that are not supported for fleet-level configuration (such as LDAP), this setup will fail. You must remove the existing provider configuration to apply the fleet-level configuration.

If you no longer want the Anthos Identity Service controller to manage your configuration, for example if you want to use a different authentication option or options, you can disable this feature by following the instructions in Disabling Anthos Identity Service management.

Provider-specific configurations

This section provides configuration guidance for OIDC providers (such as Okta), including an example configuration that you can copy and edit with your own details.

Okta

The following shows you how to set up authentication using both users and groups with Okta as your identity provider. This config lets Anthos Identity Service retrieve user and group claims by using an access token and Okta's userinfo endpoint.

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Set up user access

After you have configured the clusters, continue to set up user access.

Disable fleet-level Anthos Identity Service management

If you no longer want Google Cloud to manage your Anthos Identity Service configuration and lifecycle, you can disable this feature. Disabling fleet-level management does not remove Anthos Identity Service or your authentication configuration from the cluster, so users can still authenticate to the cluster using your configured third-party identity provider. However, if you make local manual edits on the cluster to Anthos Identity Service configuration or resources, those changes are no longer reconciled to a "single source of truth" desired state.

Disable fleet-level management for a cluster

Run the following command to remove fleet-level Anthos Identity Service management from a specific cluster:

gcloud container fleet identity-service delete --membership=CLUSTER_NAME

...where CLUSTER_NAME is your cluster's unique membership name within the fleet.

After you run this command, you can still view the cluster's Anthos Identity Service state in the Google Cloud console or by running gcloud container fleet identity-service describe, but it will no longer be automatically updated on the cluster from your fleet-level specification.

Disable fleet-level management for a fleet

Do the following to disable fleet-level Anthos Identity Service management for your fleet.

Console

  1. In the Google Cloud console, go to the Anthos Features page.

    Go to Anthos Features

  2. In the Features table, click Details in the Anthos Identity Service row, then click Disable Anthos Identity Service in the pane that displays.

gcloud

Run the following command:

gcloud container fleet identity-service disable

After disabling the feature for your fleet, you can no longer view or update any cluster's Anthos Identity Service state in the Google Cloud console or by using gcloud.