Log in using a configuration file

GKE Identity Service lets you log in to configured clusters from the command line using a username and password from a third party identity provider. Follow the instructions in this page if your cluster administrator has chosen to share a login configuration file for you to use when authenticating with gcloud CLI. For more information on accessing clusters, see Choose an access method to log in to clusters.

Login workflow

The following is the workflow that GKE Identity Service uses to let you log in to configured clusters using a login configuration file. The exact flow depends on the type of identity provider used.

OIDC workflow

With OIDC providers, a cluster administrator registers GKE Identity Service as a client application for the identity provider and sets up each cluster. They can add fine-grained access control using Kubernetes role-based access control (RBAC), if required.

You can log in to clusters in the following ways:

Command line access

Authenticate: Run the gcloud anthos auth login command and enter your OIDC login credentials. This retrieves an identity token from the provider.
Update Kubeconfig: The retrieved token is automatically added to your kubeconfig file.
Access cluster: Use kubectl to interact with your cluster. The Kubernetes API server uses GKE Identity Service to validate your token and authorize access.

Google Cloud console access

Initiate login: When you log in from the Google Cloud console, you are redirected to the identity provider's login page.
Authenticate: Enter your credentials and successfully log in.
Access cluster: Return to the Google Cloud console to view and manage your cluster resources.

LDAP workflow

With LDAP providers, a cluster administrator sets up GKE Identity Service for each cluster, which includes the LDAP client credentials. Cluster administrators can add fine-grained access control using Kubernetes role-based access control (RBAC), if required.

Command line access

Initiate login: Run the gcloud anthos auth login command and enter your LDAP login credentials.
Token generation: GKE Identity Service queries the LDAP server, retrieves your user attributes, and packages these attributes into a short-lived token (STS). Your LDAP credentials are not stored locally.
Kubeconfig update: The STS token is automatically added to your kubeconfig file.
Cluster access: Use kubectl to interact with your cluster. The Kubernetes API server uses GKE Identity Service to validate your token and authorize access. By default, the token expires after one hour, requiring the user to log in again.

To authenticate to clusters from the command line, you need to run gcloud authentication commands, using a login configuration file provided by your cluster administrator.

Get the configuration file

The gcloud CLI assumes a default filename and location on your local machine for your authentication configuration file. Your administrator might copy the file to your machine for you. If you are manually provided the file and need to save it on your machine yourself, use the defaults to simplify your gcloud authentication commands.

Use the following commands to copy the authentication configuration file to the default location:

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

where [AUTH_CONFIG_FILE] is the name of your authentication configuration file. For example kubectl-anthos-config.yaml.

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

where [AUTH_CONFIG_FILE] is the name of your authentication configuration file. For example kubectl-anthos-config.yaml.

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

where [AUTH_CONFIG_FILE] is the name of your authentication configuration file. For example kubectl-anthos-config.yaml.

If you or your administrator choose to use a different filename or location (for example, if your administrator is providing the file at a secure URL), you can specify this using the --login-config flag with each of your authentication requests. See the following section for more details.

Authenticate to the cluster

Run gcloud commands to authenticate with your clusters:

Run the gcloud anthos auth login command to initiate the authentication flow:
```
gcloud anthos auth login \
 --cluster [CLUSTER_NAME] \
 --user [USER_NAME] \
 --login-config [AUTH_CONFIG_FILE_PATH] \
 --login-config-cert [CA_CERT_PEM_FILE] \
 --kubeconfig [CLUSTER_KUBECONFIG]
```
Replace the following:
- [CLUSTER_NAME] (optional) specifies the name of your cluster. If this flag is omitted, you are prompted to choose from the clusters that are specified in your authentication configuration file.
- [USER_NAME] (optional) specifies the username for the credentials stored in the kubeconfig file. The default value is [CLUSTER_NAME]-anthos-default-user.
- [AUTH_CONFIG_FILE_PATH] (optional) specifies the custom path or URL to where your authentication configuration file is stored or hosted. You can omit this parameter, if the file is in the default location. Example: --login-config /path/to/custom/authentication-config.yaml
- [CA_CERT_PEM_FILE] (optional) specifies the path to a PEM certificate file from your CA. If your authentication configuration file is hosted securely, you can use an HTTPS connection to access the file. Example: --login-config-cert my-cert.pem
- [CLUSTER_KUBECONFIG] (optional) specifies the custom path to your cluster's kubeconfig file. The OIDC ID tokens that are returned by your OpenID provider are stored in the kubeconfig file.
  
  Use this flag if your kubeconfig file resides in a location other than the default. If this flag is omitted, authentication tokens are added to the kubeconfig file in the default location. Example: --kubeconfig /path/to/custom.kubeconfig
Examples:
- Authenticate to specific cluster:
```
gcloud anthos auth login --cluster my-production-cluster
```
- Use a prompt to select which cluster to authenticate with:
```
gcloud anthos auth login
```
  Result:
```
Please use the --cluster flag to specify a cluster from the list below:
Source: $HOME/.config/google/anthos/kubectl-anthos-config.yaml
1. Cluster: projects/1000000000000/locations/global/memberships/gke-gcp-cluster ServerIP: https://104.198.180.50:440
2. Cluster: projects/1000000000000/locations/global/memberships/gke-baremetal-cluster ServerIP: https://104.198.180.51:440
3. Cluster: projects/1000000000000/locations/global/memberships/gke-onprem-cluster ServerIP: https://104.198.180.52:440
4. Cluster: projects/1000000000000/locations/global/memberships/gke-aws-cluster ServerIP: https://104.198.180.53:440
```
- Use a hosted authentication configuration file:
```
gcloud anthos auth login \
 --cluster my-production-cluster \
 --login-config HTTPS://my-secure-server/kubectl-anthos-config.yaml \
 --login-config-cert my-cert.pem
```
- Use a prompt to select an authentication option. For more information, see Choose an authentication method.
Enter your credentials in the browser-based consent screen that opens. If this succeeds, your kubeconfig file should now contain an ID token that your kubectl commands will use to authenticate with the Kubernetes API server on your cluster.
Verify that authentication was successful by running one of the kubectl commands to access a resource on your cluster. For example, if you have access to the "nodes" resource on the cluster (this access is configured by your cluster administrator), you should be able to run the following command and view the cluster's nodes:
```
kubectl get nodes --kubeconfig [CLUSTER_KUBECONFIG]
```

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

Choose an authentication method

If your cluster administrator has configured multiple identity providers for your cluster (for example, an OIDC provider and an LDAP server), and has not configured a default provider for your cluster, you are prompted at login to select an authentication option, as in the following example:

gcloud anthos auth login

Please select your preferred authentication option for cluster [gke-onprem-ldap]
[1] LDAP Server
[2] OIDC
[3] cancel

Please enter your numeric choice:

1

Setting Preferred Authentication option to [LDAP Server]

Enter a numeric choice, then continue to log in as described in Authenticate to the cluster above.

Your chosen authentication option is saved until either your cluster administrator changes the default provider for this cluster, or you change it yourself. To change your preferred authentication option, use the --set-preferred-authentication flag.

gcloud anthos auth login --set-preferred-authentication

You should see a result like the following example, letting you choose a new preferred authentication option:

Your current authentication method is [1] AD Server. Please select your preferred authentication option for cluster [gke-onprem-ldap]
[1] LDAP Server
[2] OIDC
[3] cancel

Please enter your numeric choice:

2

Setting Preferred Authentication option to [OIDC]

Use SSH to authenticate from a remote machine

To connect to a remote machine and authenticate to a cluster with SSH, your authentication configuration file must be on the remote machine, and you must be able to reach your OpenID provider from your local machine.

On your local machine, run the following command:

ssh [USER_NAME]@[REMOTE_MACHINE] -L [LOCAL_PORT]:localhost:[REMOTE_PORT]

Replace the following:

[USER_NAME] and [REMOTE_MACHINE] are the standard values used to log in with SSH.
[LOCAL_PORT] is an open port of your choice on your local machine that you will use to access the remote machine.
[REMOTE_PORT] is the port you configured for your OIDC redirect URL. You can find this in the kubectlRedirectURI field of your authentication configuration file.

In your SSH shell, run the following command to initiate authentication:

gcloud anthos auth login --login-config [AUTH_CONFIG_FILE]

where [AUTH_CONFIG_FILE] is the path of your authentication configuration file on the remote machine.

On your local machine, in a browser, go to http://localhost:[LOCAL_PORT]/login and complete the OIDC login flow.

Now the kubeconfig file on your remote machine has the token that you need to access the cluster.

In your SSH shell, verify that you have access to the cluster:

kubectl --kubeconfig [CLUSTER_KUBECONFIG] get nodes