tsoa-oauth-express

This library enables easy implementation of OAuth2 authentication for tsoa on express. To use this library first add it as an npm dependency to your existing tsoa application.

npm i @digicatapult/tsoa-oauth-express

Your authentication file (see tsoa's documentation on authentication setup here) will then need to contain something like:

import type express from 'express'
import type * as jwt from 'jsonwebtoken'

import mkExpressAuthentication, { AuthOptions } from '@digicatapult/tsoa-oauth-express'

// module options
const options: AuthOptions = {
  ...
}

export const expressAuthentication = mkExpressAuthentication(options)

where the options value is an object with the following type and properties:

interface AuthOptions {
  securityName?: string
  verifyOptions?: jwt.VerifyOptions & { complete?: false }
  jwksUri: () => Promise<string>
  getAccessToken: (req: express.Request) => Promise<string | undefined>
  getScopesFromToken: (decoded: string | jwt.JwtPayload) => Promise<string[]>
  tryRefreshTokens: (req: express.Request) => Promise<boolean>
}

| property | required | description | | ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | jwksUri | true | Resolves to the uri for your identity providers jwks configuration | | getAccessToken | true | Resolves a JWT from the Request. For example this may come from an authorization header or a cookie based on requirements | | getScopesFromToken | true | Resolves to an array of OAuth scopes that the provided token supports | | securityName | false | OpenAPI Security scheme name to be secured | | verifyOptions | false | jsonwebtoken verification options. See the jsonwebtoken documentation for details | | tryRefreshTokens | false | Performs a token refresh. Resolves to true if the refressh succeeded otherwise false. By default this always resolves to false |

Example

An example implementation of using the OAuth client-credential flow to authenticate a machine-to-machine (m2m) API is included in the package repository. This consists of two parts, a pre-configured Keycloak instance which can be instantiated with docker compose to act as our identity provider and an example application under ./example which implements to tsoa server. For further information please see the tsoa authentication documentation and our authentication handler example at ./example/authentication.ts.

To get started first bring up the Keycloak instance by executing from the repository root:

docker compose up -d

This will automatically pre-configure a client called example with client secret example. We can then fetch a m2m token by executing:

curl --request POST \
  --url 'http://localhost:3080/realms/example/protocol/openid-connect/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=example \
  --data client_secret=example

This will return a JSON object with a JWT auth token in the access_token property that takes the form like eyJhbGci...r8TIOfRQ.

The example server can then be run with:

npm run example

This server listens on port 3000 and exposes two routes /authenticated and /unauthenticated where only the first route requires an auth token. So we can for example call

curl http://localhost:3000/unauthenticated

which should return something like

{ "message": "This route is unauthenticated", "authenticated": false }

But calling the authenticated route (curl http://localhost:3000/authenticated) in the same was will return an error

{ "message": "unauthenticated" }

Providing the JWT auth token as part of an authentication header:

curl http://localhost:3000/authenticated --header 'authorization: bearer eyJhbGci...r8TIOfRQ'

causes the call to succeed:

{ "message": "This route is authenticated", "authenticated": true }