Sign-in Handoff
On this page
Introduction#
A sign-in handoff moves a session that is already signed in (a marketing site, a web dashboard) to another origin (the Flutter web app, or a mobile app through a deep link) without ever putting a bearer token in a url. The signed-in side mints a short-lived, single-use code; the browser carries the code to the app; the app trades it, unauthenticated, for the same answer a login gives. Throughout this document {prefix} is config('magic-starter.route_prefix').
Feature: Features::signInHandoff() ('sign-in-handoff'). Neither route in this document is registered while the feature is off, and the gate is read when the routes load, so a route:cache freezes it.
Configuration#
Enable the feature in config/magic-starter.php:
'features' => [
\FlutterSdk\MagicStarter\Features::signInHandoff(),
],
The handoff block:
| Key | Env | Default | Meaning |
|---|---|---|---|
code_ttl |
MAGIC_STARTER_HANDOFF_CODE_TTL |
60 |
Seconds a code lives. |
cache_store |
MAGIC_STARTER_HANDOFF_CACHE_STORE |
null |
The cache store that holds the codes; null is the app default. Every web node must share it, since the exchange can land on another node than the mint. |
max_token_age |
MAGIC_STARTER_HANDOFF_MAX_TOKEN_AGE |
null |
Seconds. A mint from a token older than this answers 403 handoff_forbidden; null is no limit. A leaked token can otherwise mint codes and clone itself into sessions that survive its revocation, so a surface that only hands off a fresh sign-up (a landing page) should set a few minutes. |
Mint a Code#
Endpoint: POST {prefix}/auth/handoff
Middleware: auth:sanctum, throttle:magic-starter-auth-handoff (10 a minute per user and address)
The code is minted for the CALLER; nothing in the body can name another user. Because the exchange issues a full-ability token, the caller must hold one already: a guest user, or a token that cannot do everything (tokenCan('*') false), is refused before any code is minted:
Response (403):
{
"message": "Only a fully signed-in account can start a sign-in on another device.",
"code": "handoff_forbidden"
}
Request:
{
"next": "/connect?code=abc"
}
next is optional: the same-app path the app opens after the sign-in. It is refused with 422 on next unless it:
- starts with exactly one
/(so//evil.comandhttp://xare refused), - holds no backslash (a browser reads
/\evilas//evil), - holds no whitespace, separator or control character (a browser strips a tab or a newline, so
/<tab>/evil.comwould become//evil.com), - has no
..path segment, percent-encoded (%2e%2e) included, - is at most 512 characters.
A validation refusal is JSON whatever the request's Accept header says.
Response (201):
{
"data": {
"code": "<64 random characters>",
"expires_in": 60
}
}
Exchange a Code#
Endpoint: POST {prefix}/auth/handoff/exchange
Middleware: throttle:magic-starter-auth-handoff-exchange (10 a minute per address, an IPv6 address collapsed to its /64). No bearer.
Request:
{
"code": "<the code>"
}
Response (200): the login answer for the user who minted the code, plus data.next:
{
"data": {
"user": {
"id": "9b1f...",
"name": "Ada",
"email": "[email protected]"
},
"token": "1|abc...",
"next": "/connect?code=abc"
},
"message": "Login successful"
}
The token records the exchange's IP address and user agent, and a deletion the user scheduled is cancelled exactly as on a login (data.deletion_cancelled and the cancellation message, see Account Deletion).
Response (200), two-factor enabled: the same challenge a login answers, with data.next beside it so the app can finish after the Two-Factor Challenge:
{
"two_factor": true,
"two_factor_token": "eyJpdiI6...",
"data": {
"next": "/connect?code=abc"
}
}
Response (422), every refusal:
{
"message": "This sign-in link has expired. Sign in again.",
"code": "handoff_expired"
}
An unknown, spent or expired code, a code whose user was deleted since, and a code that is missing, not a string or longer than 255 characters all answer this one body: the exchange has no field validation errors. Switch on code, never on message.
Security Properties#
- Single use. The exchange claims a sentinel with the cache's atomic
addbefore it reads the code, so two racing consumers cannot both win, and the code is spent even when a later step refuses. - Short-lived. 60 seconds by default (
handoff.code_ttl). - Hashed at rest. The cache key is
magic-starter:handoff:plus the sha256 of the code, and the record holds only the user id andnext. A cache dump replays nothing. - Second factor respected. The exchange finishes through the same decision a login uses, so a confirmed 2FA is challenged, never skipped.
- No oracle. Every refusal is the one 422 above.
- Bound to its minter. A code signs in only the user whose bearer minted it.
- No escalation. A guest or a restricted-ability token cannot mint, so a code never turns a lesser credential into a full one.
nextstays in the app. See the rules under Mint a Code. The app should still opennextthrough its own router, never as a full url.
Using It from a Browser#
- The signed-in page calls
POST {prefix}/auth/handoffwith its bearer and thenextit wants. A page on another origin than the API needs the API's CORS configuration to allow it; that is the host application's setting. - It sends the browser to the app with the code, for example
https://app.example.com/auth/handoff?code=<code>or a Universal Link / App Link into the mobile app. Send it at once: the code lives a minute. - The app posts the code to
POST {prefix}/auth/handoff/exchange, signs in with the answer (or runs the 2FA challenge), replaces the url so the spent code leaves the history, and opensdata.next.
Overriding the Actions#
| Contract | Default action | Role |
|---|---|---|
IssuesHandoffCodes |
Actions\IssueHandoffCode |
issue(Authenticatable $user, ?string $next): array{code, expires_in}. Mints a code for the caller. |
ExchangesHandoffCodes |
Actions\ExchangeHandoffCode |
exchange(string $code): ?array{user, next}. Spends the code and resolves its user; null for every refusal. |
Bind your own in a service provider, as for every other action contract:
$this->app->bind(ExchangesHandoffCodes::class, MyExchangeHandoffCode::class);