How-to setup HCP SSO SAML with Google Workspaces

Introduction

This page explains how to set up SSO in HashiCorp Cloud Platform (HCP) with the Google identity provider.

Configure SSO

Organization owners and admins can set up SSO. To begin configuring SSO:

1. Log in to HCP and go to your organization.
2. Click Organization settings and then click SSO. The Single Sign-On page appears.
3. Click Configure SSO for your Organization. The Setup SAML SSO page appears, where you will enter the required information for Google Workspaces.

Verify Your Domain

You need a DNS record (secret value to set as TXT) to prove ownership of a domain. HCP uses the domain to match the email addresses for SSO. You must use different SSO domains for each HCP organization. If you try to reuse a domain name, the DNS connection request will fail.

To verify your domain:

1. Copy the verification TXT record from the HCP SSO configuration to the DNS records of any email domains your organization uses.
2. Return to the HCP Settings page and add your email address domains.
3. Click Verify domains.

If the verification is successful, you can continue configuring SSO. If the request fails, your changes to the DNS records may not have propagated yet. It can take up to 72 hours.

Initiate SAML Integration

You must add information from the the Initiate SAML Integration section in HCP to the SAML configuration for a web app in your Google Workspace.

To add the required integration information in Google Workspace:

1. Log in to your Google Workspace admin and go to Apps and select Web and mobile apps.
2. Click Add app and choose Add custom SAML app.
3. Enter your App name and then Continue.
4. Copy the SSO URL and Certificate and then Continue and save this for later.
5. Enter the following information:
   • ACS URL: https://auth.hashicorp.com/login/callback
     • NOTE: This URL is not the same as the "SSO Sign-On URL" provided in the "Initiate SAML Integration" instructions. Google does not require a connection argument.
   • Entity ID: The Entity ID from HCP.
6. Click Add Mapping in Attributes and enter the following information:
   • Basic information: Primary Email
   • App attribuates: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
7. Click Finish.

Finalize SSO Settings

To finish configuring SSO:

1. Paste the copied certificate from your Google Workspace application and into the SAML IDP Certificate field in HCP.
2. Paste the SSO URL from your Google Workspace application into the SAML IDP Single Sign-on URL field in HCP.
3. Click Save SSO Settings.

Now, users can sign in to your organization through Google Workspaces.

Testing SAML configuration

To test, please use the HCP portal login page because HCP SSO is SP-initiated and not IdP-initiated. If you try to test the SAML app directly from Google Workspaces, you'll encounter and "Oops. Something went wrong" message which is expected.