mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-04-15 19:05:41 +00:00
91 lines
8.0 KiB
Markdown
91 lines
8.0 KiB
Markdown
---
|
|
title: API Tokens
|
|
---
|
|
|
|
<head>
|
|
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/reference-guides/about-the-api/api-tokens"/>
|
|
</head>
|
|
|
|
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`.
|
|
|
|
1. Access the token you want to delete by its ID. For example, `https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt`
|
|
|
|
1. Click **Delete**.
|
|
|
|
Here is the complete list of tokens that are 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 |
|
|
| `telemetry-*` | Telemetry token |
|
|
| `drain-node-*` | Token for drain (we use `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`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 0, which means 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).
|
|
|
|
:::
|
|
|
|
### Disable Tokens in Generated Kubeconfigs
|
|
|
|
1. 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. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) 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.
|
|
|
|
2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours).
|
|
|
|
### Token Hashing
|
|
|
|
Users can enable token hashing, where tokens will 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](../../pages-for-subheaders/enable-experimental-features.md).
|
|
|
|
This feature will affect 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`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. |
|
|
| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** |
|
|
| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | TTL used for tokens generated via the CLI. **Deprecated since version 2.6.6, and will be removed in 2.8.0.** This setting will be removed, and `kubeconfig-default-token-TTL-minutes` will be used for all kubeconfig tokens. |
|
|
| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). |
|
|
| [`kubeconfig-generate-token`](#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 will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#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 will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs).
|
|
**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`](#kubeconfig-generate-token) is false. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes).
|
|
**Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes).**
|
|
|
|
#### 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 will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests.
|
|
**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.**
|
|
|
|
#### kubeconfig-generate-token
|
|
When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).
|