This page shows you how to configure authentication to Google Kubernetes Engine (GKE) clusters from external identity providers (IdPs).
This page is intended for Platform admins and operators and Identity and account admins who use an external IdP that supports OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) 2.0.
Before reading this page, ensure that you're familiar with the following authentication and OpenID concepts:
External IdP authentication methods in GKE
Recommended — Workforce Identity Federation
Workforce Identity Federation is an IAM feature that lets you authenticate to Google Cloud from any external IdP that supports OIDC or SAML 2.0. Workforce Identity Federation doesn't require any in-cluster installation, works with Autopilot clusters and Standard clusters, and is built into Google Cloud. For details, see the IAM documentation about Workforce Identity Federation.
Not recommended — Identity Service for GKE
In GKE Standard clusters only, GKE also supports Identity Service for GKE. Identity Service for GKE is limited to OIDC IdPs and installs additional components in your cluster. GKE strongly recommends using Workforce Identity Federation instead of Identity Service for GKE.
Before you begin
Before you start, make sure you have performed the following tasks:
- Enable the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- If you want to use the Google Cloud CLI for this task,
install and then
initialize the
gcloud CLI. If you previously installed the gcloud CLI, get the latest
version by running
gcloud components update
.
Considerations
Headless systems are unsupported with both Workforce Identity Federation and Identity Service for GKE. A browser-based authentication flow prompts you for consent and to authorize your user account.
Use Workforce Identity Federation in GKE
To use Workforce Identity Federation in your GKE clusters, do the following:
- Set up Workforce Identity Federation for your organization and external IdP. For instructions, see Configure Workforce Identity Federation.
- Set up access from your external IdP to the Google Cloud Workforce Identity Federation console. For details, see Set up user access to the console (federated).
Configure user access by using one the following authorization mechanisms:
Configure user access to clusters using RBAC
Google Cloud uses principal identifiers to identify users in your workforce identity pools. You can refer to these principal identifiers in your Kubernetes RBAC policies or in IAM policies. You can give permissions to individuals or groups of users, like in the following examples:
Identity | Principal identifier |
---|---|
Single user | principal://iam.googleapis.com/locations/global/workforcePools/ Replace the following:
For example: principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/amal@example.com |
All users in a group | principalSet://iam.googleapis.com/locations/global/workforcePools/ Replace the following:
For example: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre |
For every principal identifier that Workforce Identity Federation supports, see Represent workforce pool users in IAM policies.
The following example shows you how to give cluster-wide read-only access on
Secrets to any entities in the full-time-employees
workforce pool that have
the access_level="sensitive"
attribute in their IdP token.
Save the following ClusterRole manifest as
secret-viewer-cluster-role.yaml
:apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: secret-viewer rules: - apiGroups: [""] resources: ["secrets"] verbs: ["get", "watch", "list"]
Any principal to which you bind this ClusterRole can view Secrets.
Save the following ClusterRoleBinding manifest as
secret-viewer-cluster-role-binding.yaml
:apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: users-view-secrets subjects: - kind: Group name: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/attribute.access_level/sensitive apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole name: secret-viewer apiGroup: rbac.authorization.k8s.io
This ClusterRoleBinding grants the
secret-viewer
ClusterRole to any user who has theaccess_level="sensitive"
attribute.Deploy the ClusterRole and the ClusterRoleBinding:
kubectl apply -f secret-viewer-cluster-role.yaml kubectl apply -f secret-viewer-cluster-role-binding.yaml
Migrate Identity Service for GKE clusters to Workforce Identity Federation
If you use Identity Service for GKE in existing GKE clusters, migrate to Workforce Identity Federation. These methods use different syntaxes to refer to the same principals, as shown in the following table:
Identity Service for GKE syntax | Workforce Identity Federation syntax |
---|---|
amal@example.com |
principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/amal@example.com
|
sre-group |
principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre-group
|
To migrate a cluster to use Workforce Identity Federation, do the following:
Set up Workforce Identity Federation for your organization and external IdP. For instructions, see Configure Workforce Identity Federation.
Update the manifests for any RoleBindings and ClusterRoleBindings in your clusters to use the Workforce Identity Federation identifier syntax. Use one of the following options:
Programmatic updates: install and run the
gke-identity-service-migrator
utility. For instructions, see theGoogleCloudPlatform/gke-utilities
repository README.This utility finds existing RBAC bindings that use the Identity Service for GKE syntax and creates new manifests that use the corresponding Workforce Identity Federation principal identifiers.
Manual updates: For every binding that references an authenticated user or group, create a separate copy of the object's manifest file that uses the Workforce Identity Federation identifier syntax.
Apply the updated manifests for RoleBindings and ClusterRoleBindings to your cluster.
Test that users can access the same resources when they authenticate using Workforce Identity Federation.
Remove the obsolete RBAC bindings from your cluster.
Use Identity Service for GKE
To set up and use Identity Service for GKE on your GKE Standard mode cluster, cluster administrators do the following:
- Enable Identity Service for GKE on a cluster.
- Configure Identity Service for GKE.
- Create an RBAC policy for your cluster.
After cluster administrators configure Identity Service for GKE, developers can log in and authenticate to the cluster.
Kubernetes objects created by Identity Service for GKE
The following table describes the Kubernetes objects created when you enable Identity Service for GKE on a cluster:
Kubernetes objects | |
---|---|
anthos-identity-service |
Namespace Used for the Identity Service for GKE deployments. |
kube-public |
Namespace Used for the default client configuration file. |
gke-oidc-envoy |
LoadBalancer The endpoint for OIDC requests. External by default. If created in a cluster with no external IP endpoint, the endpoint is internal to the cluster Virtual Private Cloud. Created in the anthos-identity-service namespace. |
gke-oidc-service |
ClusterIP Facilitates communication between the gke-oidc-envoy
Deployment and the gke-oidc-service Deployment.Created in the anthos-identity-service namespace. |
gke-oidc-envoy |
Deployment Runs a proxy exposed to the gke-oidc-envoy
LoadBalancer. Communicates with gke-oidc-service to validate
identity tokens. Acts as a proxy for the Kubernetes API server, and
impersonates users
when passing on requests to the API server.Created in the anthos-identity-service namespace. |
gke-oidc-service |
Deployment Validates identity tokens, and provides a validating admission webhook for ClientConfig resources.Created in the anthos-identity-service namespace. |
gke-oidc-operator |
Deployment Reconciles the client configuration and the gke-oidc-envoy
LoadBalancer. Created in the anthos-identity-service namespace. |
gke-oidc-certs |
Secret Contains the cluster certificate authority (CA) and TLS certificates for the LoadBalancer. Created in the anthos-identity-service namespace |
default |
ClientConfig CRD Contains OIDC parameters such as preferred authentication method, identity provider configuration, and user and group claims mappings. Used for identity token validation. Used by cluster administrators to configure OIDC settings before distributing to developers. Created in the kube-public namespace |
Enable Identity Service for GKE on a cluster
By default, Identity and Access Management (IAM) is configured as the identity provider for cluster authentication. If you want to use OIDC with third-party identity providers, you can enable Identity Service for GKE on new or existing clusters using the Google Cloud CLI.
Enable Identity Service for GKE on a new cluster
To create a cluster with Identity Service for GKE enabled, run the following command:
gcloud container clusters create CLUSTER_NAME \
--enable-identity-service
Replace CLUSTER_NAME
with the name of your new cluster.
Enable Identity Service for GKE on an existing cluster
To enable Identity Service for GKE on an existing cluster, run the following command
gcloud container clusters update CLUSTER_NAME \
--enable-identity-service
Replace CLUSTER_NAME
with the name of your cluster.
Configure Identity Service for GKE
You can configure Identity Service for GKE parameters by downloading and
modifying the default
ClientConfig.
Download the
default
ClientConfig:kubectl get clientconfig default -n kube-public -o yaml > client-config.yaml
Update the
spec.authentication
section with your preferred settings:apiVersion: authentication.gke.io/v2alpha1 kind: ClientConfig metadata: name: default namespace: kube-public spec: name: cluster-name server: https://192.168.0.1:6443 authentication: - name: oidc oidc: clientID:
CLIENT_ID certificateAuthorityData:OIDC_PROVIDER_CERTIFICATE extraParams:EXTRA_PARAMS issuerURI:ISSUER_URI cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc kubectlRedirectURI:KUBECTL_REDIRECT_URL scopes:SCOPES userClaim:USER groupsClaim:GROUPS userPrefix:USER_PREFIX groupPrefix:GROUP_PREFIX Replace the following:
CLIENT_ID
: the ID of the client application that makes authentication requests to the OIDC provider.OIDC_PROVIDER_CERTIFICATE
: (Optional) a PEM certificate for the OIDC provider. This field might be useful if your OIDC provider uses self-signed certificates. Identity Service for GKE includes a set of public roots by default.EXTRA_PARAMS
: additional key-value parameters to send to the OIDC provider.- To authorize groups, use
resource=token-groups-claim
. - To authenticate Microsoft Azure and Okta, use
prompt=consent
. - For Cloud Identity, use
prompt=consent,access_type=offline
.
- To authorize groups, use
ISSUER_URI
: the URL to send OIDC authorization requests, such ashttps://example.com/adfs
. The Kubernetes API server uses this URL to discover public keys for verifying tokens. The URI must use HTTPS. For Cloud Identity, usehttps://accounts.google.com
.KUBECTL_REDIRECT_URL
: the redirect URL thatkubectl oidc login
uses for authorization. This is typically of the formathttp://localhost:PORT/callback
, wherePORT
is any port greater than1024
that will be available on developer workstations, for examplehttp://localhost:10000/callback
. You must register the URL with your OIDC provider as an authorized redirect URL for the client application. If you use Google Identity as your OIDC provider, read Set a redirect URI for instructions.SCOPES
: the additional scopes to send to the OIDC provider.- Microsoft Azure and Okta require the
offline_access
scope. - For Cloud Identity, use
openid, email
to obtain ID tokens that contain the email address in theemail
claim.
- Microsoft Azure and Okta require the
USER
: the user claim from the identity token.GROUPS
: the group claim from the identity token.USER_PREFIX
: prefix prepended to user claims to prevent conflicts with existing names. By default, an issuer prefix is appended to theuserID
given to the Kubernetes API server (unless the user claim isemail
). The resulting user identifier isISSUER_URI#USER
. We recommend using a prefix, but you can disable the prefix by settingUSER_PREFIX
to-
.GROUP_PREFIX
: prefix prepended to group claims to prevent clashes with existing names. For example, if you have two groups namedfoobar
, add a prefixgid-
. The resulting group isgid-foobar
.
Apply the updated configuration:
kubectl apply -f client-config.yaml
After you apply this configuration, Identity Service for GKE runs inside your cluster and serves requests behind the
gke-oidc-envoy
load balancer. The IP address in thespec.server
field must be the IP address of the load balancer. If you change thespec.server
field,kubectl
commands might fail.Make a copy of the
client-config.yaml
configuration file:cp client-config.yaml login-config.yaml
Update the
login-config.yaml
configuration file with theclientSecret
setting in thespec.authentication.oidc
section.clientSecret:
CLIENT_SECRET Replace
CLIENT_SECRET
with the shared secret between the OIDC client application and the OIDC provider.Distribute the updated
login-config.yaml
file to your developers.
Configure Identity Service for GKE on clusters with strict policies
To configure Identity Service for GKE to work as expected on clusters that have strict network policies in place, do the following:
- Add a firewall rule
for TCP port
15000
to allow your control plane to communicate with theClientConfig
validation webhook. - If the
gke-oidc-envoy
is created as an internal load balancer, expose it on your VPC. - If you have policies that deny traffic within your cluster,
add a firewall rule for TCP port
8443
to allow thegke-oidc-envoy
deployment to communicate with thegke-oidc-service
deployment.
Identity Service for GKE component version 0.2.20 and later does not use
TCP port 15000
. If your component version is 0.2.20 or
later, you don't need to add a firewall rule for port 15000
. To check your
component version, run the following command:
kubectl describe deployment gke-oidc-envoy -n anthos-identity-service \
| grep "components.gke.io/component-name: gke-oidc" -A1
Add custom properties to the load balancer
After you configure Identity Service for GKE, you can add custom
annotations and properties, such as a static IP address, to the gke-oidc-envoy
load balancer. To edit the gke-oidc-envoy
service, run the following
command:
kubectl edit service gke-oidc-envoy -n anthos-identity-service
Consult LoadBalancer Service parameters for more information about configuring TCP/UDP load balancing for GKE.
Create an RBAC policy for your cluster
Administrators can use Kubernetes role-based access control (RBAC) to grant access to authenticated cluster users. To configure RBAC for your cluster, you must grant RBAC roles for each developer. To grant access to resources in a particular namespace, create a Role and a RoleBinding . To grant access to resources across an entire cluster, create a ClusterRole and a ClusterRoleBinding.
For example, consider a user who needs to view all Secret objects across the cluster. The following steps grant the required RBAC roles to this user.
Save the following ClusterRole manifest as
secret-viewer-cluster-role.yaml
. A person who is granted this role can get, watch, and list any Secret in the cluster.apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: secret-viewer rules: - apiGroups: [""] # The resource type for which access is granted resources: ["secrets"] # The permissions granted by the ClusterRole verbs: ["get", "watch", "list"]
Apply the ClusterRole manifest:
kubectl apply -f secret-viewer-cluster-role.yaml
Save the following ClusterRoleBinding manifest as
secret-viewer-cluster-role-binding.yaml
. The binding grants thesecret-viewer
role to a username defined in the client configuration file.apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: people-who-view-secrets subjects: - kind: User name:
ISSUER_URI #USER apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole name: secret-viewer apiGroup: rbac.authorization.k8s.ioReplace the following:
ISSUER_URI
: the issuer URI fromspec.authentication.oidc.issuerURI
in the client configuration file.USER
: the user identifier in the token under the claim name configured inspec.authentication.oidc.userClaim
in the client configuration file.
Apply the ClusterRoleBinding manifest:
kubectl apply -f secret-viewer-cluster-role-binding.yaml
Sign in and authenticate to the cluster
As a developer who receives the OIDC configuration file from your administrator, you can authenticate to your clusters.
Download the
login-config.yaml
file provided by your administrator.Install the Google Cloud CLI SDK, which offers a separate OIDC component. You can install this by running the following command:
gcloud components install kubectl-oidc
Authenticate into your cluster:
kubectl oidc login --cluster=
CLUSTER_NAME --login-config=login-config.yamlA web browser opens to complete the authentication process.
After you are authenticated, you can run
kubectl
commands, for example:kubectl get pods
Disable Identity Service for GKE
You can disable Identity Service for GKE with the gcloud CLI. To disable Identity Service for GKE, run the following command:
gcloud container clusters update CLUSTER_NAME \
--no-enable-identity-service
What's next
- Learn more about Workforce Identity Federation.
- Learn more about deploying workloads.