Custom Social Login with Microsoft

When integrating Descope flows in a website, you can allow Social Login with Microsoft as one of the authentication methods for your users. This doc will walk you through all the steps to do that.

Solution

To make this happen, you'll need to configure a few things on the Microsoft side and the Descope side, as well as configure a new CNAME in your domain's DNS records.

Configuring the CNAME

You will need to create a custom domain that points to cname.descope.com (US) / CNAME.euc1.descope.com (EU), so that if the redirect URI is auth.example.com for instance, the Microsoft page will show Sign in to continue to with example.com instead of descope.com

See the Custom Domain guide for a step by step guide for managing sessions within cookies.

Once that is completed, you will need to create a new enterprise application in Azure.

Creating a new Enterpise Application

1. Navigate to your Azure portal.

2. Search For Enterprise Applications, and click on +New Application to start the process:

3. Create Your Own Application:

4. Choose a name, keep the Integrate any other application you don't find in the gallery (Non-gallery) option selected and click on Create:

5. Once you create the application, make sure to copy the application ID, and set it aside:

6. Search for Microsoft Entra ID, and navigate to App Registrations under the manage tab:

7. Search for your application by name in the App Registrations tab, after finding it, click it. Then navigate to Certificates & Secrets:

8. Create a new secret, copy the value and set it aside:

9. Navigate to Authentication, add a new web platform, and set the callback URI to https://api.descope.com/v1/oauth/callback:

10. Scroll down inside the Authentication page, and select the multi-tenant option to allow any user to use your app, click save:

11. Navigate to API Permissions, and create a new permission:

12. Now on Descope, navigate to the custom Microsoft OAuth settings

• Put the Application ID you put aside in the Client ID section.
• Put the Client secret you created in the Client Secret section.
• You can put the Prompt as Consent for testing.
• Click save.

Testing Authentication

Now we are all set to test if our application works, here is an example flow that uses Microsoft OAuth:

Now testing the flow, we can see that we get the consent screen with our custom app:

Prompt

The Prompt setting controls how users are prompted when they sign in with Microsoft, such as forcing them to re-authenticate (login), re-approve permissions (consent), or choose an account (select_account).

User Attribute Mapping

User Attribute Mapping maps the attributes Microsoft returns to fields on the Descope user, including custom attributes. See Configure User Attribute Mapping for how to set up mappings and when user information is refreshed on login.

Advanced

The Advanced section contains optional settings such as Manage tokens from provider, Callback Domain, Redirect URL, and Email address handling. See Configure Advanced Settings for the full list.

Managing Tokens from Provider

Enable Manage tokens from provider and select an Outbound App to have Descope store the user's Microsoft OAuth tokens. You must first create the Outbound App in the Descope Console before you can select it here. See Configure Advanced Settings for details.

Email Address Handling

Email address handling controls whether the email address Microsoft returns is used as a login ID, which allows sign-ins to merge with existing users who have the same email, or is only stored as a user attribute. See Configure Advanced Settings for the available options, and Handling OAuth Providers with Unverified Emails for how verified and unverified emails are handled.

Enterprise Application Authentication

For your app to appear as verified by Microsoft, you need to pass verification.

And you're done! Now when you sign in, you should see your own personalized app page with your custom domain name. If you have any questions, please reach out to us here!

Merging identities from Microsoft

When using Microsoft for social login, Azure does not certainly verify the user's email. We at Descope understand that this could be a security flaw when a user tries to authenticate and we cover this subject in this blog. By default, we do not merge email addresses to an existing user login ID to prevent this security flaw from actually happening. Inside Descope flows, we provide the option to triage based on email verification status using authInfo.user.verifiedEmail. If you want to merge the user based on the user's email address, follow these steps:

• Triage based on condition:

• Merge the identity after verifing the email:

Implementing Email Verification with Microsoft 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. There is an alternative claim primary_verified_email that can also be used for email verification. To implement this in your flow, follow these steps:

• Go to the OAuth application registration in Microsoft Azure portal, navigate to Token configuration, and add either one of the claims as optional claims for ID token:

• Go to the OAuth step inside your flow, and mark "expose raw OAuth response":

• After the OAuth step, add a Scriptlet to set the email verification status based on the claims:

Here is an example scriptlet code to set the email verification status:

// id token extraction
const idToken = oauthResponse.idToken;
//email address extraction, depending on the IdP
const email = idToken.email || idToken.sub;
//xms_edov extraction - boolean
const xms_edov = idToken.xms_edov;
//xms_edov extraction - array
const verified_primary_email = idToken.verified_primary_email;


return {
    verified: xms_edov || verified_primary_email.contains(email)
};

• Mark the email as verified if either of the claims indicate verification: