How to Use PKCE with Vultr OAuth

Proof Key for Code Exchange (PKCE) protects the authorization code flow for clients that cannot safely store a client secret, such as single-page applications and mobile apps. The client generates a secret verifier, sends a hashed challenge during authorization, and proves possession of the verifier at token exchange, which prevents an intercepted code from being redeemed by an attacker.

Follow this guide to use PKCE with the Vultr OAuth authorization flow using the Vultr API.

1. Generate a random code verifier between 43 and 128 characters, then derive the code challenge as the base64url-encoded SHA-256 hash of the verifier.

   console Copy

   $ CODE_VERIFIER=$(openssl rand -hex 32)
   $ CODE_CHALLENGE=$(printf '%s' "${CODE_VERIFIER}" | openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=')
   

   Explain Code

   Store the CODE_VERIFIER value across the redirect, because you send it at token exchange.

2. Send a POST request to the Authorize OAuth Application endpoint with the code challenge. Replace CLIENT-ID with the application id and CALLBACK-URL with a registered callback URL.

   console Copy

   $ curl "https://api.vultr.com/v2/oauth/authorize" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "client_id": "CLIENT-ID",
           "redirect_uri": "CALLBACK-URL",
           "response_type": "code",
           "approve": true,
           "code_challenge": "'"${CODE_CHALLENGE}"'",
           "code_challenge_method": "S256"
       }'
   

   Explain Code

   A successful request returns an HTTP 200 OK response with a one-time code. Note the code for the token exchange.

   Note

   Always send code_challenge_method set to S256. If you omit it, the method defaults to plain, which sends the verifier without hashing and provides weaker protection.

3. Send a POST request to the Token endpoint with the code verifier. Replace {provider-id} with the provider id, CLIENT-ID and CLIENT-SECRET with your credentials, AUTH-CODE with the code, and CALLBACK-URL with the same callback URL.

   console Copy

   $ curl "https://api.vultr.com/v2/oidc/provider/{provider-id}/token" \
       -X POST \
       -H "Authorization: Basic $(printf '%s:%s' "CLIENT-ID" "CLIENT-SECRET" | base64)" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       --data-urlencode "grant_type=authorization_code" \
       --data-urlencode "code=AUTH-CODE" \
       --data-urlencode "redirect_url=CALLBACK-URL" \
       --data-urlencode "code_verifier=${CODE_VERIFIER}"
   

   Explain Code

   A successful request returns an HTTP 200 OK response with an access_token and a refresh_token. A verifier that does not match the challenge returns an HTTP 400 Bad Request response.