Skip to content
masterclassBuddyTech Buzz5 fresh blogs · 5:00 AM IST
Start learning

Auth.js · Const

Keycloak

Keycloak is a built-in Auth.js OpenID Connect provider. Add it to the providers list and configure the client ID, secret, and realm-specific issuer.

How it works

Auth.js provides a built-in OpenID Connect integration for Keycloak. Register the provider in your Auth.js configuration, supply its client ID, secret, and realm-containing issuer through environment variables or explicit options, and configure Keycloak to use the matching callback URL.

Syntax

Keycloak(options?: OIDCUserConfig<P>)

Parameters

NameTypeDescription
optionsOIDCUserConfig<P>Provider options, including OIDC client configuration such as client ID, client secret, and issuer.

Returns

A configured Keycloak provider definition suitable for the Auth.js providers array.

Key points

  • Auth.js includes Keycloak as a ready-made provider rather than requiring a custom OAuth provider implementation.
  • The integration uses OpenID Connect semantics by default.
  • The standard environment-variable names are AUTH_KEYCLOAK_ID, AUTH_KEYCLOAK_SECRET, and AUTH_KEYCLOAK_ISSUER.
  • The documented Next.js callback endpoint is /api/auth/callback/keycloak.
  • The provider setup requires a suitable Keycloak client; the reference setup specifies OpenID Connect and confidential access.

Common mistakes

  • The issuer must contain the Keycloak realm; using only the server base URL is insufficient.
  • In newer Keycloak setups, enable client authentication before looking for the client secret.
  • For Keycloak versions before 20, create an OpenID Connect client and select confidential access.

Example: Register Keycloak with NextAuth

import NextAuth from "next-auth"
import Keycloak from "next-auth/providers/keycloak"

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [Keycloak],
})

Register the built-in provider; Auth.js reads the Keycloak client settings from the documented environment variables.

When to use it

Authenticate users through a self-hosted Keycloak realm.

Enterprise identity

Add a Keycloak sign-in button using the built-in provider.

Next.js application

Connect Auth.js to a Keycloak server without implementing the protocol manually.

OIDC integration

Interview questions

QHow do you add Keycloak to an Auth.js configuration?

Keycloak is configured as a built-in Auth.js provider using Keycloak in the providers list. The provider follows OpenID Connect and can infer its settings from AUTH_KEYCLOAK_ID, AUTH_KEYCLOAK_SECRET, and AUTH_KEYCLOAK_ISSUER.

Follow-up: What must the issuer value contain? It must include the Keycloak realm, such as /realms/My_Realm.

QWhat callback URL does the Keycloak provider use?

The callback path is /api/auth/callback/keycloak in the documented example. The exact externally reachable URL must match the callback configured for the Keycloak client.

Follow-up: What should be checked if sign-in returns a redirect error? Compare the configured callback URL and issuer realm with the Keycloak client configuration.

QWhich configuration values does Keycloak require?

The provider accepts an OIDCUserConfig<P> options object when called directly. Explicit configuration can provide clientId, clientSecret, and issuer, while the built-in provider can use the documented environment variables.

Follow-up: When would explicit options be useful? Use them when the defaults inferred from environment variables need to be overridden.

  • OIDCUserConfig
  • OAuth providers
  • customizing a built-in OAuth provider
  • AUTH_KEYCLOAK_ID
  • AUTH_KEYCLOAK_SECRET
  • AUTH_KEYCLOAK_ISSUER

Source: Auth.js | Keycloak. Checked 2026-10-15.