Authentication flows

This page describes how @sinequa/atomic-angular orchestrates authentication — how the pieces fit together and how every flow is handled. It is the Angular-side companion to the core state machine documented by @sinequa/atomic (detection, login() resolution, the OAuth/SAML redirect loop guard, error envelopes) — this page never repeats that part, only what Angular adds on top of it.

The pieces

Required routes

import { AuthGuard, AuthPageComponent, ErrorComponent } from "@sinequa/atomic-angular";
import type { Routes } from "@angular/router";

export const routes: Routes = [
  { path: "login", component: AuthPageComponent }, // not SignInComponent directly
  { path: "logout", component: AuthPageComponent },
  { path: "error", component: ErrorComponent },
  // ...protected routes use canActivate: [AuthGuard()]
];

Bootstrap sequence

When authenticated, bootstrapApp awaits initialize(createRoutes) (routing to /error on failure); when not, signIn() has already navigated to /login (credentials) or reloaded the page (sso).

signIn() per mode

On a recoverable 401 it routes to loginPath; on a fatal (non-401) error it routes to /error with the reason and resolves false, so the app never fires further doomed authenticated calls.

Token expiry and 401 re-authentication

Sessions use a sliding refresh (handled in @sinequa/atomic): every response carrying a sinequa-jwt-refresh header re-stores the token, so an active user never expires mid-use. Expiry only happens after idle time, or server-side revocation.

When a token has expired, the next API call answers 401, and the recovery runs on two channels that never handle the same request — registering both is correct, not duplicated:

Each calls signIn() and replays the original request at most once — an AUTH_RETRIED context guard prevents an infinite loop on the interceptor side. Some requests never trigger a recovery at all: audit events (fire-and-forget telemetry), the sign-in's own probes (their 401 is the answer being asked for), and anything trailing behind a deliberate logout() (see below). signIn() also never redirects when the user is already on an authentication screen — they are already where they belong.

Logout

The user menu's logout action clears the local token. The challenge response may carry a logoutUrl — the provider end-session endpoint for OAuth/SAML:

/logout renders the signed-out view, not the sign-in form — this matters for the external modes, where SignInComponent auto-initiates its handshake on mount: rendering it on /logout would immediately re-authenticate the user, a spinner that loops back in. See Signed Out.

Requests that trail behind the logout

A view being torn down as the router leaves the page, a save already in flight, a telemetry event — all of them can reach the server moments later, on a cookie that has just been deleted, and answer 401. Nothing recovers from those: @sinequa/atomic (2.3.2+) closes the recovery from a deliberate logout() until the next successful authentication, and signIn() refuses to redirect away from an authentication screen. Without either, the audit event's 401 re-probed the session, found it gone, and replaced the "signed out" confirmation with /login?returnUrl=/logout — signing back in then returned the user to the logout page.

What's next