Vault
HomeDocumentationTutorialsTry Cloud!
  • Vault
  • Documentation
    • What is Vault?
    • Use Cases
    • Setup
      • Install
      • Configuration
    • Get Started
      • Starting the server
      • Your first secret
      • Deploying Vault on VMs with Let's encrypt! TLS certs
    • Concepts
      • Operations
        • Seal/Unseal
        • "Dev" server mode
        • Namespace lock and unlock
        • Lease, renew, and revoke
        • Lease Explosions
        • Mount migration
        • Client count
        • Resource quotas
        • Response wrapping
      • Authentication
        • Identity
        • Tokens
        • OIDC provider
        • Username templating
        • Passwordless
      • Secrets
      • Storage
        • Integrated storage
        • High availability mode (HA)
        • Recovery mode
      • Policies
  • Tutorials
    • CLI
      • Operations
        • Deploy Vault
        • Using the HTTP API
        • Unseal/Seal
      • Authentication
        • Token
        • GitHub authentication
        • Username/Password
        • TLS Client Certificates
        • SSH Keys
        • AWS, Azure, GCP and external auth methods
          • Azure
          • AWS
          • GCP
          • Github
          • Terraform
      • Secrets
        • Secrets engines
        • Built-in help
      • Access Control
        • Policies
    • UI
      • Authentication
        • Username/Password
        • Passwordless
      • Operations
        • Unseal / Seal
        • API Explorer
      • Secrets
        • Secrets engines
      • Access Control
        • Policies
    • Use Cases
      • Namespaces
      • MongoDB admin password
      • VM Disk Encryption Keys
      • VM SSH Keys
      • Kubernetes Configuration
      • GitHub Actions
      • Dynamic credentials for cloud providers
        • AWS
        • Azure
        • GCP
  • CLI
    • agent
    • audit
    • auth
    • debug
    • delete
    • events
    • kv
    • lease
    • license
    • list
    • login
    • monitor
    • namespace
    • operator
    • patch
    • path-help
    • pki
    • plugin
    • policy
    • print
    • proxy
    • read
    • secrets
    • server
    • ssh
    • status
    • token
    • transit
    • unwrap
    • version
    • version-history
    • write
  • API
    • Secrets engines
      • AliCloud secrets engine (API)
      • AWS secrets engine (API)
      • Azure secrets engine (API)
      • Cubbyhole secrets engine (API)
      • Database
        • Cassandra database plugin HTTP API
        • Elasticsearch database plugin HTTP API
        • Influxdb database plugin HTTP API
        • MongoDB database plugin HTTP API
        • MSSQL database plugin HTTP API
        • MySQL/MariaDB database plugin HTTP API
        • Oracle database plugin HTTP API
        • PostgreSQL database plugin HTTP API
        • Redis database plugin HTTP API
        • Redis ElastiCache database plugin HTTP API
        • Redshift database plugin HTTP API
        • Snowflake database plugin HTTP API
      • Google Cloud secrets engine (API)
      • Google Cloud KMS secrets engine (API)
      • Identity
        • entity
        • entity-alias
        • group
        • group-alias
        • tokens
        • lookup
        • oidc-provider
        • MFA
          • duo
          • okta
          • pingid
          • totp
          • login-enforcement
      • KV secrets engine (API)
      • Buckypaper secrets engine
      • Kubernetes secrets engine (API)
      • Nomad secrets engine (API)
      • LDAP secrets engine (API)
      • PKI secrets engine (API)
      • RabbitMQ secrets engine (API)
      • SSH secrets engine (API)
      • TOTP secrets engine (API)
      • Transit secrets engine (API)
    • Auth engines
      • AliCloud auth method (API)
      • AppRole auth method (API)
      • AWS auth method (API)
      • Azure auth method (API)
      • Pivotal Cloud Foundry (CF) auth method (API)
      • GitHub auth method (API)
      • Google Cloud auth method (API)
      • JWT/OIDC auth method (API)
      • Kerberos auth method (API)
      • Kubernetes auth method (API)
      • LDAP auth method (API)
      • OCI auth method (API)
      • Okta auth method (API)
      • Passwordless auth method (API)
      • RADIUS auth method (API)
      • TLS certificate auth method (API)
      • Token auth method (API)
      • Userpass auth method (HTTP API)
    • Service engines
      • Licence Manager
    • System backend
      • /sys/audit
      • /sys/audit-hash
      • /sys/auth
      • /sys/capabilities
      • /sys/capabilities-accessor
      • /sys/capabilities-self
      • /sys/config/auditing/request-headers
      • /sys/config/control-group
      • /sys/config/cors
      • /sys/config/reload
      • /sys/config/state
      • /sys/config/ui
      • /sys/decode-token
      • /sys/experiments
      • /sys/generate-recovery-token
      • /sys/generate-root
      • /sys/health
      • /sys/host-info
      • /sys/in-flight-req
      • /sys/init
      • /sys/internal/counters
      • /sys/internal/inspect
        • /sys/internal/inspect/router
      • /sys/internal/specs/openapi
      • /sys/internal/ui/feature-flags
      • /sys/internal/ui/mounts
      • /sys/internal/ui/namespaces
      • /sys/internal/ui/resultant-acl
      • /sys/key-status
      • /sys/ha-status
      • /sys/leader
      • /sys/leases
      • /sys/license/status
      • /sys/locked-users
      • /sys/loggers
      • /sys/metrics
      • /sys/monitor
      • /sys/mounts
      • /sys/namespaces
      • /sys/plugins/reload/backend
      • /sys/plugins/catalog
      • /sys/plugins/runtimes/catalog
      • /sys/policy
      • /sys/policies/
      • /sys/policies/password/
      • /sys/pprof
      • /sys/quotas/config
      • /sys/quotas/rate-limit
      • /sys/quotas/lease-count
      • /sys/raw
      • /sys/rekey
      • /sys/rekey-recovery-key
      • /sys/remount
      • /sys/rotate
      • /sys/rotate/config
      • /sys/seal
      • /sys/seal-status
      • /sys/seal-backend-status
      • /sys/step-down
      • /sys/storage
        • /sys/storage/raft
        • /sys/storage/raft/autopilot
      • /sys/tools
      • /sys/unseal
      • /sys/version-history
      • /sys/wrapping/lookup
      • /sys/wrapping/rewrap
      • /sys/wrapping/unwrap
      • /sys/wrapping/wrap
  • Resources
    • Blog
    • GitHub
    • Youtube
    • CCx101
Powered by GitBook
On this page
  • Configure the identity tokens backend
  • Read configurations for the identity tokens backend
  • Create a named key
  • Read a named key
  • Delete a named key
  • List named keys
  • Rotate a named key
  • Create or update a role
  • Read a role
  • Delete a role
  • List roles
  • Generate a signed ID token
  • Introspect a signed ID token
  • Read .well-known configurations
  • Read active public keys
  1. API
  2. Secrets engines
  3. Identity

tokens

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

{
  "issuer": "https://example.com:1234"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/config

Sample response

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/config

Sample response

{
  "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.

  • 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.

  • 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

{
  "rotation_period": "12h",
  "verification_ttl": 43200
}

Sample request

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001

Sample response

{
  "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

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/oidc/key

Sample response

{
  "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

{
  "verification_ttl": 0
}

Sample request

$ 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.

Sample payload

{
  "key": "named-key-001",
  "ttl": "12h"
}

Sample request

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/role/role-001

Sample response

{
  "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

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/oidc/role

Sample response

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/token/role-001

Sample response

{
  "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

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/introspect

Sample response

{
  "active": true
}

Read .well-known configurations

Query this path to retrieve a set of claims about the identity tokens' configuration. The response is a compliant OpenID Provider Configuration Response.

Method
Path

GET

identity/oidc/.well-known/openid-configuration

Sample request

$ curl \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration

Sample response

{
  "issuer": "https://example.com:1234",
  "authorization_endpoint": "",
  "token_endpoint": "",
  "jwks_uri": "https://example.com:1234/.well-known/keys",
  "response_types_supported": null,
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": null,
  "token_endpoint_auth_methods_supported": null,
  "claims_supported": null
}

Read active public keys

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

$ curl \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys

Sample response

{
  "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"
    }
  ]
}
Previousgroup-aliasNextlookup

Last updated 1 year ago