Erica Thompson 0660ea6fac
Update README (#31244)
* Update README

Let contributors know that docs will now be located in UDR

* Add comments to each mdx doc

Comment has been added to all mdx docs that are not partials

* chore: added changelog

changelog check failure

* wip: removed changelog

* Fix content errors

* Doc spacing

* Update website/content/docs/deploy/kubernetes/vso/helm.mdx

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

---------

Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com>
Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
2025-07-22 08:12:22 -07:00

567 lines
14 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
layout: api
page_title: 'Identity Secret Backend: Identity Tokens - HTTP API'
description: >-
This is the API documentation for configuring, acquiring, and validating vault
issued identity tokens.
---
> [!IMPORTANT]
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
## Configure the identity tokens backend
This endpoint updates configurations for OIDC-compliant identity tokens issued by Vault.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `identity/oidc/config` |
### Parameters
- `issuer` `(string: "")` Issuer URL to be used in the iss claim of the token. If not set, Vault's api_addr will be used. The issuer is a case sensitive URL using the https scheme that contains scheme, host, and an optional port number.
### Sample payload
```json
{
"issuer": "https://example.com:1234"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/config
```
### Sample response
```json
{
"data": null,
"warnings": [
"If \"issuer\" is set explicitly, all tokens must be validated against that address, including those issued by secondary clusters. Setting issuer to \"\" will restore the default behavior of using the cluster's api_addr as the issuer."
]
}
```
## Read configurations for the identity tokens backend
This endpoint queries vault identity tokens configurations.
| Method | Path |
| :----- | :--------------------- |
| `GET` | `identity/oidc/config` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/config
```
### Sample response
```json
{
"data": {
"issuer": "https://example.com:1234"
}
}
```
## Create a named key
This endpoint creates or updates a named key which is used by a role to sign tokens.
| Method | Path |
| :----- | :------------------------ |
| `POST` | `identity/oidc/key/:name` |
### Parameters
- `name` `(string)` Name of the named key.
- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `verification_ttl` `(int or time string: "24h")` - Controls how long the public portion of a signing key will be available for verification after being rotated. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `allowed_client_ids` `(list: [])` - Array of role client ids allowed to use this key for signing. If empty, no roles are allowed. If "\*", all roles are allowed.
- `algorithm` `(string: "RS256")` - Signing algorithm to use. Allowed values are: RS256 (default), RS384, RS512, ES256, ES384, ES512, EdDSA.
### Sample payload
```json
{
"rotation_period": "12h",
"verification_ttl": 43200
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001
```
## Read a named key
This endpoint queries a named key and returns its configurations.
| Method | Path |
| :----- | :------------------------ |
| `GET` | `identity/oidc/key/:name` |
### Parameters
- `name` `(string)` Name of the key.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001
```
### Sample response
```json
{
"data": {
"algorithm": "RS256",
"rotation_period": 43200,
"verification_ttl": 43200
}
}
```
## Delete a named key
This endpoint deletes a named key.
| Method | Path |
| :------- | :------------------------ |
| `DELETE` | `identity/oidc/key/:name` |
### Parameters
- `name` `(string)` Name of the key.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001
```
## List named keys
This endpoint will List all named keys.
| Method | Path |
| :----- | :------------------ |
| `LIST` | `identity/oidc/key` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/key
```
### Sample response
```json
{
"data": {
"keys": ["named-key-001", "named-key-002"]
}
}
```
## Rotate a named key
This endpoint rotates a named key.
| Method | Path |
| :----- | :------------------------------- |
| `POST` | `identity/oidc/key/:name/rotate` |
### Parameters
- `name` `(string)` Name of the key to be rotated.
- `verification_ttl` `(string: <optional>)` - Controls how long the public portion of the key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key.
### Sample payload
```json
{
"verification_ttl": 0
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001/rotate
```
## Create or update a role
Create or update a role. ID tokens are generated against a role and signed against a named key.
| Method | Path |
| :----- | :------------------------- |
| `POST` | `identity/oidc/role/:name` |
### Parameters
- `name` `(string)` Name of the role.
- `key` `(string)` A configured named key, the key must already exist.
- `template` `(string: <optional>)` - The template string to use for generating tokens. This may be in string-ified JSON or base64 format.
- `client_id` `(string: <optional>)` - Optional client ID. A random ID will be generated if left unset.
- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Uses [duration format strings](/vault/docs/concepts/duration-format).
### Sample payload
```json
{
"key": "named-key-001",
"ttl": "12h"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/role/role-001
```
## Read a role
This endpoint queries a role and returs its configuration.
| Method | Path |
| :----- | :------------------------- |
| `GET` | `identity/oidc/role/:name` |
### Parameters
- `name` `(string)` Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/role/role-001
```
### Sample response
```json
{
"data": {
"client_id": "PGE8tf4RmJkDwvjI1FgARkXEmH",
"key": "named-key-001",
"template": "",
"ttl": 43200
}
}
```
## Delete a role
This endpoint deletes a role.
| Method | Path |
| :------- | :------------------------- |
| `DELETE` | `identity/oidc/role/:name` |
### Parameters
- `name` `(string)` Name of the role.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/oidc/role/role-001
```
## List roles
This endpoint will list all signing keys.
| Method | Path |
| :----- | :------------------- |
| `LIST` | `identity/oidc/role` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/oidc/role
```
### Sample response
```json
{
"data": {
"keys": ["role-001", "role-002", "testrole"]
}
}
```
## Generate a signed ID token
Use this endpoint to generate a signed ID (OIDC) token.
| Method | Path |
| :----- | :-------------------------- |
| `GET` | `identity/oidc/token/:name` |
### Parameters
- `name` `(string: "")` The name of the role against which to generate a signed ID token
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/token/role-001
```
### Sample response
```json
{
"data": {
"client_id": "P6CfCzyHsQY4pMcA6kWAOCItA7",
"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJkMGI4YjlkLWYwNGQtNzFlYy1iNjc0LWM3MzU4NDMyYmM1YiJ9.eyJhdWQiOiJQNkNmQ3p5SHNRWTRwTWNBNmtXQU9DSXRBNyIsImV4cCI6MTU2MTQ4ODQxMiwiaWF0IjoxNTYxNDAyMDEyLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tOjEyMzQiLCJzdWIiOiI2YzY1ZWFmNy1kNGY0LTEzMzMtMDJiYy0xYzc1MjE5YzMxMDIifQ.IcbWTmks7P5eVtwmIBl5rL1B88MI55a9JJuYVLIlwE9aP_ilXpX5fE38CDm5PixDDVJb8TI2Q_FO4GMMH0ymHDO25ZvA917WcyHCSBGaQlgcS-WUL2fYTqFjSh-pezszaYBgPuGvH7hJjlTZO6g0LPCyUWat3zcRIjIQdXZum-OyhWAelQlveEL8sOG_ldyZ8v7fy7GXDxfJOK1kpw5AX9DXJKylbwZTBS8tLb-7edq8uZ0lNQyWy9VPEW_EEIZvGWy0AHua-Loa2l59GRRP8mPxuMYxH_c88x1lsSw0vH9E3rU8AXLyF3n4d40PASXEjZ-7dnIf4w4hf2P4L0xs_g",
"ttl": 86400
}
}
```
## Introspect a signed ID token
This endpoint can verify the authenticity and active state of a signed ID token.
| Method | Path |
| :----- | :------------------------- |
| `POST` | `identity/oidc/introspect` |
### Parameters
- `token` `(string)` A signed OIDC compliant ID token
- `client_id` `(string: <optional>)` - Specifying the client ID additionally requires the token to contain a matching `aud` claim
### Sample payload
```json
{
"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/identity/oidc/introspect
```
### Sample response
```json
{
"active": true
}
```
## Read the OpenID configuration from an identity token issuer
Use the `.well-known` endpoint to retrieve an
[OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse)
with a set of claims about the identity token issuer.
| Method | Path |
| :----- | :----------------------------------------------- |
| `GET` | `identity/oidc/.well-known/openid-configuration` |
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration
```
### Sample response
```json
{
"issuer": "https://example.com/v1/identity/oidc",
"jwks_uri": "https://example.com/v1/identity/oidc/.well-known/keys",
"response_types_supported": [
"id_token"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256",
"RS384",
"RS512",
"ES256",
"ES384",
"ES512",
"EdDSA"
]
}
```
## Read identity token issuer's public JWKS
Query `identity/oidc/.well-known/keys` to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token.
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys
```
### Sample response
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "94178020-55b5-e18d-b32b-1010ba5a35b4",
"alg": "RS256",
"n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw",
"e": "AQAB"
}
]
}
```
## Read plugin identity token issuer's OpenID configuration <EnterpriseAlert product="vault" inline />
Use the `.well-known` endpoint to retrieve an
[OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse)
with a set of claims about the plugin identity token issuer.
| Method | Path |
| :----- | :----------------------------------------------- |
| `GET` | `identity/oidc/plugins/.well-known/openid-configuration` |
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/plugins/.well-known/openid-configuration
```
### Sample response
```json
{
"issuer": "https://example.com/v1/identity/oidc/plugins",
"jwks_uri": "https://example.com/v1/identity/oidc/plugins/.well-known/keys",
"response_types_supported": [
"id_token"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256",
"RS384",
"RS512",
"ES256",
"ES384",
"ES512",
"EdDSA"
]
}
```
## Read the public JWKS from a plugin identity token issuer <EnterpriseAlert product="vault" inline />
Query this path to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token.
### Sample request
```shell-session
$ curl \
--request GET \
http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys
```
### Sample response
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "94178020-55b5-e18d-b32b-1010ba5a35b4",
"alg": "RS256",
"n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw",
"e": "AQAB"
}
]
}
```