Social login registration & sign-in

Step by step

1. 1

   Click Continue with [Provider] on the Login page.

   EasyCRM generates a cryptographically random state and nonce and a PKCE code_verifier (storing code_challenge = SHA256(verifier) server-side, bound to the browser session). EasyCRM takes you the browser to the provider's authorization endpoint with response_type=code. state, nonce, code_challenge, code_challenge_method=S256, the configured client_id, and the registered redirect URI.

2. 2

   Authenticates with the provider and consents to share email and profile claims.

3. 3

   Redirects the browser back to /api/auth/external/{provider}/callback?code=…&state=….

   EasyCRM checks that state matches the value persisted in step 2. (Mismatch — .) Exchanges the authorization code for tokens by calling the provider's token endpoint over TLS, presenting the client_secret and the code_verifier. EasyCRM checks the returned id_token: signature against the provider's JWKS, iss, aud, exp, and nonce. (Failure — .) Extracts claims: sub, email, email_verified, given_name, family_name, name, picture, locale, zoneinfo. EasyCRM verifies email_verified = true. (False or absent — .) Looks up an ExternalLogin row for (provider, sub). Not found — continues to step 11. (Found — sign-in path.) Looks up an active User whose Email matches the asserted email. Not found — continues to step 12. (Found — linking prompt.) Resolves the registration path: (a) an active, non-expired Invitation exists for the email — use the invitation's role and Reports-To; (b) otherwise, the email's domain matches an active AutoProvisionDomain rule — use that rule's default role and Reports-To. (Neither matches — .) EasyCRM creates the user record with: Email, FirstName/LastName from given_name/family_name (or split name), Username generated from the email local part with collision suffixing (jdoe, jdoe2, …), Role from step 12. Timezone from zoneinfo — locale — tenant default, ProfilePhotoUrl from picture. EasyCRM creates an ExternalLogin row binding User, Provider, ProviderSubject, LinkedAt, and the email asserted at link time. If the registration path used an invitation, marks it Accepted with the resolved User. If the resolved role enforces MFA — routes the user to MFA Enrollment (UC-1.2, ). Otherwise continues to step 17. Issues a JWT access token and refresh token; sets HTTP-only Secure cookies. EasyCRM creates audit entries: UserRegisteredViaSocial (with provider and registration path) and UserLogin. If required profile fields cannot be inferred (e.g. Timezone), routes to the Profile Completion screen (). Otherwise redirects to the role-based default dashboard.

Other paths

If something goes wrong

Good to know

• Social login registration is not unrestricted self-registration. It requires either an Admin-issued invitation or a domain on the tenant's auto-provision allowlist.
• All OAuth flows MUST use Authorization Code with PKCE; state and nonce are required and validated.
• The (provider, subject) pair is the canonical, immutable external identifier; email is treated as a mutable attribute and never used alone for identity matching after the first link.
• A user account MUST have at least one usable sign-in method at all times. Unlinking the last login method without setting a password is blocked.
• Provider must assert email_verified = true for any registration. Linking to an existing account additionally requires successful local re-authentication.
• Role-based MFA enforcement applies after social authentication identically to password authentication.
• Brute-force counters and account lockout apply to the password-verification step of (linking) but NOT to the OIDC handshake itself; per-IP rate limiting protects the OIDC start endpoint.
• Auto-provisioned accounts MUST NOT be assigned the Admin role. Admin elevation is always explicit and post-registration.
• Client secrets and TOTP keys MUST be encrypted at rest using the platform key vault and MUST NOT be returned to the UI after save.
• Disabling a provider takes effect within 60 seconds; in-flight callbacks complete normally to avoid orphaning users mid-handshake.