✨ Forward login hints through Keycloak

Author: edulix

packages/voting-portal/src/App.tsx

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: AGPL-3.0-only
 
-import React, {useEffect, useContext, useMemo, useCallback} from "react"
+import React, {useEffect, useContext, useMemo, useCallback, useState} from "react"
 import {Outlet, ScrollRestoration, useLocation, useParams} from "react-router-dom"
 import {styled} from "@mui/material/styles"
 import {Footer, Header, PageBanner} from "@sequentech/ui-essentials"
@@ -33,6 +33,7 @@ import WatermarkBackground from "./components/WaterMark/Watermark"
 import SequentLogo from "@sequentech/ui-essentials/public/Sequent_logo.svg"
 import BlankLogoImg from "@sequentech/ui-essentials/public/blank_logo.svg"
 import {useElectionClassName} from "./hooks/useElectionClassName"
+import {InvalidLoginHintsError, parseLoginHints} from "./utils/loginHints"
 interface ElectionEventConfigDocument {
     id: string
     tenant_id: string
@@ -132,6 +133,27 @@ const App = () => {
     const location = useLocation()
     const {tenantId, eventId} = useParams<TenantEventType>()
     const {isAuthenticated, setTenantEvent} = useContext(AuthContext)
+    const [loginHintRequest] = useState(() => {
+        const acceptsLoginHints = ["/login", "/enroll"].some((suffix) =>
+            location.pathname.endsWith(suffix)
+        )
+
+        try {
+            const parsed = acceptsLoginHints
+                ? parseLoginHints(location.search)
+                : {hints: {}, remainingSearch: location.search}
+            return {...parsed, pathname: location.pathname, hash: location.hash}
+        } catch (error) {
+            if (error instanceof InvalidLoginHintsError) {
+                throw new VotingPortalError(VotingPortalErrorType.INVALID_LOGIN_HINT_PARAMETERS)
+            }
+            throw error
+        }
+    })
+    const loginHintsForCurrentRoute = useMemo(
+        () => (loginHintRequest.pathname === location.pathname ? loginHintRequest.hints : {}),
+        [location.pathname, loginHintRequest]
+    )
 
     const electionIds = useAppSelector(selectElectionIds)
     const ballotStyleElectionIds = useAppSelector(selectBallotStyleElectionIds)
@@ -144,6 +166,22 @@ const App = () => {
 
     useElectionClassName()
 
+    useEffect(() => {
+        if (Object.keys(loginHintRequest.hints).length === 0) {
+            return
+        }
+
+        // Keep validated hints in memory while removing PII from browser history and redirect URIs.
+        navigate(
+            {
+                pathname: loginHintRequest.pathname,
+                search: loginHintRequest.remainingSearch,
+                hash: loginHintRequest.hash,
+            },
+            {replace: true}
+        )
+    }, [loginHintRequest, navigate])
+
     useEffect(() => {
         if (location.pathname === "/") {
             throw new VotingPortalError(VotingPortalErrorType.NO_ELECTION_EVENT)
@@ -185,12 +223,19 @@ const App = () => {
                     ? languageConf.default_language_code
                     : undefined
 
-            setTenantEvent(tenantId, eventId, mode, defaultLocale)
+            setTenantEvent(tenantId, eventId, mode, defaultLocale, loginHintsForCurrentRoute)
         } catch (error) {
             console.error("Error loading election event config:", error)
-            setTenantEvent(tenantId, eventId, mode, undefined)
+            setTenantEvent(tenantId, eventId, mode, undefined, loginHintsForCurrentRoute)
         }
-    }, [tenantId, eventId, electionEventConfigUrl, location.pathname, setTenantEvent])
+    }, [
+        tenantId,
+        eventId,
+        electionEventConfigUrl,
+        location.pathname,
+        loginHintsForCurrentRoute,
+        setTenantEvent,
+    ])
 
     useEffect(() => {
         if (isAuthenticated) {

packages/voting-portal/src/providers/AuthContextProvider.tsx

@@ -10,6 +10,7 @@ import {SettingsContext} from "./SettingsContextProvider"
 import {getLanguageFromURL} from "../utils/queryParams"
 import {useTranslation} from "react-i18next"
 import {IPermissions} from "../types/keycloak"
+import {appendLoginHints, LoginHints} from "../utils/loginHints"
 
 /**
  * AuthContextValues defines the structure for the default values of the {@link AuthContext}.
@@ -66,7 +67,8 @@ export interface AuthContextValues {
         tenantId: string,
         eventId: string,
         authType?: "register" | "login",
-        defaultLocale?: string
+        defaultLocale?: string,
+        loginHints?: LoginHints
     ) => void
 
     /**
@@ -100,7 +102,13 @@ const defaultAuthContextValues: AuthContextValues = {
     keycloakAccessToken: undefined,
     logout: () => {},
     getExpiry: () => undefined,
-    setTenantEvent: (_tenantId: string, _eventId: string, _authType, _defaultLocale) => {},
+    setTenantEvent: (
+        _tenantId: string,
+        _eventId: string,
+        _authType,
+        _defaultLocale,
+        _loginHints
+    ) => {},
     hasRole: () => false,
     isKiosk: () => false,
     openProfileLink: () => new Promise(() => undefined),
@@ -144,6 +152,7 @@ const AuthContextProvider = (props: AuthContextProviderProps) => {
     const [eventId, setEventId] = useState<string | null>(null)
     const [authType, setAuthType] = useState<"register" | "login" | null>(null)
     const [defaultLocale, setDefaultLocale] = useState<string | undefined>(undefined)
+    const [loginHints, setLoginHints] = useState<LoginHints>({})
 
     const {i18n} = useTranslation()
 
@@ -294,15 +303,41 @@ const AuthContextProvider = (props: AuthContextProviderProps) => {
                     if (authType === "register") {
                         const baseUrl = window.location.origin + window.location.pathname
                         const queryString = window.location.search
-
-                        return await keycloak.register({
+                        const registerOptions = {
                             ...keycloakInitOptions,
                             // after successful enrollment, we should redirect to login
                             redirectUri: baseUrl.endsWith("/enroll")
                                 ? baseUrl.replace(/\/enroll$/, "/login") + queryString
                                 : undefined,
-                        })
+                            loginHint: loginHints.username,
+                        }
+
+                        if (Object.keys(loginHints).length > 0) {
+                            window.location.assign(
+                                appendLoginHints(
+                                    keycloak.createRegisterUrl(registerOptions),
+                                    loginHints
+                                )
+                            )
+                            return
+                        }
+
+                        return await keycloak.register(registerOptions)
                     } else {
+                        if (Object.keys(loginHints).length > 0) {
+                            window.location.assign(
+                                appendLoginHints(
+                                    keycloak.createLoginUrl({
+                                        ...keycloakInitOptions,
+                                        // Stock username forms only understand the standard OIDC hint.
+                                        loginHint: loginHints.username,
+                                    }),
+                                    loginHints
+                                )
+                            )
+                            return
+                        }
+
                         return await keycloak.login(keycloakInitOptions)
                     }
                 }
@@ -326,7 +361,7 @@ const AuthContextProvider = (props: AuthContextProviderProps) => {
         if (keycloak && !isAuthenticated && !isKeycloakInitialized) {
             initializeKeycloak()
         }
-    }, [keycloak, isAuthenticated, isKeycloakInitialized, authType, defaultLocale])
+    }, [keycloak, isAuthenticated, isKeycloakInitialized, authType, defaultLocale, loginHints])
 
     /**
      * Returns true only if the JWT has gold permissions and the JWT
@@ -395,12 +430,14 @@ const AuthContextProvider = (props: AuthContextProviderProps) => {
         tenantId: string,
         eventId: string,
         authType?: "register" | "login",
-        defaultLocale?: string
+        defaultLocale?: string,
+        initialLoginHints?: LoginHints
     ) => {
         setTenantId(tenantId)
         setEventId(eventId)
         setDefaultLocale(defaultLocale)
         authType && setAuthType(authType)
+        setLoginHints(initialLoginHints ?? {})
     }
 
     const getRedirectUrl = (redirectUrl?: string) => {

packages/voting-portal/src/utils/loginHints.test.ts

@@ -74,7 +74,7 @@ describe("parseLoginHints", () => {
 describe("appendLoginHints", () => {
     it("preserves OIDC parameters and percent-encodes hint names and values", () => {
         const result = appendLoginHints(
-            "https://id.example/authorize?state=oidc-state&login_hint=user%40example.com",
+            "https://id.example/authorize?state=oidc-state&nonce=oidc-nonce&code_challenge=pkce-challenge&redirect_uri=https%3A%2F%2Fvote.example%2Flogin&login_hint=user%40example.com",
             {
                 username: "user@example.com",
                 reference: "a&b=c % value",
@@ -83,6 +83,9 @@ describe("appendLoginHints", () => {
         const resultUrl = new URL(result)
 
         expect(resultUrl.searchParams.get("state")).toBe("oidc-state")
+        expect(resultUrl.searchParams.get("nonce")).toBe("oidc-nonce")
+        expect(resultUrl.searchParams.get("code_challenge")).toBe("pkce-challenge")
+        expect(resultUrl.searchParams.get("redirect_uri")).toBe("https://vote.example/login")
         expect(resultUrl.searchParams.get("login_hint")).toBe("user@example.com")
         expect(resultUrl.searchParams.get("login_hint__username")).toBe("user@example.com")
         expect(resultUrl.searchParams.get("login_hint__reference")).toBe("a&b=c % value")