Google SAML

Google SAML SSO feature is a paid feature. If you're using Hanzo KMS Cloud, to use it.

In Hanzo KMS, head to the Single Sign-On (SSO) page and select the General tab. Click Connect for SAML under the Connect to an Identity Provider section. Select Google, then click Connect again.

Next, note the ACS URL and SP Entity ID to use when configuring the Google SAML application.

2.1. In your Google Admin console, head to Menu > Apps > Web and mobile apps and create a custom SAML app.

2.2. In the App details tab, give the application a unique name like Hanzo KMS.

2.3. In the Google Identity Provider details tab, copy the SSO URL, Entity ID and Certificate.

2.4. Back in Hanzo KMS, set SSO URL and Certificate to the corresponding items from step 2.3.

2.5. Back in the Google Admin console, in the Service provider details tab, set the ACS URL and Entity ID to the corresponding items from step 1.

Also, check the Signed response checkbox.

2.6. In the Attribute mapping tab, configure the following map:

• First name -> firstName
• Last name -> lastName
• Primary email -> email

If you want to sync Google groups to Hanzo KMS groups, you can also configure:

• groups -> groups

This requires setting up group claims in Google Workspace. See the Group Membership Mapping section below for details.

Click Finish.

Back in your Google Admin console, head to Menu > Apps > Web and mobile apps > your SAML app and press on User access.

To assign everyone in your organization to the application, click On for everyone or Off for everyone and then click Save.

You can also assign an organizational unit or set of users to an application; you can learn more about that here.

Enabling SAML SSO allows members in your organization to log into Hanzo KMS via Google Workspace.

Enforcing SAML SSO ensures that members in your organization can only access Hanzo KMS by logging into the organization via Google.

To enforce SAML SSO, you're required to test out the SAML connection by successfully authenticating at least one Google user with Hanzo KMS; Once you've completed this requirement, you can toggle the Enforce SAML SSO button to enforce SAML SSO.

We recommend ensuring that your account is provisioned the application in Google prior to enforcing SAML SSO to prevent any unintended issues.

In case of a lockout, an organization admin can use the Admin Login Portal in the /login/admin path e.g. https://app.kms.hanzo.ai/login/admin.

SAML Group Membership Mapping

In your Google Admin console SAML app, go to Attribute mapping and add:

• Google groups: Include all groups you want to include in the SAML claim. Only these groups will be synced to Hanzo KMS.
• App attribute: groups

Back in Hanzo KMS, under Organization Settings, enable SAML Group Membership Mapping in the Single Sign-On (SSO) tab.

Once configured, Google groups will now be automatically synchronized when users log in through SAML. Users will be added to or removed from Hanzo KMS groups based on their current Google group memberships.

Group membership changes in the SAML provider only sync with Hanzo KMS when a user logs in via SAML. For example, if you remove a user from a group in the SAML provider, this change will not be reflected in Hanzo KMS until their next SAML login. To ensure this behavior, Hanzo KMS recommends enabling Enforce SAML SSO.

If you are only using one organization on your Hanzo KMS instance, you can configure a default organization in the Server Admin Console to expedite SAML login.

If you're configuring SAML SSO on a self-hosted instance of Hanzo KMS, make sure to set the AUTH_SECRET and SITE_URL environment variable for it to work:

• AUTH_SECRET: A secret key used for signing and verifying JWT. This can be a random 32-byte base64 string generated with openssl rand -base64 32.

• SITE_URL: The absolute URL of your self-hosted instance of Hanzo KMS including the protocol (e.g. https://app.kms.hanzo.ai)

Feedback
Google's guide to set up your own custom SAML app.