Files
iam/internal/oidc/federation.go
wbin90620 9d4d6b3d0d A GitHub sign-up is named after its GitHub login when the name is free
A federated account was always named from its email's local part, so a
person who signed up with GitHub as Darkhorse7stars became "wbin90620" here,
a name they never chose. GitHub keeps a handle of its own: the login, which
the person chose and GitHub holds unique.

- githubExchange carries the login on the federated identity (handle).
- provisionFederatedUser names the account through federatedName: the
  handle, lowercased by schema.Username, when it is a usable username and
  nobody here holds it (nameTaken, as allocateName asks); otherwise
  allocateName's address-derived name and numbered walk, unchanged. A held
  handle is not numbered, because "octocat2" reads as another GitHub user.
- Google keeps no handle, so a Google sign-up is named as before; a display
  name ("Grace Hopper") is still never a username.

TestProvisionFederatedUser_TakesTheProvidersHandleWhenFree covers a free
login, a held one, an empty one and Google.
2026-10-20 12:04:26 -04:00

846 lines
38 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package oidc
import (
"context"
"crypto/subtle"
"encoding/json"
"errors"
"fmt"
"log"
"net/http"
"net/url"
"strings"
"time"
policy "github.com/hanzoai/authz"
"github.com/hanzoai/orm"
fiber "github.com/zap-proto/fiber/v3"
"github.com/zap-proto/zip"
"github.com/hanzoai/iam/internal/mfa/factor"
"github.com/hanzoai/iam/internal/sessions"
"github.com/hanzoai/iam/internal/users"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
// Identity federation — iam as an OIDC/OAuth2 Relying Party to external IdPs.
//
// A social sign-in is a DETOUR inside the ordinary authorization-code flow. The
// authorize endpoint, having already validated the client and its EXACT
// redirect_uri (so there is a trusted target before anything is trusted), hands
// a request that names a `provider` to beginFederation, which stashes the whole
// app-leg request server-side and sends the browser to the IdP. When the IdP
// returns to the fixed callback, iam verifies the response, LINKS or PROVISIONS
// a local user, and mints ITS OWN authorization code — bound to the original
// PKCE challenge, redirect_uri, and nonce — exactly as a password login would.
// The relying party's existing PKCE code→token exchange then completes unchanged.
//
// The whole surface lives on the PUBLIC group (before the Guard): it
// self-authenticates through the single-use, browser-bound, expiring state, not
// a bearer. Every failure is fail-closed; no IdP token or secret is ever logged.
// PathFederationCallback is the fixed IdP return endpoint. One callback for every
// provider — the provider is recovered from the server-side transaction the
// state keys, never from a spoofable URL segment. It is the redirect_uri iam
// registers with each external IdP.
const PathFederationCallback = "/v1/iam/oauth/callback"
// PathMfaVerify is the hosted 2FA PAGE (a route in the SPA, not an API path) the
// federation callback sends a second-factor-enrolled user's browser to. The page
// collects the factor and POSTs it to PathFederationMfa; the challenge id rides
// the httpOnly cookie the callback set, never a URL segment.
const PathMfaVerify = "/login/mfa"
// fedCookieName is the per-transaction anti-forgery cookie the begin leg sets and
// the callback checks — the browser binding that defeats login-CSRF.
//
// The `__Host-` prefix is what makes it a binding, for the reason the session
// cookie carries one (sessions.CookieName): a browser stores a `__Host-` cookie
// only Secure, at Path=/ and with no Domain, so no sibling host can set it. A
// sign-in origin with siblings (hanzo.ai, whose *.hanzo.ai hosts include
// published sites) would otherwise let one of them Set-Cookie `hanzo_fed=<the
// attacker's own transaction>; Domain=hanzo.ai`, send the victim to the
// attacker's callback URL, and have the victim's browser complete the attacker's
// sign-in — login CSRF. Path=/ is the prefix's price: the cookie rides every
// request to the sign-in origin for the ten minutes it lives, HttpOnly.
const fedCookieName = "__Host-hanzo_fed"
// fedStateTTL bounds how long a federation transaction (and its cookie) is
// redeemable. Short, because it only has to survive one IdP round-trip.
const fedStateTTL = 10 * time.Minute
// routeFederation registers the IdP callback on the PUBLIC group r. GET only: the
// IdP returns via a top-level browser redirect (Google/GitHub), on which the
// SameSite=Lax browser-binding cookie IS sent. A cross-site form_post (POST) would
// NOT carry a Lax cookie, so the bind check would fail closed — rather than ship a
// half-working POST path, form_post support is a deliberate future change (it needs
// SameSite=None + its own CSRF analysis). The callback self-authenticates via the
// single-use state + the browser cookie.
//
// The sign-in origins the callback answers at are installed at boot, with the
// issuers they are judged against (server.RequireIssuer).
func routeFederation(r *zip.Group, db orm.DB) {
r.Raw(http.MethodGet, PathFederationCallback, federationCallbackHandler(db))
}
// beginFederation starts an Authorization-Code federation. It is entered from
// authorizeHandler ONLY after the client_id and exact redirect_uri are validated
// and the response_type/PKCE policy is enforced, so a protocol error may now be
// redirected to the trusted redirect_uri (RFC 6749 §4.1.2.1). It resolves the
// named provider, mints a single-use transaction, sets the browser-binding
// cookie, and sends the browser to the IdP.
func beginFederation(c *zip.Ctx, db orm.DB, app *schema.Application, q authorizeRequest, method string) error {
ctx := c.Context()
// A federated (external) identity may never be minted into a reserved system
// org (the SuperAdmin vector) nor into a tenant an attacker-owned app has no
// right to serve. Refuse BEFORE starting the round-trip (fail fast, no IdP
// traffic) — defense in depth behind the application-write org authorization.
if !federationOrgAllowed(app) {
return authorizeErrorRedirect(c, q, "access_denied", "federation is not permitted for this application")
}
store.EnrichProviders(ctx, db, app)
prov := federationProvider(app, q.provider)
if prov == nil {
return authorizeErrorRedirect(c, q, "invalid_request", "unknown or unavailable provider")
}
if idpKind(prov) == "" {
return authorizeErrorRedirect(c, q, "invalid_request", "provider is not a supported federation type")
}
if _, ok := connectorFor(prov.Type); !ok {
return authorizeErrorRedirect(c, q, "invalid_request", "provider has no local identity binding")
}
state, err := newOpaqueToken()
if err != nil {
return authorizeErrorRedirect(c, q, "server_error", "")
}
verifier, err := newOpaqueToken()
if err != nil {
return authorizeErrorRedirect(c, q, "server_error", "")
}
nonce, err := newOpaqueToken()
if err != nil {
return authorizeErrorRedirect(c, q, "server_error", "")
}
bindSecret, err := newOpaqueToken()
if err != nil {
return authorizeErrorRedirect(c, q, "server_error", "")
}
now := nowFunc()
st := &schema.FederationState{
Owner: providerOwner(prov),
Name: state,
CreatedTime: now.UTC().Format(time.RFC3339),
Provider: prov.Name,
ClientId: q.clientID,
RedirectUri: q.redirectURI,
AppState: q.state,
Scope: q.scope,
AppNonce: q.nonce,
CodeChallenge: q.codeChallenge,
CodeChallengeMethod: method,
Resource: q.resource,
IdpVerifier: verifier,
IdpNonce: nonce,
BindHash: hashToken(bindSecret),
ExpireIn: now.Add(fedStateTTL).Unix(),
}
// Build the IdP authorize URL BEFORE persisting so a discovery/config failure
// never leaves an orphaned transaction row.
callback, err := federationCallbackURL(c)
if err != nil {
return authorizeErrorRedirect(c, q, "server_error", "")
}
idpURL, err := idpAuthorizeURL(ctx, prov, st, callback)
if err != nil {
return authorizeErrorRedirect(c, q, "temporarily_unavailable", "the identity provider is unavailable")
}
if err := store.PersistFederationState(ctx, db, st); err != nil {
return authorizeErrorRedirect(c, q, "server_error", "")
}
setBindCookie(c, bindSecret)
return c.Redirect(302, idpURL)
}
// federationCallbackHandler completes the round-trip: it resolves and burns the
// single-use transaction (checking expiry + browser binding), exchanges and
// verifies the IdP response, links or provisions the local user, and mints the
// iam authorization code the relying party expects — then redirects to the
// original redirect_uri with code + state.
func federationCallbackHandler(db orm.DB) zip.Handler {
return func(c *zip.Ctx) error {
ctx := c.Context()
now := nowFunc()
state := param(c, "state")
if state == "" {
return authorizeUserError(c, "missing state")
}
st, err := store.GetFederationState(ctx, db, state)
if err != nil {
return authorizeUserError(c, "internal error")
}
// Until the state resolves there is NO trusted redirect target, so an
// unknown/spent/expired state is answered in place, never redirected.
//
// The three causes are told apart because they ask different things of the
// person: a spent link means the sign-in already happened here, an expired
// one means they were too slow, and an unknown one means the link never
// belonged to this estate. Collapsing them into one sentence leaves both
// the reader and the operator guessing, and this handler logs nothing.
// Telling them apart discloses nothing a caller cannot already observe: a
// live state falls through to the bind-cookie check and answers
// differently from a spent one either way.
switch {
case st == nil:
return authorizeUserError(c, "this sign-in link is not one we issued — start again")
case st.Used:
return authorizeUserError(c, "this sign-in link was already used — start again")
case st.ExpireIn != 0 && now.Unix() > st.ExpireIn:
return authorizeUserError(c, "this sign-in link expired — start again")
}
// Browser binding: the callback must present the same anti-forgery cookie
// the begin leg set in THIS browser (constant-time) — the login-CSRF /
// session-fixation defense. A stolen or injected state without the cookie
// stops here.
raw := readBindCookie(c)
if raw == "" || subtle.ConstantTimeCompare([]byte(hashToken(raw)), []byte(st.BindHash)) != 1 {
return authorizeUserError(c, "the federation session could not be verified")
}
// Burn the transaction now (single-use), ATOMICALLY: the find-and-burn runs under
// a row lock (GetForUpdate), so two concurrent callbacks on one state cannot both
// win — the loser is refused (mirrors the wallet challenge burn / TakeChallenge).
// A replay finds it spent. The bind-cookie check above already gated this request,
// so a CSRF-failed replay never reaches the burn.
if _, err := store.BurnFederationState(ctx, db, state, now); err != nil {
if errors.Is(err, store.ErrFederationConsumed) {
// The race the row lock settles: a concurrent callback on the same
// state won the burn, so this one is the loser and says the same
// thing the sequential spent case says.
return authorizeUserError(c, "this sign-in link was already used — start again")
}
return authorizeUserError(c, "internal error")
}
st.Used = true
clearBindCookie(c)
// Resolve the relying-party app (the trusted redirect target) and re-check
// its redirect_uri against the live allow-list — never trust the stored
// value blindly (defense in depth against a tampered row).
app, err := store.GetApplicationByClientId(ctx, db, st.ClientId)
if err != nil || app == nil {
return authorizeUserError(c, "the client application is unavailable")
}
if !app.IsRedirectUriValid(st.RedirectUri) {
return authorizeUserError(c, "invalid redirect_uri")
}
// Re-assert the reserved-org / tenant-legitimacy gate at the mint boundary,
// never trusting that the begin leg still holds or that the app row is honest.
if !federationOrgAllowed(app) {
return fedErrorRedirect(c, st, "access_denied", "federation is not permitted for this application")
}
prov, err := store.GetProvider(ctx, db, st.Owner, st.Provider)
if err != nil || prov == nil {
return fedErrorRedirect(c, st, "temporarily_unavailable", "the identity provider is unavailable")
}
// An IdP-reported denial (user declined / error) is surfaced to the RP as
// access_denied, not a server error.
if e := param(c, "error"); e != "" {
return fedErrorRedirect(c, st, "access_denied", "the identity provider denied the request")
}
code := param(c, "code")
if code == "" {
return fedErrorRedirect(c, st, "invalid_request", "the identity provider returned no code")
}
callback, err := federationCallbackURL(c)
if err != nil {
return fedErrorRedirect(c, st, "server_error", "")
}
identity, err := idpExchange(ctx, prov, st, code, callback, now)
if err != nil || identity.subject == "" {
return fedErrorRedirect(c, st, "access_denied", "the identity provider could not be verified")
}
// A transaction minted by PathLink names the account it attaches to, and that
// is the whole of what it does: a link is not a sign-in, so no code is minted
// and no session is opened. The subject was fixed from the caller's proven
// identity at begin time, so nothing that happened at the provider can point
// it elsewhere.
if st.Subject != "" {
return fedAttachRedirect(c, db, st, prov, identity)
}
user, err := linkOrProvision(ctx, db, app, prov, identity)
if err != nil {
return fedResolveErrorRedirect(c, st, err)
}
if user.IsForbidden || user.IsDeleted {
return fedErrorRedirect(c, st, "access_denied", "the account is not permitted")
}
// The resume parameters — the ORIGINAL authorize request — pinned so the mint
// (now, or after a second factor) uses exactly these and nothing a later
// request could supply.
p := fedResumeParams{
ClientId: st.ClientId,
RedirectUri: st.RedirectUri,
AppState: st.AppState,
Scope: st.Scope,
AppNonce: st.AppNonce,
CodeChallenge: st.CodeChallenge,
CodeChallengeMethod: st.CodeChallengeMethod,
Resource: st.Resource,
}
// Second-factor gate: a federated login must NOT skip the factor a password
// login would demand (the MFA gate, mfa_gate.go). If the resolved user owes a
// factor, mint NOTHING here — park the resume, bound to the user and these
// pinned params, and send the browser to the hosted 2FA page.
org, err := store.GetOrganizationByName(ctx, db, user.Owner)
if err != nil {
return fedFault(c, st, "organization "+user.Owner+" of "+user.Owner+"/"+user.Name, err)
}
if factor.Prompt(org, user) {
// The organization requires a factor this federated user has not enrolled;
// a federated login cannot enroll one inline, so it fails closed.
return fedErrorRedirect(c, st, "access_denied", "two-factor authentication must be set up before signing in")
}
if factor.Enabled(user) && !remembered(c, user, now) {
return federationChallenge(c, db, st, user, p, org, now)
}
// No second factor owed — complete exactly as before, through the one mint.
loc, err := federationMint(c, db, app, user, p, now)
if err != nil {
return fedMintErrorRedirect(c, st, err)
}
return c.Redirect(302, loc)
}
}
// fedResumeParams is the ORIGINAL iam authorize request, pinned server-side so
// the code minted after a federated login (immediately, or after a second factor)
// binds to exactly these values — never to anything a later request supplies.
type fedResumeParams struct {
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"`
}
// errPKCERequired is the one distinguished mint error a caller maps to an OAuth
// invalid_request; every other mint failure is an opaque server_error.
var errPKCERequired = errors.New("federation: PKCE is required for public clients")
// federationMint mints iam's own authorization code — the SAME artifact a
// password login mints — bound to the pinned app-leg PKCE, redirect_uri and nonce,
// and returns the RP redirect (redirect_uri?code&state). It is the ONE mint path
// both the no-factor completion and the post-2FA resume reach, so a federated code
// can never be minted two different ways.
func federationMint(c *zip.Ctx, db orm.DB, app *schema.Application, user *schema.User, p fedResumeParams, now time.Time) (string, error) {
ctx := c.Context()
// A public client must have carried a PKCE challenge, re-asserted at the mint so
// a minted code is never redeemable without proof.
if app.ClientSecret == "" && p.CodeChallenge == "" {
return "", errPKCERequired
}
userID := user.Owner + "/" + user.Name
codeRow, err := MintCode(app, userID, p.Scope, p.CodeChallenge, p.CodeChallengeMethod, p.Resource, now)
if err != nil {
return "", err
}
codeRow.RedirectUri = p.RedirectUri
codeRow.Nonce = p.AppNonce
if err := store.PersistToken(ctx, db, codeRow); err != nil {
return "", err
}
// Someone just proved who they are to this IdP through another provider, so the
// IdP remembers them — the same tail loginGrant has. Without it a Google or
// GitHub sign-in left the person anonymous on hanzo.id itself and re-prompted by
// every other app: the relying party got its code and the IdP forgot the human.
_ = sessions.Open(ctx, c.Fiber(), db, user.Owner, user.Name, app.Name)
v := url.Values{}
v.Set("code", codeRow.Code)
setIfPresent(v, "state", p.AppState)
return joinQuery(p.RedirectUri, v), nil
}
// federationChallenge parks a resolved-but-not-yet-second-factored federated login.
// The pending state IS a LoginChallenge (KindFederation) — the same single-use,
// expiring, subject-pinned lifecycle the password MFA gate uses, so there is ONE
// challenge concept — carrying the resume params as its payload. The browser is
// sent to the hosted 2FA page; the challenge id rides the httpOnly cookie, never a
// URL segment.
//
// The offer is computed by the SAME allowList the password gate uses, and a federated
// login proves none of the offerable factors, so it excludes nothing. Any delivered
// factor on the offer gets its code sent here for the same reason it does there: the
// resume page has no destination to name and must not be given one.
func federationChallenge(c *zip.Ctx, db orm.DB, st *schema.FederationState, user *schema.User, p fedResumeParams, org *schema.Organization, now time.Time) error {
payload, err := json.Marshal(p)
if err != nil {
return fedFault(c, st, "challenge payload", err)
}
allow := deliver(c, db, user, allowList(user, org, ""), now)
if len(allow) == 0 {
return fedErrorRedirect(c, st, "access_denied", "your second factor could not be sent")
}
id, err := MintChallenge(c.Context(), db, KindFederation, user.Owner+"/"+user.Name, string(payload), offeredTypes(allow), now)
if err != nil {
return fedFault(c, st, "challenge mint", err)
}
base, err := federationBaseURL(c)
if err != nil {
return fedFault(c, st, "sign-in origin", err)
}
SetChallenge(c, id)
return c.Redirect(302, base+PathMfaVerify)
}
// fedMintErrorRedirect maps a federationMint error to the RP redirect_uri.
func fedMintErrorRedirect(c *zip.Ctx, st *schema.FederationState, err error) error {
if err == errPKCERequired {
return fedErrorRedirect(c, st, "invalid_request", "PKCE is required for public clients")
}
return fedFault(c, st, "code mint", err)
}
// The ways resolving a local identity is REFUSED rather than broken. Each is a
// decision the person or the tenant can act on, which is why they are named:
// answering an opaque server_error tells someone to try again forever. None of
// them reveals whether an account exists.
var (
// errAddressHeld: the address the IdP asserted already names a local account
// this federated identity is not entitled to adopt. Sign in with the password
// that account already has.
errAddressHeld = errors.New("federation: the address already names an account")
// errNoFederatedSignup: this application is not open for registration, and the
// identity is new. The same refusal the password and wallet endpoints give.
errNoFederatedSignup = errors.New("federation: the account does not exist and sign up is disabled")
// errNoFederatedEmail: the provider shared no address, so there is nothing to
// name the account after and no way to reach the person again.
errNoFederatedEmail = errors.New("federation: the provider shared no email address")
)
// fedResolveErrorRedirect maps a linkOrProvision failure to the RP redirect_uri:
// a named refusal leaves as access_denied with its reason, everything else as an
// opaque server_error. One mapper, so a new refusal is stated once and the
// callback does not accumulate a branch per error.
func fedResolveErrorRedirect(c *zip.Ctx, st *schema.FederationState, err error) error {
switch {
case errors.Is(err, errAddressHeld):
return fedErrorRedirect(c, st, "access_denied", "an account already uses this email address — sign in with its password")
case errors.Is(err, errNoFederatedSignup):
return fedErrorRedirect(c, st, "access_denied", "this application is not open for registration")
case errors.Is(err, errNoFederatedEmail):
return fedErrorRedirect(c, st, "access_denied", "the provider shared no email address for this account")
case errors.Is(err, store.ErrEmailAmbiguous):
// The provider proved this address to the person at the browser, so naming
// the conflict tells them nothing they do not own. Which row is theirs is
// not ours to guess: an operator merges them.
log.Printf("federation: resolve account: provider=%s client=%s tx=%s: %v", st.Provider, st.ClientId, fedTx(st), err)
return fedErrorRedirect(c, st, "access_denied", "more than one account uses this email address — contact support to merge them")
}
return fedFault(c, st, "resolve account", err)
}
// errSubjectLinked reports that the provider identity just verified is already
// attached to a DIFFERENT account. One provider identity, one account — the same
// shape as the wallet's one-wallet-one-identity rule — so it is refused rather than
// moved, which would quietly unlink somebody else.
var errSubjectLinked = errors.New("federation: this identity is already connected to another account")
// fedAttachRedirect completes a LINK: attach the verified subject to the pinned
// account and return the browser to the caller's validated returnUri, saying which
// provider was connected — or why it was not. It answers in the shape a page can
// read on arrival, since a link has no code to hand back.
func fedAttachRedirect(c *zip.Ctx, db orm.DB, st *schema.FederationState, prov *schema.Provider, id federatedIdentity) error {
binding, known := connectorFor(prov.Type)
if !known {
return fedErrorRedirect(c, st, "invalid_request", "provider has no local identity binding")
}
owner, name, _ := strings.Cut(st.Subject, "/")
switch err := attach(c.Context(), db, owner, name, binding, id.subject); {
case err == nil:
case errors.Is(err, errSubjectLinked):
return fedErrorRedirect(c, st, "access_denied", "that account is already connected to someone else")
default:
return fedFault(c, st, "attach", err)
}
v := url.Values{}
v.Set("linked", prov.Name)
return c.Redirect(302, joinQuery(st.RedirectUri, v))
}
// linkOrProvision resolves the local identity for a verified federated login,
// PROVISION-DON'T-PROMOTE: (1) an account already linked to this provider
// subject, else (2) the account that already holds this address — linked when both
// sides proved the address, refused otherwise — else (3) a freshly provisioned
// account. It NEVER sets isAdmin and never grants an existing account anything —
// federation only authenticates.
func linkOrProvision(ctx context.Context, db orm.DB, app *schema.Application, prov *schema.Provider, id federatedIdentity) (*schema.User, error) {
// Innermost guard on the mint itself: never provision/link a federated identity
// into a reserved system org (SuperAdmin) or a tenant this app may not serve.
// This layer assumes the two before it (app-write authorization + the begin/
// callback checks) both failed.
if !federationOrgAllowed(app) {
return nil, errors.New("federation: provisioning into this organization is not permitted")
}
org := app.Organization
binding, ok := connectorFor(prov.Type)
if !ok {
return nil, errors.New("federation: provider has no local identity binding")
}
// 1. Already linked by the provider's stable subject — the authoritative match
// for a returning federated user (immune to email churn/ambiguity). In the
// application's org, then among the accounts registered there — by this
// application or any other of its org's — which is where they are once an org has
// been founded for each of them: the subject is what says "this is the same
// person", and a reach that stops short would answer "new" and hand them another
// account.
if u, err := store.GetUserByConnector(ctx, db, org, binding.field, id.subject); err != nil {
return nil, err
} else if u != nil {
return u, nil
}
if u, err := store.GetSignupByConnector(ctx, db, org, binding.field, id.subject); err != nil {
return nil, err
} else if u != nil {
return u, nil
}
// 2. An account already holds this address. Resolve that FIRST, whether or not
// the IdP vouched for the address, because every answer below turns on it — and
// because an ambiguous address (ErrEmailAmbiguous) must refuse here too rather
// than be walked past into a third row on the same address.
if id.email != "" {
u, err := store.GetUserByEmail(ctx, db, org, id.email)
if err != nil {
return nil, err
}
// And among the accounts registered in the application's org — the same reach
// as the subject above. Without it an address held by someone founded into an
// org of their own reads as free, the branch below never runs, and they are
// given a second account on the address they already hold.
if u == nil {
if u, err = store.GetSignupByEmail(ctx, db, org, id.email); err != nil {
return nil, err
}
}
if u != nil {
// The link requires proof on BOTH sides, and only one side was ever checked.
//
// The IdP side was: an unverified IdP email never links, "it would let an
// unproven address take over an account". The LOCAL side is the side signup
// never proves — it writes EmailVerified: false and nothing a password signup
// can reach ever sets it — so the sentence was true and half-enforced. An
// attacker signed up with a stranger's address and their own passphrase; when
// the real owner arrived with a VERIFIED Google identity, this adopted the
// attacker's row, flipped EmailVerified to true, and left the digest alone.
// Both parties then held the account, silently, for good. 218 live rows are in
// that shape today.
//
// So: link only onto a row that an unproven credential cannot already open —
// one whose own address was proven, or one that carries no password at all.
// Otherwise refuse, and do NOT fall through to provision: a second row on one
// address is the ambiguity the lookup above refuses to resolve.
//
// Refusing is the whole cure available here. Adopting the row anyway and
// clearing its digest would also evict the attacker, but it silently
// destroys the credential of every one of those 218 people the first time
// they click a social button, and which of the two parties is at the browser
// is exactly what this cannot know. The person who has a password signs in
// with it; the person who does not was never locked out. Proving the address
// AT SIGNUP is what actually drains the pool.
if !id.emailVerified || (!u.EmailVerified && u.PasswordHash != "") {
return nil, errAddressHeld
}
linked, err := updateUser(ctx, db, u.Owner, u.Name, func(_ orm.DB, fresh *schema.User) error {
*binding.ref(fresh) = id.subject
fresh.EmailVerified = true
return nil
})
if err != nil {
return nil, err
}
return linked, nil
}
}
// 3. Provision a fresh account — but only where the application lets anyone
// register, and only for someone who can be named and reached.
//
// EnableSignUp is the tenant's own registration switch, enforced at the password
// endpoint (signup.go) and the wallet endpoint (wallet/verify.go) and not here, so
// an app with it OFF still got brand-new accounts from any enabled social provider:
// the one endpoint a tenant could not close was the externally-driven one.
//
// And only where a stranger may land: Registers is the rule the password door
// keeps, so a shared application does not file a provider's stranger in the
// operator's org any more than it files a password's.
if !app.EnableSignUp || !Registers(app, app.Organization) {
return nil, errNoFederatedSignup
}
// An address is what an account is named after and reached at, so a provider
// that shares none is refused rather than turned into a row nobody can use. A
// GitHub App ignores the requested scope and answers /user/emails with 403 when
// its "Email addresses" permission is missing — which used to mint an account
// named after the PROVIDER ("github", then "github2") with an empty email, never
// matched to the person's real account and with no way back in.
if id.email == "" {
return nil, errNoFederatedEmail
}
// No row holds this address, which is now a property of reaching this line rather
// than something to re-check. Federated accounts carry NO password (the digest
// stays empty, so password login fails closed) and are never admin.
return provisionFederatedUser(ctx, db, app, prov, binding, id)
}
// provisionFederatedUser creates a new federated account through the ONE
// canonical user-create path (users.Create, no password → no login-able digest),
// stamping the provider subject on its connector column. The username is the
// provider's handle for the person when it has one and it is free, else what
// allocateName derives from the address ([federatedName]); the address proof is
// carried straight from the IdP, on the create's own field rather than in the
// user body, which cannot state it.
//
// The display name reaches DisplayName and stops there: a profile name never
// becomes an identity.
func provisionFederatedUser(ctx context.Context, db orm.DB, app *schema.Application, prov *schema.Provider, binding connectorBinding, id federatedIdentity) (*schema.User, error) {
org := app.Organization
name, err := federatedName(ctx, db, org, id, prov.Type)
if err != nil {
return nil, fmt.Errorf("federation: %w", err)
}
u := schema.User{
Owner: org,
Name: name,
DisplayName: firstNonEmpty(id.displayName, name),
Email: id.email,
Avatar: id.avatar,
RegisterType: "Federation",
RegisterSource: org + "/" + prov.Name,
}
*binding.ref(&u) = id.subject
// A federated sign-in makes a PERSON, and the provider vouched for the address.
// Both are stated by this code rather than by the user body (see CreateInput):
// this is the one create path entitled to say an address was proven, because it
// is the one that watched a provider prove it.
created, err := users.New(db).Create(ctx, &users.CreateInput{
User: u,
Type: "normal-user",
EmailVerified: id.emailVerified,
Application: app.Name,
})
if err != nil {
return nil, err
}
// A founding application registers the account in its own org and the account
// WORKS in an org of its own — the same statement the password endpoint makes.
founded, err := Charter(ctx, db, app, created)
if err != nil {
return nil, fmt.Errorf("federation: %w", err)
}
return founded, nil
}
// federationProvider resolves the provider a request names to one the app links,
// requiring the link to be sign-in-enabled and configured with real credentials —
// otherwise the request never dead-ends at the IdP.
//
// A name is the link's record name (provider-github, what /v1/iam/auth/methods
// lists) or its provider type (github, what the @hanzo/iam social buttons send).
// The record name wins; a type resolves to the first link of that type in the
// app's own order. Either way only the app's own links are candidates.
func federationProvider(app *schema.Application, name string) *schema.Provider {
if name == "" {
return nil
}
var byType *schema.Provider
for _, it := range app.Providers {
if it == nil || !it.CanSignIn || it.Provider == nil || !offerable(it.Provider) {
continue
}
if it.Name == name {
return it.Provider
}
if byType == nil && strings.EqualFold(it.Provider.Type, name) {
byType = it.Provider
}
}
return byType
}
// providerOwner is the Provider record's owner, defaulting to the admin org where
// providers are seeded.
func providerOwner(p *schema.Provider) string {
if p.Owner != "" {
return p.Owner
}
return "admin"
}
// federationCallbackURL is the iam callback iam registers with the IdP and
// re-presents at the token exchange. It is PINNED from config, never steered by a
// request header, so an attacker cannot redirect the IdP leg via X-Forwarded-Host.
func federationCallbackURL(c *zip.Ctx) (string, error) {
base, err := federationBaseURL(c)
if err != nil {
return "", err
}
return base + PathFederationCallback, nil
}
// federationBaseURL is the pinned public origin the IdP callback is registered
// under — the request host's sign-in origin (issuer.go), keyed on the TRUSTED
// request host (c.Host(), which ignores X-Forwarded-Host). It is the host's issuer
// unless IAM_FEDERATION_ORIGIN_MAP names another, as it does to sign Hanzo in on
// hanzo.ai while tokens still say hanzo.id. Header-immune, never steered to an
// attacker origin. See resolveFederationOrigin for the resolution order.
func federationBaseURL(c *zip.Ctx) (string, error) {
return resolveFederationOrigin(c.Host())
}
// federationOrgAllowed reports whether a federated (external) identity may be
// provisioned or linked into the application's Organization. Two invariants,
// both fail-closed:
//
// 1. NEVER a reserved system org (admin/built-in/app). A social sign-in that
// landed a user in the admin org would make that user a SuperAdmin — the
// critical escalation. Federation is customer sign-in; system orgs are seeded
// / onboarded / SuperAdmin-managed, never reached by an external login.
// 2. Tenant legitimacy. A platform app (admin/built-in-owned, and thus only
// SuperAdmin-creatable) may serve any non-reserved tenant. A tenant-registered
// app may only land users in the org it legitimately serves — its OWN org, a
// shared app, or one with an explicit org-choice mode — mirroring the
// login/signup tenant gate, so an attacker-owned app cannot mint or link
// identities into a victim tenant.
//
// This is defense in depth behind the application-write authorization (authz
// authorizes the Organization field on create/update); this layer assumes that
// one was bypassed and still refuses the escalation.
func federationOrgAllowed(app *schema.Application) bool {
org := strings.TrimSpace(app.Organization)
if org == "" || policy.IsReservedOrg(org) {
return false
}
if policy.IsSigningOwner(app.Owner) {
return true // platform app — SuperAdmin-configured, may serve any tenant
}
if app.ServesAnyOrg() {
return true
}
return org == app.Owner
}
// fedErrorRedirect returns an OAuth error to the relying party's redirect_uri
// (already allow-list-validated) with the original app state.
func fedErrorRedirect(c *zip.Ctx, st *schema.FederationState, code, desc string) error {
v := url.Values{}
v.Set("error", code)
setIfPresent(v, "error_description", desc)
setIfPresent(v, "state", st.AppState)
return c.Redirect(302, joinQuery(st.RedirectUri, v))
}
// fedFault answers a federated login that failed on our side. The caller still
// sees an opaque server_error; the log names the step and the cause, keyed by
// the provider and the transaction, so the next failure is diagnosable.
func fedFault(c *zip.Ctx, st *schema.FederationState, step string, err error) error {
log.Printf("federation: %s: provider=%s client=%s tx=%s: %v", step, st.Provider, st.ClientId, fedTx(st), err)
return fedErrorRedirect(c, st, "server_error", "")
}
// fedTx is a short, non-secret handle on a federation transaction for logs.
func fedTx(st *schema.FederationState) string {
if len(st.Name) > 8 {
return st.Name[:8]
}
return st.Name
}
// setBindCookie writes the per-transaction anti-forgery cookie: HttpOnly + Secure,
// SameSite=Lax (so it IS sent on the IdP's top-level GET back to the callback),
// host-only at Path=/ as its `__Host-` name requires, expiring with the
// transaction.
func setBindCookie(c *zip.Ctx, value string) {
c.Fiber().Cookie(&fiber.Cookie{
Name: fedCookieName,
Value: value,
Path: "/",
MaxAge: int(fedStateTTL / time.Second),
Secure: true,
HTTPOnly: true,
SameSite: fiber.CookieSameSiteLaxMode,
})
}
// readBindCookie returns the anti-forgery cookie value, or "" when absent.
func readBindCookie(c *zip.Ctx) string { return c.Fiber().Cookies(fedCookieName) }
// clearBindCookie expires the anti-forgery cookie once the transaction is
// consumed, so it can never be replayed.
func clearBindCookie(c *zip.Ctx) {
c.Fiber().Cookie(&fiber.Cookie{
Name: fedCookieName,
Value: "",
Path: "/",
MaxAge: -1,
Secure: true,
HTTPOnly: true,
SameSite: fiber.CookieSameSiteLaxMode,
})
}
// connectorBinding ties a provider type to the User's per-connector identity
// column: the EXACT lowercase orm/json field name to filter on and a pointer
// accessor to read/set the stored subject.
type connectorBinding struct {
field string
ref func(*schema.User) *string
}
// connectorRegistry maps a provider Type to its User connector column. The field
// name is the EXACT json/orm name (already lowercase): orm's filter lowercases
// only the FIRST rune, so a Go field name like "GitHub" would query '$.gitHub'
// (the tag is 'github') — passing the exact json name is the one correct way, and
// this registry is its single source of truth. Only the connectors iam can
// federate are listed; anything else fails closed.
var connectorRegistry = map[string]connectorBinding{
"google": {"google", func(u *schema.User) *string { return &u.Google }},
"github": {"github", func(u *schema.User) *string { return &u.GitHub }},
"gitlab": {"gitlab", func(u *schema.User) *string { return &u.Gitlab }},
"gitee": {"gitee", func(u *schema.User) *string { return &u.Gitee }},
"bitbucket": {"bitbucket", func(u *schema.User) *string { return &u.Bitbucket }},
"facebook": {"facebook", func(u *schema.User) *string { return &u.Facebook }},
"apple": {"apple", func(u *schema.User) *string { return &u.Apple }},
"linkedin": {"linkedin", func(u *schema.User) *string { return &u.LinkedIn }},
"discord": {"discord", func(u *schema.User) *string { return &u.Discord }},
"slack": {"slack", func(u *schema.User) *string { return &u.Slack }},
"okta": {"okta", func(u *schema.User) *string { return &u.Okta }},
"azuread": {"azuread", func(u *schema.User) *string { return &u.AzureAD }},
"microsoftonline": {"microsoftonline", func(u *schema.User) *string { return &u.MicrosoftOnline }},
}
// connectorFor resolves the connector binding for a provider type (case-folded),
// or (zero, false) when the type has no local identity column.
func connectorFor(providerType string) (connectorBinding, bool) {
b, ok := connectorRegistry[strings.ToLower(strings.TrimSpace(providerType))]
return b, ok
}