Using API Tokens

Rancher v2.8.0 introduced the Rancher Kubernetes API which can be used to manage Rancher resources through kubectl. This page covers information on API tokens used with the Rancher CLI, kubeconfig files, Terraform and the v3 API browser.

By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. Tokens are not invalidated by changing a password.

You can deactivate API tokens by deleting them or by deactivating the user account.

Deleting Tokens

To delete a token:

1. Go to the list of all tokens in the Rancher API view at https://<Rancher-Server-IP>/v3/tokens.

2. Access the token you want to delete by its ID. For example, https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt

3. Click Delete.

The following is a complete list of tokens generated with ttl=0:

Setting TTL on Kubeconfig Tokens

Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting kubeconfig-default-token-ttl-minutes to the desired duration in minutes. As of Rancher v2.8, the default value of kubeconfig-default-token-ttl-minutes is 43200, which means that tokens expire in 30 days.

note

This setting is used by all kubeconfig tokens except those created by the CLI to generate kubeconfig tokens.

Disable Tokens in Generated Kubeconfigs

Set the kubeconfig-generate-token setting to false. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the Rancher CLI to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as kubectl, the Rancher CLI needs to be installed to complete the log in request.

Token Hashing

You can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling.

This feature affects all tokens which include, but are not limited to, the following:

• Kubeconfig tokens
• Bearer tokens API keys/calls
• Tokens used by internal operations

Token Settings

These global settings affect Rancher token behavior.

auth-user-session-ttl-minutes

Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by auth-token-max-ttl-minutes. Session tokens are created when a user logs into Rancher.

kubeconfig-default-token-ttl-minutes

Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can’t be larger than auth-token-max-ttl-minutes. This setting applies to tokens generated in a requested kubeconfig file, except for tokens generated by Rancher CLI. As of Rancher v2.8, the default duration is 43200, which means that tokens expire in 30 days.

auth-token-max-ttl-minutes

Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than auth-token-max-ttl-minutes, Rancher sets the token TTL to the value of auth-token-max-ttl-minutes. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is 129600, which means that tokens expire in 90 days.

kubeconfig-generate-token

When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. The CLI then retrieves and caches a token for the user.