Set up SAML SSO with Google Workspace

Learn how to set up enterprise connections in Hanko for customers using Google Workspace as SAML identity provider.

Hanko Google Workspace SAML Integration Guide:

About Hanko:

Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

What This Guide Covers: This guide demonstrates how to configure Google Workspace as a SAML identity provider for your Hanko project, enabling secure single sign-on authentication for Google Workspace users.

Key Technologies:

• SAML 2.0
• XML digital signatures
• Google Workspace
• Google Admin Console
• SAML assertions

Prerequisites:

• Active Google Workspace account with admin privileges
• Hanko Cloud project
• Basic understanding of SAML authentication protocols
• Ability to host XML metadata files publicly

Tasks You’ll Complete:

• Create custom SAML application in Google Admin Console
• Download and host SAML metadata XML file
• Configure service provider details (ACS URL and Entity ID)
• Set up attribute mapping for email addresses
• Configure user access permissions
• Create enterprise connection in Hanko Cloud
• Test integration using IdP-initiated flow

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

5. Provide a name for your app.
6. Click Continue.

7. 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.
8. Click Continue.

8. Under ACS URL enter your ACS URL (see Prerequisites - Service Provider ACS URL).
9. Under Entity ID enter you project API URL (see Prerequisites - Service Provider Entity ID).
10. Click Continue.

11. In the Attributes panel, click Add Mapping.

12. Provide the following mapping:

Google Directory Attribute	App attribute
Primary email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

13. Click Finish.

14. You should be redirected to your app’s “dashboard”. Click the User access panel.

15. Set the Service status to ON for everyone.
16. Click Save.

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.

4. 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.
5. Click Save to create the 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.