Account Linking

How a Google sign-in maps to a Hawcx user — verified-email linking, the account-takeover guard, JIT provisioning, and the unique (issuer, subject) rule.

When a user signs in with Google, Hawcx must decide which Hawcx user that login belongs to: an existing account, or a new one. Get this wrong and you have an account-takeover vector, so the rules are deliberately strict and off by default.

The identity key: one user per (issuer, subject)

Hawcx records the federation as a (issuer, subject) pair — for Google, issuer is https://accounts.google.com and subject is Google's stable sub for that account. This pair is unique: it maps to exactly one Hawcx user.

Why the subject, not the email

Google's sub never changes and is never reassigned; an email address can be renamed or, on Workspace, reassigned to a different person. Hawcx keys the link on (issuer, subject) so a returning user always resolves to the same Hawcx account even if their email changed. Email is used only for the initial link decision below.

On every subsequent Google sign-in, Hawcx looks up (https://accounts.google.com, sub). A match resolves straight to that Hawcx user — no email involved.

The first time a given Google sub is seen, Hawcx has no link yet and applies your project's policy.

Verified-email linking

Two settings under Settings → Social Connect govern whether a new Google login may attach to an existing Hawcx user that shares its email:

Setting	Effect
`allow_email_linking`	If on, a Google login whose email matches an existing Hawcx user links to that user instead of creating a new one. If off, matching emails never auto-link — an unmatched Google `sub` always provisions a fresh user.
`email_verified_required`	If on (recommended), linking only proceeds when Google asserts `email_verified: true`. An unverified Google email is never allowed to link.

Both default to the safe posture: linking is opt-in, and when enabled it demands a verified email.

The account-takeover guard

Auto-linking on email is exactly the mechanism attackers abuse: register a Google account with a victim's email, sign in, and inherit the victim's Hawcx account. The guard is: link on email only when Google has verified that email.

Never link on an unverified email

With email_verified_required on, a Google login carrying email_verified: false (or no email_verified claim) will not link to an existing Hawcx user, even if the addresses match exactly. Turning this off re-opens the takeover path — leave it on unless you fully control the Google tenant (e.g. Workspace Internal apps, where Google guarantees verification).

This guarantee does not extend to Custom OIDC connections

Everything above assumes the identity provider is trustworthy — true for Google, and for Microsoft/Apple/Facebook/GitHub Actions, which Hawcx independently pins to their real origin regardless of connection config. It is not true for a Custom OIDC connection pointed at a third-party or self-hosted IdP: that IdP fully controls its own email_verified claim, so email_verified_required costs an untrusted IdP nothing — it can simply always assert true. For Custom OIDC connections, treat allow_email_linking as unsafe unless you operate or fully trust the identity provider. See Custom OIDC: account-linking.

Decision order on first sign-in:

Loading diagram...

JIT provisioning

When no link and no permitted email match exist, Hawcx just-in-time provisions a new user from Google's verified profile: it creates the Hawcx user_id, stores the normalized profile claims, and records the (issuer, subject) link. That new user_id becomes the sub of the Hawcx ID token your app receives.

This is the passwordless bootstrap: the user now exists in Hawcx with a verified email and can enroll a device for device-bound passwordless sign-in on future visits — Google is no longer required.

Provisioning is idempotent

Provisioning keys on (issuer, subject). Concurrent first logins for the same Google account resolve to a single Hawcx user, not duplicates.

Unlinking

Removing a user's Google link deletes only the (issuer, subject) record; the Hawcx user and its user_id persist. A later Google sign-in re-links (subject to the same policy) rather than creating a duplicate, because the email match / provisioning rules run again.

Next steps

Reference: the federated_identities link and normalized claims.
Google Cloud setup: ensure Google asserts verified emails.