Securing OAuth2 with PKCE: A Comprehensive Guide for Spring Boot and Keycloak

OAuth 2.0 has become ubiquitous as the authorization protocol of choice for modern web and mobile applications. According to recent studies, nearly 69% of APIs now use OAuth for access delegation and authorization^1. However, implementing OAuth 2.0 securely is challenging, with 41% of Android apps using OAuth having misconfigurations or vulnerabilities^2.

One of the most secure OAuth flows is the authorization code grant, but even this flow has some weaknesses, especially when used with public clients like single page apps (SPAs) or mobile apps. The PKCE extension was created to address these issues and make the authorization code flow safe for public clients.

In this article, we‘ll take a comprehensive look at PKCE and demonstrate how to use it to secure an OAuth2 login flow with Spring Security and Keycloak. I‘ll share some insights gleaned from my experience as an AI and machine learning expert, including how ML could potentially be used to detect PKCE-based attacks. By the end of this guide, you‘ll have a solid understanding of PKCE and how to leverage it in your own OAuth implementations.

The Case for PKCE

To understand why PKCE is needed, let‘s briefly review the standard OAuth2 authorization code flow. In this flow, the client directs the user to the authorization server to login. After successful authentication, the authorization server issues an authorization code to the client via a redirect URI. The client then sends this code along with its client ID and secret to the token endpoint to exchange it for access and refresh tokens.

The problem arises because the client secret is just that – a secret. It can be easily compromised if it‘s included in a mobile app binary or SPA JavaScript code. If an attacker is able to intercept the authorization code (e.g. through a man-in-the-middle attack), they could use the stolen code and secret to obtain tokens and access the user‘s protected data. In fact, data shows that 29% of web applications have had authorization code interception attacks^3.

The PKCE extension mitigates this attack vector by doing away with the client secret altogether. Instead, the client generates a random string called the code verifier and derives a code challenge from it. The code challenge is sent with the initial authorization request, and the code verifier is sent to the token endpoint to exchange the authorization code for tokens. The authorization server transforms the verifier using the same method to get the challenge and validates that it matches the original challenge.

This means that even if an attacker is able to intercept the authorization code, they would not be able to exchange it for tokens without also knowing the code verifier. The code verifier is never sent over the network in the PKCE flow, making it much harder to steal.

PKCE by the Numbers

To really drive home the importance of PKCE, let‘s look at some relevant statistics:

• 69% of APIs now use OAuth^1
• 41% of Android apps using OAuth have vulnerabilities^2
• 29% of web apps have had auth code interception attacks^3
• Only 19% of mobile apps currently use PKCE^4

These numbers tell a clear story: OAuth is widely used but often implemented insecurely, especially in mobile apps. Authorization code interception is a real threat, but adoption of PKCE to prevent it is still low.

As an AI and ML practitioner, I believe these stats show the need for better tooling and best practices around OAuth security. We could potentially use machine learning models to analyze OAuth implementations and identify misconfigurations or missing security features like PKCE. By flagging these issues early, we could drive wider adoption of secure OAuth extensions and reduce the overall attack surface.

The PKCE Flow in Detail

Now that we‘ve established why PKCE matters, let‘s walk through the flow step-by-step:

1. The client generates a cryptographically random code verifier string
2. The client derives the code challenge from the code verifier using a transform function like SHA256
3. The client directs the user to the authorization server‘s authorization endpoint with the code_challenge, code_challenge_method (e.g. S256), and other standard parameters like response_type=code, client_id, redirect_uri, and scope
4. The authorization server stores the code challenge and redirects the user to login and grant consent
5. After successful authentication and authorization, the authorization server redirects back to the client‘s redirect_uri with an authorization code
6. The client sends the authorization code along with the unhashed code_verifier to the token endpoint
7. The authorization server transforms the code_verifier using the code_challenge_method to get the code challenge, and validates that it matches the original code challenge
8. If the code challenge checks out, the authorization server issues access and refresh tokens to the client

One important detail to call out is the code challenge method. The spec defines two methods: plain and S256. The S256 method is preferred as it provides better security. With S256, the code challenge is derived by hashing the code verifier with SHA256 and then base64url encoding it. Here‘s an example of generating the code challenge in JavaScript using the crypto library:

const verifier = base64url(crypto.randomBytes(32));
const challenge = base64url(await crypto.subtle.digest(‘SHA-256‘, new TextEncoder().encode(verifier)));

The plain method simply uses the code verifier as-is without any transformation. This is much less secure as it would allow an attacker who has stolen the authorization code to simply guess the verifier by enumeration.

Implementing PKCE with Spring Security and Keycloak

Now that we have a good grasp on PKCE theory, let‘s see how to put it into practice using Spring Security and Keycloak. We‘ll use an Angular app as the OAuth client to demonstrate the full end-to-end flow.

Keycloak Setup

First, we need to configure PKCE settings for our client in Keycloak:

1. Open the client settings page and set the Access Type to public
2. Enable Standard Flow Enabled and Direct Access Grants Enabled
3. Set a Valid Redirect URI and Web Origins to allow the Angular app to communicate with Keycloak
4. Under Advanced Settings, set Proof Key for Code Exchange Code Challenge Method to S256

Angular App

On the Angular side, we‘ll use the angular-oauth2-oidc library to handle the OAuth flow. First install the library:

npm install angular-oauth2-oidc

Then configure the OAuth settings in the auth.config.ts file:

import { AuthConfig } from ‘angular-oauth2-oidc‘;

export const authConfig: AuthConfig = {
  issuer: ‘http://localhost:8080/auth/realms/myrealm‘,
  clientId: ‘angular-app‘,
  redirectUri: window.location.origin + ‘/login-callback‘,
  responseType: ‘code‘,
  scope: ‘openid profile email‘,
  showDebugInformation: true,
  requireHttps: false
};

In the root app.component.ts, configure the OAuthService with the auth config:

import { Component } from ‘@angular/core‘;
import { OAuthService } from ‘angular-oauth2-oidc‘;
import { authConfig } from ‘./auth.config‘;

@Component({
  selector: ‘app-root‘,
  templateUrl: ‘./app.component.html‘
})
export class AppComponent {

  constructor(private oauthService: OAuthService) {
    this.oauthService.configure(authConfig);
    this.oauthService.loadDiscoveryDocumentAndTryLogin();
  }

  login() {
    this.oauthService.initCodeFlow();
  }

  logout() {
    this.oauthService.logOut();
  }
}

The initCodeFlow() method kicks off the PKCE authorization code flow by redirecting to Keycloak‘s authorization endpoint with the PKCE code challenge.

Spring Boot Resource Server

Finally, we need to configure the resource server to validate access tokens issued by Keycloak.

Add the following dependencies to the pom.xml:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Configure OAuth settings in application.yml:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/auth/realms/myrealm

And enable JWT authentication in a @Configuration class:

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .anyRequest().authenticated()
                .and()
            .oauth2ResourceServer()
                .jwt();
    }
}

With this setup, Spring Security will authenticate all requests using JWT access tokens issued by Keycloak.

Protecting Against PKCE Attacks with Machine Learning

While PKCE is a huge step forward for OAuth security, it‘s not completely foolproof. A determined attacker could still potentially guess the code verifier through brute force, especially if using a weak PRNG.

One novel idea to harden PKCE implementations is to use machine learning to detect anomalous authorization requests that might indicate an attack. For example, an unsupervised learning model could be trained on normal PKCE exchanges and used to flag outliers like repeated requests with different code verifiers from the same IP.

The model could look at signals like:

• Number of authorization requests over a time window
• Number of unique code verifiers and challenges
• Diversity of User Agent strings
• Geolocation data
• Success ratio of exchanging codes for tokens

By combining these features, it may be possible to proactively detect and block PKCE attacks with a high degree of accuracy. The ML model could be deployed as a microservice that scores incoming requests in real-time and provides a recommended action to the authorization server.

This is just a conceptual example, but I believe it shows the potential for AI and machine learning to significantly enhance OAuth security. As more sophisticated attacks emerge, it will be crucial to evolve our defenses to stay ahead of the curve.

Conclusion and Best Practices

PKCE is a critical extension to the OAuth2 framework that all developers should be leveraging, especially when building mobile or single page apps. By replacing the client secret with a dynamically generated code verifier and challenge, PKCE substantially reduces the risk of authorization code interception and replay attacks.

When implementing PKCE, there are a few best practices to keep in mind:

• Always use the S256 code challenge method instead of plain
• Generate the code verifier using a cryptographically secure PRNG
• Enforce HTTPS for all redirect URIs
• Persist the code challenge and associate it with the authorization request on the server side
• Limit the lifespan of authorization codes to mitigate brute force attacks
• Consider using token binding or mutual TLS for additional security

As an AI practitioner, I‘m excited about the potential for machine learning to further strengthen PKCE and OAuth security in general. By training models to detect anomalous authorization requests, we may be able to proactively prevent advanced attacks that PKCE alone cannot defend against.

Ultimately, PKCE should be seen as one layer in a defense-in-depth approach to securing OAuth. It‘s a critical piece of the puzzle, but not a complete solution on its own. By combining PKCE with other security best practices and carefully validating all inputs on the server side, we can build OAuth implementations that are far more resilient against attack.

I hope this comprehensive guide has deepened your understanding of PKCE and inspired you to adopt it in your own OAuth projects. As always, feel free to reach out with any questions or ideas – I‘m always happy to geek out about auth security!