Skip to content

FerrisKey ​

FerrisKey is an open-source identity and access management server, with realms, clients, users, roles and standard OpenID Connect flows. Your AdonisJS API can verify the tokens it issues in JWKS mode, without sharing any secret.

This guide was tested end to end against FerrisKey v0.10.2, with tokens issued by the client_credentials grant.

Find the endpoints ​

Each realm publishes its discovery document at https://<ferriskey-host>/api/realms/<realm>/.well-known/openid-configuration. The two values the guard needs are:

Discovery fieldExampleGuard option
issuerhttps://auth.example.com/api/realms/my-realmissuer
jwks_urihttps://auth.example.com/api/realms/my-realm/protocol/openid-connect/jwks.jsonjwks.jwksUri

FerrisKey signs tokens with RS256.

The examples use the /api root path of the FerrisKey Helm chart. Without a root path (SERVER_ROOT_PATH), for example with the docker-compose.yaml of the FerrisKey repository, the URLs start at /realms/<realm>. Copy issuer and jwks_uri from your discovery document rather than building them by hand.

Create a client ​

In the FerrisKey console, open your realm and create a client:

  • Client ID: the identifier of your API, for example my-api;
  • Client authentication: Confidential, required for the client_credentials grant. It can't be changed afterwards;
  • Direct access grants and Device authorization grant: disabled, unless you need them.

Then enable the service account of the client, and copy the client secret from its Credentials tab. The service account is the user the client_credentials tokens are issued for.

Add an audience ​

By default, FerrisKey puts generic values in the aud claim, for example ["my-realm-realm", "account"], and the client that requested the token in azp. Every token of the realm carries these values: with audience: 'account', your API would accept tokens issued for any other client of the realm.

Add an audience mapper so tokens carry an audience specific to your API:

  1. In Client Scopes, create a client scope in the realm of your client, for example my-api-audience.
  2. In its Protocol Mappers tab, add a mapper of type Audience (oidc-audience-mapper):
    • Client audience: my-api, or leave it empty and set a Custom audience;
    • Add to access token: enabled.
  3. In Clients, open your client, and in its Client Scopes tab, assign the scope as default, so it's included without being requested. The scope itself can stay optional at the realm level: the assignment to the client decides.
  4. Check the result in the Evaluate tab of the client, or request a new token.

New tokens now contain your audience:

json
{
  "iss": "https://auth.example.com/api/realms/my-realm",
  "aud": ["my-realm-realm", "account", "my-api"],
  "azp": "my-api",
  "sub": "01a126dd-bb20-70c2-b722-2a64312f84f2",
  "scope": "openid email my-api-audience organization profile roles"
}

TIP

Make sure you're in the right realm in the console: a client scope created in master is not available to the clients of another realm.

Without an audience mapper, you can instead check the client that requested the token, in azp, with verifyPayload in place of audience. This was tested against FerrisKey too, but the audience mapper is the standard way.

The resource parameter ​

Since v0.10, FerrisKey also accepts the resource parameter (RFC 8707) on the client_credentials and password grants. List your API in the allowed_resources of the realm settings, then request a token with -d resource=https://api.example.com: the token's aud is exactly ["https://api.example.com"], and set audience: 'https://api.example.com' in the guard. A resource that isn't allowed is refused with invalid_target.

allowed_resources applies to the whole realm: every client of the realm can request a token for your API. With the audience mapper, only the clients the scope is assigned to get your audience. If you use resource, also check azp with verifyPayload to restrict which clients may call your API.

Configure the guard ​

ts
// config/auth.ts
import { defineConfig } from '@adonisjs/auth'
import { jwtGuard } from '@maximemrf/adonisjs-jwt'
import { FerrisKeyUserProvider } from '../app/auth/ferriskey_user_provider.js'

const FERRISKEY_REALM = 'https://auth.example.com/api/realms/my-realm'

const authConfig = defineConfig({
  default: 'jwt',
  guards: {
    jwt: jwtGuard({
      provider: new FerrisKeyUserProvider(),
      jwks: {
        jwksUri: `${FERRISKEY_REALM}/protocol/openid-connect/jwks.json`,
      },
      issuer: FERRISKEY_REALM,
      audience: 'my-api',
      algorithms: ['RS256'],
      getUserId: (payload) => payload.sub,
    }),
  },
})

export default authConfig

FerrisKeyUserProvider is your own user provider. Its findById receives the sub claim, the id of the FerrisKey user or service account. When the users only live in FerrisKey, it can accept every verified token:

ts
// app/auth/ferriskey_user_provider.ts
import { symbols } from '@adonisjs/auth'
import type { JwtGuardUser, JwtUserProviderContract } from '@maximemrf/adonisjs-jwt/types'

export type FerrisKeyUser = { id: string }

export class FerrisKeyUserProvider implements JwtUserProviderContract<FerrisKeyUser> {
  declare [symbols.PROVIDER_REAL_USER]: FerrisKeyUser

  async createUserForGuard(user: FerrisKeyUser): Promise<JwtGuardUser<FerrisKeyUser>> {
    return { getId: () => user.id, getOriginal: () => user }
  }

  async findById(id: string | number | BigInt): Promise<JwtGuardUser<FerrisKeyUser> | null> {
    return this.createUserForGuard({ id: String(id) })
  }
}

To attach your own data to FerrisKey users, store the FerrisKey id in a column of your model and look the user up by this column in findById, returning null for unknown ids.

Call the API ​

Request a token with the client_credentials grant, then send it as a bearer token:

sh
TOKEN=$(curl -s -X POST \
  https://auth.example.com/api/realms/my-realm/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=my-api \
  -d client_secret=<client-secret> | jq -r .access_token)

curl http://localhost:3333/me -H "Authorization: Bearer $TOKEN"
ts
router
  .get('me', async ({ auth }) => {
    return { id: auth.getUserOrFail().id }
  })
  .use(middleware.auth({ guards: ['jwt'] }))

Tokens issued to users, for example by a frontend using the authorization code flow, are verified the same way, as long as they carry your audience.

Token lifetime and revocation ​

FerrisKey access tokens expire after 5 minutes by default (access_token_lifetime_secs on the realm, overridable per client). Clients request a new token when it expires, the guard never issues FerrisKey tokens itself.

Tokens are verified offline against the JWKS: a token stays valid until its exp, even if the user or the client is disabled in FerrisKey in the meantime. Keep the lifetime short. If you need immediate revocation, call the FerrisKey introspection endpoint (/protocol/openid-connect/token/introspect) from your user provider.

Released under the MIT License.