This feature is not yet available on Hanko Cloud.


  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
  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.
Hanko Callback URL

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.
Access Microsoft Entra ID
  1. Select App registrations in the left sidebar.
Access app registrations
  1. On the top left, click on New registration.
Request new app registration
  1. Enter your Application name.
  2. 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.

  3. Under the Redirect URI section select Web as the platform.
  4. Enter the Redirect URL you obtained in the first step as the value.
  5. Click on Register.
Fill app registration form

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
View client ID
  1. To create a client secret, select Certificates & Secrets in the sidebar.
View app certificates and secrets
  1. Select the Client secrets tab.

Hanko currently does not support using Certificates.

  1. Select New client secret.
Request new client secret
  1. Give your secret a name.
  2. Select an expiration date.

Hanko Cloud currently does not provide any means to auto-rotate secrets, so keep the expiration date of your secret in mind and manually refresh the secret when necessary.

  1. Click Add to create the secret.
Configure new client secret
  1. After creating the secret, make sure to copy the secret Value. You will need this when configuring your credentials with Hanko.

You can no longer copy the Value of the secret after a full page refresh. If you you forget to do so, simply create another secret and remove the old one.

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.
View app token configuration
  1. Select Add optional claim.
Add new optional token claim
  1. Select ID as the token type.
  2. Tick the upn checkbox to select it as an additional optional claim.
  3. Click Add.
Configure optional claim
  1. Tick the checkbox to set the required Microsoft Graph permissions.
  2. Click Add.
Set Microsoft Graph permissions for the upn claim

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.

If your application was created before the publication of the vulnerability, and the application previously used unverified emails, you might need to manually alter the authenticationBehaviours as described here.

  1. 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.
View app manifest
  1. 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": []

You may notice that after adding the xms_edov claim, it is listed in the Token configuration section but it is marked with a warning icon claiming that “[t]his claim is not supported and will not be returned in the token”. At the time of writing this does not appear to be correct and the claim is in fact returned in the ID token.

  1. 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:
Hanko Callback URL
  • 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://* matches and
    •* matches URLs like and
    • Use ** to act as a super-wildcard/match-all.
  1. In the Providers section, select Microsoft and use the Enable provider toggle to enable the provider.
  2. Provide the Client ID and Client Secret you obtained in one of the previous section in the remaining inputs.
  3. 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.

We recommend following one of our quickstart guides to integrate the <hanko-auth> component from our @teamhanko/hanko-elements package in your frontend application . On successful integration, the component will display a button for signing in with Microsoft in the login view of the component.

Make sure to configure the page the web component is embedded on as your error redirect URL as well as an allowed redirect URL (see the previous step).

On successful authentication with the provider, the backend issues a session cookie and the web component continues the usual component flow on success. Errors that occur during third party provider authentication are also picked up and displayed in the web component accordingly.