mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-05-05 04:33:18 +00:00
Billy Tat
24fc5a657c
* Sync main to v2.13.0 (#2065) * It's bad form to ask users to pass something they just curled from the internet directly to sh Updated the instructions for uninstalling the rancher-system-agent to use a temporary script file instead of piping directly to sh. * doc(rancher-security): improve structure and content to latest, v2.13-preview and v2.12 (#2024) - add Rancher Kubernetes Distributions (K3s/RKE2) Self-Assessment and Hardening Guide section - add kubernetes cluster security best practices link to rancher-security section - add k3s-selinux and update selinux-rpm details - remove rhel/centos 7 support Signed-off-by: Andy Pitcher <andy.pitcher@suse.com> * Updating across supported versions and translations. Signed-off-by: Sunil Singh <sunil.singh@suse.com> --------- Signed-off-by: Andy Pitcher <andy.pitcher@suse.com> Signed-off-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Tejeev <tj@rancher.com> Co-authored-by: Andy Pitcher <andy.pitcher@suse.com> Co-authored-by: Sunil Singh <sunil.singh@suse.com> * Update roletemplate aggregation doc and version information * Add versioned docs * Remove ext token and kubeconfig feature flag sections and document bearer Token * Update corresponding v2.13 pages * update doc for pni in gke * Adding reverted session idle information from PR 1653 Signed-off-by: Sunil Singh <sunil.singh@suse.com> * [2.13.0] Add versions table entry * [2.13.0] Add webhook version * [2.13.0] Add CSP Adapter version * [2.13.0] Add deprecated feature table entry * [2.13.0] Update CNI popularity stats * Update GKE Cluster Configuration for Project Network Isolation instructions * Fix link and port to 2.13 * [2.13.0] Add Swagger JSON * [v2.13.0] Add info about Azure AD Roles claims (#2079) * Add info about Azure AD roles claims compatibility * Apply suggestions from code review Co-authored-by: Sunil Singh <sunil.singh@suse.com> * Add suggestions to v2.13 --------- Co-authored-by: Sunil Singh <sunil.singh@suse.com> * [2.13.0] Remove preview designation * user public api docs (#2069) * user public api docs * Apply suggestions from code review Co-authored-by: Andreas Kupries <akupries@suse.com> * Apply suggestions from code review Co-authored-by: Peter Matseykanets <pmatseykanets@gmail.com> * explain plaintext is never stored * add users 2.13 versioned docs * remove extra ``` * Apply suggestions from code review Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> * add space before code block --------- Co-authored-by: Andreas Kupries <akupries@suse.com> Co-authored-by: Peter Matseykanets <pmatseykanets@gmail.com> Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> * support IPv6 (#2041) * [v2.13.0] Add Configure GitHub App page (#2081) * Add Configure GitHub App page * Apply suggestions from code review Co-authored-by: Billy Tat <btat@suse.com> * Fix header/GH URL & add suggestions to v2.13 * Apply suggestions from code review Co-authored-by: Petr Kovar <pknbe@volny.cz> * Apply suggestions from code review to v2.13 * Add note describing why to use Installation ID * Apply suggestions from code review Co-authored-by: Billy Tat <btat@suse.com> --------- Co-authored-by: Billy Tat <btat@suse.com> Co-authored-by: Petr Kovar <pknbe@volny.cz> * [v2.13.0] Add info about Generic OIDC Custom Mapping (#2080) * Add info about Generic OIDC Custom Mapping * Apply suggestions from code review Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Billy Tat <btat@suse.com> * Apply suggestions from code review Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Billy Tat <btat@suse.com> * Add suggestions to v2.13 * Remove repetitive statement in intro * Move Prereq intro/note to appropriate section * Fix formatting, UI typo, add Custom Claims section under Configuration Reference section * Add section about how a custom groups claim works / note about search limitations for groups in RBAC --------- Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Billy Tat <btat@suse.com> * [v2.13.0] Add info about OIDC SLO support (#2086) * Add shared file covering OIDC SLO support to OIDC auth pages * Ad How to get the End Session Endpoint steps * Add generic curl exampleto retrieve end_session_endpoint * [2.13.0] Bump release date --------- Signed-off-by: Andy Pitcher <andy.pitcher@suse.com> Signed-off-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> Co-authored-by: Tejeev <tj@rancher.com> Co-authored-by: Andy Pitcher <andy.pitcher@suse.com> Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Jonathan Crowther <jonathan.crowther@suse.com> Co-authored-by: Peter Matseykanets <peter.matseykanets@suse.com> Co-authored-by: Petr Kovar <petr.kovar@suse.com> Co-authored-by: Krunal Hingu <krunal.hingu222@gmail.com> Co-authored-by: Raul Cabello Martin <raul.cabello@suse.com> Co-authored-by: Andreas Kupries <akupries@suse.com> Co-authored-by: Peter Matseykanets <pmatseykanets@gmail.com> Co-authored-by: Jack Luo <jiaqi.luo@suse.com> Co-authored-by: Petr Kovar <pknbe@volny.cz>
91 lines
6.8 KiB
Markdown
91 lines
6.8 KiB
Markdown
---
|
|
title: Using API Tokens
|
|
---
|
|
|
|
<head>
|
|
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/api-tokens"/>
|
|
</head>
|
|
|
|
Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher/cli-with-rancher.md), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api).
|
|
|
|
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**.
|
|
|
|
The following is a complete list of tokens generated with `ttl=0`:
|
|
|
|
| Token | Description |
|
|
| ----------------- | -------------------------------------------------------------------------------------- |
|
|
| `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 |
|
|
| `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`](#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`](#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).
|
|
|
|
:::
|
|
|
|
## 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](../reference-guides/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.
|
|
|
|
## Token Hashing
|
|
|
|
You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), 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.
|
|
|
|
| Setting | Description |
|
|
| ------- | ----------- |
|
|
| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. |
|
|
| [`auth-user-session-idle-ttl-minutes`](#auth-user-session-idle-ttl-minutes) | TTL in minutes on a user auth session token, without user activity. |
|
|
| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). |
|
|
| [`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 must 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.
|
|
|
|
### auth-user-session-idle-ttl-minutes
|
|
|
|
Time to live (TTL) without user activity for login sessions tokens, in minutes.
|
|
By default, [`auth-user-session-idle-ttl-minutes`](#auth-user-session-idle-ttl-minutes) is set to the same value as [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) (for backward compatibility). It must never exceed the value of `auth-user-session-ttl-minutes`.
|
|
|
|
### 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`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). 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](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).
|