Apps that share accounts
Several products of yours can share one set of accounts: someone signs up in one and uses the others with the same account, and arrives signed in when moving between them. In SeekAuth that is an app group.
What a group shares, and what each app keeps
Section titled “What a group shares, and what each app keeps”A group has two environments, production and development, and everything about people lives there, shared by the group’s apps:
- the users, their identities, second factors and sessions;
- the login methods, the security policy and the session lifetimes;
- the signing keys, and the issuer: one login address per environment,
https://your-group.auth.dev.seek.servicesandhttps://your-group-dev.auth.dev.seek.services, named after the group’s slug.
Each app of the group keeps what is about the product:
- its name, which its users see on the login and in the emails it causes;
- its look (an app theme replaces the environment’s, see Branding);
- its access mode (open, invite only or closed), its terms, and whether it needs an email address (see Sign-ups and access);
- its clients, its APIs and their permissions, and its roles.
An app created on its own is a group of one, with the app’s name and slug. Most apps never need more.
Adding an app to a group
Section titled “Adding an app to a group”In the dashboard, add the app from the group’s page. With the management API:
{ "name": "Storefront", "slug": "storefront", "access_mode": "open" }slug is optional (it follows from the name), and access_mode defaults to open. The answer has the app’s id, the group’s two environments and development_client_id: like every new app, it gets a single-page app client in development, {slug}-dev-spa, to start with. See Apps and groups.
The app’s slug is its own handle; the login address stays the group’s. A plan includes a number of apps per group: 3 on Free, 10 on Pro, 25 on Scale. See Plans and limits.
Who may use which app
Section titled “Who may use which app”A user who signs up through one app is a user of the group. Whether they may use another app of it is that app’s access mode:
| Access mode | Who gets in |
|---|---|
open |
Every user of the group. Sign-up is offered through this app when the environment’s sign-up is open. |
invite_only |
Only users the app was granted to (Access page, or POST …/apps/:app/users), and not disabled. |
closed |
Only users granted before; it takes no new grants. |
The first time a user enters an app, the app_user.joined event is recorded (and sent to webhooks). A user an app refuses gets access_denied, decided only after they have proven who they are.
Roles can belong to one app or to the whole group: a group-wide role is carried by tokens for every app’s APIs. A client of one app can be allowed to call another app’s API. See Roles and permissions and Calling your API.
Carrying a login to another app
Section titled “Carrying a login to another app”Apps of a group on different domains do not share cookies. A session ticket carries the login across: the app the user is in asks for a ticket for the other app’s client, and the other app redeems it at the issuer, which signs the user in there with the same login.
From a single-page app
Section titled “From a single-page app”import { useAuthStore } from '@seek-services/auth-react'
// in the app the user is signed in toconst ticket = await useAuthStore.getState().createSessionTicket('storefront-spa')window.location.assign(`https://shop.example.com/?ticket=${encodeURIComponent(ticket)}`)// in the other app, on the page the link opensconst ticket = new URLSearchParams(window.location.search).get('ticket')if (ticket) await useAuthStore.getState().loginWithRedirect({ sessionTicket: ticket })How the ticket reaches the other app is yours to choose; here it travels in the query string of the link, and is spent within a minute. loginWithRedirect goes to the issuer’s /authorize with the ticket; the issuer answers with a code, and the app is signed in. auth-js has the same createSessionTicket(targetClientId) and loginWithRedirect({ sessionTicket }) on AuthClient.
From a web client
Section titled “From a web client”A web client’s backend mints the ticket, since it holds the tokens. auth-react’s createSessionTicket calls the backend’s /auth/session-ticket route for you, and a backend can call WebClient::session_ticket(&headers, "storefront-spa") itself. The route answers only the app’s own pages: same-origin requests, or the one origin set with with_page_origin.
The rules
Section titled “The rules”- A ticket is for one client of the same environment (a web, single-page or native client), works once, and only within 60 seconds.
- It comes in a link, and a link can come from anyone. Unless the browser is already signed in as that user, the issuer first asks “Continue to Storefront?” with a button “Continue as [email protected]”; when another account is signed in there, it asks “Switch account?”. Only the answer given in that same browser counts. Confirming a switch ends the other account’s session.
- With
prompt=nonethe question cannot be asked, and the answer isinteraction_required. Withprompt=loginthe ticket is ignored. - The new login has the same strength as the one it came from: its
acr,amrandauth_time.
See Session tickets for the endpoint.
Changing a group’s slug
Section titled “Changing a group’s slug”The slug names the login address, so changing it (PATCH /v1/groups/:id, admin role, with the current slug repeated in confirm) moves both environments to new hosts and changes iss for every client of every app of the group. Every app has to be given its new issuer. A slug a group gives up stays held for its workspace, so nobody else can answer on the old address. A custom domain is not affected.