Log in using a fully qualified domain name (FQDN)

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 let you authenticate directly on the GKE Identity Service server with a fully qualified domain name (FQDN). For SAML providers, login access is supported only through this authentication approach.

This authentication approach is supported only for on-prem clusters (Google Distributed Cloud) on VMware and bare metal, from version 1.29. Other cluster types are not supported.

The gcloud CLI version required to log in with your provided FQDN is atleast version 474.0.0.

Login workflow

Here are the workflow steps when a user logs in using the FQDN access approach:

1. Initiate login: The user runs the command gcloud anthos auth login --server APISERVER-URL to initiate the login process.
2. Identity provider selection: The user is given a list of configured identity providers. The user selects the provider where their credentials are stored.

3. Authentication with identity provider: The authentication process differs based on the identity provider protocol you choose:

   • OIDC: The user is redirected to the OIDC-provider login page. After a successful login, the provider sends a code back to the GKE Identity Service, which exchanges it for an access token through a back-channel communication.
   • SAML: The user is redirected to the SAML-provider login page. After a successful login, the provider directly sends a token (assertion) back to the GKE Identity Service thereby avoiding an additional callback.
   • LDAP: Instead of redirecting to an external provider, the GKE Identity Service displays a login page where the user enters their LDAP credentials, which is verified directly with the LDAP server.

4. Token verification and kubeconfig file generation: The GKE Identity Service verifies the token received (or assertion), creates a new token for the user, and sends back a kubeconfig file containing this token.

5. Cluster access: The user can access the cluster using kubectl commands. The kubectl client automatically sends the token from the kubeconfig file with each request.

6. Token validation and RBAC authorization: The Kubernetes API server receives the token, GKE Identity Service verifies this token, and retrieves the user's claims (username and groups). After successful validation, the API server runs Role-Based Access Control (RBAC) checks to determine the resources that the user is authorized to access.

Log in using trusted SNI certificates

SNI certificates simplify cluster access by leveraging trusted certificates already present on corporate devices. Administrators can specify this certificate at the time of cluster creation. If your cluster uses a trusted SNI certificate at the cluster level, use the command in this section with the FQDN provided by your administrator to log in to the cluster and receive an access token. You can also use a secure kubeconfig file where the token is stored after successful authentication.

Run the following command to authenticate to the server:

gcloud anthos auth login --server APISERVER-URL --kubeconfig OUTPUT_FILE

Replace the following:

• APISERVER-URL: FQDN of the cluster's Kubernetes API server.
• OUTPUT_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. For example: --kubeconfig /path/to/custom.kubeconfig.

Log in using cluster CA-issued certificates

If you don't use a trusted SNI certificate at the cluster level, then the certificate used by the identity service is issued by the cluster's certificate authority (CA). Administrators distribute this CA certificate to users. Run the following command using the cluster's CA certificate to log in to your cluster:

gcloud anthos auth login --server APISERVER-URL --kubeconfig OUTPUT_FILE --login-config-cert CLUSTER_CA_CERTIFICATE

Note: As a recommendation, users can trust the CA certificate on their devices and browsers by following the device-specific instructions. This is a one-time activity. Once the CA certificate is trusted, you can log in to the cluster without specifying the --login-config-cert argument in the command.