Docs: example of using returned Access Tokens in middleware?

[bessey]

(Hello, me again 😅)

I'm getting a bit stuck rolling out an OAuth2 implementation built upon this library. On the OAuth2 flows side of things, all is well mostly thanks to cribbing bits I didn't understand from the docs from the example/ directory.

However, not present in the example is the recommended way to use the generated Access Tokens to actually authorise requests to other private endpoints.

Without this, I have these assumptions / questions:

• I guess I should be using JwtService to verify the JWT and decode its contents? But that's stateless so the token could have been revoked...
• So I guess I should also be calling OAuthTokenRepository.getByAccessToken to confirm the token is not revoked?
• I was kind of expecting the library to expose a convenient API to do a lot of this for me, e.g. authorizationServer.verifyToken(accessToken: string): Promise<OAuthToken>, but it seems this is up to the User?. I've provided AuthorizationServer all these repositories and a custom JWT service, why do I have to string them back together on the middleware side of things?

[jasonraimondi]

Hey @bessey, happy to help no problem at all! You've actually got the right approach with your assumptions. Here are a couple of ways to handle this:

Option 1: JWT + Repository Check

This is exactly what you described and it's solid:

async function validateToken(accessToken: string) {
  // Verify JWT signature and decode
  const decoded = await jwtService.verify(accessToken);
  
  // Check if token exists and isn't revoked
  const storedToken = await accessTokenRepository.getByAccessToken(accessToken);
  
  return storedToken && !isExpired(storedToken) ? { valid: true, decoded, storedToken } : { valid: false };
}

Option 2: Use the Introspection Endpoint

The library does provide an /introspect endpoint (RFC 7662) that handles all this for you! You could either:

• Expose it and call it from your middleware
• Or use the same logic internally by calling authorizationServer.introspect() directly

async function validateToken(accessToken: string) {
  // Create a mock request object for introspection
  const mockRequest = {
    body: {
      token: accessToken,
      token_type_hint: 'access_token'
    },
    headers: {
      'content-type': 'application/x-www-form-urlencoded',
      // Add client auth if needed based on your config
    }
  };
  
  try {
    const response = await authorizationServer.introspect(mockRequest);
    const result = JSON.parse(response.body);
    return { valid: result.active, ...result };
  } catch (error) {
    return { valid: false };
  }
}

The reason there's no built-in verifyToken() method is that the OAuth 2.0 spec intentionally leaves token validation up to individual implementations - different apps have different needs for scope checking, audience validation, etc.

Your instinct about needing both JWT verification AND repository checking is spot on - the JWT handles signature/tampering, while the repository check handles revocation. You're definitely on the right track!

[bessey]

Thanks for confirming I'm on the right path @jasonraimondi. Having an example of option 1 would have been handy. Option 2 feels a bit backhanded faking web requests within the server, although involves the simplest setup I suppose.

Though I think the example is a little off, because getByAccessToken expects the token inside the token (the jti claim). Or perhaps thats an implementation detail from my repos? I don't think so though, I am not explicitly setting or extracting from the jti claim

async function validateToken(accessToken: string) {
  // Verify JWT signature and decode
  const decoded = await jwtService.verify(accessToken);
  
  // Check if token exists and isn't revoked
  const storedToken = await accessTokenRepository.getByAccessToken(decoded.accessToken);
  
  return storedToken && !isExpired(storedToken) ? { valid: true, decoded, storedToken } : { valid: false };
}

[jasonraimondi]

You're absolutely right! Good catch. Yes, getByAccessToken() expects the jti claim from the decoded token, not the raw access token.

Here's the corrected Option 1:

async function validateToken(accessToken: string) {
  // Verify JWT signature and decode
  const decoded = await jwtService.verify(accessToken);
  
  // Check if token exists and isn't revoked using the jti claim
  const storedToken = await accessTokenRepository.getByAccessToken(decoded.jti);
  
  return storedToken && !isExpired(storedToken) ? { valid: true, decoded, storedToken } : { valid: false };
}

This is how the library works internally - the jti claim contains the unique access token ID used for repository lookups. When a token is issued, accessToken.accessToken becomes the jti in the JWT, and when validating, you use that jti to query the repository.

This is definitely not an implementation detail from your repos - it's the library's design. Thanks for the correction!

I added this info to a FAQ, although I imagine there is a better spot..