Add Microsoft Login

​

Prerequisites

1. You need a Hanko Cloud account and a project. Learn more on how to set them up here.
2. You need a Microsoft Azure account. You can create account here.

​

Get your provider redirect URL

When creating an Azure Application, you need to provide a redirect URL that determines where the third party provider redirects after a successful login. This redirect URL consists of the base URL of the Hanko API and the /thirdparty/callback endpoint. You can always view your redirect URL in the Hanko Cloud Console:

1. Sign in to cloud.hanko.io.
2. Select your Organization.
3. Select your Project.
4. In the left sidebar, click Settings, then select Identity providers.
5. Find your redirect URL in the Redirect URL input.

You need the redirect URL for creating a new Azure application in the next step and when configuring your credentials with Hanko (you will also configure the remaining configuration options visible in the above screen in this step).

​

Create a new Azure application

1. Navigate to and log in to the Azure portal.
2. Click the hamburger menu in the navbar in the top left.
3. Select Microsoft Entra ID.

4. Select App registrations in the left sidebar.

5. On the top left, click on New registration.

6. Enter your Application name.
7. Under Supported account types choose the 3rd option i.e Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
   The above option allows any user to login to your application. Other account types (single-tenant only, multi-tenant or public only) are currently not supported.

8. Under the Redirect URI section select Web as the platform.
9. Enter the Redirect URL you obtained in the first step as the value.
10. Click on Register.

​

Get your client ID and secret

Next, you need to obtain your client ID and client secret.

1. You can view the client ID of your app in the Essentials section on the Overview page (Application (client) ID) of your application/app registration. You will need this when configuring your credentials with Hanko

2. To create a client secret, select Certificates & Secrets in the sidebar.

3. Select the Client secrets tab.

4. Select New client secret.

5. Give your secret a name.
6. Select an expiration date.

7. Click Add to create the secret.

8. After creating the secret, make sure to copy the secret Value. You will need this when configuring your credentials with Hanko.

​

Token configuration

Next, we recommend making some additional adjustments to the claims containend in the tokens handed out by Microsoft.

​

Add UPN claim

It is possible that users do not have a primary email address set but Hanko requires email addresses to create accounts. To ensure Hanko is provided with an email address, set the optional upn (UserPrincipalName) claim. In general, the upn domain suffix cannot be changed to an unverified domain and hence the upn will be prioritized over a users’ email (see the next section). To configure the claim:

1. Select your app registration and then select the Token configuration section.

2. Select Add optional claim.

3. Select ID as the token type.
4. Tick the upn checkbox to select it as an additional optional claim.
5. Click Add.

6. Tick the checkbox to set the required Microsoft Graph permissions.
7. Click Add.

​

Protection against the nOAuth vulnerability

In 2023 Descope discovered a vulnerability resulting from misconfigurations of multi-tenant apps that could potentially lead to account takeovers when linking accounts with the provider (account linking is activated by default in Hanko). To mitigate this vulnerability Microsoft provides the following guidance:

1. Configure the authenticationBehaviors setting of your application to disallow unverified email domains. This should be the default case for newly created applications, so no further steps should be required.

2. Use the optional xms_edov token claim to check if an email domain owner has been verified. We recommend implementing this additional security measure in case the tokens do not contain a upn (e.g. if the claim has not been configured or the configuration has been reverted) and decisions have to be based on a users’ email property. To do so, first open your applications Manifest.

3. Find the optionalClaims.idToken key in the manifest. It should already contain an entry for the upn claim you configured in the previous step. Add an entry for the xms_edov claim to the array (make a backup of the manifest file, just in case):

"optionalClaims": {
		"idToken": [
			{
				"name": "upn",
				"source": null,
				"essential": false,
				"additionalProperties": []
			},
			{
				"name": "xms_edov",
				"source": null,
				"essential": false,
				"additionalProperties": []
			}
		]
	}

4. Add another optional claim, only this time add the email claim. Proceed just as described in the previous section when you added the upn claim.

Hanko per default requires email verification. When you configure the xms_edov claim, Hanko will reject any attempt at connecting a Microsoft account if no verified email address is provided.

​

Configure credentials with Hanko

1. In the Hanko Cloud Console, navigate to your project Settings and select Identity providers.
2. Configure the following:

• Error Redirect URL: This is the URL target in your frontend the Hanko API redirects to if an error occurs during third party sign-in. If your frontend uses the hanko-elements web components, this URL should be the URL of the page that embeds the web component such that errors can be processed properly by the web component.

• Allowed Redirect URL: This is the URL target in your frontend the Hanko API is allowed to redirect to after third party authentication was successful. If your frontend uses the hanko-elements web components, this URL should be the URL of the page that embeds the web component.

  The allowed redirect URL supports wildcard matching through globbing:

  • https://*.example.com matches https://foo.example.com and https://bar.example.com.
  • https://foo.example.com/* matches URLs like https://foo.example.com/page1 and https://foo.example.com/page2.
  • Use ** to act as a super-wildcard/match-all.

2. In the Providers section, select Microsoft and use the Enable provider toggle to enable the provider.
3. Provide the Client ID and Client Secret you obtained in one of the previous section in the remaining inputs.
4. Click Save.

​

Frontend integration

To enable a login with Mircosoft in your frontend application we recommend using either our pre-built UI as provided by the @teamhanko/hanko-elements package or building a custom UI using the @teamhanko/hanko-frontend-sdk.

• Hanko Elements
• Hanko Frontend SDK