5.8 KiB
JWT Secret Backend
Name: jwt
The JWT secret backend for Vault generates JSON Web Tokens dynamically based on configured roles. This means services can get tokens needed for authentication without going through the usual manual process of generating a private key and signing the token and maintaining the private key's security. Vault's built-in authentication and authorization mechanisms provide the verification functionality.
This page will show a quick start for this backend. For detailed documentation on every path, use vault path-help after mounting the backend.
The JWT secret backend acts like the transit backend, it does not store any information.
Algorithms
RSA
- RS256
- RS384
- RS512
These require a RSA private/public keypair for signing and verification.
ECDSA
- EC256
- EC384
- EC512
These require an ECDSA private/public keypair for signing and verification.
HMAC
- HS256
- HS384
- HS512
These require a shared secret for signing and verification.
Roles
Roles are defined with the signing algorithm, the secret key or private key to be used, as well as allowing for default but optional JWT Token claims. Once you write a private key or a secret to the role, it CANNOT be read back out.
Quick Start
The first step to using the jwt backend is to mount it.
Unlike the generic backend, the jwt backend is not mounted by default.
$ vault mount jwt
Successfully mounted 'jwt' at 'jwt'!
The next step is to configure a role. A role is a logical name that maps to a few settings used to generated the tokens. For example, lets create a "webauth" role:
$ vault write jwt/roles/webauth \
algorithm=RS256 \
key=@/path/to/private.key
Each role requires a secret or a private key to be associated against it.
Generating a token requires passing of additional information so we use the "jwt/issue/ROLE" path.
$ vault write jwt/issue/webauth \
issuer="Vault" \
audience="Vault Client" \
expiration="1538096292" \
claims=@extra.json
API
/jwt/roles/
POST
- Description
- Creates or updates a named role.
- Method
- POST
- URL
- `/jwt/roles/`
- Parameters
-
- algorithm required The algorithm used by JWT to sign the token.
- key required The private key or string used to sign the token.
- default_issuer required The default issuer claim for the role, can be overridden at issue time.
- default_subject required The default subject claim for the role, can be overridden at issue time.
- default_audience required The default audience claim for the role, can be overridden at issue time.
- Returns
- A `204` response code.
GET
- Description
- Queries a named role.
- Method
- GET
- URL
- `/jwt/roles/`
- Parameters
- None
- Returns
-
```javascript { "data": { "algorithm": "..." } } ```
DELETE
- Description
- Deletes a named role.
- Method
- DELETE
- URL
- `/jwt/roles/`
- Parameters
- None
- Returns
- A `204` response code.
/jwt/issue/
POST
- Description
- Generates a JWT token based on the named role.
- Method
- GET
- URL
- `/jwt/issue/`
- Parameters
-
- issuer optional The Issuer of the token.
- audience optional The Audience of the token.
- subject optional The Subject of the token.
- expiration optional The expiration of the token, expressed in seconds (unix time).
- issued_at optional The issued at time of the token, expressed in seconds (unix time). (Default: current time)
- not_before optional Not Before: the time at which the token is not useful before. Expressed as seconds, unix time. (Default: current time)
- jti optional JSONWebToken Identifier. Unique ID useful for preventing replay attacks. (Default: Random UUID)
- claims optional Should be a JSON Object of additional key/values you want in the token.
- Returns
-
```javascript { "data": { "jti": "...", "token": "..." } } ```