Dispensing tokens via OAuthV2 with PKCE (RFC 7636)  

Let's talk about OAuth, shall we?

Authorization Code grants

The authorization code grant, as described in the OAuth V2 spec (RFC 6749), is intended for use with 3rd-party client apps. "3rd party" means, an app that is not written by the same party that produces the API. The app is therefore not implicitly trusted, and OAuth says that a user should grant consent to the app, to allow it interact with the APIs on behalf of the user. This consent is embodied in the access token issued to the app, via the authorization code grant.

With the authorization code grant, both the user and the app credentials must be verified before the authorization server issues a token. In the Apigee Edge model, an external Identity Provider verifies the user credentials, and Apigee Edge itself verifies the application (client) credentials.

Beyond authenticating the user, the authorization grant should also check the user consent. In a typical login-and-consent user experience, the user first authenticates, and then consents to the app (client) receiving a token with the stated scopes. Some login-and-consent experiences may collapse those two steps into one interaction). Login-and-consent is almost always performed via a trusted user agent, in other words the web browser builtin to the client platform. In some cases a different interaction model can be used to grant consent, like an SMS exchange. Eg, "Do you consent to App X obtaining scope Y? Reply YES to allow this."

After consent, login-and-consent returns the code to the client (app) via a 302 redirect, sent to the redirect address registered for that client. The client POSTs that code to the /token endpoint to receive an access token.

PKCE

All of that is just standard authorization code grant. aka "The 3-legged OAuth dance." Proof Key for Code Exchange, also known as PKCE (RFC 7636) extends that basic model to add a code challenge and code verifier to the protocol, in this way:

In the GET /authorize call, the client passes the CHALLENGE.

When exchanging the code for a token (POST /token), the client passes the VERIFIER.

The Authorization server (Apigee Edge in this case) is responsible for retaining the challenge, and during exchange-code-for-token, checking that the verifier matches the challenge. The idea is to eliminate the possibility for a malefactor to intercept the code, and then be able to obtain a bonafide token with it. You can look at the write-up by Okta for a more detailed description of the motivation for PKCE.

Can Apigee Edge be used for PKCE grants?

PKCE is on the standards track from IETF. It's an open protocol at this point. Can Apigee Edge dispense tokens using the PKCE extension to OAuth2 3-legged grants?

YES. Out of the box, the OAuthV2 policy (and the GenerateAccessToken Operation) does not include support for PKCE. But, it's really straightforward to add this into your own token dispensing proxy, if you want it.

The way to do it:

1. in the handler for the GET /authorize call, Apigee Edge creates a session which stores the CHALLENGE
2. In the handler for the POST /token call, Apigee Edge checks the VERIFIER against the CHALLENGE.

It's that simple.

OK, it's not absolutely simple, because OAuthV2 authorization code grants are not simple. There are numerous interactions to handle and you need to consider all of them in the design of the token dispensing proxy. But Apigee Edge handles those grants quite easily. Adding PKCE to the mix requires a very simple enhancement to the normal token dispensing proxy that uses authorization code grant.

AND, the good news is that I have put together s a screencast showing how PKCE works in Apigee Edge:

And here is a repo that contains all the proxy configuration, as well as some tools, so you can use the same thing in your own Apigee Edge organization.

https://github.com/DinoChiesa/Edge-OAuthV2-PKCE-Proxy

I'd love to hear your comments on this.