Require Proof Key for Code Exchange (PKCE)

Introduction

Proof Key for Code Exchange (abbreviated PKCE, pronounced “pixie”) is an extension to the authorization code flow to prevent CSRF and authorization code injection attacks.

Please note The WPO365 | LOGIN plugin implements Microsoft based single sign-on as a hybrid flow. This means it retrieves - in a first step - an ID token and an authorization code from the authorize endpoint whenever the user authenticates successfully. This first step is also referred to as the authorization code flow. Then - in a second step - the plugin requests refresh and access tokens from the token endpoint by exchanging the authorization code it received in the first step.

PKCE was originally designed to protect the authorization code flow in mobile apps, and was later recommended to be used by single-page apps as well. In later years, it was recognized that its ability to prevent authorization code injection makes it useful for every type of OAuth client, even apps running on a web server that use a client secret.

The technique involves the client first creating a secret on each authorization request, and then using that secret again when exchanging the authorization code for an access token. This way if the code is intercepted, it will not be useful since the token request relies on the initial secret.

The full version of this text can be found here: https://www.oauth.com/oauth2-servers/pkce/.

Before you start

• You are an Administrator for your WordPress website.
• You have installed one of the following extensions / bundles:
  • WPO365 | LOGIN+
  • WPO365 | SYNC
  • WPO365 | INTRANET

Enable PKCE protection for your WordPress website

To add PKCE protection you can simply navigate to WP Admin > WPO365 > Integration and check the option to Require Proof Key for Code Exchange (PKCE).

Once enabled the plugin will generate a code verifier with a length of 56 characters randomly. It will then create the code challenge as the SHA256 hash of the code verifier and send it along when requesting an ID token for the current user (and thus forcing the current user to authenticate). The plugin will then cache the code verifier and when the user returns from Microsoft after he / she successfully authenticated the code verifier will be retrieved from cache and stored as a user attribute in WordPress. As soon as an access token is requested for that user the code verifier will be included in the request and this will allow Microsoft to validate the authenticity of the sender and thus the request.

Troubleshooting

The plugin uses WordPress transients (see https://developer.wordpress.org/apis/handbook/transients/ for technical details) to cache unclaimed code verifiers. Some caching solutions for WordPress may not update the transients on each request and you may see errors that the plugin failed to retrieve an access token because the code verifier is missing. If this is the case then it may not be possible to get PKCE protection working as expected.