Skip to main content
Version: v2.0 (latest)

Authorization Code Flow With PKCE

The Authorization Code flow with PKCE is the baseline. Learn it here, then turn it into the recommended signed flow in JAR. The example requests Dynamic Liveness against the hosted profile of jane.doe@example.com.

Step 1 — Generate PKCE Values and Build the Authorization URL​

PKCE (RFC 7636) protects the authorization code. OIDC Web supports the S256 method.

import base64, hashlib, os

code_verifier = base64.urlsafe_b64encode(os.urandom(32)).rstrip(b"=").decode()
code_challenge = (
    base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
    .rstrip(b"=").decode()
)
# store code_verifier in the user's server-side session for step 3

Redirect the user's browser to the authorization endpoint:

$BASE/oidc/v1/authorize
    ?response_type=code
    &client_id=$CLIENT_ID
    &redirect_uri=https://yourapp.example/callback
    &scope=openid%20faceauth_dynamic_only
    &login_hint=jane.doe%40example.com
    &state=<opaque-random>
    &nonce=<opaque-random>
    &code_challenge=<code_challenge>
    &code_challenge_method=S256
  • state — an opaque value you generate and later verify. The check defends against cross-site request forgery (CSRF) on the redirect.
  • nonce — an opaque value echoed back inside the ID token. The echo binds the token to this request.

The browser lands on the iProov-hosted verification page and the user completes the face scan. OIDC Web then redirects back to your redirect_uri:

https://yourapp.example/callback?code=<authorization_code>&state=<state>

Step 2 — Verify state​

Reject the response if state does not match the value you issued.

Step 3 — Exchange the Code for Tokens​

Call the token endpoint (application/x-www-form-urlencoded):

curl -s -X POST "$BASE/oidc/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=<authorization_code> \
  -d redirect_uri=https://yourapp.example/callback \
  -d client_id=$CLIENT_ID \
  -d code_verifier=<code_verifier>

Response:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 86400,
  "id_token": "<JWT>"
}

No refresh token is issued for face-verification requests (see Scopes).

Step 4 — Validate the ID Token​

Verify the signature against the keys at the jwks_uri. Then check the standard claims: iss matches your environment's issuer, aud equals your client_id, exp is in the future, and nonce matches what you sent. Use a vetted OIDC/JWT library for validation — do not validate by hand.

Step 5 — Read the Result​

Check acr and amr to confirm the verification level you received (see Reading the Result). You can also fetch the claims from the userinfo endpoint with the access token:

curl -s "$BASE/oidc/v1/userinfo" -H "Authorization: Bearer <access_token>"