Skip to content

Sign-in Handoff

View raw .md

How a session that is already signed in mints a short-lived, single-use code that another origin or a mobile app trades for a sign-in, without a bearer token ever appearing in a url.

On this page

Quick Reference#

Enable Features::signInHandoff(). {prefix} is the route_prefix config value.

Endpoint Auth Does
POST {prefix}/auth/handoff auth:sanctum The signed-in side mints a code and passes the next path it wants opened.
POST {prefix}/auth/handoff/exchange none The app spends the code and receives the same answer a login gives.
Setting Default Meaning
handoff.code_ttl 60 Seconds a code lives.
handoff.cache_store null The cache store that holds the codes; every web node must share it.
handoff.max_token_age null Seconds; a mint from an older token answers 403 handoff_forbidden.

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:

php
'features' => [
    \AnilcanCakir\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):

json
{
    "message": "Only a fully signed-in account can start a sign-in on another device.",
    "code": "handoff_forbidden"
}

Request:

json
{
    "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.com and http://x are refused),
  • holds no backslash (a browser reads /\evil as //evil),
  • holds no whitespace, separator or control character (a browser strips a tab or a newline, so /<tab>/evil.com would 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):

json
{
    "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:

json
{
    "code": "<the code>"
}

Response (200): the login answer for the user who minted the code, plus data.next:

json
{
    "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:

json
{
    "two_factor": true,
    "two_factor_token": "eyJpdiI6...",
    "data": {
        "next": "/connect?code=abc"
    }
}

Response (422), every refusal:

json
{
    "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 add before 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 and next. 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.
  • next stays in the app. See the rules under Mint a Code. The app should still open next through its own router, never as a full url.

Using It from a Browser#

  1. The signed-in page calls POST {prefix}/auth/handoff with its bearer and the next it 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.
  2. 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.
  3. 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 opens data.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:

php
$this->app->bind(ExchangesHandoffCodes::class, MyExchangeHandoffCode::class);

Gotchas#

Mistake Fix
Putting a bearer token in the url Put the code there; it is single use and lives handoff.code_ttl seconds.
Sending the browser to the app late The code expires after 60 seconds by default. Redirect at once.
Running web nodes on separate cache stores Point handoff.cache_store at one shared store, or an exchange that lands on another node finds no code.
Minting from a guest or a restricted-ability token It is refused. A code never upgrades a lesser credential into a full one.
Caching the routes before enabling the feature The gate is read when the routes load, so a route:cache freezes it. Rebuild the cache after you change features.
Opening next as a full url Open it through the app's own router.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.