Keycloak

A Keycloak authentication plugin for Vendure.

It adds Keycloak OAuth 2.0 / OpenID Connect sign-in to both the Admin API (back-office users) and the Shop API (storefront customers), links Keycloak identities to Vendure Users by email, and ships a dashboard extension with a “Login with Keycloak” button, an OAuth callback page and identity-management blocks on the Administrator and Customer detail pages.

Installation

npm install @datasolution/vendure-plugin-keycloak

Peer dependencies

The plugin declares the following peerDependencies, which must be present on your Vendure project:

jose is used to verify the Keycloak id_token against the realm's JWKS. It is not a Vendure dependency, so install it on the host project:

npm install jose@^6.1.3

Without jose, token verification throws at authentication time.

Usage

1. Register the plugin

Add KeycloakPlugin to the plugins array of your Vendure config:

import { VendureConfig } from '@vendure/core';import { KeycloakPlugin } from '@datasolution/vendure-plugin-keycloak';export const config: VendureConfig = {  // ...  plugins: [    KeycloakPlugin.init({      serverUrl: 'https://keycloak.example.com',      realm: 'my-realm',      adminClient: {        clientId: 'vendure-admin',        clientSecret: process.env.KEYCLOAK_ADMIN_SECRET!,        redirectUri: 'https://shop.example.com/dashboard/keycloak-callback'      }      // shopClient is optional — see below    })  ]};

The plugin appends its strategies to authOptions.shopAuthenticationStrategy and authOptions.adminAuthenticationStrategy rather than replacing them, so Vendure's native email/password login keeps working alongside Keycloak.

2. Configure the Keycloak realm

For each client (admin and, if separate, shop) you need a confidential client in the realm — the plugin performs a server-side authorization_code exchange with client_secret:

• Client authentication: on (confidential client, a secret is required).
• Standard flow: enabled.
• Valid redirect URIs: must contain the exact URIs your front-ends use. For the Vendure dashboard that is https://<your-host>/dashboard/keycloak-callback (the dashboard builds this from window.location.origin); for the storefront it is whichever URI you pass to the Shop keycloakAuthConfig query.
• Scopes: the plugin requests openid email profile. The realm must return an id_token with an email claim — authentication is rejected without it.

3. The dashboard UI

There is nothing extra to set up for the dashboard. The plugin ships a dashboard extension declared through its dashboard slot, and the Vendure dashboard Vite plugin discovers it automatically — simply registering KeycloakPlugin.init({...}) in vendure-config.ts (step 1) is enough.

Rebuild the dashboard and you get:

• a Login with Keycloak button under the standard login form;
• a /keycloak-callback route (unauthenticated) that completes the flow;
• a Keycloak Authentication card on the Administrator detail page and on the Customer detail page, listing linked identities with an unlink action.

Bundled translations: en, fr, de.

The UI honours Vendure permissions: the Administrator block requires ReadAdministrator + UpdateAdministrator, the Customer block requires ReadCustomer + UpdateCustomer, and the Admin API is independently guarded.

4. Database migration

None required. The plugin adds no entities and no custom fields — links are stored in Vendure's built-in ExternalAuthenticationMethod table.

Configuration

init() takes a KeycloakPluginOptions object. serverUrl, realm and adminClient are required; everything else has a default.

Top-level options

KeycloakClientConfig

Full example:

KeycloakPlugin.init({  serverUrl: 'https://keycloak.example.com',  realm: 'my-realm',  // back-office users  adminClient: {    clientId: 'vendure-admin',    clientSecret: process.env.KEYCLOAK_ADMIN_SECRET!,    redirectUri: 'https://shop.example.com/dashboard/keycloak-callback'  },  // storefront customers (optional — defaults to adminClient)  shopClient: {    clientId: 'vendure-shop',    clientSecret: process.env.KEYCLOAK_SHOP_SECRET!,    redirectUri: 'https://www.example.com/auth/callback'  },  // require customers to exist in Vendure before they can log in  autoRegisterShopCustomers: false});

How authentication works

Both strategies implement Vendure's AuthenticationStrategy and follow the same five steps; they differ only in who is allowed in (see step 4).

Step by step, server side:

1. Code exchange — POST {realm}/protocol/openid-connect/token with grant_type=authorization_code, the client credentials and the redirect URI. The redirect URI sent here must be byte-identical to the one used in step 2.
2. Token verification — the id_token is verified with jose against the realm JWKS (/protocol/openid-connect/certs), checking issuer (the realm URL) and audience (the client ID). The JWKS keyset is fetched lazily and cached for the process lifetime. No userinfo round-trip is needed. Authentication is rejected if Keycloak returns no id_token (missing openid scope) or if the token carries no email claim.
3. Already linked? — the sub claim is looked up in ExternalAuthenticationMethod for this strategy. On a hit, that User is returned immediately.
4. Otherwise, match by email (lower-cased, soft-deleted records excluded):
   • Admin API — the email must match an existing Administrator. Pre-registration is mandatory: an unknown email is refused with No administrator found with email: …. Keycloak never creates administrators, so realm membership alone grants no back-office access.
   • Shop API — the email is matched against Customer. If none matches, the behaviour depends on autoRegisterShopCustomers: true (default) creates a verified Customer + User from the given_name / family_name claims; false refuses with No customer found with email: ….
5. Link — an ExternalAuthenticationMethod row is written with the strategy name, externalIdentifier = the Keycloak sub, and metadata.clientID = the client used. Subsequent logins short-circuit at step 3.

Any thrown error is logged under the KeycloakPlugin logger context and surfaced to the caller as an InvalidCredentialsError message.

Strategy names

The strategy name is the key you pass inside the authenticate mutation input:

On the Admin API redirectUri is optional and falls back to adminClient.redirectUri. On the Shop API it is required: the storefront chooses its own redirect URI at runtime, so it must send back the exact value it used.

Shop API

Get the authorization URL

query {  keycloakAuthConfig(redirectUri: "https://www.example.com/auth/callback") {    authorizationUrl  }}

The returned URL already carries client_id, redirect_uri, response_type=code and scope=openid email profile. Append your own state parameter before redirecting, and verify it on the way back.

Complete the login

mutation {  authenticate(    input: {      keycloak_shop: { code: "<code from the redirect>", redirectUri: "https://www.example.com/auth/callback" }    }  ) {    ... on CurrentUser {      id      identifier    }    ... on InvalidCredentialsError {      errorCode      message    }  }}

A minimal storefront callback handler:

const { data } = await shopApi.query(GET_KEYCLOAK_AUTH_CONFIG, {  redirectUri: `${window.location.origin}/auth/callback`});sessionStorage.setItem('kc_state', state);window.location.href = `${data.keycloakAuthConfig.authorizationUrl}&state=${state}`;// …on /auth/callbackconst code = new URLSearchParams(location.search).get('code')!;await shopApi.mutate(AUTHENTICATE, {  input: { keycloak_shop: { code, redirectUri: `${window.location.origin}/auth/callback` } }});

Admin API

Authentication

query {  keycloakAuthConfig {    authorizationUrl  }}

No argument here — the Admin flow uses the server-configured adminClient.redirectUri. Authentication then goes through authenticate(input: { keycloak_admin: { code, redirectUri } }).

The bundled dashboard extension already implements this end to end (login button → /dashboard/keycloak-callback → authenticate), including a state value stored in sessionStorage for CSRF protection.

Managing linked identities

Each entry exposes externalIdentifier (the Keycloak sub) and clientID (the OAuth client that performed the link, from the record's metadata).

query {  keycloakExternalAuthMethods(administratorId: "42") {    externalIdentifier    clientID  }}

Unlinking only removes the ExternalAuthenticationMethod row — the Vendure Administrator / Customer and the Keycloak account are both left untouched. The next Keycloak login re-links by email (subject to the step 4 rules above), so unlinking is a re-binding tool, not a way to revoke access; to revoke, delete or disable the Vendure user or the Keycloak account.

Programmatic access

The package root exports the plugin and its types:

import {  KeycloakPlugin,  KeycloakPluginOptions,  KeycloakClientConfig,  KeycloakShopAuthData,  KeycloakAdminAuthData,  KeycloakTokenResponse,  KeycloakUserInfo} from '@datasolution/vendure-plugin-keycloak';

KeycloakService (OIDC endpoints, authorization URL, code exchange, token verification) and KeycloakAdmin (read/delete external auth methods) are exported from the plugin's Nest module, so they can be injected into your own providers. They are not re-exported from the package root — import them from their module path:

import { KeycloakService } from '@datasolution/vendure-plugin-keycloak/lib/src/services/keycloak-service';

Security notes

• Confidential clients only. The code→token exchange sends client_secret; it happens server-side in Vendure, and the secret never reaches a browser. Keep it in an environment variable.
• Administrators are never auto-created. Being a member of the realm is not enough to reach the back office — an Administrator with a matching email must already exist, with its roles and permissions assigned in Vendure.
• Email is the join key. A Keycloak account whose email matches an existing administrator or customer will be linked to it on first login. Only enable realms where email addresses are verified and controlled by your IdP.
• state is enforced by the caller. The plugin returns a bare authorization URL; the shipped dashboard adds a random state and validates it on callback. If you build your own storefront flow, do the same.
• Auto-registered customers are marked verified, since the identity comes from the IdP. Set autoRegisterShopCustomers: false if you would rather gate storefront access on pre-existing customer records.

Compatibility

License

MIT

Contributing

Source code and contribution guidelines live at gitlab.datasolution.fr/datasolution/vendure/plugins/keycloak. See DEVELOPMENT.md for the contributor workflow, including the per-developer “dev mode” that syncs this plugin's src/ into a host Vendure project.