Public Clients

Public clients are applications that cannot keep a client secret. Browser apps are the common example. DarkAuth supports public clients through the Authorization Code flow with PKCE.

Why PKCE matters

In a public client, anyone who can inspect the app can see the client ID. PKCE adds a one-time verifier that the app generates before redirecting to DarkAuth. The authorization code is only useful to whoever still has that verifier.

DarkAuth supports the S256 PKCE method. Public clients should always use it.

Authorization request

A typical request includes:

• client_id
• redirect_uri
• response_type=code
• scope=openid profile email
• state
• code_challenge
• code_challenge_method=S256
• optional organization_id
• optional zk_pub for ZK-enabled clients

The app redirects the browser to DarkAuth. DarkAuth validates the client, redirect URI, response type, scopes, and PKCE challenge before continuing.

Callback handling

After the user signs in and consents, DarkAuth redirects to the registered redirect_uri with code and state. The app must verify state before exchanging the code.

The token request sends:

• grant_type=authorization_code
• client_id
• redirect_uri
• code
• code_verifier

The app should validate the returned ID token, store only what it needs, and use refresh behavior appropriate for the deployment.

UserInfo and revocation

Public clients can call GET /userinfo or POST /userinfo with a bearer access token to retrieve claims allowed by the token scopes.

Public clients can call POST /revoke with client_id to revoke refresh tokens issued to that client. They cannot call token introspection because introspection requires confidential client authentication.

Public clients with ZK delivery

If the client is configured for fragment-jwe, the authorization request can include zk_pub. The app must generate a fresh ephemeral P-256 key pair for the request and keep the private key in memory until the callback is handled.

Current v2 clients receive darkauth_key_jwe in the URL fragment. The token response contains zk_key_hash, zk_key_kind, and zk_key_version. The app must verify the fragment hash and payload metadata before decrypting and using the delivered CAK.

Explicit legacy v1 clients receive drk_jwe in the fragment and zk_drk_hash in the token response. Keep that path only for apps that still depend on the legacy root-key delivery model.

Common mistakes

• Reusing a PKCE verifier across requests.
• Not validating state.
• Registering overly broad redirect URIs.
• Losing the code verifier on page reload.
• Treating a public client as if it can protect a secret.
• Enabling ZK delivery before the app has implemented hash verification and memory-only key custody.