@contember/engine-tenant-api 2.1.0-beta.2 → 2.2.0-alpha.1

package/src/model/service/idp/index.ts

@@ -1,10 +1,14 @@
-export * from './IdentityProviderHandler'
-export * from './IdentityProviderNotFoundError'
-export * from './IDPHandlerRegistry'
-export * from './IDPManager'
-export * from './IDPResponseError'
-export * from './IDPValidationError'
-export * from './InvalidIDPConfigurationError'
-export * from './providers/AppleProvider'
-export * from './providers/OIDCProvider'
-export * from './providers/FacebookProvider'
+export * from './IdentityProviderHandler.js'
+export * from './IdentityProviderNotFoundError.js'
+export * from './IDPHandlerRegistry.js'
+export * from './IdpSessionRevalidator.js'
+export * from './BackchannelLogoutManager.js'
+export * from './IDPRevalidation.js'
+export * from './IDPManager.js'
+export * from './PersonIdentityProviderManager.js'
+export * from './IDPResponseError.js'
+export * from './IDPValidationError.js'
+export * from './InvalidIDPConfigurationError.js'
+export * from './providers/AppleProvider.js'
+export * from './providers/OIDCProvider.js'
+export * from './providers/FacebookProvider.js'

package/src/model/service/idp/providers/AppleProvider.ts

@@ -1,10 +1,10 @@
 import * as Typesafe from '@contember/typesafe'
-import { IdentityProviderHandler, IDPResponse, InitIDPAuthResult } from '../IdentityProviderHandler'
-import { OIDCConfiguration, OIDCConfigurationOptions, OIDCInitData, OIDCResponseData, OIDCSessionData } from './OIDCTypes'
-import { catchTypesafe } from './helpers'
-import { IDPValidationError } from '../IDPValidationError'
-import { InvalidIDPConfigurationError } from '../InvalidIDPConfigurationError'
-import { handleOIDCResponse, initOIDCAuth } from './OIDCHelpers'
+import { IdentityProviderHandler, IDPResponse, InitIDPAuthResult } from '../IdentityProviderHandler.js'
+import { OIDCConfiguration, OIDCConfigurationOptions, OIDCInitData, OIDCResponseData, OIDCSessionData } from './OIDCTypes.js'
+import { catchTypesafe } from './helpers.js'
+import { IDPValidationError } from '../IDPValidationError.js'
+import { InvalidIDPConfigurationError } from '../InvalidIDPConfigurationError.js'
+import { handleOIDCResponse, initOIDCAuth } from './OIDCHelpers.js'
 import { Client, Issuer } from 'openid-client'
 import { importPKCS8, SignJWT } from 'jose'
 

package/src/model/service/idp/providers/FacebookProvider.ts

@@ -1,13 +1,13 @@
 import * as Typesafe from '@contember/typesafe'
 import { Client, Issuer } from 'openid-client'
-import { IdentityProviderHandler, IDPResponse, InitIDPAuthResult } from '../IdentityProviderHandler'
-import { IDPValidationError } from '../IDPValidationError'
-import { InvalidIDPConfigurationError } from '../InvalidIDPConfigurationError'
-import { catchTypesafe } from './helpers'
-import { BaseOIDCConfiguration, OIDCConfiguration, OIDCInitData, OIDCResponseData } from './OIDCTypes'
-import { handleOIDCResponse, initOIDCAuth } from './OIDCHelpers'
+import { IdentityProviderHandler, IDPResponse, InitIDPAuthResult } from '../IdentityProviderHandler.js'
+import { IDPValidationError } from '../IDPValidationError.js'
+import { InvalidIDPConfigurationError } from '../InvalidIDPConfigurationError.js'
+import { catchTypesafe } from './helpers.js'
+import { BaseOIDCConfiguration, OIDCConfiguration, OIDCInitData, OIDCResponseData } from './OIDCTypes.js'
+import { handleOIDCResponse, initOIDCAuth } from './OIDCHelpers.js'
 import { createHmac } from 'node:crypto'
-import { IDPResponseError } from '../IDPResponseError'
+import { IDPResponseError } from '../IDPResponseError.js'
 
 const FacebookConfiguration = BaseOIDCConfiguration
 type FacebookConfiguration = ReturnType<typeof FacebookConfiguration>

package/src/model/service/idp/providers/OIDCHelpers.ts

@@ -1,8 +1,40 @@
-import { Client, custom, errors, generators } from 'openid-client'
-import { OIDCResponseData } from './OIDCTypes'
-import { IDPValidationError } from '../IDPValidationError'
-import { IDPResponseError } from '../IDPResponseError'
-import { IDPResponse, InitIDPAuthResult } from '../IdentityProviderHandler'
+import { Client, custom, errors, generators, Issuer, TokenSet } from 'openid-client'
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+import { OIDCClaimMapping, OIDCResponseData } from './OIDCTypes.js'
+import { IDPValidationError } from '../IDPValidationError.js'
+import { IDPResponseError } from '../IDPResponseError.js'
+import {
+	IDPResponse,
+	IDPSessionState,
+	InitIDPAuthResult,
+	LogoutTokenClaims,
+	LogoutUrlRequest,
+	RevalidationResult,
+} from '../IdentityProviderHandler.js'
+
+/**
+ * Build the persisted session state from an OIDC token set. Stores the tokens needed for
+ * later re-validation (refresh/access) and SLO (id_token); the whole `tokens` blob is
+ * encrypted at rest by the command layer.
+ *
+ * `prevTokens` carries the previously stored tokens forward: a refresh-grant response MAY omit
+ * the refresh token (RFC 6749 §6 — IdPs that don't rotate just don't re-send it), in which case
+ * the client must keep using the old one. Without this fallback a non-rotating IdP would persist
+ * a session with no refresh token and be revoked (`no_refresh_token`) on the very next tick.
+ */
+export const tokenSetToSessionState = (tokenSet: TokenSet, sessionId?: string, prevTokens?: Record<string, unknown>): IDPSessionState => {
+	const refreshToken = tokenSet.refresh_token ?? (typeof prevTokens?.refresh_token === 'string' ? prevTokens.refresh_token : undefined)
+	const idToken = tokenSet.id_token ?? (typeof prevTokens?.id_token === 'string' ? prevTokens.id_token : undefined)
+	return {
+		sessionId,
+		tokens: {
+			...(refreshToken ? { refresh_token: refreshToken } : {}),
+			...(tokenSet.access_token ? { access_token: tokenSet.access_token } : {}),
+			...(idToken ? { id_token: idToken } : {}),
+		},
+		expiresAt: tokenSet.expires_at ? new Date(tokenSet.expires_at * 1000) : undefined,
+	}
+}
 
 export const initOIDCAuth = async (
 	client: Client,
@@ -24,11 +56,24 @@ export const initOIDCAuth = async (
 	}
 }
 
+export type HandleOIDCResponseOptions = {
+	fetchUserInfo?: boolean
+	returnOIDCResult?: boolean
+	captureSession?: boolean
+	claimMapping?: OIDCClaimMapping
+}
+
+/** Read a claim by name, supporting dot-paths into nested objects (`a.b.c`). */
+const getClaim = (source: Record<string, unknown>, path: string): unknown =>
+	path.split('.').reduce<unknown>(
+		(acc, key) => (acc != null && typeof acc === 'object' ? (acc as Record<string, unknown>)[key] : undefined),
+		source,
+	)
+
 export const handleOIDCResponse = async (
 	client: Client,
 	{ sessionData, redirectUrl, ...otherData }: OIDCResponseData,
-	fetchUserInfo?: boolean,
-	returnOIDCResult?: boolean,
+	{ fetchUserInfo, returnOIDCResult, captureSession, claimMapping }: HandleOIDCResponseOptions = {},
 ): Promise<IDPResponse> => {
 	const params = 'parameters' in otherData ? otherData.parameters : client.callbackParams(otherData.url)
 	if (params.state && !sessionData?.state) {
@@ -40,12 +85,61 @@ export const handleOIDCResponse = async (
 		const { at_hash, c_hash, nonce, ...claimsWithoutHashes } = claims
 		const userInfo = result.access_token && fetchUserInfo ? await client.userinfo(result) : {}
 		const oidcResult = returnOIDCResult ? result : {}
+		const idpSession = captureSession ? tokenSetToSessionState(result, typeof claims.sid === 'string' ? claims.sid : undefined) : undefined
+
+		// Merge ID-token claims with userInfo (userInfo wins, per spec). Then optionally lift a
+		// nested attributes object to the top level so providers that nest their claims (notably
+		// Apereo CAS userinfo, which returns them under `attributes`) map without a code change.
+		// The nested attributes are UNSIGNED, so they must not override a claim already present in
+		// the (signature-verified) ID-token / userInfo merge — spread them UNDER `source`, not over
+		// it, so a signed `sub` / `email_verified` keeps precedence over an attributes-level value.
+		let source: Record<string, unknown> = { ...claimsWithoutHashes, ...userInfo }
+		const attributesKey = claimMapping?.attributesKey
+		if (attributesKey) {
+			const nested = source[attributesKey]
+			if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+				source = { ...(nested as Record<string, unknown>), ...source }
+			}
+		}
+
+		// The OIDC `email_verified` claim is a boolean per spec, but some providers send the
+		// string "true". userInfo (and any unwrapped attributes) take precedence over the ID token.
+		const rawEmailVerified = source.email_verified
+		const emailVerified = rawEmailVerified === true || rawEmailVerified === 'true'
+
+		// `externalIdentifier` is the federation key persisted in `person_identity_provider` and
+		// matched on the next sign-in, so it must be a stable scalar. A `claimMapping` that pointed
+		// it at an object/array would otherwise be coerced by `String(...)` to `'[object Object]'` /
+		// a comma-join — collapsing every user of the provider onto one key (account takeover). Fail
+		// closed instead. The default `sub` path is safe (openid-client guarantees `sub` is a string).
+		const mappedSubject = getClaim(source, claimMapping?.externalIdentifier ?? 'sub')
+		let externalIdentifier: string
+		if (mappedSubject === undefined || mappedSubject === null) {
+			externalIdentifier = claims.sub
+		} else if (typeof mappedSubject === 'string' || typeof mappedSubject === 'number') {
+			externalIdentifier = String(mappedSubject)
+		} else {
+			throw new IDPValidationError(`The mapped externalIdentifier claim is not a scalar value`)
+		}
+		if (externalIdentifier === '') {
+			throw new IDPValidationError(`The mapped externalIdentifier claim resolved to an empty value`)
+		}
+
+		// `email` / `name` are typed `string | undefined` on IDPResponse and feed the by-e-mail
+		// account lookup (which crashes on a non-string). `...source` already placed the raw claim
+		// of whatever type, so OVERWRITE (don't conditionally add) with the mapped value when it is
+		// a string, otherwise `undefined` — a non-string claim must not leak through `...source`.
+		const email = getClaim(source, claimMapping?.email ?? 'email')
+		const name = getClaim(source, claimMapping?.name ?? 'name')
 
 		return {
-			externalIdentifier: claims.sub,
 			...oidcResult,
-			...claimsWithoutHashes,
-			...userInfo,
+			...source,
+			externalIdentifier,
+			email: typeof email === 'string' ? email : undefined,
+			name: typeof name === 'string' ? name : undefined,
+			emailVerified,
+			...(idpSession ? { idpSession } : {}),
 		}
 	} catch (e: any) {
 		if (e instanceof errors.RPError) {
@@ -61,3 +155,192 @@ export const handleOIDCResponse = async (
 		throw e
 	}
 }
+
+/** OIDC errors that definitively mean "this session is no longer valid at the IdP". */
+const REVOKED_OIDC_ERRORS = new Set(['invalid_grant', 'invalid_token', 'expired_token'])
+
+/**
+ * Re-validate a stored OIDC session against the IdP. Returns `revoked` only for definitive
+ * IdP responses (invalid/expired grant or inactive introspection). Transient failures
+ * (network, IdP down) re-throw so the caller can fail-open and keep the session — IdP
+ * downtime must not log everyone out.
+ */
+export const revalidateOIDC = async (
+	client: Client,
+	method: 'refresh' | 'userinfo' | 'introspection',
+	session: IDPSessionState,
+): Promise<RevalidationResult> => {
+	const tokens = session.tokens ?? {}
+	const refreshToken = typeof tokens.refresh_token === 'string' ? tokens.refresh_token : undefined
+	const accessToken = typeof tokens.access_token === 'string' ? tokens.access_token : undefined
+	try {
+		if (method === 'refresh') {
+			if (!refreshToken) {
+				return { status: 'revoked', reason: 'no_refresh_token' }
+			}
+			const tokenSet = await client.refresh(refreshToken)
+			let claims: Record<string, unknown> | undefined
+			try {
+				claims = tokenSet.id_token ? tokenSet.claims() : undefined
+			} catch {
+				claims = undefined
+			}
+			return {
+				status: 'valid',
+				claims,
+				// carry the stored tokens forward: a non-rotating IdP omits the refresh token here
+				idpSession: tokenSetToSessionState(tokenSet, session.sessionId, tokens),
+			}
+		}
+		if (method === 'userinfo') {
+			if (!accessToken) {
+				return { status: 'revoked', reason: 'no_access_token' }
+			}
+			const userInfo = await client.userinfo(accessToken)
+			return { status: 'valid', claims: userInfo }
+		}
+		// introspection
+		const token = accessToken ?? refreshToken
+		if (!token) {
+			return { status: 'revoked', reason: 'no_token' }
+		}
+		const result = await client.introspect(token, accessToken ? 'access_token' : 'refresh_token')
+		if (!result.active) {
+			return { status: 'revoked', reason: 'inactive' }
+		}
+		return { status: 'valid' }
+	} catch (e: any) {
+		if (e instanceof errors.OPError) {
+			if (typeof e.error === 'string' && REVOKED_OIDC_ERRORS.has(e.error)) {
+				return { status: 'revoked', reason: e.error }
+			}
+			// The userinfo endpoint signals a rejected access token with a bare HTTP 401 — per
+			// RFC 6750 the `WWW-Authenticate` error code is optional, so openid-client may not
+			// surface a parseable `error` here. A 401 is still definitive: the token is no
+			// longer accepted → revoked. (Introspection is NOT treated this way: it returns 200
+			// `{active:false}` for revoked tokens, so a 401/400 there means client-auth/config
+			// failure — transient, must not log users out.)
+			if (method === 'userinfo' && e.response?.statusCode === 401) {
+				return { status: 'revoked', reason: 'userinfo_unauthorized' }
+			}
+		}
+		// transient (network / IdP unavailable) — propagate, do not revoke
+		throw e
+	}
+}
+
+/**
+ * Build an RP-initiated (front-channel) logout URL (OIDC RP-Initiated Logout 1.0). Returns null
+ * when the IdP advertises no `end_session_endpoint` — the caller then degrades to a local-only
+ * logout (legacy-IdP graceful fallback). The `id_token_hint` lets the IdP identify and confirm the
+ * session to terminate; `post_logout_redirect_uri` is where the IdP returns the browser afterwards.
+ */
+export const buildOIDCLogoutUrl = (client: Client, { idToken, postLogoutRedirectUri }: LogoutUrlRequest): string | null => {
+	if (!client.issuer.metadata.end_session_endpoint) {
+		return null
+	}
+	return client.endSessionUrl({
+		...(idToken ? { id_token_hint: idToken } : {}),
+		...(postLogoutRedirectUri ? { post_logout_redirect_uri: postLogoutRedirectUri } : {}),
+	})
+}
+
+/**
+ * The OIDC Back-Channel Logout 1.0 event member that MUST be present in a logout token's `events`
+ * claim. Its presence (and the absence of a `nonce`) is what distinguishes a logout token from an
+ * ID token — both are signed by the same IdP, so without this check an ID token could be replayed
+ * to forcibly log a user out.
+ */
+const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout'
+
+/**
+ * Max accepted age of a back-channel logout token, derived from its `iat`. OIDC Back-Channel Logout
+ * tokens are single-use and short-lived; bounding the age (together with requiring `exp`) limits the
+ * window in which a captured token could be replayed to force a logout.
+ */
+const LOGOUT_TOKEN_MAX_AGE_SECONDS = 120
+const LOGOUT_TOKEN_CLOCK_TOLERANCE_SECONDS = 5
+
+/**
+ * Remote JWKS sets keyed by `jwks_uri`. `createRemoteJWKSet` returns a function with its own internal
+ * key cache + fetch cooldown, so it MUST be reused across requests — re-creating it per call (as the
+ * unauthenticated back-channel endpoint would otherwise do) defeats the cache and turns every request
+ * into a potential outbound JWKS fetch. Keyed by URL, so two providers sharing an IdP share the set.
+ */
+const remoteJwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>()
+
+const getRemoteJwks = (jwksUri: string): ReturnType<typeof createRemoteJWKSet> => {
+	let jwks = remoteJwksCache.get(jwksUri)
+	if (!jwks) {
+		jwks = createRemoteJWKSet(new URL(jwksUri))
+		remoteJwksCache.set(jwksUri, jwks)
+	}
+	return jwks
+}
+
+/**
+ * Validate an OIDC back-channel logout token (OIDC Back-Channel Logout 1.0 §2.4–2.6) and extract
+ * the targeted `sid` / `sub`. The token is a JWT signed by the IdP; we verify the signature against
+ * the issuer's JWKS and enforce the issuer + audience (client_id) the same way ID tokens are
+ * verified, pinning the signing algorithm to the provider's configured one, then assert the
+ * back-channel-specific claims:
+ *   - `iat` is present and recent and `exp` is present (§2.4 requires both) — bounds the replay window;
+ *   - `events` contains the back-channel-logout member (it really is a logout token);
+ *   - it carries a `sid` and/or `sub` (otherwise there is nothing to act on);
+ *   - it does NOT carry a `nonce` (a `nonce` means it is an ID token being replayed).
+ * Throws {@link IDPValidationError} on any failure so the caller can answer 400.
+ */
+export const validateOIDCLogoutToken = async (client: Client, issuer: Issuer<Client>, logoutToken: string): Promise<LogoutTokenClaims> => {
+	const jwksUri = issuer.metadata.jwks_uri
+	if (!jwksUri) {
+		throw new IDPValidationError('IdP has no jwks_uri; cannot verify logout token')
+	}
+	const clientId = client.metadata.client_id
+	if (typeof clientId !== 'string' || clientId === '') {
+		// The `aud` check is a core anti-token-substitution defence on this unauthenticated endpoint.
+		// jose treats `audience: undefined` as "skip the aud check entirely", so a missing client_id
+		// must fail closed (reject the token) rather than fall through and accept any audience.
+		throw new IDPValidationError('cannot verify logout token audience: client_id is missing')
+	}
+	const expectedAlg = typeof client.metadata.id_token_signed_response_alg === 'string'
+		? client.metadata.id_token_signed_response_alg
+		: 'RS256'
+	const jwks = getRemoteJwks(jwksUri)
+	let payload: Record<string, unknown>
+	try {
+		const verified = await jwtVerify(logoutToken, jwks, {
+			issuer: issuer.metadata.issuer,
+			audience: clientId,
+			// pin to the provider's configured signing alg so a JWKS containing a symmetric/none key
+			// can never be selected (defence-in-depth on top of jose's own key-type check).
+			algorithms: [expectedAlg],
+			// §2.4: `iat` and `exp` are REQUIRED. `maxTokenAge` makes `iat` required + bounds freshness;
+			// `requiredClaims` makes `exp` required (jose only checks `exp` when present).
+			maxTokenAge: LOGOUT_TOKEN_MAX_AGE_SECONDS,
+			requiredClaims: ['exp'],
+			clockTolerance: LOGOUT_TOKEN_CLOCK_TOLERANCE_SECONDS,
+		})
+		payload = verified.payload as Record<string, unknown>
+	} catch (e: any) {
+		throw new IDPValidationError(`Invalid logout token: ${e?.message ?? 'verification failed'}`)
+	}
+
+	// A logout token MUST NOT contain a nonce; its presence means an ID token is being replayed.
+	if ('nonce' in payload) {
+		throw new IDPValidationError('Logout token must not contain a nonce')
+	}
+
+	const events = payload.events
+	const hasLogoutEvent = typeof events === 'object' && events !== null && BACKCHANNEL_LOGOUT_EVENT in (events as Record<string, unknown>)
+	if (!hasLogoutEvent) {
+		throw new IDPValidationError('Logout token is missing the back-channel-logout event')
+	}
+
+	const sid = typeof payload.sid === 'string' ? payload.sid : undefined
+	const sub = typeof payload.sub === 'string' ? payload.sub : undefined
+	if (!sid && !sub) {
+		throw new IDPValidationError('Logout token must contain a sid or sub claim')
+	}
+
+	return { sid, sub }
+}

package/src/model/service/idp/providers/OIDCProvider.ts

@@ -1,12 +1,21 @@
 import { Client, custom, Issuer } from 'openid-client'
-import { IdentityProviderHandler, IDPResponse, InitIDPAuthResult } from '../IdentityProviderHandler'
-import { InvalidIDPConfigurationError } from '../InvalidIDPConfigurationError'
-import { catchTypesafe } from './helpers'
-import { OIDCConfiguration, OIDCInitData, OIDCResponseData } from './OIDCTypes'
-import { handleOIDCResponse, initOIDCAuth } from './OIDCHelpers'
-import { IDPValidationError } from '../IDPValidationError'
+import {
+	IdentityProviderHandler,
+	IDPResponse,
+	IDPSessionState,
+	InitIDPAuthResult,
+	LogoutTokenClaims,
+	LogoutUrlRequest,
+	RevalidationResult,
+} from '../IdentityProviderHandler.js'
+import { InvalidIDPConfigurationError } from '../InvalidIDPConfigurationError.js'
+import { catchTypesafe } from './helpers.js'
+import { OIDCConfiguration, OIDCInitData, OIDCResponseData } from './OIDCTypes.js'
+import { buildOIDCLogoutUrl, handleOIDCResponse, initOIDCAuth, revalidateOIDC, validateOIDCLogoutToken } from './OIDCHelpers.js'
+import { IDPValidationError } from '../IDPValidationError.js'
 
 const DEFAULT_OIDC_TIMEOUT = 5000
+const OFFLINE_ACCESS_SCOPE = 'offline_access'
 
 export class OIDCProvider implements IdentityProviderHandler<OIDCConfiguration> {
 	private issuerCache: Record<string, Issuer<Client>> = {}
@@ -17,7 +26,7 @@ export class OIDCProvider implements IdentityProviderHandler<OIDCConfiguration>
 		const initData = catchTypesafe(OIDCInitData, IDPValidationError)(data)
 		const client = await this.createOIDCClient(configuration)
 		return await initOIDCAuth(client, {
-			scope: configuration.scope ?? configuration.claims,
+			scope: this.resolveScope(configuration),
 			...initData,
 		})
 	}
@@ -28,11 +37,44 @@ export class OIDCProvider implements IdentityProviderHandler<OIDCConfiguration>
 		return await handleOIDCResponse(
 			client,
 			responseData,
-			configuration.fetchUserInfo,
-			configuration.returnOIDCResult,
+			{
+				fetchUserInfo: configuration.fetchUserInfo,
+				returnOIDCResult: configuration.returnOIDCResult,
+				captureSession: configuration.revalidation?.enabled === true,
+				claimMapping: configuration.claimMapping,
+			},
 		)
 	}
 
+	public async revalidate(configuration: OIDCConfiguration, session: IDPSessionState): Promise<RevalidationResult> {
+		const client = await this.createOIDCClient(configuration)
+		return await revalidateOIDC(client, configuration.revalidation?.method ?? 'refresh', session)
+	}
+
+	public async buildLogoutUrl(configuration: OIDCConfiguration, request: LogoutUrlRequest): Promise<string | null> {
+		const client = await this.createOIDCClient(configuration)
+		return buildOIDCLogoutUrl(client, request)
+	}
+
+	public async validateLogoutToken(configuration: OIDCConfiguration, logoutToken: string): Promise<LogoutTokenClaims> {
+		const client = await this.createOIDCClient(configuration)
+		return await validateOIDCLogoutToken(client, client.issuer, logoutToken)
+	}
+
+	/**
+	 * Resolve the requested scope, appending `offline_access` when refresh-token
+	 * re-validation is enabled (so the IdP issues a refresh token to revalidate against).
+	 */
+	private resolveScope(configuration: OIDCConfiguration): string {
+		const baseScope = configuration.scope ?? configuration.claims ?? 'openid email'
+		const needsOfflineAccess = configuration.revalidation?.enabled === true
+			&& (configuration.revalidation.method ?? 'refresh') === 'refresh'
+		if (needsOfflineAccess && !baseScope.split(/\s+/).includes(OFFLINE_ACCESS_SCOPE)) {
+			return `${baseScope} ${OFFLINE_ACCESS_SCOPE}`
+		}
+		return baseScope
+	}
+
 	getPublicConfiguration({ clientSecret, ...config }: OIDCConfiguration): Partial<OIDCConfiguration> {
 		return config
 	}
@@ -46,6 +88,7 @@ export class OIDCProvider implements IdentityProviderHandler<OIDCConfiguration>
 				client_secret: configuration.clientSecret,
 				response_types: [configuration.responseType || 'code'],
 				id_token_signed_response_alg: configuration.idTokenSignedResponseAlg ?? 'RS256',
+				...(configuration.tokenEndpointAuthMethod ? { token_endpoint_auth_method: configuration.tokenEndpointAuthMethod } : {}),
 			},
 			undefined,
 			{

package/src/model/service/idp/providers/OIDCTypes.ts

@@ -1,20 +1,80 @@
 import * as Typesafe from '@contember/typesafe'
-import { ResponseType } from 'openid-client'
+import { ClientAuthMethod, ResponseType } from 'openid-client'
+import { IDPRevalidationConfig } from '../IDPRevalidation.js'
 
 export interface OIDCSessionData {
 	nonce: string
 	state: string
 }
 
+/** OIDC re-validation config: the generic settings plus the OIDC-specific probe method. */
+export const OIDCRevalidationConfig = Typesafe.intersection(
+	IDPRevalidationConfig,
+	Typesafe.partial({
+		/** How to probe the IdP. `refresh` needs `offline_access`; default `refresh`. */
+		method: Typesafe.enumeration('refresh', 'userinfo', 'introspection'),
+	}),
+)
+
+export type OIDCRevalidationConfig = ReturnType<typeof OIDCRevalidationConfig>
+
+/**
+ * Maps provider claims onto the normalized {@link IDPResponse} fields. Each value is a claim
+ * name, dot-path supported (e.g. `address.region`). Lets a provider whose claims don't follow
+ * the OIDC defaults still be consumed without a per-provider code change.
+ */
+export const OIDCClaimMapping = Typesafe.partial({
+	/**
+	 * Claim used as the stable external identifier (the IdP subject). Default `sub`.
+	 * Must resolve to a scalar (string/number) — a non-scalar claim is rejected at sign-in.
+	 * Mapping this to a claim that only appears in userInfo / `attributes` takes the federation
+	 * key off the signature-verified ID-token subject; prefer a signed claim where possible.
+	 */
+	externalIdentifier: Typesafe.string,
+	/** Claim used as the e-mail address. Default `email`. */
+	email: Typesafe.string,
+	/** Claim used as the display name. Default `name`. */
+	name: Typesafe.string,
+	/**
+	 * Key of a nested object whose properties are lifted to the top level before mapping.
+	 * Some providers (notably Apereo CAS userinfo) nest the actual claims under `attributes`.
+	 */
+	attributesKey: Typesafe.string,
+})
+
+export type OIDCClaimMapping = ReturnType<typeof OIDCClaimMapping>
+
 export const OIDCConfigurationOptions = Typesafe.partial({
 	responseType: Typesafe.enumeration<ResponseType>('code', 'code id_token', 'code id_token token', 'code token', 'id_token', 'id_token token', 'none'),
 	claims: Typesafe.string, // deprecated, use scope instead
 	scope: Typesafe.string,
 	additionalAuthorizedParties: Typesafe.array(Typesafe.string),
 	idTokenSignedResponseAlg: Typesafe.string,
+	/**
+	 * How the client authenticates to the token endpoint. `openid-client` defaults to
+	 * `client_secret_basic`; set `client_secret_post` for providers (e.g. some Apereo CAS
+	 * registrations) that only accept the secret in the request body.
+	 */
+	tokenEndpointAuthMethod: Typesafe.enumeration<ClientAuthMethod>(
+		'client_secret_basic',
+		'client_secret_post',
+		'client_secret_jwt',
+		'private_key_jwt',
+		'tls_client_auth',
+		'self_signed_tls_client_auth',
+		'none',
+	),
 	fetchUserInfo: Typesafe.boolean,
 	returnOIDCResult: Typesafe.boolean,
 	timeout: Typesafe.number,
+	revalidation: OIDCRevalidationConfig,
+	claimMapping: OIDCClaimMapping,
+	/**
+	 * Where the IdP should send the browser back after an RP-initiated (front-channel) logout
+	 * (A10). Used as `post_logout_redirect_uri` in the end-session URL; must be registered at the
+	 * IdP. When unset, the IdP applies its own default post-logout behavior.
+	 */
+	postLogoutRedirectUri: Typesafe.string,
 })
 export const BaseOIDCConfiguration = Typesafe.intersection(
 	Typesafe.object({

package/src/model/service/index.ts

@@ -1,20 +1,31 @@
-export * from './apiKey'
-export * from './idp'
+export * from './apiKey/index.js'
+export * from './captcha/index.js'
+export * from './idp/index.js'
 
-export * from './EmailValidator'
-export * from './IDPSignInManager'
-export * from './InviteManager'
-export * from './MailTemplateManager'
-export * from './MembershipValidator'
-export * from './OtpAuthenticator'
-export * from './OtpManager'
-export * from './PasswordChangeManager'
-export * from './PasswordResetManager'
-export * from './PersonAccessManager'
-export * from './PersonManager'
-export * from './ProjectManager'
-export * from './ProjectMemberManager'
-export * from './RolesManager'
-export * from './SecretsManager'
-export * from './SignInManager'
-export * from './SignUpManager'
+export * from './AuthLogService.js'
+export * from './AuthPolicyManager.js'
+export * from './AuthPolicyResolver.js'
+export * from './BackupCodeManager.js'
+export * from './EmailChangeManager.js'
+export * from './EmailOtpManager.js'
+export * from './EmailValidator.js'
+export * from './EmailVerificationManager.js'
+export * from './IDPSignInManager.js'
+export * from './InviteManager.js'
+export * from './LoginRiskAnalyzer.js'
+export * from './MailTemplateManager.js'
+export * from './MembershipValidator.js'
+export * from './OtpAuthenticator.js'
+export * from './OtpManager.js'
+export * from './PasswordChangeManager.js'
+export * from './PasswordResetManager.js'
+export * from './PersonAccessManager.js'
+export * from './PersonManager.js'
+export * from './ProjectManager.js'
+export * from './RateLimiter.js'
+export * from './ProjectMemberManager.js'
+export * from './RolesManager.js'
+export * from './SecretsManager.js'
+export * from './SignInManager.js'
+export * from './SignOutManager.js'
+export * from './SignUpManager.js'

package/src/model/service/membershipUtils.ts

@@ -1,4 +1,4 @@
-import { MembershipInput, MembershipUpdateInput, VariableUpdateInput } from '../commands'
+import { MembershipInput, MembershipUpdateInput, VariableUpdateInput } from '../commands/index.js'
 import { Acl } from '@contember/schema'
 
 export const createSetMembershipVariables = (memberships: readonly Acl.Membership[]): MembershipInput[] => {