fastify-keycloak-adapter

KO | EN

gitlite — search

#python #hacktoberfest #go #android #machine-learning #deep-learning #linux #nodejs #macos #java #windows #mcp #openai #open-source

fastify-keycloak-adapter

(★ 25)

a Fastify plugin for Keycloak

fastify-keycloak-adapter Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Fastify-Keycloak-Adapter

[![Node.js CI](https://github.com/yubinTW/fastify-keycloak-adapter/actions/workflows/node.js.yml/badge.svg)](https://github.com/yubinTW/fastify-keycloak-adapter/actions/workflows/node.js.yml)
[![NPM version](https://img.shields.io/npm/v/fastify-keycloak-adapter.svg?style=flat)](https://www.npmjs.com/package/fastify-keycloak-adapter)

`fastify-keycloak-adapter` is a keycloak adapter for a Fastify app.

## Install

<https://www.npmjs.com/package/fastify-keycloak-adapter>

```bash
npm i fastify-keycloak-adapter
```

```bash
yarn add fastify-keycloak-adapter
```

## Fastify Version

- Fastify 5 -> `npm i fastify-keycloak-adapter`
- Fastify 4 -> `npm i fastify-keycloak-adapter@2.3.3`
- Fastify 3 -> `npm i fastify-keycloak-adapter@0.6.3` (deprecated)

## Usage

```typescript
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)
```

## Configuration

- `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 uses `https` (optional, defaults to `false`)

- `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 to `false`)

- `disableCookiePlugin` set true if your application register the [fastify-cookie](https://github.com/fastify/fastify-cookie) plugin itself. Otherwise **fastify-cookie** will be registered by this plugin, because it's mandatory. (optional, defaults to `false`)

- `disableSessionPlugin` set true if your application register the [fastify-session](https://github.com/fastify/fastify-session) plugin itself. Otherwise **fastify-session** will be registered by this plugin, because it's mandatory. (optional, defaults to `false`)

- `userPayloadMapper(userPayload)` defined the fields of `fastify.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 prevent `userPayloadMapper` from being called and `fastify.session.user` from being generated.

- `usePostLogoutRedirect` set true to enable compatibility with Keycloak versions 18.0.0 and later, where `post_logout_redirect_uri` and `id_token_hint` are used instead of `redirect_uri` during logout. When set to false, the plugin will default to using the old `redirect_uri` for backward compatibility. (optional, defaults to `false`)

## Configuration example

```typescript
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)
```

## Set userPayloadMapper

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

```typescript
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
}
```

## Set unauthorizedHandler

Provides a custom handler for unauthorized requests.

```typescript
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
}
```

## Set bypassFn

Provides a function that returns true if you want to stop the normal authentication workflow and allow the request.

```typescript
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
}
```

## Disable mandatory plugin registration

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.

```typescript
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)
```

## Get login user

use `request.session.user`

```typescript
server.get('/users/me', async (request, reply) => {
  const user = request.session.user
  return reply.status(200).send({ user })
})
```

## Get OpenID Connect (OIDC) tokens

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](https://github.com/simov/grant/blob/5f60a595161aa96cd110192bc810eb8fa478da21/grant.d.ts#L318) object

```typescript
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)
```

## License

[MIT License](LICENSE)

fastify-keycloak-adapter

fastify-keycloak-adapter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

fastify-keycloak-adapter

fastify-keycloak-adapter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README