1--- 2layout: "api" 3page_title: "Identity Secret Backend: Identity Tokens - HTTP API" 4sidebar_title: "Identity Tokens" 5sidebar_current: "api-http-secret-identity-tokens" 6description: |- 7 This is the API documentation for configuring, acquiring, and validating vault issued identity tokens. 8--- 9 10## Configure the Identity Tokens Backend 11 12This endpoint updates configurations for OIDC-compliant identity tokens issued by Vault. 13 14| Method | Path | 15| :------------------ | :----------------------| 16| `POST` | `identity/oidc/config` | 17 18### Parameters 19 20- `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 optionally, port number and path components, but no query or fragment components. 21 22### Sample Payload 23 24```json 25{ 26 "issuer": "https://example.com:1234" 27} 28``` 29 30### Sample Request 31 32``` 33$ curl \ 34 --header "X-Vault-Token: ..." \ 35 --request POST \ 36 --data @payload.json \ 37 http://127.0.0.1:8200/v1/identity/oidc/config 38``` 39 40### Sample Response 41 42```json 43{ 44 "data": null, 45 "warnings": [ 46 "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." 47 ], 48} 49``` 50 51## Read Configurations for the Identity Tokens Backend 52 53This endpoint queries vault identity tokens configurations. 54 55| Method | Path | 56| :------------------ | :----------------------| 57| `GET` | `identity/oidc/config` | 58 59### Sample Request 60 61``` 62$ curl \ 63 --header "X-Vault-Token: ..." \ 64 --request GET \ 65 http://127.0.0.1:8200/v1/identity/oidc/config 66``` 67 68### Sample Response 69 70```json 71{ 72 "data": { 73 "issuer": "https://example.com:1234" 74 }, 75} 76``` 77 78## Create a Named Key 79 80This endpoint creates or updates a named key which is used by a role to sign tokens. 81 82| Method | Path | 83| :------------------ | :----------------------| 84| `POST` | `identity/oidc/key/:name` | 85 86### Parameters 87 88- `name` `(string)` – Name of the named key. 89 90- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Can be specified as a number of seconds or as a time string like "30m" or "6h". 91 92- `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. 93 94- `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. 95 96- `algorithm` `(string: "RS256")` - Signing algorithm to use. Allowed values are: RS256 (default), RS384, RS512, ES256, ES384, ES512, EdDSA. 97 98### Sample Payload 99 100```json 101{ 102 "rotation_period":"12h", 103 "verification_ttl":43200 104} 105``` 106 107### Sample Request 108 109``` 110$ curl \ 111 --header "X-Vault-Token: ..." \ 112 --request POST \ 113 --data @payload.json \ 114 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 115``` 116 117## Read a Named Key 118 119This endpoint queries a named key and returns its configurations. 120 121| Method | Path | 122| :------------------ | :----------------------| 123| `GET` | `identity/oidc/key/:name` | 124 125### Parameters 126 127- `name` `(string)` – Name of the key. 128 129### Sample Request 130 131``` 132$ curl \ 133 --header "X-Vault-Token: ..." \ 134 --request GET \ 135 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 136``` 137 138### Sample Response 139 140```json 141{ 142 "data": { 143 "algorithm": "RS256", 144 "rotation_period": 43200, 145 "verification_ttl": 43200 146 }, 147} 148``` 149 150## Delete a Named Key 151 152This endpoint deletes a named key. 153 154| Method | Path | 155| :------------------ | :----------------------| 156| `DELETE` | `identity/oidc/key/:name` | 157 158### Parameters 159 160- `name` `(string)` – Name of the key. 161 162### Sample Request 163 164``` 165$ curl \ 166 --header "X-Vault-Token: ..." \ 167 --request DELETE \ 168 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 169``` 170 171## List Named Keys 172 173This endpoint will List all named keys. 174 175| Method | Path | 176| :------------------ | :----------------------| 177| `LIST` | `identity/oidc/key` | 178 179### Sample Request 180 181``` 182$ curl \ 183 --header "X-Vault-Token: ..." \ 184 --request LIST \ 185 http://127.0.0.1:8200/v1/identity/oidc/key 186``` 187 188### Sample Response 189 190```json 191{ 192 "data": { 193 "keys": [ 194 "named-key-001", 195 "named-key-002" 196 ] 197 }, 198} 199``` 200 201## Rotate a Named Key 202 203This endpoint rotates a named key. 204 205| Method | Path | 206| :------------------ | :----------------------| 207| `POST` | `identity/oidc/key/:name/rotate` | 208 209### Parameters 210 211- `name` `(string)` – Name of the key to be rotated. 212 213- `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. 214 215### Sample Payload 216 217```json 218{ 219 "verification_ttl": 0 220} 221``` 222 223### Sample Request 224 225``` 226$ curl \ 227 --header "X-Vault-Token: ..." \ 228 --request POST \ 229 --data @payload.json \ 230 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001/rotate 231``` 232 233## Create or Update a Role 234 235Create or update a role. ID tokens are generated against a role and signed against a named key. 236 237| Method | Path | 238| :------------------ | :----------------------| 239| `POST` | `identity/oidc/role/:name` | 240 241### Parameters 242 243- `name` `(string)` – Name of the role. 244 245- `key` `(string)` – A configured named key, the key must already exist. 246 247- `template` `(string: <optional>)` - The template string to use for generating tokens. This may be in string-ified JSON or base64 format. 248 249- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Can be specified as a number of seconds or as a time string like "30m" or "6h". 250 251### Sample Payload 252 253```json 254{ 255 "key": "named-key-001", 256 "ttl":"12h" 257} 258``` 259 260### Sample Request 261 262``` 263$ curl \ 264 --header "X-Vault-Token: ..." \ 265 --request POST \ 266 --data @payload.json \ 267 http://127.0.0.1:8200/v1/identity/oidc/role/role-001 268``` 269 270## Read a Role 271 272This endpoint queries a role and returs its configuration. 273 274| Method | Path | 275| :------------------ | :----------------------| 276| `GET` | `identity/oidc/role/:name` | 277 278### Parameters 279 280- `name` `(string)` – Name of the role. 281 282### Sample Request 283 284``` 285$ curl \ 286 --header "X-Vault-Token: ..." \ 287 --request GET \ 288 http://127.0.0.1:8200/v1/identity/oidc/role/role-001 289``` 290 291### Sample Response 292 293```json 294{ 295 "data": { 296 "client_id": "PGE8tf4RmJkDwvjI1FgARkXEmH", 297 "key": "named-key-001", 298 "template": "", 299 "ttl": 43200 300 }, 301} 302``` 303 304## Delete a Role 305 306This endpoint deletes a role. 307 308| Method | Path | 309| :------------------ | :----------------------| 310| `DELETE` | `identity/oidc/role/:name` | 311 312### Parameters 313 314- `name` `(string)` – Name of the role. 315 316### Sample Request 317 318``` 319$ curl \ 320 --header "X-Vault-Token: ..." \ 321 --request DELETE \ 322 http://127.0.0.1:8200/v1/identity/oidc/role/role-001 323``` 324 325## List Roles 326 327This endpoint will list all signing keys. 328 329| Method | Path | 330| :------------------ | :----------------------| 331| `LIST` | `identity/oidc/role` | 332 333### Sample Request 334 335``` 336$ curl \ 337 --header "X-Vault-Token: ..." \ 338 --request LIST \ 339 http://127.0.0.1:8200/v1/identity/oidc/role 340``` 341 342### Sample Response 343 344```json 345{ 346 "data": { 347 "keys": [ 348 "role-001", 349 "role-002", 350 "testrole" 351 ] 352 }, 353} 354``` 355 356## Generate a Signed ID Token 357 358Use this endpoint to generate a signed ID (OIDC) token. 359 360| Method | Path | 361| :------------------ | :----------------------| 362| `GET` | `identity/oidc/token/:name` | 363 364### Parameters 365 366- `name` `(string: "")` – The name of the role against which to generate a signed ID token 367 368### Sample Request 369 370``` 371$ curl \ 372 --header "X-Vault-Token: ..." \ 373 --request GET \ 374 --data @payload.json \ 375 http://127.0.0.1:8200/v1/identity/oidc/token/role-001 376``` 377 378### Sample Response 379 380```json 381{ 382 "data": { 383 "client_id": "P6CfCzyHsQY4pMcA6kWAOCItA7", 384 "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJkMGI4YjlkLWYwNGQtNzFlYy1iNjc0LWM3MzU4NDMyYmM1YiJ9.eyJhdWQiOiJQNkNmQ3p5SHNRWTRwTWNBNmtXQU9DSXRBNyIsImV4cCI6MTU2MTQ4ODQxMiwiaWF0IjoxNTYxNDAyMDEyLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tOjEyMzQiLCJzdWIiOiI2YzY1ZWFmNy1kNGY0LTEzMzMtMDJiYy0xYzc1MjE5YzMxMDIifQ.IcbWTmks7P5eVtwmIBl5rL1B88MI55a9JJuYVLIlwE9aP_ilXpX5fE38CDm5PixDDVJb8TI2Q_FO4GMMH0ymHDO25ZvA917WcyHCSBGaQlgcS-WUL2fYTqFjSh-pezszaYBgPuGvH7hJjlTZO6g0LPCyUWat3zcRIjIQdXZum-OyhWAelQlveEL8sOG_ldyZ8v7fy7GXDxfJOK1kpw5AX9DXJKylbwZTBS8tLb-7edq8uZ0lNQyWy9VPEW_EEIZvGWy0AHua-Loa2l59GRRP8mPxuMYxH_c88x1lsSw0vH9E3rU8AXLyF3n4d40PASXEjZ-7dnIf4w4hf2P4L0xs_g", 385 "ttl": 86400 386 }, 387} 388``` 389 390## Introspect a signed ID Token 391 392This endpoint can verify the authenticity and active state of a signed ID token. 393 394| Method | Path | 395| :------------------ | :----------------------| 396| `POST` | `identity/oidc/introspect` | 397 398### Parameters 399 400- `token` `(string)` – A signed OIDC compliant ID token 401 402- `client_id` `(string: <optional>)` - Specifying the client ID optimizes validation time 403 404### Sample Payload 405 406```json 407{ 408 "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg" 409} 410``` 411 412### Sample Request 413 414``` 415$ curl \ 416 --header "X-Vault-Token: ..." \ 417 --request POST \ 418 --data @payload.json \ 419 http://127.0.0.1:8200/v1/identity/oidc/introspect 420``` 421 422### Sample Response 423 424 425```json 426 427{ 428 "active": true 429} 430``` 431 432## Read .well-known Configurations 433 434Query this path to retrieve a set of claims about the identity tokens' configuration. The response is a compliant [OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). 435 436| Method | Path | 437| :------------------ | :----------------------| 438| `GET` | `identity/oidc/.well-known/openid-configuration` | 439 440### Sample Request 441 442``` 443$ curl \ 444 --request GET \ 445 http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration 446``` 447 448### Sample Response 449 450```json 451{ 452 "issuer": "https://example.com:1234", 453 "authorization_endpoint": "", 454 "token_endpoint": "", 455 "jwks_uri": "https://example.com:1234/.well-known/keys", 456 "response_types_supported": null, 457 "subject_types_supported": [ 458 "public" 459 ], 460 "id_token_signing_alg_values_supported": [ 461 "RS256" 462 ], 463 "scopes_supported": null, 464 "token_endpoint_auth_methods_supported": null, 465 "claims_supported": null 466} 467``` 468 469## Read Active Public Keys 470Query this path to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token. 471 472### Sample Request 473 474``` 475$ curl \ 476 --request GET \ 477 http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys 478``` 479 480### Sample Response 481 482```json 483{ 484 "keys": [ 485 { 486 "use": "sig", 487 "kty": "RSA", 488 "kid": "94178020-55b5-e18d-b32b-1010ba5a35b4", 489 "alg": "RS256", 490 "n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw", 491 "e": "AQAB" 492 } 493 ] 494} 495``` 496