Set up an authentication method for user access

This document is for cluster administrators who have already configured their clusters for GKE Identity Service. It provides instructions on how to set up and manage user access to these configured clusters for your organization's developers and other users.

There are two types of authentication methods you can use to set up user access to your clusters:

  • Set up with FQDN access (Recommended): With this approach, users can directly authenticate to the GKE Identity Service server using the fully qualified domain name (FQDN) of the cluster's Kubernetes API server. For more information, see Set up FQDN access.
  • Set up with file-based access: With this approach, you generate a login configuration file and distribute it to cluster users. Users can then log in to configured clusters with gcloud authentication commands using this file. For more information, see Set up file-based access.

Set up FQDN access (Recommended)

This section tells you how to set up user login access by providing the user with the URL (FQDN) for a server to use for authentication. The authentication flow lets the user log in with their IdP and provides the user with a token that is added to their kubeconfig file for accessing the cluster. This authentication approach is supported only for on-premises clusters (Google Distributed Cloud) on VMware and bare metal, from version 1.29 onwards. Other cluster types are not supported. If you need to set up authentication for on-premises clusters using an older supported software version, or for other cluster types, follow the instructions to set up file-based access.

Before sharing the FQDN to users, ensure that you or your platform administrator have followed the appropriate setup, including DNS setup for the FQDN and providing the FQDN as part of registering to your identity provider if required.

Share FQDN with users

Instead of a configuration file, cluster administrators can share the FQDN of the cluster's Kubernetes API server with users. Users can use this FQDN to log in to the cluster. The URL format for login is APISERVER-URL, where the URL contains the FQDN of the API server.

An example format of an APISERVER-URL is https://apiserver.company.com.

Configure Identity Service options

With this set up option, you can configure the token lifetime duration. The IdentityServiceOptions in the ClientConfig CR has a sessionDuration parameter that lets you configure the token lifetime (in minutes). The sessionDuration parameter has a lower limit of 15 minutes and a maximum limit of 1440 minutes (24 hours).

Here's an example of what it looks like in the ClientConfig CR:

spec:
    IdentityServiceOptions:
      sessionDuration: INT

where INT is the session duration in minutes.

Set up file-based access

As an alternative to FQDN access, cluster administrators can generate a login configuration file and distribute it to cluster users. You may want to use this option if you are setting up authentication to a cluster with a version or type that does not support FQDN access. This file lets users access clusters from the command line with the chosen provider. This authentication approach is supported for OIDC and LDAP providers only.

Generate the login config

Console

(Fleet-level setup only)

Copy the displayed gcloud command and run it to generate the file.

gcloud

If you configured the cluster using gcloud CLI or if you need to generate the file again, run the following command to generate the file:

gcloud anthos create-login-config --kubeconfig=KUBECONFIG

where KUBECONFIG is the path to the kubeconfig file for the cluster. If there are multiple contexts in the kubeconfig, the current context is used. You may need to reset the current context to the correct cluster before running the command.

You can see complete reference details for this command, including additional optional parameters, in the Google Cloud CLI reference guide.

The default name for the login config file is kubectl-anthos-config.yaml, which is the name the Google Cloud CLI expects when using the file to log in. If you want to change this to a non-default name, see the relevant section in Distribute the login config.

For troubleshooting information related to user access, see Troubleshoot user access issues.

Distribute the login config

The following are some ways to distribute the config file:

  • Host the file at an accessible URL. Users can specify this location with the --login-config flag when running gcloud anthos auth login, allowing the Google Cloud CLI to get the file.

    Consider hosting the file on a secure host. See the --login-config-cert flag of the gcloud CLI for more information about using PEM certificates for secure HTTPS access.

  • Manually provide the file to each user, with information on where to save it on their local machine—the Google Cloud CLI expects to find the file in an OS-specific default location. If the file has a non-default name or location, your users must use the --login-config flag to specify the config file location when running commands against the cluster. Instructions for users to save the file are in Access clusters with GKE Identity Service.

  • Use your internal tools to push the authentication configuration file onto each user's machine. The Google Cloud CLI expects to find the file in the following locations, depending on the user OS:

    Linux

    $HOME/.config/google/anthos/kubectl-anthos-config.yaml

    macOS

    $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

    Windows

    %APPDATA%\google\anthos\kubectl-anthos-config.yaml