https://github.com/pcman312/vault-plugin-secrets-jwt
JWT secrets engine for Vault. Originally built for a hackathon, but a reasonable starting point to make production ready.
https://github.com/pcman312/vault-plugin-secrets-jwt
jwt vault vault-plugins
Last synced: 16 days ago
JSON representation
JWT secrets engine for Vault. Originally built for a hackathon, but a reasonable starting point to make production ready.
- Host: GitHub
- URL: https://github.com/pcman312/vault-plugin-secrets-jwt
- Owner: pcman312
- Created: 2020-11-16T18:56:05.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2021-10-27T01:07:36.000Z (over 4 years ago)
- Last Synced: 2025-12-17T06:23:51.335Z (6 months ago)
- Topics: jwt, vault, vault-plugins
- Language: Go
- Homepage:
- Size: 47.9 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# vault-plugin-secrets-jwt
A Vault secrets engine for generating and validating arbitrary JWTs.
## Usage
1. Register the plugin via [Vault's plugin system](https://www.vaultproject.io/docs/internals/plugins.html)
2. Enable the engine:
```shell script
$ vault secrets enable -path=jwt vault-plugin-secrets-jwt
Success! Enabled the vault-plugin-secrets-jwt secrets engine at: jwt/
```
3. Configure a role. You must specify two fields:
- `alg`: The signing algorithm to use. Allowed values: `RS256`, `RS384`, `RS512`, `HS256`, `HS384`,
`HS512`, `ES256`, `ES384`, `ES512`. This is case-insensitive.
- `exp`: The amount of time before a JWT expires. Unlike in an actual JWT, this is the duration that the JWT
should live. This can be either an integer indicating a number of seconds, or use a suffix notation such as `1h`
If you do not specify the `key` field, a key will be generated automatically by Vault. If you do specify a key,
it must match the signing method specified in `alg`.
You may specify any arbitrary key/value pairs you wish.
```shell script
$ vault write jwt/roles/myrole/config alg=RS512 exp=1h foo=bar bar=baz
Success! Data written to: jwt/roles/myrole/config
```
4. Generate a JWT
```shell script
$ vault read jwt/roles/myrole/generate
Key Value
--- -----
token eyJhbGciOiJSUzUxM oN6s7FfP4NuFc-K1yg
```
5. Validate a JWT
```shell script
$ vault write jwt/roles/myrole/validate token="${TOKEN}"
Key Value
--- -----
claims map[bar:baz exp:1605829718 foo:bar iat:1605826118 iss:vault/myrole jti:34e888e2-22f1-4f96-f22e-8ef1894aed42]
```
## Endpoints
### `/roles/{name}/config`
Configures a JWT role. Generates an RSA key by default.
Allows user to specify any key/value pairs to include in the JWT.
When read, only the public key will be returned (or the key redacted if a symmetric key).
This is to protect the key from access by users who shouldn't be able to see it.
Key-exporting is not supported. If you need the key outside of this engine, generate it and
provide it rather than having the engine generate one.
### `/roles/{name}/generate`
Generates a JWT & returns it as a secret.
### `/roles/{name}/validate`
Validates a provided JWT against the role specified
## Features/TODO list
- ✅ Certain fields will need to be explicitly specified types:
- `exp` - Duration (creation + this value => JWT expiration)
- ✅ Validation of key/value pairs against default types
- ✅ Not allowed:
- `jti` (JWT ID)
- `iat` (Issued At)
- ✅ Defaults:
- `iss` - `"vault/{name}"` where `{name}` is the name of the role?
- ✅ Allow user to provide key
- ✅ Generate keys when one isn't provided
- ✅ RSA
- ✅ HMAC
- ✅ ECDSA
- ✅ Supported key types
- ✅ RSA (RS256, RS384, RS512)
- ✅ HMAC (HS256, HS384, HS512)
- ✅ ECDSA (ES256, ES384, ES512)
- ❌ Logging?
- ❌ Key lifecycle
- ❌ Replace an existing key
- ❌ Allow validation with an old key for a configurable amount of time?
- ❌ Allow for time skewing
- This one is potentially problematic with the library I'm using here since it is configured
with a global TimeFunc variable.
## Possible features
- Allow generation-time claims? `nbf` comes to mind, but possibly allow other fields? This would
allow JWTs to be configurable during generation. We would probably need to have some protections
that the operator can specify on what fields can be specified & maybe what values in each
field can be used.
- Allow users to invalidate specific JWTs based on the JWT ID field (`jti`)
- An endpoint that returns the role name of the provided JWT
- Templating within fields. Ex: `{.RoleName}` for the name of the role in Vault