Token

Token auth method

The token auth method is built-in and automatically available at /auth/token. It allows users to authenticate using a token, as well to create new tokens, revoke secrets by token, and more.

When any other auth method returns an identity, Stronghold core invokes the token method to create a new unique token for that identity.

The token store can also be used to bypass any other auth method: you can create tokens directly, as well as perform a variety of other operations on tokens such as renewal and revocation.

Authentication

Via the CLI

To log in with a token, run the following command:

d8 stronghold login token=<TOKEN>

stronghold login token=<TOKEN>

Where <TOKEN> is the token value.

Via the API

The token is set directly as a header for the HTTP API. The header should be either X-Vault-Token: <TOKEN> or Authorization: Bearer <TOKEN>, where <TOKEN> is the token value.

Creating tokens

Tokens are created with d8 stronghold token create (the auth/token/create endpoint). By default, a new token becomes a child of the token that makes the request and can only receive a subset of its policies. For more on token properties, see Tokens.

Service token

A service token is the default. It is persisted in Stronghold, supports renewal, revocation, and child tokens, and has an accessor:

d8 stronghold token create -policy="app-read" -ttl=1h -display-name="app-1"

Batch token

A batch token is not persisted in Stronghold, cannot be renewed or manually revoked, and has no accessor. It fits large numbers of short-lived operations:

d8 stronghold token create -type=batch -policy="app-read" -ttl=15m

Orphan token

An orphan token has no parent and is not revoked when the token that created it is revoked. Creating one requires access to auth/token/create-orphan or the sudo capability on auth/token/create:

d8 stronghold token create -orphan -policy="app-read" -ttl=24h

Periodic token

A periodic token has no maximum lifetime: on every renewal, its TTL is reset to the period. The token expires if it is not renewed within the period:

d8 stronghold token create -period=1h -policy="app-read"

Explicit max TTL

The -explicit-max-ttl flag sets a hard limit on the token lifetime that renewal cannot exceed, including for periodic tokens:

d8 stronghold token create -policy="app-read" -ttl=1h -explicit-max-ttl=8h

Use limit

The -use-limit flag sets how many times the token can be used. Once the limit is reached, the token is revoked:

d8 stronghold token create -policy="app-read" -use-limit=3 -ttl=10m

Other parameters

Token store roles

A token store role (auth/token/roles/<ROLE_NAME>) defines the properties of tokens issued through it: allowed policies, token type, TTL, period, orphan flag, and more. Roles let you allow creating tokens with policies the calling token does not have, without granting it sudo.

1. Create a role:

   d8 stronghold write auth/token/roles/ci-deploy allowed_policies="deploy" disallowed_policies="admin" orphan=true token_type=service token_period=1h token_explicit_max_ttl=24h renewable=true

   Key role parameters:

   Parameter	Description
   allowed_policies, allowed_policies_glob	Policies that can be assigned to the token.
   disallowed_policies, disallowed_policies_glob	Policies that must not be requested.
   orphan	Issue orphan tokens.
   token_type	Token type: service or batch.
   token_period	Period for periodic tokens.
   token_explicit_max_ttl	Explicit maximum TTL.
   token_num_uses	Token use limit.
   token_bound_cidrs	CIDR blocks the token can be used from.
   renewable	Whether tokens can be renewed.
   path_suffix	Token path suffix for later prefix-based revocation.
   allowed_entity_aliases	Allowed entity aliases.

2. Issue a token from the role:

   d8 stronghold token create -role=ci-deploy

   The calling token needs the update capability on auth/token/create/ci-deploy.

3. View roles:

   d8 stronghold list auth/token/roles
   d8 stronghold read auth/token/roles/ci-deploy

Looking up, renewing, and revoking tokens

In the commands below, <TOKEN> is the value of the token to look up, renew or revoke.

• Look up the current token:

  d8 stronghold token lookup

• Look up another token:

  d8 stronghold token lookup <TOKEN>

• Renew the current token, or another token requesting a new TTL:

  d8 stronghold token renew
  d8 stronghold token renew -increment=1h <TOKEN>

• Revoke a token together with all its child tokens and leases:

  d8 stronghold token revoke <TOKEN>

• Revoke only the token itself; its direct children become orphans:

  d8 stronghold token revoke -mode=orphan <TOKEN>

• Revoke the current token:

  d8 stronghold token revoke -self

• Check token capabilities on a path:

  d8 stronghold token capabilities <TOKEN> secret/data/app

Working with accessors

An accessor is a reference to a token that lets you look up, renew, and revoke the token without knowing its value. The accessor is returned when a token is created (the token_accessor field) and in token lookup output (the accessor field). Batch tokens have no accessor.

In the commands below, <ACCESSOR> is the token accessor.

• Look up a token by accessor:

  d8 stronghold token lookup -accessor <ACCESSOR>

• Renew a token by accessor:

  d8 stronghold token renew -accessor <ACCESSOR>

• Revoke a token by accessor:

  d8 stronghold token revoke -accessor <ACCESSOR>

• Check token capabilities by accessor:

  d8 stronghold write sys/capabilities-accessor accessor=<ACCESSOR> paths=secret/data/app

• List the accessors of all tokens (requires sudo):

  d8 stronghold list auth/token/accessors

Tidying the token store

The auth/token/tidy endpoint removes stale entries from the token store, such as accessors of expired tokens:

d8 stronghold write -force auth/token/tidy

Additional resources

• Break-glass access
• Usage examples