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

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.

​

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

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

​

Add UPN 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

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.

​

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