​
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.

​
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.

​
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.
  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.
  1. Once your app is created, select Single sign-on in the application sidebar.
  2. Select SAML as the SSO method.
  1. Find the Basic SAML configuration panel and click Edit.
  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.
  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.

​
Attribute mapping

SAML SSO integration with Hanko requires an attribute with a user’s email address in IdP’s SAML response’s attribute statement. To ensure this attribute is present:

  1. In your application’s Single sign-on configuration, find the Attributes & Claims panel and click Edit.
  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.
  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.

​
Assign users to your application

In order for users to log in you probably have to assign users to it.

  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.
  1. If you selected Yes in step 4, then select Manage > Users and groups.
  2. Click Add user/group.
  1. Under Users, click None selected/X user selected.
  2. Select the users you want to assign.
  3. Click Select.

​
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.
  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.

​
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.