Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

Broker sign-in

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner programUpdated

A client of an identity broker asks for nothing but an email address. The broker sends the person to the member organization that verified the address's domain, the member signs them in with its own screens, and the person comes back to the application signed in at the broker. The screen appears for a client the broker's memberships admit; every other client of the same organization keeps the ordinary sign-in.

The email screen

A single email field under the broker's name, with a Continue button
A single email field under the broker's name, with a Continue buttonOpen in Storybook

The screen wears the broker's branding and asks for a work email address. A login_hint from the application fills it in:

The email field prefilled with alice@acme.example
The email field prefilled with alice@acme.exampleOpen in Storybook

While the address is routed, the form is disabled and the button spins:

The prefilled form, disabled, with a spinner on the button
The prefilled form, disabled, with a spinner on the buttonOpen in Storybook

An address the server cannot take is answered under its field:

Enter a valid email address, under the field holding alice@
Enter a valid email address, under the field holding alice@Open in Storybook

The broker's own branding can stand beside the form, as on every sign-in screen:

The email form beside the broker's branded panel
The email form beside the broker's branded panelOpen in Storybook

Routing to the member

The address goes to the member organization that has verified its domain, when the membership is active and admits the application's client. The broker then sends the browser to the member's own /authorize with the address as login_hint, a fresh state, nonce and PKCE challenge, prompt=login when the application asked for a fresh sign-in, and the application's max_age.

From there the person is on the member's pages: its branding, its password, its second factor, its passkeys, its lockout. Everything on Sign in, Second factor and Passkeys applies as it does for the member's own applications. The member treats the broker's reserved client as its own, so it asks for no consent; any consent to the application is asked at the broker.

Coming back, the broker checks that the answer is for this browser and this member, and that the member's iss, nonce and auth_time hold, then signs the person in to its own linked account. The application's tokens name the member in member_org and member_org_slug.

No organization found

An address whose domain no member has verified, or one verified by an organization that is not a member of this broker, ends here. The broker reveals nothing beyond that no member matched, and offers to try another address:

No organization found, naming bob@unknown.example, with Use a different email
No organization found, naming bob@unknown.example, with Use a different emailOpen in Storybook

The broker's own users end here too: the broker routes only to members. Give them an organization of their own that is a member, with its domain verified.

When it comes back unfinished

A sign-in at the member that comes back refused lands on the email screen again with the reason as a banner:

Sign-in failed: This app can't sign you in through that organization, above the email form
Sign-in failed: This app can't sign you in through that organization, above the email formOpen in Storybook
ReasonWhat happened
not_allowedThere is no active membership admitting this client, at the start or on the way back (it ended during the sign-in), or the member's account is already linked to another of the broker's accounts.
failedThe member's answer could not be accepted: a state from another browser, used twice or expired; the member refused the sign-in; the wrong issuer; a code or ID token that did not verify; or a member sign-in older than the prompt=login or max_age the application asked for.

A failure the server answered is shown the same way:

Something went wrong. Try again., as a banner above the email form
Something went wrong. Try again., as a banner above the email formOpen in Storybook

Every step is in the audit log of both organizations: the routing, the hop, the member's sign-in, and any refusal with its cause.

Related