AlaricCross6851

Posted on Oct 29

Node.js OAuth Linking: Resolve Social Identity for Existing Users, Avoid Duplicates

#node #oauth #healthtech #security

A social login should never create a patient profile until the service has resolved the identity against existing records. In a healthtech signup flow, the least complicated reliable rule is: verify the provider assertion, normalize the provider subject, look up an immutable identity key, and only then decide whether to link, sign in, or start a new profile. Put the abuse gate before account creation, but keep the CAPTCHA result separate from identity proof.

Short answer: model a social credential as a unique identity record, not as an email address. In Node.js, the transaction that consumes that record should lock the candidate user, require an authenticated session before linking, and make a second request harmless. Email is useful for discovery and notification; it is a weak basis for silent account merging.

Keep the states explicit.

What page fired at 3am?

The alert I want is not “OAuth callback errors increased.” That is a dashboard-shaped question. I want to know which action fired: did one person receive two patient profiles, did the callback bind an identity twice, or did the signup gate reject legitimate enrollment? Those are different incidents with different reversals.

A useful incident trace starts at the visible failure. A patient signs in with a social account and sees an empty profile, while support can find an older profile under a prior enrollment method. Work backward: the callback accepted an assertion, an email lookup found a possible match, and the application created a new profile before anyone had explicitly authenticated the old one. The missing signal was an account-resolution event before insertion.

That is the instrumentation change I would make first. Emit a structured event for identity.resolution with a decision such as existing_identity, authenticated_link, new_profile, or manual_review; include a request correlation ID and provider subject hash, but never log the raw token. Alert on impossible transitions, such as the same identity key attached to two users, rather than on a noisy count of all callback failures.

False positives matter. A threshold of one duplicate-binding event is appropriate for a uniqueness violation; a threshold of one manual-review decision is not. Page on the former, sample the latter, and retain enough audit data to explain the decision without putting health information in application logs.

How can Node.js link a social identity to an existing user?

An OAuth subject is scoped to an issuer and client, so the durable lookup key is a tuple such as (issuer, subject). OpenID Connect defines the subject identifier as locally unique and never reassigned within the issuer’s context; the exact scope still has to be understood for the provider integration you operate. Treating an email claim as proof that two accounts are the same skips the question that matters: who authenticated the existing account?

The safe resolution states are small. An existing identity signs the user in. A missing identity with an already authenticated local session can be linked after a deliberate confirmation step. A missing identity with a matching email becomes a recovery or review path, not an automatic merge. Otherwise, create a new profile only after the abuse check and the normal consent and enrollment steps pass.

This is where the “find user by email, then attach provider” shortcut becomes dangerous. An attacker who controls a login address, or a provider whose email claim is unverified or mutable, can turn discovery into account takeover. OWASP’s authentication guidance treats account recovery and verification as security boundaries; the implementation should do the same.

The binding transaction should be boring

The database constraint is the final guard, not a substitute for the resolver. Keep one row per external identity, with a unique constraint over the issuer and subject, and make the link operation transactional. The following Go sketch shows the decision boundary without tying it to a commercial SDK; the same sequence can be implemented behind a Node.js route.

Exactly once.

type ExternalIdentity struct {
    Issuer  string
    Subject string
    UserID  string
}

type Resolution string

const (
    ExistingIdentity  Resolution = "existing_identity"
    AuthenticatedLink Resolution = "authenticated_link"
    NewProfile        Resolution = "new_profile"
    ManualReview      Resolution = "manual_review"
)

func ResolveIdentity(ctx context.Context, tx *sql.Tx, issuer, subject string,
    localUserID *string, verifiedEmail *string) (Resolution, string, error) {
    identity, err := findIdentityForUpdate(ctx, tx, issuer, subject)
    if err != nil && !errors.Is(err, sql.ErrNoRows) {
        return "", "", err
    }
    if err == nil {
        return ExistingIdentity, identity.UserID, nil
    }

    if localUserID != nil {
        if err := insertIdentity(ctx, tx, issuer, subject, *localUserID); err != nil {
            return "", "", err
        }
        return AuthenticatedLink, *localUserID, nil
    }

    if verifiedEmail != nil && emailHasPossibleMatch(ctx, tx, *verifiedEmail) {
        return ManualReview, "", nil
    }
    userID, err := insertNewUser(ctx, tx)
    if err != nil {
        return "", "", err
    }
    if err := insertIdentity(ctx, tx, issuer, subject, userID); err != nil {
        return "", "", err
    }
    return NewProfile, userID, nil
}

The important detail is not the language. It is the order and the constraint. findIdentityForUpdate must run inside the same transaction as the insert, and a uniqueness conflict must be handled as a normal concurrent request, followed by a fresh lookup where appropriate. Do not return a new session merely because the provider callback was valid. The callback authenticates the external identity; your application still has to choose the local account.

The trade-off is deliberate: a possible email match can send a person through recovery or support instead of giving an instant login. That adds friction and creates an operational queue, but the alternative is silently merging records that may represent different people. A CAPTCHA can reduce automated enrollment; it cannot resolve that ambiguity.

In a Node.js service, keep provider verification, resolution, persistence, and session issuance as separate functions. That makes it possible to test the resolver with a fake assertion and a real database constraint, rather than mocking the entire callback into a happy-path boolean.

No shortcut survives a retry.

Where does CAPTCHA belong in this flow?

CAPTCHA is an abuse signal. It is not an identity-linking signal. Run the server-side challenge verification before an anonymous request can create a profile or consume an invitation, and bind the result to a short-lived, single-use signup attempt. Do not let a successful challenge authorize linking to an existing patient profile. That step requires a local authenticated session and explicit confirmation.

The decision table is more useful than a clever callback:

Identity lookup	Local session	Abuse check	Action
Found	Any	Valid request	Sign in to the mapped user
Missing	Present	Valid request	Ask for confirmation, then link
Email candidate	Absent	Valid request	Recovery or manual review
Missing	Absent	Failed or absent	Reject before profile creation

A challenge can fail because the request is automated, malformed, expired, or outside the service’s policy. Those outcomes should be observable, but the client should not receive enough detail to turn the endpoint into an account-enumeration oracle. The same restraint applies to “email already exists” messages.

This design is a poor fit when the application needs a regulated, high-assurance identity proof rather than account continuity. In that case, an OAuth subject and a challenge are insufficient evidence; add a separately governed verification process. It is also less convenient for teams that cannot operate transactional storage and audit retention. Those are real boundaries, not reasons to hide the unresolved match.

What should the on-call measure?

Start with invariants, then measure user friction. The hard invariants are one external identity mapped to one local user, one link operation requiring an authenticated local session, and no profile creation after a failed abuse gate. The useful counters are resolution decisions, uniqueness conflicts, recovery starts, challenge failures, and support reversals, each partitioned by flow rather than dumped into one signup rate.

Test the ugly transitions: two callbacks arriving together, a browser retry after a timeout, a provider subject changing because the issuer configuration changed, and a user attempting to link an identity already owned elsewhere. Verify that retries converge on the same local user and that a failed transaction leaves no half-created profile.

I would review the alert by asking one question: what page fired? If the answer is still “the dashboard looked unusual,” the system has not made its failure mode legible.

The design decision is therefore less about selecting an OAuth library and more about refusing to collapse discovery, authentication, abuse prevention, and account mutation into one callback. Resolve first. Link only from a trusted local session. Keep CAPTCHA in its lane. That sequence prevents duplicate patient profiles without making an automated challenge carry a security promise it cannot support.

DEV Community