diff --git a/website/source/api/auth/jwt/index.html.md b/website/source/api/auth/jwt/index.html.md new file mode 100644 index 000000000..04f1fc0b1 --- /dev/null +++ b/website/source/api/auth/jwt/index.html.md @@ -0,0 +1,299 @@ +--- +layout: "api" +page_title: "JWT/OIDC - Auth Methods - HTTP API" +sidebar_current: "docs-http-auth-jwt" +description: |- + This is the API documentation for the Vault JWT authentication + method plugin. +--- + +# JWT Auth Method (API) + +This is the API documentation for the Vault JWT auth method +plugin. To learn more about the usage and operation, see the +[Vault JWT method documentation](/docs/auth/jwt.html). + +This documentation assumes the plugin method is mounted at the +`/auth/jwt` path in Vault. Since it is possible to enable auth methods +at any location, please update your API calls accordingly. + +## Configure + +Configures the validation information to be used globally across all roles. One +(and only one) of `oidc_discovery_url` and `jwt_validation_pubkeys` must be +set. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/jwt/config` | `204 (empty body)` | + +### Parameters + +- `oidc_discovery_url` `(string: )` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with `jwt_validation_pubkeys`. +- `oidc_discovery_ca_pem` `(string: )` - The CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used. +- `jwt_validation_pubkeys` `(comma-separated string, or array of strings: )` - A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with `oidc_discovery_url`. +- `bound_issuer` `(string: )` - The value against which to match the `iss` claim in a JWT. + +### Sample Payload + +```json +{ + "oidc_discovery_url": "https://myco.auth0.com/", + "bound_issuer": "https://myco.auth0.com/" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/azure/config +``` + +# Read Config + +Returns the previously configured config. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/jwt/config` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/auth/jwt/config +``` + +### Sample Response + +```json +{ + "data":{ + "oidc_discovery_url": "https://myco.auth0.com/", + "oidc_discovery_ca_pem": [], + "bound_issuer": "https://myco.auth0.com/", + "jwt_validation_pubkeys": [] + }, + ... +} +``` + +## Create Role + +Registers a role in the method. Role types have specific entities +that can perform login operations against this endpoint. Constraints specific +to the role type must be set on the role. These are applied to the authenticated +entities attempting to login. At least one of the bound values must be set. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/jwt/role/:name` | `204 (empty body)` | + +### Parameters +- `name` `(string: )` - Name of the role. +- `bound_audiences` `(array: )` - List of `aud` claims to match + against. Any match is sufficient. +- `user_claim` `(string: )` - The claim to use to uniquely identify + the user; this will be used as the name for the Identity entity alias created + due to a successful login. The claim value must be a string. +- `policies` `(array: )` - Policies to be set on tokens issued using + this role. +- `ttl` `(int: )` - The initial/renewal TTL of tokens issued using + this role, in seconds. +- `max_ttl` `(int: )` - The maximum allowed lifetime of tokens issued + using this role, in seconds. +- `period` `(int: )` - If set, indicates that the token generated + using this role should never expire, but instead always use the value set + here as the TTL for every renewal. +- `num_uses` `(int: )` - If set, puts a use-count limitation on the + issued token. +- `bound_subject` `(string: )` - If set, requires that the `sub` + claim matches this value. +- `bound_cidrs` `(array: )` - If set, a list of CIDRs valid as the + source address for login requests. This value is also encoded into any + resulting token. +- `groups_claim` `(string: )` - The claim to use to uniquely identify + the set of groups to which the user belongs; this will be used as the names + for the Identity group aliases created due to a successful login. The claim + value must be a list of strings. + +### Sample Payload + +```json +{ + "policies": [ + "dev", + "prod" + ], + "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients", + "bound_audiences": "https://myco.test", + "user_claim": "https://vault/user", + "groups_claim": "https://vault/groups" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/jwt/role/dev-role +``` + +## Read Role + +Returns the previously registered role configuration. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/jwt/role/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/auth/jwt/role/dev-role +``` + +### Sample Response + +```json +{ + "data":{ + "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients", + "bound_audiences": [ + "https://myco.test" + ], + "bound_cidrs": [], + "user_claim": "https://vault/user", + "groups_claim": "https://vault/groups", + "policies": [ + "dev", + "prod" + ], + "period": 0, + "ttl": 0, + "num_uses": 0, + "max_ttl": 0 + }, + ... +} + +``` + +## List Roles + +Lists all the roles that are registered with the plugin. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/jwt/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/auth/jwt/roles +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "dev-role", + "prod-role" + ] + }, + ... +} +``` + +## Delete Role + +Deletes the previously registered role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/jwt/role/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/auth/jwt/role/dev-role +``` + +## Login + +Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and +a role name for some entity. It verifies the JWT signature to authenticate that +entity and then authorizes the entity for the given role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/jwt/login` | `200 application/json` | + +### Sample Payload + +- `role` `(string: )` - Name of the role against which the login is being + attempted. +- `jwt` `(string: )` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT). + +### Sample Payload + +```json +{ + "role": "dev-role", + "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/jwt/login +``` + +### Sample Response + +```json +{ + "auth":{ + "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c", + "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d", + "policies":[ + "default", + "dev", + "prod" + ], + "lease_duration":2764800, + "renewable":true + }, + ... +} +``` diff --git a/website/source/docs/auth/jwt.html.md b/website/source/docs/auth/jwt.html.md new file mode 100644 index 000000000..b9ed6ae33 --- /dev/null +++ b/website/source/docs/auth/jwt.html.md @@ -0,0 +1,101 @@ +--- +layout: "docs" +page_title: "JWT/OIDC - Auth Methods" +sidebar_current: "docs-auth-jwt" +description: |- + The JWT/OIDC auth method allows authentication using JWTs and OIDC. +--- + +# JWT/OIDC Auth Method + +The `jwt` auth method can be used to authenticate with Vault using a JWT. This +JWT can be cryptographically verified using locally-provided keys, or, if +configured, an OIDC Discovery service can be used to fetch the appropriate +keys. + +## Authentication + +### Via the CLI + +The default path is `/jwt`. If this auth method was enabled at a +different path, specify `-path=/my-path` in the CLI. + +```text +$ vault write auth/jwt/login role=demo token=... +``` + +### Via the API + +The default endpoint is `auth/jwt/login`. If this auth method was enabled +at a different path, use that value instead of `jwt`. + +```shell +$ curl \ + --request POST \ + --data '{"jwt": "your_jwt", "role": "demo"}' \ + http://127.0.0.1:8200/v1/auth/jwt/login +``` + +The response will contain a token at `auth.client_token`: + +```json +{ + "auth": { + "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674", + "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3", + "policies": [ + "default" + ], + "metadata": { + "role": "demo" + }, + "lease_duration": 2764800, + "renewable": true + } +} +``` + +## Configuration + +Auth methods must be configured in advance before users or machines can +authenticate. These steps are usually completed by an operator or configuration +management tool. + + +1. Enable the JWT auth method: + + ```text + $ vault auth enable jwt + ``` + +1. Use the `/config` endpoint to configure Vault with local keys or an OIDC Discovery URL. For the +list of available configuration options, please see the API documentation. + + ```text + $ vault write auth/jwt/config \ + oidc_discovery_url="https://myco.auth0.com/" + ``` + +1. Create a named role: + + ```text + vault write auth/jwt/role/demo \ + bound_subject="r3qX9DljwFIWhsiqwFiu38209F10atW6@clients" \ + bound_audiences="https://vault.plugin.auth.jwt.test" \ + user_claim="https://vault/user" \ + groups_claim="https://vault/groups" \ + policies=webapps \ + ttl=1h + ``` + + This role authorizes JWTs with the given subject and audience claims, gives + it the `webapps` policy, and uses the given user/groups claims to set up + Identity aliases. + + For the complete list of configuration options, please see the API + documentation. + +## API + +The JWT Auth Plugin has a full HTTP API. Please see the +[API docs](/api/auth/jwt/index.html) for more details. diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 7a0a7072b..6d987f8cd 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -147,6 +147,9 @@ > Google Cloud + > + JWT/OIDC + > Kubernetes diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 7d4a2bcaf..ce08e994d 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -498,6 +498,10 @@ Google Cloud + > + JWT/OIDC + + > Kubernetes