Files
iam/pkg/schema/federation.go
zeekay 9798803a4f unlink had no counterpart, so a provider could only be linked by coincidence
There was no way to CONNECT a provider. linkOrProvision has three arms — match
the provider subject, match an address the account already proved, else provision
— so a link only ever happened as a side effect of that address coincidence. A
person whose GitHub address differs from their account address got a SECOND
account instead of a link, and once unlinked, re-linking needed the same
coincidence, which nobody can arrange from a settings page. The security half was
right (never link on an unproven address); the missing half was the deliberate,
authenticated link.

POST /v1/iam/link runs the SAME federation transaction a sign-in runs — one
begin, one IdP leg, one callback, one atomic burn, the same browser binding — and
differs in one field: the transaction carries the caller's Subject, so the
callback attaches the verified identity to THAT account instead of resolving one.
There is no second IdP round-trip to keep in step with the first, and a link
mints no code and opens no session, because a link is not a sign-in.

WHY A POST AND NOT A LINK IN A PAGE, since the shortcut is tempting: attaching a
provider to a signed-in account is an account takeover if an attacker can cause
it — their identity, your account, and afterwards they sign in as you. A
top-level GET is exactly what an attacker can cause, because a Lax cookie rides a
navigation, so having the callback attach to whatever session it finds would be
that vulnerability. Intent is proven instead by a request their page cannot make:
a same-site JSON POST that authenticates as the account it will act on, with the
subject fixed server-side from the credential already held and never readable
from a request.

The rest is the law already in the file: the return target is validated against
the application's registered list (so this is not an open redirector), the
reserved-org and tenant gates are the federation ones, and a provider subject
already on another account is refused rather than moved.
2026-08-07 23:26:03 -07:00

76 lines
3.8 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package schema
import "github.com/hanzoai/orm"
// FederationState is ONE in-flight identity-federation transaction: the
// server-side memory that spans the browser's round-trip to an external identity
// provider (Google/GitHub, …) during an Authorization-Code federation, where
// iam acts as the OIDC/OAuth2 Relying Party. It is what lets the IdP callback
// RESUME the original iam authorize request, and it is the CSRF / replay guard
// for that callback.
//
// Identity is the (Owner, Name) pair; Name IS the opaque 256-bit `state` value
// iam sends to the IdP, so the callback resolves the transaction by the state
// the IdP reflects back. The row is single-use (Used) and expiring (ExpireIn),
// and is bound to the initiating browser by BindHash — the SHA-256 of a
// per-transaction anti-forgery cookie — so a state that is stolen or injected
// into another browser cannot complete (login-CSRF / session-fixation defense).
//
// No IdP access/ID tokens are persisted here: only the material needed to VERIFY
// the IdP response (the IdP-leg PKCE verifier and, for OIDC, the nonce checked
// against the id_token) and to RESUME the app-leg (the original authorize
// parameters, so the callback mints an iam authorization code identical to the
// one a password login mints). The row is burned on consume.
type FederationState struct {
orm.Model[FederationState]
// (Owner, Name) is the natural key. Owner is the federated Provider's owner
// (e.g. "admin"); Name is the opaque `state` token — the value the IdP
// reflects back and the callback looks the transaction up by.
Owner string `json:"owner" orm:"index"`
Name string `json:"name" orm:"index"`
CreatedTime string `json:"createdTime" orm:"index"`
// Provider is the Provider row NAME this transaction federates to
// (e.g. "provider-google") — the connector whose callback this state authorizes.
Provider string `json:"provider"`
// App-leg: the ORIGINAL iam authorize request, stashed so the callback can
// resume it. The minted iam code is bound to CodeChallenge/RedirectUri/Nonce
// exactly as a password-login code is, so the relying party's existing PKCE
// code→token exchange completes unchanged. AppState is echoed on the final
// redirect back to the relying party.
ClientId string `json:"clientId"`
RedirectUri string `json:"redirectUri"`
AppState string `json:"appState"`
Scope string `json:"scope"`
AppNonce string `json:"appNonce"`
CodeChallenge string `json:"codeChallenge"`
CodeChallengeMethod string `json:"codeChallengeMethod"`
Resource string `json:"resource"`
// Subject is the account this transaction ATTACHES the verified provider
// identity to: "<org>/<name>", set from the CALLER's already-proven identity
// when a signed-in person deliberately connects a provider (PathLink), and
// empty for a sign-in. It is the whole difference between the two flows, and it
// is never read from a request — a transaction that could be told whose account
// to attach to would be an account takeover with one forged parameter.
Subject string `json:"subject,omitempty"`
// IdP-leg verification material (single-use; never leaves the process, never
// logged). IdpVerifier is the PKCE code_verifier for the IdP token exchange;
// IdpNonce is the nonce sent to an OIDC IdP and checked against the returned
// id_token; BindHash is the SHA-256 of the browser anti-forgery cookie value.
IdpVerifier string `json:"idpVerifier"`
IdpNonce string `json:"idpNonce"`
BindHash string `json:"bindHash"`
// ExpireIn is the unix expiry; Used marks the transaction consumed so a
// replayed callback completes nothing.
ExpireIn int64 `json:"expireIn"`
Used bool `json:"used"`
}