Introduction
The heart of cross-site single sign-on (SSO) is this "handoff token." It's the mechanism for safely handing over a certificate that says "this person is already logged in" at the instant a logged-in user moves to another site.
Handing over a certificate sounds simple, but on the web you have to design it assuming that slip of paper might be stolen or forged. In this article I'll explain what goes into a handoff token, how it's signed, and how we make it a "single-use item valid only for a moment."
What Goes Into the Token
The Contents: "Who, Where, Until When"
A handoff token is a small bundle of information in itself. At minimum, it carries elements like these.
The important thing is to not put secrets like passwords into the token. Keep it strictly a temporary permit that says "you may carry over this user's login," so that even if it leaks, the damage is contained.
Why Keep It Minimal
The token travels to another site riding in the URL. That means it may end up in browser history and server access logs.
That's exactly why the information you put in it should only be "things that are tolerable if they leak." Even the user identifier is safer as a reference value used solely for the hand-off, rather than the internal ID itself. Keeping the contents minimal is a solid security measure in its own right.
Preventing Tampering with HMAC Signatures
Signing with a Shared Secret
To guarantee the token wasn't rewritten in transit, we use an HMAC signature. This computes a unique signature string from the token's contents using a secret key (the secret) shared across all sites.
Site A computes a signature over the token body with the shared secret and appends it
Site B recomputes the signature from the received token body using the same secret
If its own computed signature matches the one attached, there was no tampering
A third party who doesn't know the secret can't produce a valid signature even if they rewrite the contents. So tricks like "quietly swap just the user ID for someone else" simply don't work.
Why HMAC
Signing and encryption are different
An HMAC signature doesn't encrypt the token. The contents stay readable; it only guarantees "no tampering." The goal isn't to keep the contents secret but to prevent forgery, so this is enough.
We chose shared-secret HMAC rather than a heavy scheme like public-key crypto because all the sites are under the same operator's control, and we could safely share the secret. The simpler the mechanism, the fewer operational mistakes.
Preventing Reuse with Short Life and Single-Use
Short Expiry (TTL)
Even if signing prevents forgery, there's still a chance the legitimate token itself gets stolen. This is where a short expiry comes in.
A handoff token exists only for the few to a dozen or so seconds of moving between sites. So we set the expiry extremely short. Even if it's stolen, by the time the attacker tries to use it, it's long since expired. A long-lived token is an attack target just by existing.
One-Time (Single-Use)
A stolen token can be used any number of times within its expiry. Replay attacks succeed
A token used once for verification is invalidated. A second use of the same token always fails
On top of the short expiry, we layer the constraint "once used, never usable again." The receiving side records the one-time ID of a token that passed verification, and rejects it if the same ID arrives again. This shuts down replay attacks (reusing a stolen token).
The Idea of Defense in Depth
Signature, TTL, and single-use each prevent a different attack. The signature stops tampering, the TTL stops delayed abuse, and single-use stops reuse. Even if one is broken, the others remain — that's the defense-in-depth mindset.
Security is often stronger as "a stack of several decent measures" than "one perfect measure." The handoff token is a fine example of that.
Conclusion
A handoff token is a "single-use permit" valid only for the instant of crossing between sites. The design essentials were:
- Minimal contents: no secrets — only the info needed for the hand-off
- HMAC signature: detect tampering with a shared secret
- Short TTL: so short that a stolen token can't be used in time
- One-time: invalidate after a single use to prevent reuse
How the receiving side actually verifies this token and establishes a session is covered in "SSO Callback and Session Establishment Flow." For where SSO fits overall, see "Single Sign-On Across Multiple EC Sites."