Social Login (OAuth)CustomizeDefault OAuth Providers

Custom Social Login with Microsoft

When integrating Descope flows in a website, often you'll want to allow Social Login with Microsoft as one of the authentication methods for your users. However, when you actually sign in with the flow, the Microsoft sign-in page will not be personalized to your website domain by default. In order to get that to work, you'll need to make a few changes and create a Microsoft enterprise application and integrate it with Descope. This tutorial will explain all the steps on how to do that.

Note

This guide is specifically for Microsoft Social Login

Current Default Login Page

The default Descope login app looks like this (Click on Microsoft):

Descope custom social login with Microsoft, customize Microsoft OAuth

However, if you use the Descope login app, the sign in page will default to show Sign in to continue to Descope.

Descope custom social login with microsoft, Descope signin example

Instead of displaying Descope and our logo, this guide will show you how to personalize your Microsoft Sign-In Page to display your own company logo and domain instead.

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 CNAME 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 Configuring CNAME and Managing Sessions in Cookies 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:

Descope custom social login with microsoft, creating microsoft enterprise application 1

  1. Create Your Own Application:

Descope custom social login with microsoft, creating microsoft enterprise application 2

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

Descope custom social login with microsoft, creating microsoft enterprise application 3

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

Descope custom social login with microsoft, creating Microsoftf application 3

  1. Go to the Microsoft Entra ID Azure Application, and navigate to App Registrations:

Descope custom social login with Microsoft, creating microsoft application 4

  1. Search for your application by name, after finding it, navigate inside to Certificates & Secrets:

Descope custom social login with Microsoft, creating microsoft application 5

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

Note

Exiting the page will hide the secret forever.

Descope custom social login with Microsoft, creating microsoft application 6

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

Descope custom social login with Microsoft, creating microsoft application 7

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

Descope custom social login with Microsoft, creating microsoft application 8

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

Descope custom social login with Microsoft, creating microsoft application 9

Descope custom social login with Microsoft, creating microsoft application 10

Descope custom social login with Microsoft, creating microsoft application 11

Note

You should ask your administrators to approve the permission granted to the app.

  1. Now on Descope, navigate to the custom Microsoft OAuth settings, and fill the details we've set aside, once done, click on save:

Descope custom social login with Microsoft, creating microsoft application 12

Testing Authentication

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

Descope custom social login with Microsoft, creating microsoft application 13

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

Descope custom social login with Microsoft, creating microsoft application 14

Enterpise 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:

Descope custom social login with Microsoft, triage

  • Merge the identity after verifing the email:

Descope custom social login with Microsoft, merge identity inside the flow

Was this helpful?

Previous

Google

Next

OAuth Scopes and Provider Tokens

On this page

Custom Social Login with MicrosoftCurrent Default Login PageSolutionConfiguring the CNAMECreating a new Enterpise ApplicationTesting AuthenticationEnterpise Application AuthenticationMerging identities from Microsoft