PKCE policy for authorisation requests

1. Overview

Proof Key for Code Exchange (PKCE, pronounced “pixie”), defined in RFC 7636, is an OAuth 2.0 extension that protects the authorisation code flow. It achieves that by binding the issued authorisation code to a secret value, called the code_verifier, known only to the client.

OAuth 2.1 raises the baseline security by requiring PKCE for authorisation requests.

Connect2id server deployments are able to define a PKCE policy at two levels:

• Globally, with the op.authz.allowedPKCE and op.authz.requiredPKCE configuration properties. They determine which PKCE methods are accepted for authorisation requests, and whether PKCE is required.

• Per client, with the optional code_challenge_method client metadata parameter, to further restrict an individual client to a specific PKCE method.

The Connect2id server supports the two standard PKCE code challenge methods:

The S256 method is recommended for normal deployments.

2. Global PKCE policy

The global PKCE policy is configured by these properties:

• op.authz.allowedPKCE
• op.authz.requiredPKCE

Both settings accept a comma and / or space separated list of PKCE methods.

The default global policy is permissive: PKCE is allowed, but not required globally; individual clients can be controlled with the code_challenge_method metadata parameter:

op.authz.allowedPKCE=plain,S256
op.authz.requiredPKCE=

For new deployments, the recommended policy is to require PKCE with S256 only:

op.authz.allowedPKCE=S256
op.authz.requiredPKCE=S256

3. Per-client PKCE policy

An individual OAuth 2.0 client can be registered with a code_challenge_method metadata parameter.

When this metadata parameter is set, the client must use that exact PKCE method in its authorisation requests.

For example, a client registered with

{
  "code_challenge_method" : "S256"
}

must send

code_challenge_method=S256

in its authorisation request.

If the client sends a different PKCE method, or omits the method, the request is rejected.

The per-client code_challenge_method setting therefore acts as a client-specific PKCE requirement. It can be used to enforce a stricter policy for selected clients, even when PKCE is not required globally.

4. PKCE enforcement order

The Connect2id server enforces the PKCE policy in this order:

1. The server checks whether the supplied PKCE method is allowed by op.authz.allowedPKCE.

2. The server checks whether op.authz.requiredPKCE is set. If it is set, a PKCE method must be supplied, and it must be listed in op.authz.requiredPKCE.

3. The server checks whether the client is registered with a code_challenge_method metadata parameter. If it is set, the supplied PKCE method must match the registered client method.

5. Policy examples

5.1 Compatible default policy

op.authz.allowedPKCE=plain,S256
op.authz.requiredPKCE=

This is the most compatible policy. PKCE is allowed, but not required globally. Clients may use either supported method, unless a stricter per-client code_challenge_method is registered.

5.2 Require PKCE with S256 only

op.authz.allowedPKCE=S256
op.authz.requiredPKCE=S256

This is the recommended strict policy. Clients must use PKCE, and only the S256 method is accepted.

5.3 Require PKCE, allow both methods

op.authz.allowedPKCE=plain,S256
op.authz.requiredPKCE=plain,S256

Clients must use PKCE, and either plain or S256 is accepted.

6. Recommended policy

For new deployments, the recommended policy is to require PKCE with S256 only:

op.authz.allowedPKCE=S256
op.authz.requiredPKCE=S256

This gives the strongest and simplest PKCE policy:

• Clients must use PKCE.
• Only the S256 method is accepted.
• The weaker plain method is not accepted.
• Client metadata cannot accidentally require a globally prohibited method.