Javascript SPA using Code Flow + PKCE

Javascript SPA using Code Flow + PKCE

Code Examples / spa-integration

Overview

This tutorial provides a small code sample to demonstrate the behavior of an OpenID Connect SPA login using Authorization Code Flow with PKCE, as recommended in OAuth 2.0 for Browser Based Apps.

Best Practice Update

For best results and strongest security it is no longer recommended to implement OAuth for SPAs solely in Javascript. See our resources on the Token Handler Pattern, for using only the latest secure cookies in the browser without losing any of the benefits of an SPA architecture.

Configure the Identity Server

In the Identity Server, create an OAuth Client and assign properties as follows. Change values to suit your environment if required.

  • Client ID: public_test_client
  • Capabilities: Code Flow
  • Redirect URI: http://localhost:8080/
  • Scope: openid

Also select an Authentication Method of No Authentication option when prompted, since SPAs are public clients and do not send secrets to identify themselves.

Configure the SPA

Download the code example from the GitHub repository link, then configure properties in the index.html file, to point to your installation of the Identity Server:

  • Client ID: public_test_client
  • Authorize Endpoint: https://localhost:8443/oauth/v2/oauth-authorize
  • Token Endpoint: https://localhost:8443/oauth/v2/oauth-token

Run the SPA

The Demo SPA can be run with the command npx http-server -p 8080. It has a trivial UI just to allow an authentication flow to be triggered. This causes a full browser redirect to the Identity Server where the user signs in, perhaps via an HTML Form authenticator:

Full Screen Sign In

Once complete, the UI swaps the authentication result for tokens and displays the access token that would be sent to an API:

Signed in SPA

Understand Code Flow + PKCE

The authentication workflow for an SPA login consists of two main steps as summarized below. Proof Key for Code Exchange (PKCE) is used to prove that these two messages are part of the same flow.

StepDescription
Authorization RedirectThe user’s browser is redirected to the Authorization Endpoint of the Identity Server. The message parameters identify the SPA and the user is then prompted to authenticate. Once complete a login result in the form of an Authorization Code is returned to the application.
Authorization Code GrantThe browser then sends an HTTPS POST body to the Token Endpoint of the Identity Server, and sends the authorization code. This results ion the code being swapped for OAuth tokens, after which the SPA would typically call the API with an access token.

Viewing Messages

You can use your browser’s developer tools to see the messages being sent to the Identity Server. The Authorization Redirect sends a code_challenge field generated from a secret calculated in Javascript code:

HTTP GET https://localhost:8443/oauth/v2/authorize/
?response_type=code
&client_id=public-test-client
&code_challenge_method=S256
&code_challenge=c2x9RGpVeF9GdIJ6AgIHnYzyl7gXPatBNtUT43BCLrQ
&redirect_uri=http://localhost:8080/

The Authorization Code Grant message then sends the Authorization Code along with a code_verifier that is generated from the same runtime secret. The Identity Server then verifies that the code_challenge and code_verifier values match:

HTTP POST https://localhost:8443/oauth/v2/token

grant_type=authorization_code&
client_id=public-test-client&
code: XIHUN0xFEXZkCewgH1k5ZLl7mXPT2Tjy&
code_verifier: hLzkNM0LlyQkSCXYlt9qI7dVeRxTjFcobLUyyaF6PncrvpgtmZt14Eif9ID6Hm0e&
redirect_uri: http://localhost:8080/

Conclusion

The Authorization Code Flow with PKCE is designed to work for web and mobile clients and is straightforward to implement in Javascript code.

Keep up with our latest articles and how-tos RSS feeds.