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- `algorithm` `(string: "RS256")` - Signing algorithm to use. This will default to `"RS256"`, and is currently the only allowed value. 95 96### Sample Payload 97 98```json 99{ 100 "rotation_period":"12h", 101 "verification_ttl":43200, 102} 103``` 104 105### Sample Request 106 107``` 108$ curl \ 109 --header "X-Vault-Token: ..." \ 110 --request POST \ 111 --data @payload.json \ 112 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 113``` 114 115## Read a Named Key 116 117This endpoint queries a named key and returns its configurations. 118 119| Method | Path | 120| :------------------ | :----------------------| 121| `GET` | `identity/oidc/key/:name` | 122 123### Parameters 124 125- `name` `(string)` – Name of the key. 126 127### Sample Request 128 129``` 130$ curl \ 131 --header "X-Vault-Token: ..." \ 132 --request GET \ 133 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 134``` 135 136### Sample Response 137 138```json 139{ 140 "data": { 141 "algorithm": "RS256", 142 "rotation_period": 43200, 143 "verification_ttl": 43200 144 }, 145} 146``` 147 148## Delete a Named Key 149 150This endpoint deletes a named key. 151 152| Method | Path | 153| :------------------ | :----------------------| 154| `DELETE` | `identity/oidc/key/:name` | 155 156### Parameters 157 158- `name` `(string)` – Name of the key. 159 160### Sample Request 161 162``` 163$ curl \ 164 --header "X-Vault-Token: ..." \ 165 --request DELETE \ 166 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 167``` 168 169## List Named Keys 170 171This endpoint will List all named keys. 172 173| Method | Path | 174| :------------------ | :----------------------| 175| `LIST` | `identity/oidc/key` | 176 177### Sample Request 178 179``` 180$ curl \ 181 --header "X-Vault-Token: ..." \ 182 --request LIST \ 183 http://127.0.0.1:8200/v1/identity/oidc/key 184``` 185 186### Sample Response 187 188```json 189{ 190 "data": { 191 "keys": [ 192 "named-key-001", 193 "named-key-002" 194 ] 195 }, 196} 197``` 198 199## Rotate a Named Key 200 201This endpoint rotates a named key. 202 203| Method | Path | 204| :------------------ | :----------------------| 205| `POST` | `identity/oidc/key/:name/rotate` | 206 207### Parameters 208 209- `name` `(string)` – Name of the key to be rotated. 210 211- `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. 212 213### Sample Payload 214 215```json 216{ 217 "verification_ttl": 0 218} 219``` 220 221### Sample Request 222 223``` 224$ curl \ 225 --header "X-Vault-Token: ..." \ 226 --request POST \ 227 --data @payload.json \ 228 http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001/rotate 229``` 230 231## Create or Update a Role 232 233Create or update a role. ID tokens are generated against a role and signed against a named key. 234 235| Method | Path | 236| :------------------ | :----------------------| 237| `POST` | `identity/oidc/role/:name` | 238 239### Parameters 240 241- `name` `(string)` – Name of the role. 242 243- `key` `(string)` – A configured named key, the key must already exist. 244 245- `template` `(string: <optional>)` - The template string to use for generating tokens. This may be in string-ified JSON or base64 format. 246 247- `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". 248 249### Sample Payload 250 251```json 252{ 253 "key": "named-key-001", 254 "ttl":"12h" 255} 256``` 257 258### Sample Request 259 260``` 261$ curl \ 262 --header "X-Vault-Token: ..." \ 263 --request POST \ 264 --data @payload.json \ 265 http://127.0.0.1:8200/v1/identity/oidc/role/role-001 266``` 267 268## Read a Role 269 270This endpoint queries a role and returs its configuration. 271 272| Method | Path | 273| :------------------ | :----------------------| 274| `GET` | `identity/oidc/role/:name` | 275 276### Parameters 277 278- `name` `(string)` – Name of the role. 279 280### Sample Request 281 282``` 283$ curl \ 284 --header "X-Vault-Token: ..." \ 285 --request GET \ 286 http://127.0.0.1:8200/v1/identity/oidc/role/role-001 287``` 288 289### Sample Response 290 291```json 292{ 293 "data": { 294 "client_id": "PGE8tf4RmJkDwvjI1FgARkXEmH", 295 "key": "named-key-001", 296 "template": "", 297 "ttl": 43200 298 }, 299} 300``` 301 302## Delete a Role 303 304This endpoint deletes a role. 305 306| Method | Path | 307| :------------------ | :----------------------| 308| `DELETE` | `identity/oidc/role/:name` | 309 310### Parameters 311 312- `name` `(string)` – Name of the role. 313 314### Sample Request 315 316``` 317$ curl \ 318 --header "X-Vault-Token: ..." \ 319 --request DELETE \ 320 http://127.0.0.1:8200/v1/identity/oidc/role/role-001 321``` 322 323## List Roles 324 325This endpoint will list all signing keys. 326 327| Method | Path | 328| :------------------ | :----------------------| 329| `LIST` | `identity/oidc/role` | 330 331### Sample Request 332 333``` 334$ curl \ 335 --header "X-Vault-Token: ..." \ 336 --request LIST \ 337 http://127.0.0.1:8200/v1/identity/oidc/role 338``` 339 340### Sample Response 341 342```json 343{ 344 "data": { 345 "keys": [ 346 "role-001", 347 "role-002", 348 "testrole" 349 ] 350 }, 351} 352``` 353 354## Generate a Signed ID Token 355 356Use this endpoint to generate a signed ID (OIDC) token. 357 358| Method | Path | 359| :------------------ | :----------------------| 360| `POST` | `identity/oidc/token/:name` | 361 362### Parameters 363 364- `name` `(string: "")` – The name of the role against which to generate a signed ID token 365 366### Sample Request 367 368``` 369$ curl \ 370 --header "X-Vault-Token: ..." \ 371 --request GET \ 372 --data @payload.json \ 373 http://127.0.0.1:8200/v1/identity/oidc/token/role-001 374``` 375 376### Sample Response 377 378```json 379{ 380 "data": { 381 "client_id": "P6CfCzyHsQY4pMcA6kWAOCItA7", 382 "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJkMGI4YjlkLWYwNGQtNzFlYy1iNjc0LWM3MzU4NDMyYmM1YiJ9.eyJhdWQiOiJQNkNmQ3p5SHNRWTRwTWNBNmtXQU9DSXRBNyIsImV4cCI6MTU2MTQ4ODQxMiwiaWF0IjoxNTYxNDAyMDEyLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tOjEyMzQiLCJzdWIiOiI2YzY1ZWFmNy1kNGY0LTEzMzMtMDJiYy0xYzc1MjE5YzMxMDIifQ.IcbWTmks7P5eVtwmIBl5rL1B88MI55a9JJuYVLIlwE9aP_ilXpX5fE38CDm5PixDDVJb8TI2Q_FO4GMMH0ymHDO25ZvA917WcyHCSBGaQlgcS-WUL2fYTqFjSh-pezszaYBgPuGvH7hJjlTZO6g0LPCyUWat3zcRIjIQdXZum-OyhWAelQlveEL8sOG_ldyZ8v7fy7GXDxfJOK1kpw5AX9DXJKylbwZTBS8tLb-7edq8uZ0lNQyWy9VPEW_EEIZvGWy0AHua-Loa2l59GRRP8mPxuMYxH_c88x1lsSw0vH9E3rU8AXLyF3n4d40PASXEjZ-7dnIf4w4hf2P4L0xs_g", 383 "ttl": 86400 384 }, 385} 386``` 387 388## Introspect a signed ID Token 389 390This endpoint can verify the authenticity and active state of a signed ID token. 391 392| Method | Path | 393| :------------------ | :----------------------| 394| `POST` | `identity/oidc/introspect` | 395 396### Parameters 397 398- `token` `(string)` – A signed OIDC compliant ID token 399 400- `client_id` `(string: <optional>)` - Specifying the client ID optimizes validation time 401 402### Sample Payload 403 404```json 405{ 406 "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg" 407} 408``` 409 410### Sample Request 411 412``` 413$ curl \ 414 --header "X-Vault-Token: ..." \ 415 --request POST \ 416 --data @payload.json \ 417 http://127.0.0.1:8200/v1/identity/oidc/introspect 418``` 419 420### Sample Response 421 422 423```json 424 425{ 426 "active": true 427} 428``` 429 430## Read .well-known Configurations 431 432Query 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). 433 434| Method | Path | 435| :------------------ | :----------------------| 436| `GET` | `identity/oidc/.well-known/openid-configuration` | 437 438### Sample Request 439 440``` 441$ curl \ 442 --header "X-Vault-Token: ..." \ 443 --request GET \ 444 http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration 445``` 446 447### Sample Response 448 449```json 450{ 451 "issuer": "https://example.com:1234", 452 "authorization_endpoint": "", 453 "token_endpoint": "", 454 "jwks_uri": "https://example.com:1234/.well-known/keys", 455 "response_types_supported": null, 456 "subject_types_supported": [ 457 "public" 458 ], 459 "id_token_signing_alg_values_supported": [ 460 "RS256" 461 ], 462 "scopes_supported": null, 463 "token_endpoint_auth_methods_supported": null, 464 "claims_supported": null 465} 466``` 467 468## Read Active Public Keys 469Query this path to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token. 470 471### Sample Request 472 473``` 474$ curl \ 475 --header "X-Vault-Token: ..." \ 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