fastify-keycloak-adapter
is a keycloak adapter for a Fastify app.
https://www.npmjs.com/package/fastify-keycloak-adapter
npm i fastify-keycloak-adapter
yarn add fastify-keycloak-adapter
- Fastify 4 ->
npm i fastify-keycloak-adapter
- Fastify 3 ->
npm i fastify-keycloak-adapter@0.6.3
(deprecated)
import fastify from 'fastify'
import keycloak, { KeycloakOptions } from 'fastify-keycloak-adapter'
const server = fastify()
const opts: KeycloakOptions = {
appOrigin: 'http://localhost:8888',
keycloakSubdomain: 'keycloak.yourcompany.com/auth/realms/realm01',
clientId: 'client01',
clientSecret: 'client01secret'
}
server.register(keycloak, opts)
-
appOrigin
app url, used for redirect to the app when user login successfully (required) -
keycloakSubdomain
keycloak subdomain, endpoint of a realm resource (required) -
useHttps
set true if keycloak server useshttps
(optional, defaults tofalse
) -
clientId
client id (required) -
clientSecret
client secret (required) -
scope
client scope of keycloak (optional, string[], defaults to['openid']
) -
callback
Relative or absolute URL to receive the response data (optional, defaults to/
) -
retries
The number of times to retry before failing. (optional, number, defaults to 3) -
logoutEndpoint
route path of doing logout (optional, defaults to/logout
) -
excludedPatterns
string array for non-authorized urls (optional, support?
,*
and**
wildcards) -
autoRefreshToken
set true for refreshing token automatically when token has expired (optional, defaults tofalse
) -
disableCookiePlugin
set true if your application register the fastify-cookie plugin itself. Otherwise fastify-cookie will be registered by this plugin, because it's mandatory. (optional, defaults tofalse
) -
disableSessionPlugin
set true if your application register the fastify-session plugin itself. Otherwise fastify-session will be registered by this plugin, because it's mandatory. (optional, defaults tofalse
) -
userPayloadMapper(userPayload)
defined the fields offastify.session.user
(optional) -
unauthorizedHandler(request, reply)
is a function to customize the handling (e.g. the response) of unauthorized requests (optional) -
bypassFn(request)
is a function that returns true if you want to stop the normal authentication workflow and allow the request. It will preventuserPayloadMapper
from being called andfastify.session.user
from being generated. -
usePostLogoutRedirect
set true to enable compatibility with Keycloak versions 18.0.0 and later, wherepost_logout_redirect_uri
andid_token_hint
are used instead ofredirect_uri
during logout. When set to false, the plugin will default to using the oldredirect_uri
for backward compatibility. (optional, defaults tofalse
)
import keycloak, { KeycloakOptions, UserInfo } from 'fastify-keycloak-adapter'
import fastify, { FastifyInstance } from 'fastify'
const server: FastifyInstance = fastify()
const opts: KeycloakOptions = {
appOrigin: 'http://localhost:8888',
keycloakSubdomain: 'keycloak.mycompany.com/auth/realms/myrealm',
useHttps: false,
usePostLogoutRedirect: false,
clientId: 'myclient01',
clientSecret: 'myClientSecret',
logoutEndpoint: '/logout',
excludedPatterns: ['/metrics', '/manifest.json', '/api/todos/**'],
callback: '/hello'
}
server.register(keycloak, opts)
defined the fields of fastify.session.user
, use the payload from JWT token
use DefaultToken
in default case
or you should define the type by yourself, in case the keycloak server has custom payload
import { KeycloakOptions, DefaultToken } from 'fastify-keycloak-adapter'
const userPayloadMapper = (tokenPayload: unknown) => ({
account: (tokenPayload as DefaultToken).preferred_username,
name: (tokenPayload as DefaultToken).name
})
const opts: KeycloakOptions = {
// ...
userPayloadMapper: userPayloadMapper
}
Provides a custom handler for unauthorized requests.
import { FastifyReply, FastifyRequest } from 'fastify'
import { KeycloakOptions } from 'fastify-keycloak-adapter'
const unauthorizedHandler = (request: FastifyRequest, reply: FastifyReply) => {
reply.status(401).send(`Invalid request`)
}
const opts: KeycloakOptions = {
// ...
unauthorizedHandler: unauthorizedHandler
}
Provides a function that returns true if you want to stop the normal authentication workflow and allow the request.
import { FastifyReply, FastifyRequest } from 'fastify'
import { KeycloakOptions } from 'fastify-keycloak-adapter'
const bypassFn = (request: FastifyRequest) => {
return Math.random() * 6 < 1 // russian roulette of security DO NOT USE IT !
}
const opts: KeycloakOptions = {
// ...
bypassFn: bypassFn
}
Use the options to disable the cookie and session plugin registration, in case you want to initialize the plugins yourself, to provide your own set of configurations for these plugins.
import fastify from 'fastify'
import fastifyCookie from '@fastify/cookie'
import session from '@fastify/session'
import keycloak, { KeycloakOptions } from 'fastify-keycloak-adapter'
const server = fastify()
server.register(fastifyCookie)
server.register(session, {
secret: '<SOME_SECRET>',
cookie: {
secure: false
}
})
const opts: KeycloakOptions = {
// ...
disableCookiePlugin: true,
disableSessionPlugin: true
}
server.register(keycloak, opts)
use request.session.user
server.get('/users/me', async (request, reply) => {
const user = request.session.user
return reply.status(200).send({ user })
})
in some case, you may want to handle the id_token (or access_token, refresh_token) by yourself
use request,session.grant
can get the GrantResponse object
const id_token = request.session.grant.response?.id_token
console.log('id_token', id_token)
const access_token = request.session.grant.response?.access_token
console.log('access_token', access_token)
const refresh_token = request.session.grant.response?.refresh_token
console.log('refresh_token', refresh_token)