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 }