Authentication
Which mode your deployment uses, why you rarely choose it, and what your interface has to render in each case.
You do not pick how users sign in — the server does, and it announces it. Your job is smaller than it looks:
call login(), and render either a loader or a credentials form depending on what came back.
await client.initializeConfig(); // asks the server how it authenticates
await client.auth.login(); // does itEverything below exists because that pair behaves differently per deployment, and because sessions expire.
Which mode is yours?
If you cannot answer the first question, that is the normal case: leave the mode alone and let it be detected.
The modes
| Mode | Sign-in | What your interface renders |
|---|---|---|
credentials | Username and password posted to the server | A form. login() with no arguments returns false. |
sso | The transport authenticates every request — Windows integrated auth, a reverse proxy, an SPFx host | Nothing. A loader at most. |
oauth | Full-page redirect to an identity provider, and back | A loader; the page is left. |
saml | The same, with a SAML provider | A loader; the page is left. |
bearer | A configured access token sent on every request | Nothing — usually there is no interface. |
unknown | Not resolved yet: the default | Wait. It becomes one of the above. |
One predicate covers the rendering decision, and it exists so nobody has to enumerate that list again:
import { isExternalAuthMode } from "@sinequa/atomic";
// true for sso, oauth, saml and bearer — every mode that needs no form.
if (isExternalAuthMode(client.config.authMode)) showLoader();
else showCredentialsForm();unknown is deliberately not external: treating an unresolved mode as formless risks a loader with no way
out.
Declaring it explicitly
When you know, say so — an explicit mode other than unknown always wins over what the server announces:
import { AuthMode } from "@sinequa/atomic";
client.configure({ authMode: AuthMode.sso() });
client.configure({ authMode: AuthMode.oauth("my-provider") });
client.configure({ authMode: AuthMode.bearer(token) });
client.configure({ authMode: AuthMode.bearer(token, { sessionCookie: false }) });
client.configure({ authMode: AuthMode.credentials() });Declaring credentials is also an optimisation: initializeConfig() then makes no pre-login request, since
a form needs nothing from the server.
What to read next
How it works
The cookie, the CSRF token, and why an active session never expires under the user. Read this before the per-mode pages.
Session lifecycle
Knowing whether you are signed in, signing out, and the events that report both.
Handling a 401
Recovering an expired session — and the deadlock the naive version produces.
Auto-detection
What happens when you leave the mode alone, and how it resolves.