diagrams
Authentication

Social Login Flow

Social login (also called federated login or "Sign in with X") lets users authenticate to your application using an existing account at a trusted identity provider — Google, GitHub, Apple, Facebook, or any OIDC-compatible provider — instead of creating and managing a separate password.

diagram.mmd — sequence
Edit in Graphlet →
Social Login Flow sequence diagram
About Source

Social login (also called federated login or "Sign in with X") lets users authenticate to your application using an existing account at a trusted identity provider — Google, GitHub, Apple, Facebook, or any OIDC-compatible provider — instead of creating and managing a separate password.

Under the hood, social login is the OAuth2 Authorization Code Flow combined with OpenID Connect Flow. The application acts as the OAuth2 client (relying party), the social platform acts as both the authorization server and the identity provider, and your backend links the provider's user identity to a local user account.

The flow starts when a user clicks "Sign in with Google" (or any provider). Your server generates a state parameter (anti-CSRF nonce) and optionally a nonce (anti-replay), stores them in a short-lived cookie or server session, and redirects the user to the provider's authorization endpoint with scope=openid email profile.

The provider handles authentication entirely — the user may be silently signed in (existing session) or prompted for credentials and consent. After approval, the provider redirects back to your redirect_uri with an authorization code. Your server exchanges the code for tokens at the provider's /token endpoint. You validate the ID token's signature (using the provider's JWKS), extract the sub claim (a stable provider-scoped user ID), and either link it to an existing account or create a new one.

The critical account linking logic must handle edge cases: what if the same email exists from a different provider or from a password signup? Most applications match on email with the user's explicit confirmation, or require users to link accounts from settings. After linking, a local session is created. Subsequent logins skip account creation and directly match on the sub claim.

This flow is the foundation of SSO Architecture in consumer-facing applications.

Free online editor
Edit this diagram in Graphlet
Fork, modify, and export to SVG or PNG. No sign-up required.
Open in Graphlet →

Frequently asked questions

Social login (also called federated login or "Sign in with X") lets users authenticate to your application using an existing account at a trusted identity provider — such as Google, GitHub, Apple, or Facebook — instead of creating a separate password. It reduces sign-up friction and offloads credential management to providers with mature security infrastructure.
Social login combines the OAuth2 Authorization Code Flow with OpenID Connect. The user clicks "Sign in with Google", your server redirects them to Google's authorization endpoint with `scope=openid email profile`, Google authenticates the user and redirects back with an authorization code, and your server exchanges the code for tokens at Google's `/token` endpoint. The ID token contains a stable `sub` claim that uniquely identifies the user at that provider.
When a user signs in with a social provider, check whether their provider `sub` claim is already linked to an account. If not, check whether their email matches an existing account and ask the user to confirm the link. Never auto-link on email alone without confirmation — a provider might not verify email addresses, allowing account takeover. After linking, subsequent logins match directly on the `sub` claim.
Always validate the `state` parameter to prevent CSRF attacks. Verify the ID token signature against the provider's JWKS endpoint. Check `aud` matches your `client_id` and `iss` matches the expected provider URL. Be aware that some providers allow unverified email addresses — check the `email_verified` claim before trusting email for account matching.
Social login uses consumer identity providers (Google, GitHub, Apple) and is primarily for end-user convenience. Enterprise SSO uses corporate identity providers (Okta, Azure AD, ADFS) with SAML or OIDC and is primarily for employee access management and security policy enforcement. Both rely on the same underlying federated identity principles but target different user populations and trust models.
mermaid
sequenceDiagram participant User participant App as Your Application participant Provider as Identity Provider (Google/GitHub) participant DB as Your Database User->>App: Click "Sign in with Google" App-->>App: Generate state nonce, store in session App->>User: Redirect to provider /authorize with client_id, scope, state User->>Provider: Authenticate (existing session or login prompt) Provider->>User: Show consent screen User->>Provider: Approve requested scopes Provider->>App: Redirect to /callback with authorization code + state App-->>App: Validate state matches stored nonce App->>Provider: POST /token with code + client_secret Provider-->>App: Access token + ID token (JWT) App-->>App: Validate ID token signature via JWKS App-->>App: Extract sub, email, name from claims App->>DB: Look up user by provider + sub alt Existing account found DB-->>App: Return existing user record else New user App->>DB: Create new user linked to provider sub DB-->>App: Return new user record end App-->>App: Create local session App->>User: Redirect to dashboard with session cookie
Copied to clipboard