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 Hank Cloud enterprise settings of a project

Create an Okta application

  1. Create an account at Okta. Once registered, access the Okta Administration console at https://<your_organization>-admin.okta.com.
  2. Select Applications > Applications in the left sidebar.
  3. Click Create App Integration.
Create app integration in the Okta Administrative Console's Applications settings
  1. In the shown modal select SAML as the sign-in method.
  2. Click Next.
Select SAML as sign-in method for new app integration
  1. In the Create SAML Integration wizard, provide an App name.
  2. Click Next.
Configure basic properties like app name and logo in SAML integration wizard
  1. Under Single sign-on URL enter your ACS URL (see Prerequisites - Service Provider ACS URL).
  2. Under Audience URI (SP Entity ID) enter you project API URL (see Prerequisites - Service Provider Entity ID).
Configure Hanko project ACS URL as Single sign-on URL and API URL as Audience URI in SAML integration wizard
  1. Scroll down and find the Attribute statements panel. Under Name enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
  2. Under Name format select URI Reference
  3. Under Value select user.email.
  4. Click Next.
Configure email address attribute mapping in SAML integration wizard
  1. Provide feedback on the next screen of the configuration wizard and click Finish.
  2. Select Sign On in the top tab navigation.
  3. In the Settings > Sign-on methods > SAML 2.0 panel find the Metadata URL in the Metadata details and copy it. You need this for configuring the enterprise connection with Hanko.
Configure email address attribute mapping in SAML integration wizard

Assign users to your application

In order for users to log in you probably have to assign users to it. To assign users
  1. Select Applications > Applications in the left sidebar.
  2. Click Assign Users to Apps.
Assign users to apps in Applications settings
  1. Select the app you want to assign users to.
  2. Select users you want to assign to the app.
  3. Click Next.
Select which users should be assigned to which app
  1. Review your assignments and click Confirm assignments.

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 16 in Create an Okta 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. On the top right click the user dropdown.
  2. Click My settings.
Access user Okta user profile
  1. In your end-user profile select My Apps in the left sidebar.
  2. Find your app and click its icon.
Access user's assigned applications in Okta user profile