How a login works
A login has two doors, and both lead through the same steps on the server: the same methods, the same rules for sign-up, second factors, terms and access, and the same tokens at the end.
| Embedded login | Hosted page | |
|---|---|---|
| Where it shows | A dialog on your own page | SeekAuth’s page on the issuer host, in your app’s look |
| Endpoint | POST /authorize-challenge, one call per step |
GET /authorize, a redirect there and back |
| Who drives it | The SDK: login() in auth-react, beginLogin() in auth-js |
The browser |
| Clients | First-party spa, web and native clients |
Every spa, web and native client, including any OpenID Connect library |
| Social providers | Always leave through the hosted page’s redirect | Redirect to the provider and back |
| Already signed in | The page keeps its own session, with its refresh token | A session cookie on the issuer host answers without a page |
The embedded login
Section titled “The embedded login”/authorize shows it and sends the browser back with the code.- Your page starts an attempt with a PKCE challenge. SeekAuth answers
403 insufficient_authorizationwith a challenge to render (identifyfirst) and anauth_sessionvalue that names the attempt. - The page sends one step per call: the email address, the code from the email, a password, a passkey, a wallet signature, a second factor, accepting the terms. Each answer is the next challenge, or a refusal with a rejection code and the same challenge again.
- When nothing more is needed, SeekAuth answers
200with an authorization code: one use, 60 seconds. - The page exchanges it at
/tokenwith the PKCE verifier and a DPoP proof, and gets an access token, an ID token and (withoffline_access) a refresh token, all bound to the page’s DPoP key. - The page calls your API with the access token and a fresh proof. Your API verifies the token with the environment’s published keys, without asking SeekAuth.
An attempt lasts 15 minutes however far it got. The auth-react modal does all of this; auth-js exposes it step by step for a UI of your own.
The hosted page
Section titled “The hosted page”Your app sends the browser to /authorize with the usual OpenID Connect parameters (response_type=code, client_id, redirect_uri, scope, state, nonce, and a PKCE code_challenge with code_challenge_method=S256). SeekAuth shows the login there, runs the same steps, and redirects back to your registered redirect_uri with code, state and iss. Your app exchanges the code at /token as above.
If the browser already has a session on the issuer host that is good enough for the request, /authorize answers at once, without a page. prompt=login always asks; prompt=none never shows a page and answers login_required instead; max_age and acr_values=aal2 ask for a recent or a two-step login. See /authorize.
What decides the steps
Section titled “What decides the steps”After each step, SeekAuth works out what is still missing, in this order:
- A first factor: an email code, a password, a passkey, a provider or a wallet, from the methods the environment has enabled.
- The account’s standing: a disabled account is refused.
- A second factor, when the user has one, the environment requires two-step login, or the request asked for
aal2. A user without one, where it is required, sets up an authenticator app first. See Two-step login. - The app’s access: an app that is invite-only or closed lets in only the users it was granted. See Sign-ups and access.
- An email address, when the app needs one and the user has none (after a wallet or a provider that gave none).
- The app’s terms, once per user, when the app has a terms address.
A sign-up is the same attempt: an email code to an address nobody has makes the account, when sign-up is open. Answers are the same for addresses that have an account and addresses that do not, so the login cannot be used to find out who has one.
What your app gets
Section titled “What your app gets”- An access token for one API, with
sub,sid,acr(aal1oraal2),amr(how the user logged in),rolesandpermissions. Without aresource, it is for the client’s default API, or the account API when the client has none. - An ID token with the user’s profile for the scopes granted:
nameandpicturewithprofile,emailandemail_verifiedwithemail. - A refresh token, with
offline_access. It rotates on each use and ends the session if it is ever used twice.
See Tokens and claims.