oidc-provider

Create or update a provider

This endpoint creates or updates a Provider.

Method	Path
POST	identity/oidc/provider/:name

Parameters

• name (string: <required>) – The name of the provider. This parameter is specified as part of the URL.

• issuer (string: <optional>) - Specifies what will be used as the scheme://host:port component for the iss claim of ID tokens. This defaults to a URL with OpenBao's api_addr as the scheme://host:port component and /v1/identity/oidc/provider/:name as the path component. If provided explicitly, it must point to an OpenBao instance that is network reachable by clients for ID token validation.

• allowed_client_ids ([]string: <optional>) – The client IDs that are permitted to use the provider. If empty, no clients are allowed. If "*" is provided, all clients are allowed.

• scopes_supported ([]string: <optional>) – The scopes available for requesting on the provider.

Sample payload

{
  "allowed_client_ids": ["*"],
  "scopes_supported": ["test-scope"]
}

Sample request

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

Read provider by name

This endpoint queries the OIDC provider by its name.

Method	Path
GET	/identity/oidc/provider/:name

Parameters

• name (string: <required>) – The name of the provider.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider

Sample response

{
  "data": {
      "allowed_client_ids":["*"],
      "issuer":"",
      "scopes_supported":["test-scope"]
    }
}

List providers

This endpoint returns a list of all OIDC providers.

Method	Path
LIST	/identity/oidc/provider

Query parameters

• allowed_client_id (string: <optional>) – Filters the list of OIDC providers to those that allow the given client ID in their set of allowed_client_ids.

Sample request

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

Sample response

{
  "data": {
    "key_info": {
      "default": {
        "allowed_client_ids": [
          "*"
        ],
        "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default",
        "scopes_supported": []
      }
    },
    "keys": [
      "default"
    ]
  }
}

Delete provider by name

This endpoint deletes an OIDC provider.

Method	Path
DELETE	/identity/oidc/provider/:name

Parameters

• name (string: <required>) – The name of the provider.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider

Create or update a scope

This endpoint creates or updates a scope.

Method	Path
POST	identity/oidc/scope/:name

Parameters

• name (string: <required>) – The name of the scope. This parameter is specified as part of the URL. The openid scope name is reserved.

• template (string: <optional>) - The JSON template string for the scope. This may be provided as escaped JSON or base64 encoded JSON.

• description (string: <optional>) – A description of the scope.

Sample payload

{
   "template":"{ \"groups\": {{identity.entity.groups.names}} }",
   "description":"A simple scope example."
}

Sample request

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

Read scope by name

This endpoint queries a scope by its name.

Method	Path
GET	/identity/oidc/scope/:name

Parameters

• name (string: <required>) – The name of the scope.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope

Sample response

{
  "data": {
      "description":"A simple scope example.",
      "template":"{ \"groups\": {{identity.entity.groups.names}} }"
   }
}

List scopes

This endpoint returns a list of all configured scopes.

Method	Path
LIST	/identity/oidc/scope

Sample request

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

Sample response

{
  "data": {
      "keys":[
         "test-scope"
      ]
   }
}

Delete scope by name

This endpoint deletes a scope.

Method	Path
DELETE	/identity/oidc/scope/:name

Parameters

• name (string: <required>) – The name of the scope.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope

Create or update a client

This endpoint creates or updates a client.

Method	Path
POST	identity/oidc/client/:name

Parameters

• name (string: <required>) – The name of the client. This parameter is specified as part of the URL.

• key (string: "default") – A reference to a named key resource. This key will be used to sign ID tokens for the client. This cannot be modified after creation. If not supplied, defaults to the built-in default key.

• redirect_uris ([]string: <optional>) - Redirection URI values used by the client. One of these values must exactly match the redirect_uri parameter value used in each authentication request.

• assignments ([]string: <optional>) – A list of assignment resources associated with the client. Client assignments limit the OpenBao entities and groups that are allowed to authenticate through the client. By default, no OpenBao entities are allowed. To allow all OpenBao entities to authenticate through the client, supply the built-in allow_all assignment.

• client_type (string: "confidential") – The client type based on its ability to maintain confidentiality of credentials. This cannot be modified after creation. The following list details the differences between confidential and public clients in OpenBao:

  • confidential
    • Capable of maintaining the confidentiality of its credentials
    • Has a client secret
    • Uses the client_secret_basic or client_secret_post client authentication method
    • May use Proof Key for Code Exchange (PKCE) for the authorization code flow
  • public
    • Not capable of maintaining the confidentiality of its credentials
    • Does not have a client secret
    • Uses the none client authentication method
    • Must use Proof Key for Code Exchange (PKCE) for the authorization code flow

• id_token_ttl (int or duration: "24h") – The time-to-live for ID tokens obtained by the client. Accepts duration format strings. The value should be less than the verification_ttl on the key.

• access_token_ttl (int or duration: "24h") – The time-to-live for access tokens obtained by the client. Accepts duration format strings.

Sample payload

{
   "key":"test-key",
   "access_token_ttl":"30m",
   "id_token_ttl":"1h"
}

Sample request

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

Read client by name

This endpoint queries a client by its name.

Method	Path
GET	/identity/oidc/client/:name

Parameters

• name (string: <required>) – The name of the client.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/client/test-client

Sample response

{
  "data":{
      "access_token_ttl":1800,
      "assignments":[],
      "client_id":"014zXvcvbvIZWwD5NfD1Uzmv7c5JBRMb",
      "client_secret":"hvo_secret_bZtgQPBZaJXK7F5vOI7JlvEuLOfOUS7DmwynFjE3xKcsen7TyowqPFfYFXG2tbWM",
      "client_type": "confidential",
      "id_token_ttl":3600,
      "key":"test-key",
      "redirect_uris":[]
   }
}

List clients

This endpoint returns a list of all configured clients.

Method	Path
LIST	/identity/oidc/client

Sample request

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

Sample response

{
  "data": {
    "key_info": {
      "my-app": {
        "access_token_ttl": 86400,
        "assignments": [
          "allow_all"
        ],
        "client_id": "wGr981oYLJbcr4zrUriYxjxSc80JL7HW",
        "client_type": "confidential",
        "id_token_ttl": 86400,
        "key": "default",
        "redirect_uris": [
          "http://localhost:5555/callback"
        ]
      }
    },
    "keys": [
      "my-app"
    ]
  }
}

Delete client by name

This endpoint deletes a client.

Method	Path
DELETE	/identity/oidc/client/:name

Parameters

• name (string: <required>) – The name of the client.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/client/test-client

Create or update an assignment

This endpoint creates or updates an assignment.

Method	Path
POST	identity/oidc/assignment/:name

Parameters

• name (string: <required>) – The name of the assignment. This parameter is specified as part of the URL.

• entity_ids ([]string: <optional>) - A list of OpenBao entity IDs.

• group_ids ([]string: <optional>) – A list of OpenBao group IDs.

Sample payload

{
   "group_ids":["262ca5b9-7b69-0a84-446a-303dc7d778af"],
   "entity_ids":["b6094ac6-baf4-6520-b05a-2bd9f07c66da"]
}

Sample request

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

Read assignment by name

This endpoint queries an assignment by its name.

Method	Path
GET	/identity/oidc/assignment/:name

Parameters

• name (string: <required>) – The name of the assignment.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment

Sample response

{
  "data":{
      "entity_ids":[
         "b6094ac6-baf4-6520-b05a-2bd9f07c66da"
      ],
      "group_ids":[
         "262ca5b9-7b69-0a84-446a-303dc7d778af"
      ]
   }
}

List assignments

This endpoint returns a list of all configured assignments.

Method	Path
LIST	/identity/oidc/assignment

Sample request

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

Sample response

{
  "data": {
      "keys":[
         "test-assignment"
      ]
   }
}

Delete assignment by name

This endpoint deletes an assignment.

Method	Path
DELETE	/identity/oidc/assignment/:name

Parameters

• name (string: <required>) – The name of the assignment.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment

Read provider OpenID configuration

Returns OpenID Connect Metadata for a named OIDC provider. The response is a compliant OpenID Provider Configuration Response.

Method	Path
GET	/identity/oidc/provider/:name/.well-known/openid-configuration

Parameters

• name (string: <required>) – The name of the provider. This parameter is specified as part of the URL.

Sample request

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

Sample response

{
  "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider",
  "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys",
  "authorization_endpoint": "http://127.0.0.1:8200/ui/identity/oidc/provider/test-provider/authorize",
  "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token",
  "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo",
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "ES256",
    "ES384",
    "ES512",
    "EdDSA"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ]}

Read provider public keys

Query this path to retrieve the public portion of keys for an OIDC provider. Clients can use them to validate the authenticity of an identity token.

Method	Path
GET	/identity/oidc/provider/:name/.well-known/keys

Parameters

• name (string: <required>) – The name of the provider. This parameter is specified as part of the URL.

Sample request

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

Sample response

{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "ee7c0920-fdb9-5c1a-9c69-6dab710d1a09",
      "alg": "RS256",
      "n": "zdFjUV9lBw5nQPvTtwH-gzKgRG7iepvYbFoc2hNB0-inJL25oh-mvNW3GS8jPY5XHLsiWa_1TKKE99JrKQgane2C96soFeOvR7SozbCeH8_FpZelH1Pym1NV038j05Vp87uB9FeKPsy1PNOLPTs_Fp42JIAenly7ojYwPp1s61p9V0U9rOhtldY7GkXHLN9s8v3aJjxqrTS3Puhs9MFS7EgRrEDAc69uiLXCoYXKygjXddvJi6j446XxnO2eTRMGl1f2t04s_vDgVnFQgjQSKYWPbOMhf2slkeR47fqE3qqUDzINxauqMbkW-PlLP9IN0crR2uC07cG2os4RxN4YHw",
      "e": "AQAB"
    },
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "6e468221-b7c2-9d2d-744d-33b7ae0357cb",
      "alg": "RS256",
      "n": "rMaucILJKiFg_lkCE8ZEV_8jiYdaVDjKkc-8XPBW8S34wIRl1EbsgCYfMHtJnIJ_3eUgOVorW5KVeN9C8W16LR3lhqRWS9y4qlt0AcWpOvsmxr5q5dS_QqgCjeftCKwJzUsMi5bMW8wKjRZdd-qLz6X1rVSZWX82G0So8nRBg9d3MNJbKcdIJrRbrxWkm8U9xMqRouzbyQ2Hsp2rRVgGh7yjEA6daI5Ao8UsPdBmlCM9oKZ1_Kje5JTfZKeHlT-58vn_ylCjMVlapLuUsDN6He2kPVyOzGbie297VOfjmB7QX0ah1f7Ni1UJFJYHrVK9wMfCLTltSFZBcQ9--FlVdQ",
      "e": "AQAB"
    }
  ]}

Authorization endpoint

Provides the Authorization Endpoint for an OIDC provider. This allows OIDC clients to request an authorization code to be used for the Authorization Code Flow.

Method	Path
GET/POST	/identity/oidc/provider/:name/authorize

Parameters

• name (string: <required>) - The name of the provider. This parameter is specified as part of the URL.

• scope (string: <required>) - A space-delimited list of scopes to be requested. The openid scope is required.

• response_type (string: <required>) - The OIDC authentication flow to be used. The following response types are supported: code.

• client_id (string: <required>) - The ID of the requesting client.

• redirect_uri (string: <required>) - The redirection URI to which the response will be sent.

• state (string: <optional>) - A value used to maintain state between the authentication request and client.

• nonce (string: <optional>) - A value that is returned in the ID token nonce claim. It is used to mitigate replay attacks, so we strongly encourage providing this optional parameter.

• max_age (integer: <optional>) - The allowable elapsed time in seconds since the last time the end-user was actively authenticated.

• code_challenge (string: <optional>) - The PKCE code challenge derived from the client's code verifier. Optional for confidential clients. Required for public clients.

• code_challenge_method (string: "plain") - The method that was used to derive the PKCE code challenge. The following methods are supported: S256, plain.

Sample request

$ curl \
    --request GET \
    --header "X-Vault-Token: ..." \
    -G \
    -d "response_type=code" \
    -d "client_id=$CLIENT_ID" \
    -d "state=af0ifjsldkj" \
    -d "nonce=abcdefghijk" \
    --data-urlencode "scope=openid" \
    --data-urlencode "redirect_uri=http://127.0.0.1:8251/callback" \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/authorize

Sample response

{
  "code": "BDSc9kVYljxND93YpveBuJtSvguM3AWe",
  "state": "af0ifjsldkj"
}

Token endpoint

Provides the Token Endpoint for an OIDC provider.

Method	Path
POST	/identity/oidc/provider/:name/token

Parameters

• name (string: <required>) - The name of the provider. This parameter is specified as part of the URL.

• code (string: <required>) - The authorization code received from the provider's authorization endpoint.

• grant_type (string: <required>) - The authorization grant type. The following grant types are supported: authorization_code.

• redirect_uri (string: <required>) - The callback location where the authorization request was sent. This must match the redirect_uri used when the original authorization code was generated.

• client_id (string: <optional>) - The ID of the requesting client. This parameter is required for public clients which do not have a client secret or confidential clients using the client_secret_post client authentication method.

• client_secret (string: <optional>) - The secret of the requesting client. This parameter is required for confidential clients using the client_secret_post client authentication method.

• code_verifier (string: <optional>) - The code verifier associated with the given code. Required for authorization codes that were granted using PKCE. Required for public clients.

Headers

• Authorization: Basic (string: <optional>) - An HTTP Basic authentication scheme header including the client_id and client_secret as described in the client_secret_basic authentication method. This header is only required for confidential clients using the client_secret_basic client authentication method.

Sample request

$ BASIC_AUTH_CREDS=$(printf "%s:%s" "$CLIENT_ID" "$CLIENT_SECRET" | base64)
$ curl \
    --request POST \
    --header "Authorization: Basic $BASIC_AUTH_CREDS" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "code=4RL50r78p8HsNJY0GVUNGfjLHnpkRf3N" \
    -d "grant_type=authorization_code" \
    -d "redirect_uri=http://127.0.0.1:8251/callback" \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token

Sample response

{
  "access_token": "b.AAAAAQJEH5VXjfjUESCwySTKk2MS1MGVNc9oU-N2EyoLKVo9SYa-NnOWAXloYfrlO45UWC3R1PC5ZShl3JdmRJ0264julNnlBduSNXJkYjgCQsFQwXTKHcjhqdNsmJNMWiPaHPn5NLSpNQVtzAxfHADt4r9rmX-UEG5seOWbmK_Z5WwS_4a8-wcVPB7FpOGzfBydP7yMxHu-3H1TWyQvYVr28XUfYxcBbdlzxhJn0yqkWItgmZ25xEOp7SW7Pg4tYB7AXfk",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzMjk5ZWVmLTllNDEtOGNiYS1kNWExLTZmZWM2NjIyODRjYyJ9.eyJhdF9oYXNoIjoiMUdlQlEzUFdtUjJ2ajZVU2swSW42USIsImF1ZCI6InpTSktMVmk0R1BYS1o3TTZzUUEwY3FNc05VaHNPYkVTIiwiY19oYXNoIjoiN09SOUszNmhNdllENzJkUkFLUHhNdyIsImNvbnRhY3QiOnsiZW1haWwiOiJ2YXVsdEBoYXNoaWNvcnAuY29tIiwicGhvbmVfbnVtYmVyIjoiMTIzLTQ1Ni03ODkwIn0sImV4cCI6MTYzMzEwNjI5NCwiZ3JvdXBzIjpbImVuZ2luZWVyaW5nIl0sImlhdCI6MTYzMzEwNDQ5NCwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MjAwL3YxL2lkZW50aXR5L29pZGMvcHJvdmlkZXIvbXktcHJvdmlkZXIiLCJuYW1lc3BhY2UiOiJyb290Iiwibm9uY2UiOiJhYmNkZWZnaGlqayIsInN1YiI6IjUwMDA3OTZlLTM2ZGYtMGQ4Yy02NDYwLTgxODUzZDliMjY2NyIsInVzZXJuYW1lIjoiZW5kLXVzZXIifQ.ehdLj6jnrJvltar1kkVSyNK48w2M5vkh5DTFJFZDqatnDWhQbbKGLZnVgd3wD6KPboXRaUwhGe4jDiTIiSoJaovOhsia77NKukym_ROLvGZw-LG7xaYkzJLnmEfeQhelLxWe0DHPROB7VXcFqBx8vX5hkuoVyqrB87vwiobK42pDPZ9MRsmbM2yzBC3wrnT7RQFtT4q2Bbyt9YIAHUaq9rU0PwJRoNISw6of1uQHo3_UzLdpwth7PEOEcI47OBGFA5vR_Gw3ocREfSrUWfCWOInAKCT43cImvg4Bts6qiZYfv9n-iNBq4AihGqq_VEF-hB1Hrprn7VgnEZ1VjUHaQQ",
  "token_type": "Bearer"
}

UserInfo endpoint

Provides the UserInfo Endpoint for an OIDC provider. The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User.

Method	Path
POST	/identity/oidc/provider/:name/userinfo

Parameters

• name (string: <required>) - The name of the provider. This parameter is specified as part of the URL.

Headers

• Access Token (string: <required>) - The access token provided by the Authorization: Bearer <access_token> HTTP header acquired from the authorization endpoint.

Sample request

$ curl \
    -X GET \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo

Sample response

{
  "contact": {
    "email": "openbao@lists.lfedge.org",
    "phone_number": "123-456-7890"
  },
  "groups": [
    "engineering"
  ],
  "sub": "5000796e-36df-0d8c-6460-81853d9b2667",
  "username": "end-user"}