Introduction

Social login allows users to authenticate with their existing accounts from providers like Google, Apple, Microsoft, GitHub, Okta, Facebook, and LinkedIn.

​

Prerequisites

Before you start, make sure you have:

• A Prelude account with access to Prelude Auth
• An Application ID (appID) — see Applications
• Your Management API key for backend calls
• OAuth credentials from the provider you want to configure (client ID, client secret, etc.)

​

Supported providers

​

Configuration options

All providers share the following options: Some providers require additional configuration — see the provider-specific guides below.

​

Email verification trust model

use_email_as_identifier and allow_email_account_merge both depend on whether the provider vouches that the email belongs to the signed-in user. Prelude Auth uses provider-specific signals: When a provider surfaces an email as unverified, Prelude Auth will not store it as an identifier and will not auto-merge it into an existing account. If allow_email_account_merge is enabled and an unverified email collides with an existing Auth user, the flow is rejected with an email_in_use error instead of silently linking the accounts.

​

Verify email via OTP

Enable verify_email on a provider when you want users to keep signing in even if the IdP returns the email as unverified. Instead of rejecting the flow or creating an unlinked account, Prelude Auth sends an email OTP to the address surfaced by the IdP and links the OAuth identifier only after the user proves ownership. The flow:

1. The user signs in with the OAuth provider.
2. The IdP returns an email but does not vouch for it (e.g. Microsoft without xms_edov, or a custom Okta tenant).
3. Prelude Auth redirects back to your app with challenge_token=…&status=otp_required instead of finalizing the login.
4. The Web SDK’s finalizeOAuthLogin returns { status: "otp_required", challengeId, email } so your app can route to its OTP screen and call checkOTP with the code the user entered.
5. On a successful OTP, Prelude Auth attaches the OAuth identifier to (or creates) the user that owns the email and finalizes the login automatically.

Preconditions enforced when you save the OAuth config:

• use_email_as_identifier must be true. Verifying an email that will never be persisted as an identifier serves no purpose.
• The application must have at least one email OTP login config. Removing the last email OTP login config while any provider still has verify_email=true is rejected.

If verify_email is true but use_email_as_identifier is later flipped off, the OTP step is skipped at runtime and the account is created with only the OAuth identifier — the existing config keeps loading instead of breaking, but the OAuth-link flow is effectively disabled until both flags are aligned. When the email already belongs to another account and allow_email_account_merge is false, Prelude Auth rejects with email_in_use before sending the OTP so the user does not get sent through a screen for a flow that would dead-end.

​

Provider guides