Handling OAuth Providers with Unverified Emails

Some OAuth providers do not consistently return verified email addresses, even after their verification process. This inconsistency can lead to security and trust issues for applications that rely on the verified email status.

To address this, Descope takes a cautious approach and does not automatically merge social login identities with existing user accounts based solely on the email address. Merging accounts without a verified email could result in linking different individuals or exposing accounts to unauthorized access.

Understanding Unverified Emails

Example: Microsoft Authentication

Here is an example of an unwanted outcome when a user signs up without email verification, specifically with Microsoft:

As shown above, the unverified email is marked with a warning. In this state, merging with existing user accounts is not possible, as well as any other operations that rely on a verified email.

Email Verification Process

When using Descope flows, you can verify email addresses using any kind of email-based authentication method, like OTP, Magic Link, etc.

The following sections demonstrate how to do so using a Sign In or Sign Up flow, using Microsoft as the OAuth Provider.

Sign In Flow

This section assumes that user accounts have already been created by email, and you expect social login to work with the user's existing email address.

Due to Microsoft's unverified email behavior, Descope creates a new user with the login ID microsoft-xxxxxxx when the email is unverified. This means that during sign in, the user won't be found automatically, as the email is not an additional login ID:

To handle this situation, you can add error handling to the OAuth response within your flow, as shown below.

The following flow is also available to use as a template in the Flow Library.

Error Handling Process

1. Expose the OAuth Raw Response

2. Use Scriptlet to Set Overrides

   Add an email address override:

3. Verify the Email Address

4. Merge the Accounts

Sign Up Flow

When allowing only sign ups, the user will be created with the Microsoft ID as the primary login ID. To handle this:

1. Triage Based on Condition

2. Merge Identity After Verification

Best Practices

Social Login Merging Settings

When configuring "Social Login (OAuth/OIDC)" authentication:

1. Navigate to the "Email address handling" section for your Social Login Provider
2. Select "Promote the email to be a login ID"
3. Keep "Only if the email is verified" selected

Blocking Self-Registration Settings

When "Block self-registration sign up" is enabled in project settings, it affects providers like Microsoft that return unverified emails. You must either:

• Allow self-registration
• Handle the error as described in the "Sign In" section

Email Verification Claims

Microsoft provides the xms_edov (Email Domain Owner Verified) claim that indicates whether an email is domain-verified. Using this claim can bypass verification issues entirely.

Other providers may offer similar claims with different names. Check your provider's documentation for available verification claims.