​
Prerequisites

You need your project’s SAML Assertion Consumer Service (ACS) URL and the Service Provider (SP) Entity ID.

​
Service Provider Entity ID

The SP Entity ID for your Hanko project is equal to the API URL of your project. To find the API URL for your project:
  1. Log in to Hanko Cloud and select your project.
  2. Navigate to Dashboard.
  3. Copy and save the API URL.
Obtain the API URL from the Hanko Cloud project dashboard

​
Service Provider ACS URL

To find the Assertion Consumer Service (ACS) URL for your project:
  1. Log in to Hanko Cloud and select your project.
  2. Navigate to Settings > Enterprise connections.
  3. Under Enterprise connections find the Redirect URL panel.
  4. Copy and save the URL.
Obtain the Assertion Consumer Service URL in the Hanko Cloud enterprise settings of a project

​
Create a Microsoft Entra application

  1. Sign up or sign in with Microsoft Entra.
  2. Once you’re logged in, select Identity > Applications > Enterprise Applications in the left sidebar.
  3. Click New Application. This will open the Microsoft Entra Gallery.
Create a new Entra application
  1. In the Microsoft Entra Gallery, click Create your own appplication.
  2. Give your application a name.
  3. Select Integrate any other application you don't find in the gallery (Non-gallery).
  4. Click Create to create the application.
Create a new custom Entra application
  1. Once your app is created, select Single sign-on in the application sidebar.
  2. Select SAML as the SSO method.
Configure new custom Entra application to use SAML as SSO method
  1. Find the Basic SAML configuration panel and click Edit.
Configure new custom Entra application to use SAML as SSO method
  1. Under Identifier (Entity ID) click Add identifier and enter you project API URL (see Prerequisites - Service Provider Entity ID).
  2. Under Reply URL (Assertion Consumer Service URL) click Add reply URL and enter your ACS URL (see Prerequisites - Service Provider ACS URL).
  3. Click Save.
Configure Entity ID and ACS URL in the basic SAML settings
  1. In the SAML Certificates panel, find the App Fedration Metadata Url and copy it. You need this for configuring the enterprise connection with Hanko.
Obtain IdP Metadata URL from SAML certificates settings

​
Attribute mapping

SAML SSO integration with Hanko requires an email address attribute in the IdP’s SAML response. To ensure this attribute is present:
  1. In your application’s Single sign-on configuration, find the Attributes & Claims panel and click Edit.
Access SAMl attribute mappings through Attributes & Claims panel
  1. There should be Additional Claims listed that have been added to your application per default. Find the claim that maps the Entra user’s user.email property and click it.
Select email address attribute mapping
  1. Ensure that the Name is equal to emailaddress and the Namespace is equal to http://schemas.xmlsoap.org/ws/2005/05/identity/claims.
  2. If your users do not have an email set for the user.email property, choose a different source for the mapping. Note that the email address value present in this attribute is used to provision and link accounts. This means that any new accounts created at your Hanko project will use this email address value and any existing accounts in your Hanko project will be linked via this email address value.
Ensure email address attribute name and namepsace matches defaults

​
Assign users to your application

To enable users to log in, you need to assign users to the application.
  1. Select Identity > Applications > Enterprise Applications in the left sidebar.
  2. Select your application, then select Manage > Properties.
  3. Ensure that your application is enabled for users to sign-in.
  4. Choose whether user assignment is required for this app. If set to No, all users will be able to sign in.
  5. Choose whether this app is visible to users. If this option is set to yes, then assigned users will see the application on My Apps in their profile and the O365 app launcher.
Configure custom application properties to make the app available to users
  1. If you selected Yes in step 4, then select Manage > Users and groups.
  2. Click Add user/group.
Configure users and groups for custom application
  1. Under Users, click None selected/X user selected.
  2. Select the users you want to assign.
  3. Click Select.
Select and assign specific users to the application

​
Configure an enterprise connection

  1. Log in to Hanko Cloud and select your project.
  2. Navigate to Settings > Enterprise connections.
  3. Under Connections, click New connection.
Create a new enterprise connection in the Hanko Cloud project settings
  1. In the shown modal provide the following data:
    • A Name for the connection.
    • A Domain for the connection. When users authenticate via SAML SSO, the domain of the email address provided as an identifier at the start of an authentication flow must match the domain configured here.
    • A Metadata URL. This is the URL you copied in step 14 in Create a Microsoft Entra application.
    • Select whether you want skip email verification for this provider.
  2. Click Save to create the connection.
Provide name, domain, metadata URL and email verification requirement for a new enterprise connection

​
Testing your integration

To test your integration via IdP-initiated flow:
  1. Navigate to the Single sign-on configuration for your application (see step 8 in Create a Microsoft Entra application).
  2. Find the Test single sign-on with My App panel and click the Test.
Testing IdP-initiated single sign-on with your Entra application