Sign-in and linking in a popup
Sign people in, or add a way to sign in, in a popup over your page on a laptop, and by a redirect that comes back to the same screen on a phone.
@synqauth/react signs people in, and adds ways to sign in, either by sending the browser to the brand's hosted pages and back (a redirect, the default) or in a popup over your page, which carries on once the person finishes there. Pass display:
redirect: the page leaves for Synq and comes back toreturnTo(this page by default).popup: a popup of about 500 by 640 pixels opens over the page.auto: a popup on a laptop (a fine pointer, a window at least 640px wide, a real browser), a redirect on a phone, a tablet's touch screen and in an app's built-in browser (X's, Instagram's, an Android web view), where a popup opens in another tab or not at all.
import { useAuth } from '@synqauth/react'
export function SignInWithGoogle() {
const { signIn } = useAuth()
return (
<button type="button" onClick={() => void signIn({ method: 'google', display: 'auto' })}>
Continue with Google
</button>
)
}useAuth().link(method, { display }), useLink(method) and useAuth().reauthenticate({ display }) take the same option. useLink and reauthenticate use auto unless told otherwise (adding ways to sign in, signing in again).
How the popup works
Call signIn or link from the tap's own handler. The SDK opens the popup at once, before it awaits anything, so popup blockers let it through, takes away the popup's window.opener, and only then points it at your route mount's sign-in (/api/auth/sign-in?display=popup), or, for a link, at the link request's sign-in. Where the browser blocks the popup anyway, the same sign-in runs as a redirect, with no message.
The popup's last hop is your app's own callback (/api/auth/callback), so the session cookie is set first-party, as for any sign-in. Instead of going back to returnTo, the callback answers a small page that reports on a BroadcastChannel named synq, which every page of your app's origin hears, and closes itself. The page that opened it reads who is signed in again, and so does every other open tab of your app. Nothing uses window.opener: providers' Cross-Origin-Opener-Policy cuts it, and a popup they cut off can't close itself, so its page says "You're signed in. You can close this window." The callback's page sends its own Content-Security-Policy, allowing only its one script by hash; if your app adds a stricter policy to every response, leave your route mount's callback out of it.
signIn answers once the session is the new one's, with { method, kept }, or the error the sign-in ended with: cancelled when the person closed the popup (seen once your page, which lost the focus to the popup, has it back; a browser that tells every page it has the focus, as test and agent browsers do, waits for the popup's own answer instead), or the provider's own code (access_denied when they declined). For a redirect, it answers null as the page leaves.
link answers the way in that joined, one the person didn't have before. It answers cancelled when none did: they closed the popup, chose "Not now", or proved a way in they already had. Where the way in belongs to another account, and they chose to sign in to that account instead, it answers account_switched: nothing joined theirs, and the session is now the other account's.
Keeping your page's state
A redirect reloads your app. To come back to the same screen, pass keep, small JSON of your own (at most 4 KB), such as which panel was open:
await signIn({ method: 'telegram', display: 'auto', keep: { panel: 'account', step: 'alerts' } })It stays in this tab's sessionStorage across the redirect. Back on the page, useRedirectResult() hands it back once, with what left the page (kind: sign-in, link or reauthenticate, and the method) and the error your callback came back with (synq_error), until you call consume(). After a popup, kept is in the call's own answer.
A sign-in that finished, in a popup or by a redirect, also carries it on its event: useSignInEvent().kept, next to isNewUser and method, until you consume() the event. A link's keep, or a sign-in that came back with an error, doesn't. The event needs the app's sign-in claims on (Build your own sign-in panel).
import { useRedirectResult } from '@synqauth/react'
import { useEffect } from 'react'
export function ReopenPanel({ open }: { open: (panel: string) => void }) {
const returned = useRedirectResult()
useEffect(() => {
const kept = returned?.kept as { panel?: string } | undefined
if (kept?.panel) open(kept.panel)
returned?.consume()
}, [returned, open])
return null
}Signing in again
Some changes want a recent sign-in: removing a way in, for one, answers fresh_sign_in_required when the person last signed in more than 5 minutes ago. useAuth().reauthenticate() signs the person who is signed in now in again, without leaving your page where a popup fits:
import { useAuth, useRedirectResult } from '@synqauth/react'
import { useEffect, useState } from 'react'
export function RemoveWallet({ wallet }: { wallet: string }) {
const auth = useAuth()
const returned = useRedirectResult()
const [confirming, setConfirming] = useState(false)
// Back from signing in again by a redirect: finish the removal it was for.
useEffect(() => {
const kept = returned?.kept as { remove?: string } | undefined
if (returned?.kind !== 'reauthenticate' || kept?.remove !== wallet) return
returned.consume()
if (!returned.error) void auth.wallets.remove(wallet)
}, [returned, auth, wallet])
async function remove() {
const result = await auth.wallets.remove(wallet)
setConfirming(result.error?.code === 'fresh_sign_in_required')
}
// Its own tap: the popup opens before anything is awaited.
async function confirm() {
const again = await auth.reauthenticate({ keep: { remove: wallet } })
if (again.error || !again.data) return
setConfirming(false)
await auth.wallets.remove(wallet)
}
return confirming ? (
<button type="button" onClick={() => void confirm()}>
Confirm it’s you
</button>
) : (
<button type="button" onClick={() => void remove()}>
Remove
</button>
)
}It runs a fresh sign-in at the brand (prompt=login), straight to method when you name one (reauthenticate({ method: 'google' })), else on the brand's page with every way in. Call it from a tap's own handler, before anything is awaited, as with signIn. A browser that doesn't carry the tap across an awaited request, Safari among them, blocks a popup opened after one, and the sign-in again runs as a redirect. That's why the example asks first and confirms on a second tap. In a popup it answers once the session is the fresh one, so the change can go again at once. By a redirect it answers null as the page leaves, and comes back with kind: 'reauthenticate' and your keep in useRedirectResult(): finish the change there.
Only the same person counts. If someone else signs in at the provider, your route mount ends what that sign-in made at once: their session at the brand in this browser, then their grant. It keeps the session as it was and answers other_account. It answers not_signed_in when nobody is signed in, or when the person was signed out before the sign-in again finished, and cancelled when they closed the popup.
With a wallet on the person's profile, useWalletSignIn().reauthenticate() from @synqauth/solana/react does the same with one signature and no page.
Without React
Any server that answers the same routes as @synqauth/nextjs can run the popup: GET /sign-in takes display=popup with attempt, the page's id for this popup (8 to 64 of A-Z a-z 0-9 _ -), and POST /link takes them in its JSON body. The callback then posts { type: 'synq:popup', attempt, ok, error? } on the synq channel. GET /sign-in?reauthenticate=true signs the person signed in now in again: it takes no prompt but login and no intent, and its callback keeps the new session only when its ID token names the same sub, still signed in there. Otherwise it ends the brand's session that sign-in made (synq_session_revocation_endpoint, with its ID token) and revokes its refresh token.
Adding and removing ways to sign in
Let a person add a wallet, an email address or a provider account to their account, and remove one.
One brand, many apps vs several brands
Should people use one account across your products? Yes means one brand with an app for each product; no means a brand for each.