Module Configuration

The @thunderid/nuxt module is configured via the thunderid key in nuxt.config.ts. The configuration covers credentials, redirect URLs, session handling, and UI preferences.

Usage

nuxt.config.ts

ts

export default defineNuxtConfig({
  modules: ['@thunderid/nuxt'],
  thunderid: {
    clientId: '<your-client-id>',
    clientSecret: '<your-client-secret>',
    baseUrl: 'https://localhost:8090',
    afterSignInUrl: '/dashboard',
    afterSignOutUrl: '/',
    scopes: ['openid', 'profile', 'internal_login'],
    preferences: {
      theme: {
        inheritFromBranding: true,
        mode: 'system',
      },
    },
  },
})

Environment Variables

Secret values should be provided through environment variables rather than hardcoded in nuxt.config.ts. The module reads the following variables automatically:

Variable	Maps to
NUXT_PUBLIC_THUNDERID_BASE_URL	baseUrl
NUXT_PUBLIC_THUNDERID_CLIENT_ID	clientId
NUXT_THUNDERID_CLIENT_SECRET	clientSecret
NUXT_THUNDERID_SESSION_SECRET	sessionSecret

note

clientSecret and sessionSecret are placed in the Nuxt private runtime config and are never exposed to the browser.

Configuration Options

Option	Type	Required	Description
baseUrl	string	✅	The base URL of the ThunderID instance (e.g., https://localhost:8090)
clientId	string	✅	Client ID of your application
clientSecret	string	✅	Client secret of your application
sessionSecret	string	✅	Secret used to sign session cookies. Must be at least 32 characters
afterSignInUrl	string	❌	URL to redirect to after a successful sign-in. Defaults to '/'
afterSignOutUrl	string	❌	URL to redirect to after sign-out. Defaults to '/'
signInUrl	string	❌	Custom sign-in page URL. Defaults to '/api/auth/signin'
signUpUrl	string	❌	Custom sign-up page URL. Defaults to '/api/auth/signup'
scopes	string[]	❌	OIDC scopes to request. Defaults to ['openid', 'profile']
applicationId	string	❌	Application ID used for branding and flow configuration
platform	string	❌	Platform identifier for the SDK
tokenRequest	object	❌	Token endpoint request configuration
preferences	object	❌	UI and behavior preferences
backchannelLogout	object	❌	Receive back-channel logout notifications from ThunderID. See backchannelLogout

tokenRequest

Property	Type	Description
authMethod	TokenEndpointAuthMethod	Token endpoint authentication method (e.g., 'client_secret_basic', 'client_secret_post')

preferences

The preferences object controls SSR data-fetching behavior and UI customization.

Theme (preferences.theme)

Property	Type	Default	Description
inheritFromBranding	boolean	true	Fetch branding from ThunderID and apply it to SDK components. Set to false to skip the branding fetch on each SSR request
mode	'light' | 'dark' | 'system' | 'class' | 'branding'	'system'	Theme mode. 'system' follows the user's OS preference; 'branding' uses the fetched branding colors

Internationalization (preferences.i18n)

Property	Type	Default	Description
language	string	Browser default	Default language code for SDK UI components (e.g., 'en-US', 'fr-FR')
fallbackLanguage	string	'en-US'	Fallback language when a translation is not available
bundles	object	{}	Custom translation bundles to override default text

User Data (preferences.user)

Controls which data is fetched server-side during SSR and hydrated into the client.

Property	Type	Default	Description
fetchUserProfile	boolean	true	Fetch the user's profile on each SSR request and hydrate it into the client

backchannelLogout

ThunderID posts a logout_token to the application when a Single Sign-On session it took part in ends. With backchannelLogout.enabled, the module serves the route that receives it. Register that route's URL as the application's back-channel logout URI, see Back-Channel Logout.

nuxt.config.ts

ts

export default defineNuxtConfig({
  modules: ['@thunderid/nuxt'],
  thunderid: {
    backchannelLogout: { enabled: true },
  },
})

Property	Type	Default	Description
enabled	boolean	false	Serve the route. Off by default, because the route accepts unauthenticated requests
path	string	/api/auth/backchannel-logout	Route of the handler
store	string	Process memory	Name of a Nitro storage mount point that records ended sessions. Needed when more than one instance of the application runs

The route accepts a POST with an application/x-www-form-urlencoded body carrying one logout_token, at most 16 kB, with a declared Content-Length. It answers 200 for a valid token, including one that names no session the application holds, 400 for a request or token that is not valid, and 500 when the logout could not be recorded, which makes ThunderID retry. Every response carries Cache-Control: no-store. A rejected token is logged by its error code only.

The session lives in a cookie that only the browser can delete, so the route records the logout, and useServerSession(), requireServerSession(), getValidAccessToken() and the SSR plugin return no session for a matching cookie from then on. The session cookie records the sid of the ID token and the sign-in time, and keeps both across a token refresh. A token with a sid ends exactly that session; a token with only a sub ends the subject's sessions that began before the token was issued, or within the ID token clock tolerance after it.

For several instances, name a Nitro storage mount point they share, since ThunderID posts the notification to one instance only:

nuxt.config.ts

ts

export default defineNuxtConfig({
  modules: ['@thunderid/nuxt'],
  thunderid: {
    backchannelLogout: { enabled: true, store: 'redis' },
  },
  nitro: {
    storage: { redis: { driver: 'redis', url: process.env.REDIS_URL } },
  },
})

note

The logout token is addressed to the client id, so back-channel logout works with the redirect-based flow (clientId set). An access token already handed to the browser or to another API stays valid until it expires. An encrypted logout token, sent to a client configured for ID token encryption, is not supported.

Advanced Configuration

Minimal Configuration (No SSR Data Fetching)

Disable server-side data fetching to reduce SSR latency when you don't need user profile data pre-loaded:

nuxt.config.ts

ts

export default defineNuxtConfig({
  modules: ['@thunderid/nuxt'],
  thunderid: {
    clientId: process.env.NUXT_PUBLIC_THUNDERID_CLIENT_ID!,
    clientSecret: process.env.NUXT_THUNDERID_CLIENT_SECRET!,
    baseUrl: process.env.NUXT_PUBLIC_THUNDERID_BASE_URL!,
    preferences: {
      theme: {
        inheritFromBranding: false,
      },
      user: {
        fetchUserProfile: false,
      },
    },
  },
})