@ngbplatform/ui 1.3.0

package/src/ngb/auth/keycloak.ts

@@ -0,0 +1,374 @@
+import Keycloak, {
+  type KeycloakInitOptions,
+  type KeycloakLoginOptions,
+  type KeycloakLogoutOptions,
+  type KeycloakTokenParsed,
+} from 'keycloak-js'
+import type { AuthSnapshot } from './types'
+import { readAppEnv } from '../env/runtimeConfig'
+
+type KeycloakClaims = KeycloakTokenParsed & {
+  email?: string
+  preferred_username?: string
+  given_name?: string
+  family_name?: string
+  name?: string
+  role?: string | string[]
+  roles?: string | string[]
+  groups?: string[]
+}
+
+type AuthListener = (snapshot: AuthSnapshot) => void
+
+const keycloak = new Keycloak({
+  url: requiredEnv('VITE_KEYCLOAK_URL'),
+  realm: requiredEnv('VITE_KEYCLOAK_REALM'),
+  clientId: requiredEnv('VITE_KEYCLOAK_CLIENT_ID'),
+})
+
+const listeners = new Set<AuthListener>()
+let initialized = false
+let initPromise: Promise<boolean> | null = null
+let refreshPromise: Promise<string | null> | null = null
+let callbacksRegistered = false
+
+function requiredEnv(name: string): string {
+  const value = readAppEnv(name)
+  if (!value) throw new Error(`Missing required env var: ${name}`)
+  return value
+}
+
+function normalizeUrl(value: string | null | undefined, fallbackPath: string): string {
+  const raw = String(value ?? '').trim()
+  if (!raw) return new URL(fallbackPath, window.location.origin).toString()
+
+  const next = new URL(raw, window.location.origin)
+  if (next.host === window.location.host && next.protocol !== window.location.protocol) {
+    next.protocol = window.location.protocol
+  }
+
+  return next.toString()
+}
+
+function resolveAppBaseUrl(): string {
+  const rawBase = String(import.meta.env.BASE_URL ?? '/').trim()
+  const normalizedBase = rawBase
+    ? (rawBase.endsWith('/') ? rawBase : `${rawBase}/`)
+    : '/'
+
+  return new URL(normalizedBase, window.location.origin).toString()
+}
+
+function resolveAppPublicUrl(path: string): string {
+  const normalizedPath = String(path ?? '').trim().replace(/^\/+/, '')
+  return new URL(normalizedPath, resolveAppBaseUrl()).toString()
+}
+
+function parseBoolean(value: string | boolean | null | undefined, defaultValue: boolean): boolean {
+  if (typeof value === 'boolean') return value
+
+  const normalized = String(value ?? '').trim().toLowerCase()
+  if (!normalized) return defaultValue
+  if (normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on') return true
+  if (normalized === 'false' || normalized === '0' || normalized === 'no' || normalized === 'off') return false
+  return defaultValue
+}
+
+function resolveOnLoad(): 'login-required' | 'check-sso' {
+  const normalized = (readAppEnv('VITE_KEYCLOAK_ON_LOAD') || 'login-required').toLowerCase()
+  return normalized === 'check-sso' ? 'check-sso' : 'login-required'
+}
+
+function shouldUseSilentCheckSso(onLoad: 'login-required' | 'check-sso'): boolean {
+  if (onLoad !== 'check-sso') return false
+  return parseBoolean(readAppEnv('VITE_KEYCLOAK_SILENT_CHECK_SSO_ENABLED'), false)
+}
+
+function resolveSilentCheckSsoRedirectUri(): string {
+  return normalizeUrl(readAppEnv('VITE_KEYCLOAK_SILENT_CHECK_SSO_REDIRECT_URI'), resolveAppPublicUrl('silent-check-sso.html'))
+}
+
+function resolvePostLogoutRedirectUri(): string {
+  const explicit = readAppEnv('VITE_KEYCLOAK_POST_LOGOUT_REDIRECT_URL')
+  if (explicit) return normalizeUrl(explicit, resolveAppBaseUrl())
+  return normalizeUrl(readAppEnv('VITE_KEYCLOAK_REDIRECT_URL'), resolveAppBaseUrl())
+}
+
+function resolveAdminConsoleLocalLogoutEndpoints(): string[] {
+  const configuredUrls = [
+    readAppEnv('VITE_WATCHDOG_URL'),
+    readAppEnv('VITE_BACKGROUND_JOB_URL'),
+  ]
+
+  return Array.from(
+    new Set(
+      configuredUrls
+        .map((value) => String(value ?? '').trim())
+        .filter((value) => value.length > 0)
+        .map((value) => new URL(value, window.location.origin))
+        .map((url) => `${url.origin}/account/local-logout`),
+    ),
+  )
+}
+
+async function logoutKnownAdminConsoles(): Promise<void> {
+  const endpoints = resolveAdminConsoleLocalLogoutEndpoints()
+  if (endpoints.length === 0) return
+
+  await Promise.allSettled(
+    endpoints.map(async (endpoint) => {
+      await fetch(endpoint, {
+        method: 'POST',
+        credentials: 'include',
+        mode: 'cors',
+        cache: 'no-store',
+        keepalive: true,
+        headers: {
+          Accept: '*/*',
+        },
+      })
+    }),
+  )
+}
+
+function resolveLoginRedirectUri(targetPath?: string | null): string {
+  const target = String(targetPath ?? '').trim()
+  if (/^https?:\/\//i.test(target)) return target
+  if (target.startsWith('/')) return new URL(target, window.location.origin).toString()
+
+  const currentUrl = new URL(window.location.href)
+  currentUrl.hash = ''
+  return currentUrl.toString()
+}
+
+function unique(values: Iterable<string | null | undefined>): string[] {
+  return Array.from(
+    new Set(
+      Array.from(values)
+        .map((value) => String(value ?? '').trim())
+        .filter((value) => value.length > 0),
+    ),
+  )
+}
+
+function readStringArrayClaim(value: unknown): string[] {
+  if (Array.isArray(value)) return unique(value.map((entry) => String(entry ?? '')))
+  if (typeof value === 'string') return unique(value.split(/[,\s]+/g))
+  return []
+}
+
+function accessClaims(): KeycloakClaims | null {
+  return (keycloak.tokenParsed ?? null) as KeycloakClaims | null
+}
+
+function identityClaims(): KeycloakClaims | null {
+  const access = accessClaims()
+  const identity = (keycloak.idTokenParsed ?? null) as KeycloakClaims | null
+  if (!access && !identity) return null
+
+  return {
+    ...(access ?? {}),
+    ...(identity ?? {}),
+  }
+}
+
+function readRealmRoles(claims: KeycloakClaims | null): string[] {
+  return unique(claims?.realm_access?.roles ?? [])
+}
+
+function readTopLevelRoles(claims: KeycloakClaims | null): string[] {
+  return unique([
+    ...readStringArrayClaim(claims?.role),
+    ...readStringArrayClaim(claims?.roles),
+  ])
+}
+
+function readResourceRoles(claims: KeycloakClaims | null): Record<string, string[]> {
+  const resourceAccess = claims?.resource_access ?? {}
+  const entries = Object.entries(resourceAccess).map(([clientId, access]) => [
+    clientId,
+    unique(access?.roles ?? []),
+  ] as const)
+
+  return Object.fromEntries(entries.filter(([, roles]) => roles.length > 0))
+}
+
+function readGroupRoles(claims: KeycloakClaims | null): string[] {
+  return unique(
+    readStringArrayClaim(claims?.groups)
+      .map((group) => group.split('/').filter(Boolean).at(-1) ?? '')
+      .filter((group) => group === 'ngb-admin' || group === 'ngb-user'),
+  )
+}
+
+function resolveDisplayName(claims: KeycloakClaims | null): string | null {
+  const explicitName = String(claims?.name ?? '').trim()
+  if (explicitName) return explicitName
+
+  const fullName = [claims?.given_name, claims?.family_name]
+    .map((part) => String(part ?? '').trim())
+    .filter((part) => part.length > 0)
+    .join(' ')
+
+  if (fullName) return fullName
+
+  const preferredUsername = String(claims?.preferred_username ?? '').trim()
+  if (preferredUsername) return preferredUsername
+
+  const email = String(claims?.email ?? '').trim()
+  return email || null
+}
+
+function snapshot(): AuthSnapshot {
+  const profile = identityClaims()
+  const access = accessClaims()
+  const topLevelRoles = readTopLevelRoles(access)
+  const realmRoles = readRealmRoles(access)
+  const resourceRoles = readResourceRoles(access)
+  const groupRoles = readGroupRoles(profile)
+  const roles = unique([
+    ...topLevelRoles,
+    ...realmRoles,
+    ...Object.values(resourceRoles).flat(),
+    ...groupRoles,
+  ])
+
+  return {
+    initialized,
+    authenticated: Boolean(keycloak.authenticated),
+    token: keycloak.token ?? null,
+    subject: keycloak.subject ?? (typeof profile?.sub === 'string' ? profile.sub : null),
+    displayName: resolveDisplayName(profile),
+    preferredUsername: String(profile?.preferred_username ?? '').trim() || null,
+    email: String(profile?.email ?? '').trim() || null,
+    realmRoles,
+    resourceRoles,
+    roles,
+  }
+}
+
+function notifyListeners(): void {
+  const nextSnapshot = snapshot()
+  for (const listener of listeners) listener(nextSnapshot)
+}
+
+function registerCallbacks(): void {
+  if (callbacksRegistered) return
+  callbacksRegistered = true
+
+  keycloak.onReady = () => {
+    initialized = true
+    notifyListeners()
+  }
+  keycloak.onAuthSuccess = notifyListeners
+  keycloak.onAuthLogout = notifyListeners
+  keycloak.onAuthRefreshSuccess = notifyListeners
+  keycloak.onAuthRefreshError = notifyListeners
+  keycloak.onAuthError = notifyListeners
+  keycloak.onTokenExpired = () => {
+    void refreshAccessToken(0).catch(() => {
+      keycloak.clearToken()
+      notifyListeners()
+    })
+  }
+}
+
+export function subscribeAuth(listener: AuthListener): () => void {
+  listeners.add(listener)
+  listener(snapshot())
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+export function getAuthSnapshot(): AuthSnapshot {
+  return snapshot()
+}
+
+export async function initializeAuth(): Promise<AuthSnapshot> {
+  registerCallbacks()
+
+  if (!initPromise) {
+    const onLoad = resolveOnLoad()
+    const initOptions: KeycloakInitOptions = {
+      onLoad,
+      pkceMethod: 'S256',
+      responseMode: 'fragment',
+      checkLoginIframe: false,
+    }
+
+    if (shouldUseSilentCheckSso(onLoad)) {
+      initOptions.silentCheckSsoRedirectUri = resolveSilentCheckSsoRedirectUri()
+      initOptions.silentCheckSsoFallback = false
+    }
+
+    initPromise = keycloak
+      .init(initOptions)
+      .then((authenticated) => {
+        initialized = true
+        notifyListeners()
+        return authenticated
+      })
+      .catch((error) => {
+        initPromise = null
+        throw error
+      })
+  }
+
+  await initPromise
+  return snapshot()
+}
+
+async function refreshAccessToken(minValidity: number): Promise<string | null> {
+  if (!initialized) await initializeAuth()
+  if (!keycloak.authenticated || !keycloak.token) return null
+
+  if (!refreshPromise) {
+    refreshPromise = keycloak
+      .updateToken(minValidity)
+      .then(() => {
+        notifyListeners()
+        return keycloak.token ?? null
+      })
+      .catch((error) => {
+        keycloak.clearToken()
+        notifyListeners()
+        throw error
+      })
+      .finally(() => {
+        refreshPromise = null
+      })
+  }
+
+  return await refreshPromise
+}
+
+export async function getAccessToken(minValidity: number = 30): Promise<string | null> {
+  return await refreshAccessToken(minValidity)
+}
+
+export async function forceRefreshAccessToken(): Promise<string | null> {
+  return await refreshAccessToken(-1)
+}
+
+export async function loginWithKeycloak(targetPath?: string | null): Promise<void> {
+  if (!initialized) await initializeAuth()
+
+  const options: KeycloakLoginOptions = {
+    redirectUri: resolveLoginRedirectUri(targetPath),
+  }
+
+  await keycloak.login(options)
+}
+
+export async function logoutFromKeycloak(): Promise<void> {
+  if (!initialized) await initializeAuth()
+
+  await logoutKnownAdminConsoles()
+
+  const options: KeycloakLogoutOptions = {
+    redirectUri: resolvePostLogoutRedirectUri(),
+  }
+
+  await keycloak.logout(options)
+}

package/src/ngb/auth/router.ts

@@ -0,0 +1,35 @@
+import type { NavigationGuardWithThis } from 'vue-router'
+
+export type AuthGuardStore = {
+  redirecting: boolean
+  initialized: boolean
+  initializing: boolean
+  authenticated: boolean
+  error: string | null
+  initialize(): Promise<void>
+  login(targetPath?: string | null): Promise<void>
+}
+
+export function createAuthGuard(resolveAuthStore: () => AuthGuardStore): NavigationGuardWithThis<undefined> {
+  return async (to) => {
+    if (to.meta?.public === true) return true
+
+    const auth = resolveAuthStore()
+    if (auth.redirecting) return false
+
+    if (!auth.initialized && !auth.initializing) {
+      try {
+        await auth.initialize()
+      } catch {
+        return true
+      }
+    }
+
+    if (auth.authenticated) return true
+    if (auth.initializing || auth.error) return false
+
+    await auth.login(to.fullPath)
+    return false
+  }
+}
+

package/src/ngb/auth/types.ts

@@ -0,0 +1,12 @@
+export type AuthSnapshot = {
+  initialized: boolean
+  authenticated: boolean
+  token: string | null
+  subject: string | null
+  displayName: string | null
+  preferredUsername: string | null
+  email: string | null
+  realmRoles: string[]
+  resourceRoles: Record<string, string[]>
+  roles: string[]
+}

package/src/ngb/auth/useAuthStore.ts

@@ -0,0 +1,209 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+import {
+  getAuthSnapshot,
+  initializeAuth,
+  loginWithKeycloak,
+  logoutFromKeycloak,
+  subscribeAuth,
+} from './keycloak'
+import type { AuthSnapshot } from './types'
+import { readAppEnv } from '../env/runtimeConfig'
+
+const adminRole = readAppEnv('VITE_KEYCLOAK_ROLE_ADMIN')
+
+function normalizeRoleKey(role: string): string {
+  return String(role ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^\/+/, '')
+    .replace(/[\s._:]+/g, '-')
+}
+
+function toKeycloakInitErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) return error.message.trim()
+  return 'Unable to initialize Keycloak. Check the UI env vars and the client redirect URI settings.'
+}
+
+function toFriendlyRoleLabel(role: string): string {
+  const value = String(role ?? '').trim()
+  const normalizedRole = normalizeRoleKey(value)
+  if (!value) return 'User'
+
+  switch (normalizedRole) {
+    case 'ngb-admin':
+    case 'admin':
+    case 'administrator':
+    case 'realm-admin':
+      return 'Administrator'
+    case 'ngb-user':
+    case 'user':
+      return 'User'
+    default: {
+      const normalized = value
+        .replace(/^ngb[-_:]?/i, '')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+
+      const source = normalized || value
+      return source
+        .split(/\s+/g)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ')
+    }
+  }
+}
+
+function rolePriority(role: string): number {
+  switch (normalizeRoleKey(role)) {
+    case 'ngb-admin':
+    case 'admin':
+    case 'administrator':
+    case 'realm-admin':
+      return 0
+    case 'ngb-user':
+    case 'user':
+      return 10
+    default:
+      return 100
+  }
+}
+
+export const useAuthStore = defineStore('auth', () => {
+  const initialized = ref(false)
+  const initializing = ref(false)
+  const redirecting = ref(false)
+  const authenticated = ref(false)
+  const token = ref<string | null>(null)
+  const subject = ref<string | null>(null)
+  const displayName = ref<string | null>(null)
+  const preferredUsername = ref<string | null>(null)
+  const email = ref<string | null>(null)
+  const realmRoles = ref<string[]>([])
+  const resourceRoles = ref<Record<string, string[]>>({})
+  const roles = ref<string[]>([])
+  const error = ref<string | null>(null)
+
+  let initializePromise: Promise<void> | null = null
+
+  function applySnapshot(snapshot: AuthSnapshot): void {
+    initialized.value = snapshot.initialized
+    authenticated.value = snapshot.authenticated
+    token.value = snapshot.token
+    subject.value = snapshot.subject
+    displayName.value = snapshot.displayName
+    preferredUsername.value = snapshot.preferredUsername
+    email.value = snapshot.email
+    realmRoles.value = snapshot.realmRoles
+    resourceRoles.value = snapshot.resourceRoles
+    roles.value = snapshot.roles
+  }
+
+  subscribeAuth(applySnapshot)
+  applySnapshot(getAuthSnapshot())
+
+  const userName = computed(() => displayName.value || preferredUsername.value || email.value || 'User')
+  const isAdmin = computed(() => {
+    const normalizedConfiguredAdminRole = normalizeRoleKey(adminRole)
+    return roles.value.some((role) => {
+      const normalizedRole = normalizeRoleKey(role)
+      return normalizedRole === 'ngb-admin'
+        || normalizedRole === 'admin'
+        || normalizedRole === 'administrator'
+        || normalizedRole === 'realm-admin'
+        || (!!normalizedConfiguredAdminRole && normalizedRole === normalizedConfiguredAdminRole)
+    })
+  })
+  const primaryTechnicalRole = computed(() => {
+    const sorted = [...roles.value].sort((a, b) => rolePriority(a) - rolePriority(b) || a.localeCompare(b))
+    return sorted[0] ?? ''
+  })
+  const friendlyRoles = computed(() => {
+    const sorted = [...roles.value].sort((a, b) => rolePriority(a) - rolePriority(b) || a.localeCompare(b))
+    return Array.from(new Set(sorted.map((role) => toFriendlyRoleLabel(role))))
+  })
+  const primaryRoleLabel = computed(() => toFriendlyRoleLabel(primaryTechnicalRole.value))
+  const primaryRoleIcon = computed<'shield-check' | 'user'>(() =>
+    rolePriority(primaryTechnicalRole.value) === 0 ? 'shield-check' : 'user')
+
+  async function initialize(): Promise<void> {
+    if (initialized.value) return
+    if (initializePromise) return await initializePromise
+
+    initializing.value = true
+    error.value = null
+
+    initializePromise = initializeAuth()
+      .then((snapshot) => {
+        applySnapshot(snapshot)
+      })
+      .catch((cause) => {
+        error.value = toKeycloakInitErrorMessage(cause)
+        throw cause
+      })
+      .finally(() => {
+        initializing.value = false
+        initializePromise = null
+      })
+
+    return await initializePromise
+  }
+
+  async function login(targetPath?: string | null): Promise<void> {
+    redirecting.value = true
+    error.value = null
+
+    try {
+      await loginWithKeycloak(targetPath)
+    } catch (cause) {
+      redirecting.value = false
+      error.value = toKeycloakInitErrorMessage(cause)
+      throw cause
+    }
+  }
+
+  async function logout(): Promise<void> {
+    redirecting.value = true
+    error.value = null
+
+    try {
+      await logoutFromKeycloak()
+    } catch (cause) {
+      redirecting.value = false
+      error.value = toKeycloakInitErrorMessage(cause)
+      throw cause
+    }
+  }
+
+  function hasRole(role: string): boolean {
+    const value = String(role ?? '').trim()
+    return value.length > 0 && roles.value.includes(value)
+  }
+
+  return {
+    initialized,
+    initializing,
+    redirecting,
+    authenticated,
+    token,
+    subject,
+    displayName,
+    preferredUsername,
+    email,
+    realmRoles,
+    resourceRoles,
+    roles,
+    userName,
+    isAdmin,
+    primaryTechnicalRole,
+    friendlyRoles,
+    primaryRoleLabel,
+    primaryRoleIcon,
+    error,
+    initialize,
+    login,
+    logout,
+    hasRole,
+  }
+})