c256118aa9
* API token docs are outdated, out of sync synced 2.8 and latest * updates and syncing with v2.7 * more syncing, more revisions, v2.6 versioning * more syncing * sync v2.8 w latest * Duration according to https://github.com/rancher/rancher/pull/42269 * Apply suggestions from code review Co-authored-by: Billy Tat <btat@suse.com> * syncing how we describe the value * capitalization of ttl --------- Co-authored-by: Billy Tat <btat@suse.com>
8.1 KiB
title
| title |
|---|
| API Tokens |
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:
-
Go to the list of all tokens in the Rancher API view at
https://<Rancher-Server-IP>/v3/tokens. -
Access the token you want to delete by its ID. For example,
https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt -
Click Delete.
The following is a complete list of tokens generated with ttl=0:
| Token | Description |
|---|---|
kubeconfig-* |
Kubeconfig token |
kubectl-shell-* |
Access to kubectl shell in the browser |
agent-* |
Token for agent deployment |
compose-token-* |
Token for compose |
helm-token-* |
Token for Helm chart deployment |
*-pipeline* |
Pipeline token for project |
telemetry-* |
Telemetry token |
drain-node-* |
Token for drain (Rancher uses kubectl for drain because there is no native Kubernetes API) |
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. The default value of kubeconfig-default-token-ttl-minutes is 0, which means that tokens never expire.
:::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-tokensetting tofalse. 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 askubectl, the Rancher CLI needs to be installed to complete the log in request. -
Set the
kubeconfig-token-ttl-minutessetting to the desired duration in minutes. By default,kubeconfig-token-ttl-minutesis 960 (16 hours).
Token Hashing
Users 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. It is advisable to take backups prior to enabling and/or evaluating in a test environment first.
To enable token hashing, refer to this section.
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.
| Setting | Description |
|---|---|
auth-user-session-ttl-minutes |
TTL in minutes on a user auth session token. |
kubeconfig-default-token-ttl-minutes |
Default TTL applied to all kubeconfig tokens except those generated by Rancher CLI. Introduced in version 2.6.6. |
kubeconfig-token-ttl-minutes |
TTL used for tokens generated via the CLI. Deprecated since version 2.6.6, and removed in 2.8.0. Rancher v2.8 and later instead use kubeconfig-default-token-ttl-minutes for all kubeconfig tokens. |
auth-token-max-ttl-minutes |
Max TTL for all tokens except those controlled by auth-user-session-ttl-minutes. |
kubeconfig-generate-token |
If true, automatically generate tokens when a user downloads a kubeconfig. |
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. The default value is 0, which means that tokens never expire.
Introduced in version 2.6.6.
kubeconfig-token-ttl-minutes
Time to live (TTL) duration in minutes, used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when kubeconfig-generate-token is false. When the token is expired, the API rejects the token. This setting can't be larger than auth-token-max-ttl-minutes.
Deprecated since Rancher v2.6.6.
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. Auth tokens are tokens created for authenticating API requests. The default value is 0, which means that tokens never expire.
Rancher v2.6.6 and later: Applies to all kubeconfig tokens and api tokens.
kubeconfig-generate-token
When true, kubeconfigs requested through the UI contain a valid token. When false, the kubeconfig contains 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.