Set Up SAML SSO for HashiCorp Cloud Platform (HCP) Using IBM Security Verify

Introduction

This article provides step-by-step instructions on how to configure IBM Security Verify SAML Single Sign-On (SSO) for the HashiCorp Cloud Platform (HCP). The process is similar to other SSO providers, but this guide specifically details the steps for IBM Security Verify.

1. Configure SSO

•  To set up SSO, you must have admin permissions for your HCP organization. Refer to organizations for more information. Navigate to Organization Settings > SSO > Configure SSO for your Organization > Select SAML. Click the SAML SSO setup page appears with useful details which we will use later.
  

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

  • Copy the verification TXT record from the HCP SSO configuration to the DNS records of any email domains your organization uses.
    
  • Return to the HCP Settings page and add your email address domains.
  • 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.

3. Configure SSO on IBM Security Verify 

Now that your domain is verified and HCP SSO settings are ready, you can proceed with configuring IBM Security Verify as the Identity Provider (IdP).With the admin privileges in IBM Security Verify dashboard, follow these steps to configure the SAML application:

1. Go to Application > Click Add application & select Custom Application.
   
    
2. Give name to your custom application and put the appropriate company name in the General Details page.
3. Now come to Sign-on page, here we will add the details given on HCP SSO configuration page.
4. Select Sign-on method as SAML 2.0
5. Uncheck the metadata box and paste the Entity ID given in HCP SSO configuration page in Provider ID.
6. In Assertion consumer service URL (ACS) enter the following URL in this field: https://auth.hashicorp.com/login/callback 
   Please note: Do not use any other ACS URL here. 
   
7. Now, copy the value of Email Attribute Assertion Name from HCP SSO configuration page then in IDP scroll to Attribute mapping, paste the value in Attribute Name then select Attribute source as Email from drop-down.
   

4. Configuration on HCP 

The SAML IDP Single Sign-On URL will be the Login URL given in the IBM IdP page, scroll to the right to get the value and paste in HCP SSO configuration.

Get the value of SAML IDP Certificate from the IDP and paste it in HCP SSO configuration.

5. Testing

To test the SSO integration, follow these steps:

1. Add the user to IBM Security Verify’s Directory with the appropriate access policy, ensuring their email domain matches the one verified in HCP.
2. Using a user account that has been added to the appropriate group in your Identity Provider (IdP), open a browser and go to:
   https://portal.cloud.hashicorp.com/
3. If the SSO integration has been configured correctly, you will be redirected to IBM Security Verify for authentication. Upon successful authentication, you should be automatically logged in to your HCP (HashiCorp Cloud Platform) account.

References:

HCP SSO Overview
Configuration of single sign-on - IBM
IBM Verify Identity Governance - User Access Control