»Introduction to Single Sign-On
HashiCorp Cloud Platform (HCP) allows organizations to configure SAML 2.0 SSO (Single Sign-On) as an alternative to traditional user management with GitHub and email-based options. This can help mitigate Account Take Over (ATO) attacks, provide a universal source of truth to federate identities from your identity provider (IDP), and better manage user access to your organization. At this time, HCP only integrates with Okta as an identity provider, with others planned as future work.
Enabling SSO on an organization will disable user invites and require new users to be provisioned via the external identity provider. User accounts that join via SSO are limited to that one organization within HCP, and currently cannot be associated with an existing personal (GitHub or email-based) account. Users provisioned will be automatically granted the least privileged role of organization Viewer. An HCP administrator will need to manually update a user on the Access Control page to elevate permissions.
Once SSO is enabled, existing personal user accounts will still be able to access the organization unless removed by an admin. Existing user accounts with email and password, if their email matches the configured SSO domain, would need to log in with the SSO URL link found in the SSO settings tab.
»Set Up SSO
As an organization owner, you can configure SSO in the Settings page in the primary navigation, within the organization name section. Once on that page, there will be a tab specifically for setting up Okta as your SSO provider. This page provides a form to configure SSO on HCP and also provides instructions on how to configure the SAML integration on your IDP side.
Currently, only the owner who created the organization can configure and modify SSO settings. This may expand to admin roles in the future.
»Verify Your Domain
A DNS record (secret value to set as TXT) is needed to prove ownership of a domain. The domain will be used to match the email addresses for SSO. First, copy the provided verification TXT record from the HCP SSO configuration page and add it to the DNS records of any email domains used by your organization.
There are two scenarios where the request may fail:
- If the domain ownership DNS record hasn’t been configured (or propagated).
- If any of the chosen domains is in use by another HCP organization. HCP currently does not support configuring the same SSO domain on multiple organizations.
Once the verification record has been added, return to the Settings page within HCP to add your email address domains. After selecting Verify domains to check the status of the DNS connection, you may continue by initiating the Okta integration.
NOTE: It may take up to 72 hours for the DNS change to propagate, but it typically happens much faster.
»Initiate Okta Integration
HCP provides two configuration values required by Okta to complete the setup flow. Copy the SAML Assertion Customer URL and the SAML Entity ID from Step 2 in the SSO form, and paste them into Okta.
HCP also requires the email address of all users. HCP provides an Email Attribute Assertion Name that you may copy and paste into Okta as an Attribute Statement.
Within Okta, the Email Attribute Assertion Name that HCP provide will go
into the Name field with the Value being
»Finalize SSO Settings
You may now finish the rest of your SAML back within HCP. Once you have completed the setup within Okta, Okta will provide you with two values: the Okta SSO Sign-On URL and the Okta Certificate. The values can be found in the View Setup instructions.
»Manage an Organization with SSO Enabled
The SSO settings page will now display a summary of the current SSO setup. Pre-existing HCP users who were members of the organization will remain unless removed. The HCP Access Controls (IAM) invite system is immediately disabled and will hide the invitation UI. If a user tries to invite another user, it will return an error. Pre-existing pending invitations can no longer be accepted.
Organization administrators and owners may change the roles of other organization members. You may elevate access roles from Viewer to Contributor and Admin.
The administrator who owns the organization and enabled SSO will be able to sign into the HCP web portal and access the SSO-enabled organization using their original, non-SSO account. If they signed in via GitHub before, they can sign in as normal. If it was through email and password, they can use a special force email + password sign-in link. This is because the login page will default to SSO and hide the password if the email domain matches.
The owner will also be able to sign up with a new SSO user principal, like everyone else, and promote themselves to Admin if appropriate. The old user account cannot be removed or have ownership transferred at this time and can be used as a recovery option in case the SSO configuration requires troubleshooting.
The owner may edit the SSO configuration within the SSO tab in the settings page, under the Manage action menu. They can modify the list of domains, the public signing certificate, and the endpoints. New domains can be added and removed; however, they cannot be empty.
If they have been provisioned on the identity provider configured for the Auth0-SSO-Connection, adding a new domain will allow users with an email address matching the domain to sign up as new SSO users. Other SSO users using email addresses for the other domains will not be affected.
Removing an existing domain will affect SSO users whose email addresses match the removed domain. They can sign in through other methods but will become different users in the database. Organization administrators can remove inactive users from the organization.
The owner may fully delete the SSO configuration from their organization. It has the same effect as removing all domains:
- No SSO user will be able to sign in anymore.
- The current SSO users will remain in the organization but will be inactive.
The owner will be able to re-invite other users using the Access Controls (IAM) invite system again.
To delete SSO from an organization, select Delete SSO Configuration in the Manage menu.
A dialog will appear for you to confirm the deletion of SSO from this organization.