Tokens
Token Resource
Rancher has an imperative API resource tokens.ext.cattle.io
that allows you to generate tokens for authenticating with Rancher.
kubectl api-resources --api-group=ext.cattle.io
To get a description of the fields and structure of the Token resource, run:
kubectl explain tokens.ext.cattle.io
Feature Flag
The Tokens Public API is available for Rancher v2.12.0 and later, and is enabled by default. You can disable the Tokens Public API by setting the ext-tokens
feature flag to false
as shown in the example kubectl
command below:
kubectl patch feature ext-tokens -p '{"spec":{"value":false}}'
Creating a Token
The Token value is only returned once in the status.value
field.
Only a valid and active Rancher user can create a Token. Otherwise, you will get an error displayed (Error from server (Forbidden)...
) when attempting to create a Token.
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
EOF
Error from server (Forbidden): error when creating "STDIN": tokens.ext.cattle.io is forbidden: user system:admin is not a Rancher user
A Token is always created for the user making the request. Attempting to create a Token for a different user, by specifying a different spec.userID
, is forbidden and will fail.
The
spec.description
field can be set to an arbitrary human-readable description of the Token's purpose. The default value is empty.The
spec.kind
field can be set to the kind of Token. The valuesession
indicates a login Token. All other values, including the default empty string, indicate a kind of derived Token.The
metadata.name
andmetadata.generateName
fields are ignored, and the name of the new Token is automatically generated using the prefixtoken-
.kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
spec:
description: My Token
EOFIf the
spec.ttl
is not specified, the Token is created with the expiration time defined in theauth-token-max-ttl-minutes
setting. The default expiration time is 90 days. Ifspec.ttl
is specified, it should be greater than 0 and less than or equal to the value of theauth-token-max-ttl-minutes
setting expressed in milliseconds.kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
spec:
ttl: 7200000 # 2 hours
EOF
Listing Tokens
Listing previously generated Tokens can help clean up tokens that are no longer needed (e.g., they were issued temporarily). Admins can list all Tokens, while regular users can only see their own.
kubectl get tokens.ext.cattle.io
NAME KIND TTL AGE
token-chjc9 90d 18s
token-6fzgj 90d 16s
token-8nbrm 90d 14s
Use -o wide
to get more details:
kubectl get tokens.ext.cattle.io -o wide
NAME USER KIND TTL AGE DESCRIPTION
token-chjc9 user-jtghh 90d 24s example
token-6fzgj user-jtghh 90d 22s box
token-8nbrm user-jtghh 90d 20s jinx
Viewing a Token
Admins can get any Token, while regular users can only get their own.
kubectl get tokens.ext.cattle.io token-chjc9
NAME KIND TTL AGE
token-chjc9 90d 18s
Use -o wide
to get more details:
kubectl get tokens.ext.cattle.io token-chjc9 -o wide
NAME USER KIND TTL AGE DESCRIPTION
token-chjc9 user-jtghh 90d 24s example
Deleting a Token
Admins can delete any Token, while regular users can only delete their own.
kubectl delete tokens.ext.cattle.io token-chjc9
token.ext.cattle.io "token-chjc9" deleted
Updating a Token
Only the metadata fields spec.description
, spec.ttl
, and spec.enabled
can be updated. All other spec
fields are immutable. Admins can extend the spec.ttl
field, while regular users can only reduce the value.
An example kubectl
command to edit a Token:
kubectl edit tokens.ext.cattle.io token-zp786