Use external identity providers to authenticate to GKE


This page explains how to configure an external identity provider to authenticate into Google Kubernetes Engine (GKE) clusters.

Overview

Identity Service for GKE extends your existing identity solutions for authentication into your GKE clusters. With support for OpenID Connect (OIDC), you can manage access to Kubernetes clusters by using the standard procedures in your organization for creating, enabling, and disabling user accounts. Identity Service for GKE is limited to OIDC identity providers.

Before you begin

  • Before reading this page, ensure that you're familiar with the following authentication and OpenID concepts:

  • Headless systems are unsupported. A browser-based authentication flow is used to prompt you for consent and authorize your user account.

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.

Who uses Identity Service for GKE

The tasks in this document apply to you if you are one of the following:

  • Cluster administrators: Create one or more user clusters and create authentication configuration files for developers who use the clusters.

  • Developers: Run workloads on one or more clusters and uses OIDC to authenticate.

How it works

To set up and use Identity Service for GKE on your GKE cluster, cluster administrators do the following:

  1. Enable Identity Service for GKE on a cluster.
  2. Configure Identity Service for GKE.
  3. Create an RBAC policy for your cluster.

After cluster administrators configure Identity Service for GKE, developers can log in and authenticate to the cluster.

Enable Identity Service for GKE on a cluster

This section is for cluster administrators.

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.

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

Configure Identity Service for GKE

This section is for cluster administrators.

You can configure Identity Service for GKE parameters by downloading and modifying the default ClientConfig.

  1. Download the default ClientConfig:

    kubectl get clientconfig default -n kube-public -o yaml > client-config.yaml
    
  2. 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.
    • ISSUER_URI: the URL to send OIDC authorization requests, 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. For Cloud Identity, use https://accounts.google.com.
    • KUBECTL_REDIRECT_URL: the redirect URL that kubectl oidc login uses for authorization. This is typically of the format http://localhost:PORT/callback, where PORT is any port above 1024 that will be available on developer workstations, for example http://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 the email claim.
    • 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 the userID given to the Kubernetes API server (unless the user claim is email). The resulting user identifier is ISSUER_URI#USER. We recommend using a prefix, but you can disable the prefix by setting USER_PREFIX to -.
    • GROUP_PREFIX: 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.
  3. 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 the spec.server field must be the IP address of the load balancer. If you change the spec.server field, kubectl commands might fail.

  4. Make a copy of the client-config.yaml configuration file:

    cp client-config.yaml login-config.yaml
    
  5. Update the login-config.yaml configuration file with the clientSecret setting in the spec.authentication.oidc section.

    clientSecret: CLIENT_SECRET
    

    Replace CLIENT_SECRET with the shared secret between the OIDC client application and the OIDC provider.

  6. 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:

  1. Add a firewall rule for TCP port 15000 to allow your control plane to communicate with the ClientConfig validation webhook.
  2. If the gke-oidc-envoy is created as an internal load balancer, expose it on your VPC.
  3. If you have policies that deny traffic within your cluster, add a firewall rule for TCP port 8443 to allow the gke-oidc-envoy deployment to communicate with the gke-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

This section is for cluster administrators.

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.

  1. 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"]
    
  2. Apply the ClusterRole manifest:

    kubectl apply -f secret-viewer-cluster-role.yaml
    
  3. Save the following ClusterRoleBinding manifest as secret-viewer-cluster-role-binding.yaml. The binding grants the secret-viewer role to a user name 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.io
    

    Replace the following:

    • ISSUER_URI: the issuer URI from spec.authentication.oidc.issuerURI in the client configuration file.
    • USER: the user identifier in the token under the claim name configured in spec.authentication.oidc.userClaim in the client configuration file.
  4. Apply the ClusterRoleBinding manifest:

    kubectl apply -f secret-viewer-cluster-role-binding.yaml
    

Log in and authenticate to the cluster

This section is for developers.

When you receive the OIDC configuration file from your administrator, you can authenticate to your clusters.

  1. Download the login-config.yaml file provided by your administrator.

  2. 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
    
  3. Authenticate into your cluster:

    kubectl oidc login --cluster=CLUSTER_NAME --login-config=login-config.yaml
    

    A web browser opens to complete the authentication process.

  4. After you are authenticated, you can run kubectl commands, for example:

    kubectl get pods
    

Disable Identity Service for GKE

This section is for cluster administrators.

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