Configuring clusters for Anthos Identity Service with OIDC
This document is for cluster administrators or application operators who want to configure Anthos Identity Service on individual clusters, allowing developers and other users to log in to the clusters using their existing identity details from an OpenID Connect (OIDC) provider. The guide assumes that you have read the Anthos Identity Service Overview.
- To find out how to set up Anthos Identity Service for a cluster with an LDAP provider instead, see Setting up Anthos Identity Service with LDAP.
- To find out how to set up Anthos Identity Service at fleet level for supported cluster types, with your authentication configuration managed by Google Cloud, see Setting up Anthos Identity Service for a fleet. This is a preview feature.
The instructions in this document assume that Anthos Identity Service has already been registered with your identity provider as a client application.
Setup overview
Setting up Anthos Identity Service for an individual cluster involves the following users and steps:
- The platform administrator registers Anthos Identity Service as a client application with their preferred identity provider and gets a client ID and secret. To do this, follow the instructions in Configuring providers for Anthos Identity Service.
- The cluster administrator configures clusters to use the service, following the instructions in this page.
- The cluster administrator sets up user access, and optionally configures Kubernetes role-based access control (RBAC) for users on the clusters. To do this, follow the instructions in Setting up user access for Anthos Identity Service.
Prerequisites
- Your cluster must be an Anthos cluster on-premises (VMware or bare metal), on AWS, or on Azure. Per-cluster OIDC configuration is not supported for attached clusters or GKE clusters.
- To authenticate through the Cloud console, each cluster that you want to configure for OIDC authentication must be registered to your project fleet.
Before you begin
- Ensure that your platform administrator has given you all the necessary information from Registering Anthos Identity Service with your provider before you start setup, including the client ID and secret for Anthos Identity Service.
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 installkubectl
, follow these instructions.
If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.
- The latest version of the Google Cloud CLI, which includes
Ensure that you have initialized the gcloud CLI for use with the project where the clusters are registered.
If you need to connect to an AWS or Azure Anthos cluster's control plane that is outside your current VPC through a bastion host, make sure that you have created the bastion host and started an SSH tunnel at port 8118 before this setup. Then prepend your
kubectl
commands when following this guide withHTTPS_PROXY=http://localhost:8118
. If you used a different port when starting the SSH tunnel, replace8118
with your selected port.
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' userClaim: 'sub' groupsClaim: 'groupList' ...
Your platform administrator, or whoever manages identity in your organization, should provide you with most of the information you need to create the configuration.
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. Each Anthos cluster has a ClientConfig resource named default
in the kube-public
namespace that you update with your configuration details, following the instructions below.
You can see some specific example configurations for popular providers in Provider-specific configurations.
kubectl
To edit your default ClientConfig, make sure you can connect to your cluster
via kubectl
, and run the following command:
kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public
Replace KUBECONFIG_PATH
with the path to your
cluster's kubeconfig file—for example $HOME/.kube/config
.
A text editor loads your cluster's ClientConfig resource. Add the
spec.authentication.oidc
object as shown below. Do not modify any
default data that has already been written.
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
enableAccessToken: ENABLE_ACCESS_TOKEN
proxy: PROXY_URL
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 | No | Shared secret between the OIDC client application and the OIDC provider. | String |
deployCloudConsoleProxy | No | Specifies whether a proxy is deployed that lets the 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 |
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 |
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 |
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 |
After you complete your ClientConfig, save the file, which updates the ClientConfig on your cluster. If you make any syntax errors, you are prompted to re-edit the config to fix them.
Provider-specific configurations
This section provides configuration guidance for some popular OIDC providers, including example configurations that you can copy and edit with your own details.
Azure AD
...
spec:
authentication:
- name: oidc-ad
oidc:
clientID: CLIENT_ID
clientSecret: CLIENT_SECRET
cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
extraParams: prompt=consent, access_type=offline
issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
kubectlRedirectURI: http://localhost:PORT/callback
scopes: openid,email,offline_access
userClaim: email
...
Getting group information with azuread
(on-premises clusters only)
From Anthos 1.9, Anthos Identity Service lets you configure on-premises Anthos clusters (both VMware and bare metal) for Azure AD by adding a specific azuread
section in your ClientConfig instead of oidc
. Using this configuration lets Anthos Identity Service get users' group membership information from Azure AD, even if the user is a member of more than 200 groups (Azure AD can only provide up to approximately 200 groups per user with our default OIDC configuration). This lets you set up Kubernetes role based access control (RBAC) based on groups.
- Your platform admin must have set up Anthos Identity Service as a client with the relevant permissions to use this feature.
- Each user must have an associated email address configured as their identifier in Azure AD. Anthos Identity Service uses the user's email to assert the user's identity and authenticate the request.
If you don't need to use group membership information, you can still use an azuread
section instead of oidc
to simplify configuration of on-premises clusters for Azure AD: defaults for any remaining configuration information are provided by Anthos Identity Service.
Add an azuread
section as follows. All fields are required.
...
spec:
authentication:
- name: NAME
azureAD:
clientID: CLIENT_ID
clientSecret: CLIENT_SECRET
tenant: TENANT_ID
kubectlRedirectURI: http://localhost:PORT/callback
...
Replace the following:
- NAME: 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.
- CLIENT_ID: The client ID returned when registering Anthos Identity Service with your provider.
- CLIENT_SECRET: Shared secret between the OIDC client application and the OIDC provider.
- TENANT: The kind of Azure AD account to be authenticated. Supported values are the tenant ID, or the tenant name for accounts belonging to a specific tenant. The tenant name is also known as the primary domain. For details on how to find these values, see Find the Microsoft Azure AD tenant ID and primary domain name.
- PORT: The port number chosen for the redirect URL used by the gcloud CLI, specified by your platform admin at registration.
Okta
With this config, you can authenticate using both users and groups with Okta as the identity provider.
...
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
...
What's next?
After the configuration is applied, continue to set up user access to clusters.