How to : Vault OIDC authentication through API call

Avatar
Nitesh Kumar
  • Updated

Scope :

This article works as a guide for authenticating to vault using OIDC auth method through API. While UI and CLI are the common ways to authenticate using OIDC auth method, API login can also be performed if required using oidc-callback endpoint.

 

Prerequisites:

  • OIDC auth method configured and login working through CLI & UI.
  • In this guide, OIDC auth method is mounted at /auth/OIDC. The role being used to perform API login is named vault-role-okta-admin.

Steps :

  • Obtain an authorization URL from Vault to start an OIDC login flow:

Request :

curl --request POST --data @payload.json http://192.168.64.10:8200/v1/auth/oidc/oidc/auth_url

Content of payload.json:

{
  "role": "vault-role-okta-admin",
  "redirect_uri": "http://192.168.64.10:8200/ui/vault/auth/oidc/oidc/callback"
}

Response:

{"request_id":"10995ed0-8e63-4090-508e-b409ced3bcf5","lease_id":"","renewable":false,"lease_duration":0,"data":{"auth_url":"https://dev-94332139.okta.com/oauth2/v1/authorize?client_id=0oafasqa99UWbta4H5d7&code_challenge=8oztmvYcmtygIrKB5zdVMIvf3hTiUw-2AMVHAAhvraA&code_challenge_method=S256&nonce=n_5CQxy1ELXPMd4fRULY1U&redirect_uri=http%3A%2F%2F192.168.64.10%3A8200%2Fui%2Fvault%2Fauth%2Foidc%2Foidc%2Fcallback&response_type=code&scope=openid&state=st_mauDCl8KATfkx3tCVBzx"},"wrap_info":null,"warnings":null,"auth":null}

Get the authorization code required for oidc-callback step. Open the auth_url from last response in browser, and complete required authentication through Okta.

https://dev-94332139.okta.com/oauth2/v1/authorize?client_id=0oafasqa99UWbta4H5d7&code_challenge=8oztmvYcmtygIrKB5zdVMIvf3hTiUw-2AMVHAAhvraA&code_challenge_method=S256&nonce=n_5CQxy1ELXPMd4fRULY1U&redirect_uri=http%3A%2F%2F192.168.64.10%3A8200%2Fui%2Fvault%2Fauth%2Foidc%2Foidc%2Fcallback&response_type=code&scope=openid&state=st_mauDCl8KATfkx3tCVBzx

Copy the response from the URL redirection after successful Okta authentication. Alternatively, this can also be done by using inspect tool in browser of choice during authentication. Sample below :

http://192.168.64.10:8200/ui/vault/auth/oidc/oidc/callback?code=is4MCorxfg24AmFQfeaex8D22J99rXjcUFq4QJkbpzk&state=st_mauDCl8KATfkx3tCVBzx
  •   Obtain vault token through callback URL. 

Use the code, state & nonce to prepare callback URL first. The callback URL has /v1/authoidc/oidc/callback endpoint. Open callback URL in browser.

Sample URL:

http://192.168.64.10:8200/v1/auth/oidc/oidc/callback?state=st_mauDCl8KATfkx3tCVBzx&code=is4MCorxfg24AmFQfeaex8D22J99rXjcUFq4QJkbpzk&nonce=n_5CQxy1ELXPMd4fRULY1U

 Response(vault token highlighted in bold):

{"request_id":"bbd6516b-809d-ce33-8d4e-e96e9664c8f0","lease_id":"","renewable":false,"lease_duration":0,"data":null,"wrap_info":null,"warnings":["Endpoint ignored these unrecognized parameters: [nonce]"],"auth":{"client_token":"hvs.CAESIFLQBjnVRs_FqFFTY1kCjy-L3iw3M-s_ImTiKCJcN1gqGiEKHGh2cy45aFFqZUlyazhGU2tzc1hiNFJMQUN1Qm0Q3wI","accessor":"Wb0mMCoZafcFJVbMODoPqUzj","policies":["default","vault-policy-developer-read"],"token_policies":["default","vault-policy-developer-read"],"metadata":{"role":"vault-role-okta-admin"},"lease_duration":2764800,"renewable":true,"entity_id":"75851ee8-49d6-7e71-19bb-ed3778b5ade0","token_type":"service","orphan":true,"mfa_requirement":null,"num_uses":0}}

*Please note that the order of attributes state, code and nonce in the callback URL is not significant. Also, nonce is an optional attribute(value of nonce can be found in auth_url. Nonce can be excluded from the callback URL, if it is not mandatory as per Okta configuration.

 

Note:

  • While opening the auth_url in browser; the redirection leads to an error page on vault; which can be ignored. The error shown is expected as this step is only intended to capture code, state & nonce.
  • The only way found to exchange the authorization code from provider is using a browser. This is because of the reason that OIDC authentication is required before the exchange can be made. This is as per OIDC authorization code requirements, as user agent is directed to along with code  in browser only.
  • The authorization code can only be used once, and remains valid for 300 seconds, during which time it can be exchanged for tokens.
  • There is browser dependency from Okta perspective for exchanging and verifying the authorisation code with OIDC providers. Therefore, calling the callback URL in a browser is a necessity.
  • If OIDC auth method is configured at namespace level, add name of the namespace in callback URL. Below is an example where test is the name of the namespace :
http://192.168.64.10:8200/v1//test/auth/oidc/oidc/callback?state=st_mauDCl8KATfkx3tCVBzx&code=is4MCorxfg24AmFQfeaex8D22J99rXjcUFq4QJkbpzk&nonce=n_5CQxy1ELXPMd4fRULY1U

 

References:

OIDC authorization code requirements

JWT/OIDC auth method (API)

 

Articles in this section

See more

Related articles