Skip to content

PKCE Client Integration Guide (Provisioning Tools)

Device provisioning tools authenticate to the Keyserver with the OAuth2 Authorization Code Flow with PKCE (Proof Key for Code Exchange).

PKCE is the right flow for applications that cannot safely store a client secret:

  • Provisioning stations on the factory floor
  • Command-line provisioning tools on desktop PCs
  • Browser-based manufacturing consoles

Instead of a stored secret, a human operator logs in through the organization's identity provider (with MFA), and the tool receives a short-lived access token to call the Keyserver.

The fragments below are not a complete client

Before shipping a provisioning tool, your implementation must also:

  • Generate a cryptographically random state per authorization request and reject any callback whose state does not match. Without this the tool accepts authorization codes injected by an attacker.
  • Send an OIDC nonce and verify it in the returned ID token, binding the token to this request.
  • Bind the callback to the request that started it, and accept only one callback: run the redirect listener on the loopback interface only, on a port you opened for this exchange, and shut it down as soon as the code arrives.
  • Enforce a timeout on the whole exchange, and handle operator cancellation and identity-provider error responses (error, error_description) rather than hanging.
  • Never log or persist the code_verifier, the authorization code, or the resulting tokens.

Use a maintained OAuth2/OIDC library for your language rather than hand-rolling this.

Requires an identity provider with public-client support

This flow depends on your identity provider (IdP) registering the provisioning tool as a public client (no client secret; supported by Entra ID and most compliant OAuth2/OIDC providers). The internal trial Authserver registers only confidential clients, so this secretless flow cannot be demonstrated against a trial environment.

How it works

sequenceDiagram
    participant T as Provisioning tool
    participant O as Operator (browser)
    participant I as Identity provider
    participant K as Keyserver

    T->>T: Generate code verifier + challenge,<br/>random state, random nonce
    T->>O: Open authorization URL<br/>(challenge + state + nonce)
    O->>I: Log in (MFA)
    I-->>T: Authorization code + state (redirect URI)
    T->>T: Reject unless returned state matches
    T->>I: Exchange code + verifier for token
    I-->>T: Access token + ID token
    T->>T: Reject unless ID token nonce matches
    T->>K: API calls (Bearer token)

Diagram: Provisioning tool; Operator (browser); Identity provider; Keyserver; Generate code verifier + challenge, random state, random nonce; Open authorization URL (challenge + state + nonce); Log in (MFA); Authorization code + state (redirect URI); Reject unless returned state matches; Exchange code + verifier for token; Access token + ID token; Reject unless ID token nonce matches; API calls (Bearer token)

PKCE extends the Authorization Code Flow with two values:

  • Code Verifier: a random secret generated by the tool, kept in memory only
  • Code Challenge: a SHA-256 hash of the verifier, sent with the authorization request

The tool presents the verifier at token exchange, so an intercepted authorization code is useless without it.

Step 1: Configure the Identity Provider

Azure Entra ID

The Keyserver's Entra ID app registration is extended with a PKCE platform, as described in the Azure Entra ID Integration Guide. In short:

  • Manage → Authentication → Add a platform → Mobile and desktop applications
  • Insert the PKCE_REDIRECT_URI value provided by Cryptera as a custom redirect URI

By default PKCE reuses the Keyserver app registration in public-client mode, with no client secret. Some deployments use a dedicated registration for provisioning tools instead. Confirm the client ID and redirect URI with Cryptera; they must match your instance's configuration.

Other providers

  1. Configure a public client (no client secret)
  2. Enable Authorization Code Flow with PKCE (S256)
  3. Register the redirect URI provided by Cryptera
  4. Expose a scope for the Keyserver API so issued tokens carry the Keyserver audience

Step 2: Register the Operator as a Keyserver Subject

A valid token is not enough. The logged-in user must also be a registered subject in the Keyserver, with a role granting the needed permissions:

  • For device certificate issuance: a role with the devcertsigner nature scoped to the CA key
  • For firmware signing: a role with the fwsigner nature scoped to the FW key

See Manage Subjects in the Keyserver and Manage Roles in the Keyserver.

Step 3: Generate the Code Verifier and Challenge

VERIFIER=$(openssl rand -base64 64 | tr -d '=+/\n')

CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

# Anti-forgery values — generate fresh per authorization request, keep in memory,
# and validate on the way back (see the next two steps). Never reuse them.
STATE=$(openssl rand -hex 16)
NONCE=$(openssl rand -hex 16)

Step 4: Send the Operator to the Authorization URL

Include the Keyserver API scope

For Entra ID the scope is api://<APPLICATION_ID>/keyserver, created in the Azure guide. A token requested with only openid profile does not carry the Keyserver audience and is rejected with 401.

https://<IDP>/authorize?
  response_type=code&
  client_id=<CLIENT_ID>&
  redirect_uri=<PKCE_REDIRECT_URI>&
  code_challenge=$CHALLENGE&
  code_challenge_method=S256&
  state=$STATE&
  nonce=$NONCE&
  scope=openid%20profile%20<KEYSERVER_SCOPE>

The operator logs in (including MFA if configured). The IdP redirects back to the tool with an authorization code:

<PKCE_REDIRECT_URI>?code=<AUTH_CODE>&state=<STATE>

Discard the callback unless the returned state equals $STATE:

[ "$RETURNED_STATE" = "$STATE" ] || { echo "state mismatch - aborting"; exit 1; }

Step 5: Exchange the Code for a Token

The token endpoint path varies by provider. Read it from token_endpoint in the IdP's discovery document (/.well-known/openid-configuration).

POST <token_endpoint>
grant_type=authorization_code
client_id=<CLIENT_ID>
code_verifier=$VERIFIER
code=<AUTH_CODE>
redirect_uri=<PKCE_REDIRECT_URI>

The response contains access_token, id_token, and expires_in.

Validate the ID token's nonce against the $NONCE you sent, before trusting the tokens. This binds the response to your authorization request:

PAYLOAD=$(printf '%s' "$ID_TOKEN" | cut -d '.' -f 2 | tr '_-' '/+')
while [ $((${#PAYLOAD} % 4)) -ne 0 ]; do PAYLOAD="$PAYLOAD="; done
[ "$(printf '%s' "$PAYLOAD" | base64 -d | jq -r .nonce)" = "$NONCE" ] || \
  { echo "nonce mismatch - aborting"; exit 1; }

Step 6: Verify the Token Claims

Before wiring the token into the tool, decode the access token's payload and check that the IdP issued what the Keyserver expects (example for Entra ID):

PAYLOAD=$(printf '%s' "$ACCESS_TOKEN" | cut -d '.' -f 2 | tr '_-' '/+')
while [ $((${#PAYLOAD} % 4)) -ne 0 ]; do PAYLOAD="$PAYLOAD="; done
printf '%s' "$PAYLOAD" | base64 -d | jq '{iss, aud, scp, preferred_username, ver}'
Claim Must be If it is not
iss Your IdP's issuer URL (for Entra: https://login.microsoftonline.com/<TENANT_ID>/v2.0) The Keyserver rejects tokens from unconfigured issuers (401)
aud The Keyserver app registration's client ID (or its api:// URI) The authorization request lacked the Keyserver scope (Step 4), so 401
scp Contains keyserver Wrong scope requested; the Keyserver rejects the token
preferred_username The operator's login (a user token). At first login it is matched against the subject's Subject name; later logins match the user-ID claim (such as oid) against Subject ID Login still succeeds, but subsequent API calls return 401 "The user/client is not valid" if the operator is not registered (Step 2)
ver "2.0" (Entra only) Set requestedAccessTokenVersion to 2 on the Keyserver app registration's manifest

Unlike CI tokens, a PKCE token identifies a human user. The Keyserver maps it to a user subject, not a client subject.

Step 7: Use the Access Token with the Keyserver

curl -sS --tlsv1.3 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://keyserver.<UNIQUE-ID>.cryptera-security.io/api/keys"

From here the flow is identical to any other client: create an operation, obtain approval if the key requires it, then submit sign orders or CSRs. For the complete device-provisioning walkthrough, see Issue a Device Certificate Using the Trial Environment and Issue Device Certificates from CI/CD and Provisioning Pipelines.

Tokens are short-lived; the tool should refresh (re-run the flow or use a refresh token if the IdP issues one) rather than caching tokens across provisioning sessions.

If something fails

Symptom Cause
401 from the Keyserver Token lacks the Keyserver audience: the authorization request did not include the Keyserver scope, or aud is wrong (Step 6)
Login succeeds, but API calls return 401 "The user/client is not valid" The operator is not registered as a Keyserver subject (Step 2)
403 "Access forbidden" Subject registered, but its role lacks the needed permission (e.g. devcertsigner for the CA key)
Token exchange fails with invalid_grant Authorization code expired (they are valid for minutes) or the code_verifier does not match. Restart the flow

Full status-code reference: Error Codes.