@seek.services/auth-react
v0.1.0
Published
React SDK of SeekAuth: AuthProvider, the login modal, a session store, and components for passkeys, two-step login and linked accounts
Maintainers
Readme
@seek.services/auth-react
The React SDK of SeekAuth: the provider that
connects an app to its auth environment, the login modal, a store with the
session, and ready-made components for an account settings page (passkeys,
two-step login, linked accounts). The same login UI is what SeekAuth serves as
its hosted login page. It is built on
@seek.services/auth-js,
which it installs with it.
npm install @seek.services/auth-reactIt needs React 18 or 19 (react and react-dom), and ships as an ES module
with its TypeScript types.
A login in a few lines
You need an app in the SeekAuth dashboard. Its
development environment comes with a single-page app client, and its
Quickstart page shows the issuer and the client id. Development accepts
any page on http://localhost:<port>; in production, list your page under
the client's allowed origins and redirect URIs.
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { AuthProvider, useAuthStore } from '@seek.services/auth-react'
function App() {
const { user, status, login, logout } = useAuthStore()
if (status === 'loading') return null
if (!user) return <button onClick={login}>Log in</button>
return <button onClick={logout}>Log out {user.email}</button>
}
createRoot(document.getElementById('root')!).render(
<StrictMode>
<AuthProvider issuer='https://your-app-dev.auth.seek.services' clientId='your-app-dev-spa'>
<App />
</AuthProvider>
</StrictMode>,
)Log in opens the login dialog on your page: an email code by default, and
every other method the environment enabled. The session survives reloads, and
authFetch calls your API with the user's token:
import { authFetch } from '@seek.services/auth-react'
const res = await authFetch('https://api.your-app.com/orders', { resource: 'orders-api' })Documentation
- React single-page app quickstart
- auth-react reference
- An app with its own backend
- Account settings for your users
- Changelog
@seek.services/auth-react and @seek.services/auth-js are released
together and always carry the same version.
Styles
The stylesheet is added to the page by <AuthProvider>. Every rule is scoped
to .seek-auth, so nothing else on the page changes. The same rules are also
a file, @seek.services/auth-react/styles.css, for an app that loads its
styles itself (a Content Security Policy without inline styles, for one).
Appearance comes from the environment's theme (dashboard, Appearance) and
follows the light or dark scheme of the device.
<AuthProvider>
Renders the login modal and, on mount, finishes a redirect-door return or restores the stored session.
| Prop | Meaning |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| issuer | The environment's URL, e.g. https://linkpay.auth.seek.services. |
| clientId | The client registered in the dashboard. |
| backend | Web clients: base path of the backend's auth routes, e.g. /auth. The backend then holds the tokens and the browser only its cookie. |
| redirectUri | Where social logins return to. Defaults to the page the login started on. |
| postLogoutRedirectUri | Where the browser returns to after the logout of a redirect-door session. Defaults to the page the logout started on. |
| scope | Defaults to openid profile email offline_access. |
useAuthStore
A zustand store: useAuthStore() in a component, useAuthStore.getState() anywhere.
| Member | Meaning |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| user | The signed-in user from the ID token (id, email, acr, amr, authTime, …), or null. |
| status | loading, authenticated or unauthenticated. |
| error | Why the last redirect-door return or session restore failed. |
| login() | Opens the modal. Resolves with the user, or null when it was closed. |
| logout() | Ends the session. |
| stepUp({ acr, maxAge }) | Opens the modal for a step-up of the running session; the server asks only for what is missing. |
| getAccessToken({ resource }) | A valid access token (SPA clients). With resource, one for that API. |
| createSessionTicket(targetClientId) | A ticket that signs this user in at another app of the group. |
| loginWithRedirect(options) | Sends the browser through the redirect door (the hosted page). |
Functions
| Function | Meaning |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| authFetch(input, init) | fetch for the app's API calls: SPA clients get the access token and a DPoP proof added, web clients send their cookie. |
| withStepUp(action) | Runs an account call; when the server answers step_up_required, sends the user through the step-up it asked for and makes the call once more. |
| sendEmailCode(email), verifyEmailCode(code) | Whitelabel email-code login, without the modal. A second factor still opens it. |
| loginWithPasskey() | Whitelabel passkey login: the browser's own dialog with the passkeys it holds for the environment's passkey domain. Rejects with passkey_cancelled when the dialog is closed. |
| listWallets(chain?), loginWithWallet(name?, { chain }) | Whitelabel wallet login: Sign In With Solana (the default), or Sign-In with Ethereum with chain: 'evm'. |
| loginWithProvider(provider) | Starts a social login (google, github, …, custom-…) through the redirect door. |
| passkeysSupported(), passkeyAllowedHere(rpId), conditionalMediationAvailable() | What this browser and this page can do with passkeys. |
Login methods in the modal
The modal and the hosted page render exactly the methods the environment enabled. Two of them depend on the page they run on:
- Passkeys belong to the environment's passkey domain (dashboard, Login
methods) and browsers use them on pages of that domain only. The login UI
offers "Sign in with a passkey", lists passkeys in the autofill of the email
field, and asks for the passkey as a second step only when the page's host
is that domain or under it and the browser has WebAuthn; elsewhere it shows
nothing about passkeys. A domain of one label (
localhost) covers that host alone. - Wallets: Solana wallets are found through the Wallet Standard registry,
EVM wallets through EIP-6963 (and
window.ethereumwhere nothing announces itself). With both families enabled they share one chooser, each entry labelled with its family.<LoginFlow wallets={…}>takes another source.
<Passkeys />
The signed-in user's passkeys, ready for an app's settings page. Put it
anywhere inside <AuthProvider>:
import { Passkeys } from '@seek.services/auth-react'
function SecuritySettings() {
return (
<section>
<h2>Security</h2>
<Passkeys />
</section>
)
}What it does:
- Lists each passkey with its name, when it was added and last used, and a "Synced" hint when the user's platform keeps it on more than one device.
- Add a passkey explains what changes (a passkey logs the user in on its own, and from then on every login by another way finishes with the passkey or a recovery code, exactly like an authenticator app), suggests a name from the device ("Mac", "iPhone", "Windows PC", …) and has the browser make the passkey.
- When the passkey is the account's first second factor, the server answers with ten recovery codes. They are shown once, with "Copy codes" and "Download codes", in a dialog that closes only with "I saved them".
- Rename and Remove, the latter after a confirmation.
- Adding and removing need a login within the last ten minutes at the user's
highest level. When the server asks for one (
step_up_required), the login modal opens for exactly that step-up and the change is then made once more. - "Add a passkey" is disabled, with the reason beside it, when the browser has no WebAuthn, when the environment has no passkey domain, when this page is not under that domain, and when the account has as many passkeys as it may (ten).
It takes the look of the login UI: the environment's theme, light and dark.
| Prop | Meaning |
| ----------- | ------------------------------------------------------------- |
| title | The panel's heading. Defaults to Passkeys. |
| className | Added to the panel's root element, for the app's own layout. |
The app's pages have to be on the environment's passkey domain, and their
origin one of the client's allowed origins (in a development environment any
http://localhost:<port> is). SPA clients call the issuer's account API with
their own token. Web clients (backend='/auth') go through the backend's
/auth/account/* route, which auth-client's WebClient mounts; that route
passes the server's refusal on without the header that says what a step-up
has to prove, so the component then asks for a fresh login.
usePasskeys()
The same data and actions for an app that draws its own page:
const { status, passkeys, unavailable, add, rename, remove } = usePasskeys()| Member | Meaning |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| status | loading, ready or error (then error says why). |
| passkeys | { id, name, created_at, last_used_at, backed_up, transports }[]. |
| rpId, max | The passkey domain (null: none) and how many passkeys an account may have. |
| unavailable | Why none can be added here: unsupported, not_configured, wrong_domain, limit, or null. |
| steppingUp | The login modal is open for a step-up one of the calls needed. |
| add(name?) | Makes a passkey on this device and stores it. Resolves with { passkey, recovery_codes? }; show the codes and have the user save them. |
| rename(id, name), remove(id) | Change the list. All three run the step-up themselves and try once more; they reject with StepUpRequiredError when the user closes it. |
| reload() | Reads the list again. |
add rejects with an AuthError whose error is passkey_cancelled when
the user closed the browser's prompt (nothing to show), passkey_exists when
this device already holds one of the account's passkeys, and the server's own
code otherwise.
<TwoStep />
Two-step login with an authenticator app, ready for an app's settings page
inside <AuthProvider>, beside <Passkeys /> or without it:
import { LinkedAccounts, TwoStep } from '@seek.services/auth-react'
function SecuritySettings() {
return (
<section>
<LinkedAccounts />
<TwoStep />
</section>
)
}What it does:
- Set up an authenticator app shows the key as a QR code and as text. Nothing is stored until a code of the app confirms it; the sixth digit typed is the answer. The server then answers with the recovery codes, shown once in a dialog that closes only with "I saved them".
- Once it is on: Remove, after a confirmation, and New codes, which says first that the saved ones stop working. An app that requires two-step login refuses to remove the only second step, and the panel says so.
- An account whose second step is a passkey has recovery codes too: the panel lists them and still offers the authenticator app.
- Every change needs a login within the last ten minutes at the user's
highest level; the step-up runs as in
<Passkeys />.
Props: title (defaults to Two-step login) and className.
useTwoStep() gives an app that draws its own page status, totp,
passkeys, recoveryCodesLeft, steppingUp, reload(), and start(),
confirm(setup, code), remove() and newRecoveryCodes(). confirm and
newRecoveryCodes resolve with the codes: show them and have the user save
them.
<LinkedAccounts />
The ways the user can log in: the email address and every provider linked to the account, with Link … for each provider the environment enabled that the account has no login with yet, and Unlink after a confirmation. The email address is the account's own and is not unlinked; the server keeps the last way to log in whatever is asked.
Linking leaves the page: the browser goes to the provider and comes back to
the address it left, with #link_code=… (or #link_error=…). The panel
takes that out of the address and finishes the link, so the page it is on
has to render it again when the browser returns, at the same address. That
page's origin has to be one of the client's allowed origins, and its address
at most 200 characters. Nothing has to be registered at the provider: the
return goes through the callback address its login already uses.
A link can be sent to anyone, so going through the provider proves nothing about the account: the code the browser comes back with only counts in a request of the user who started the link. Somebody who follows another person's link ends with a code that is of no use to either.
Props: title (defaults to Linked accounts) and className.
useIdentities() gives status, identities
({ id, provider, subject, email, name, created_at, last_used_at }[]),
available (the providers that can still be linked, { id, label }),
returned (what a return from a provider did: { status: 'linked', identity }
or { status: 'failed', error }), steppingUp, reload(),
link(provider), which leaves the page, and unlink(id).
<LoginFlow> and <ThemeRoot>
<LoginFlow client config onComplete> is the login UI itself, for a page
that hosts it without the modal: it renders whichever challenge the server
last returned and sends the answer back. <ThemeRoot theme> is the
.seek-auth element the stylesheet hangs off; <LoginFlow> brings its own
when it stands alone.
