​
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 Google Workspace application

  1. Sign in to the Google Admin Console.
  2. In the left sidebar select Apps > Web and mobile apps.
  3. Toggle the Add app dropdown in the main view.
  4. Click Add custom SAML app.
Create a custom SAML app in the Google Admin Console
  1. Provide a name for your app.
  2. Click Continue.
Create a custom SAML app in the Google Admin Console
  1. Click Download Metadata. You need to download and host this file publicly because Hanko requires access to the metadata file via URL. See Hosting the SAML XML Metadata file for details.
  2. Click Continue.
Download SAML IdP Metadata XML for your application
  1. Under ACS URL enter your ACS URL (see Prerequisites - Service Provider ACS URL).
  2. Under Entity ID enter you project API URL (see Prerequisites - Service Provider Entity ID).
  3. Click Continue.
Provide Service Provider details
  1. In the Attributes panel, click Add Mapping.
Provide Service Provider details
  1. Provide the following mapping:
Google Directory AttributeApp attribute
Primary emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  1. Click Finish.
Create an attribute mapping for the email address
  1. You should be redirected to your app’s “dashboard”. Click the User access panel.
Configure user access for your application
  1. Set the Service status to ON for everyone.
  2. Click Save.
Configure user access for your application

​
Hosting the SAML XML Metadata file

Google only provides SAML metadata as a downloadable XML file, but Hanko requires access to metadata files via URL rather than file upload. You must host the downloaded file on a publicly accessible web service (such as AWS S3, Cloudflare R2, or a public website) that Hanko can access.

​
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 of your hosted SAML XML Metadata file.
    • 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. Open one of the Google Workspace applications, e.g. Google Calendar.
  2. Access the user’s available applications in the top navigation.
  3. Find your application and click the icon for your application.
Test identity provider initiated login via google workspace app (calendar)