Skip to main content

How to set-up a custom SAML single sign-on (SSO)

With Enterprise Security package, use this guide to set up a custom SAML configuration if your Identity Provider isn't yet supported.

Written by Ellen Kajca

See our overview of Security in Hive.

Before you begin

SAML SSO is part of the Enterprise Security add-on. To add it to your plan, an Admin can turn on the Enterprise Security card in Apps.

If you already use Okta, you can follow this guide to get SSO set up. Okta and One Login ask for your Workspace ID. You can copy it from the Authentication page in Hive.

Parameters to configure

You can find all of the Hive values on the Authentication page. Open Workspace settings. Under Advanced, select Security, then select Authentication.

If your Identity Provider (IdP) can import metadata, use the SP metadata URL at the top of the page. Select Copy URL, or select Download XML. If not, enter the values below manually.

Assertion Consumer Service URL (ACS URL)

The ACS URL to use is https://app.hive.com/sso/saml/your_workspace_id. To copy it, go to Your ACS URL on the Authentication page and select Copy URL.

For example, if your workspace ID is "9W72AGwBUhYeKSpiS", then your ACS URL is:
​https://app.hive.com/sso/saml/9W72AGwBUhYeKSpiS

Note: Older versions of this guide used https://hive.com/sso/saml/your_workspace_id. That URL does not work. Use the app.hive.com URL.

Entity ID

https://hive.com

If you connect more than one Hive workspace to the same IdP (for example, with Azure), select Use unique Service Provider Entity ID on the Authentication page. Then copy the value under Service Provider Issuer (Entity ID). It is https://app.hive.com/workspace/your_workspace_id.

Settings to include

  • NameID (required): The NameID must be the user's email address. Hive uses it to find the user. The default format is "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress". If you use ADFS, use the "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" format, and enter it in the Identifier format field in Hive. The value must still be the email address.

  • You do not need a separate email attribute. Hive gets the email from the NameID.

  • "firstName" attribute (optional, recommended): Can be mapped from whatever attribute your IdP uses for first/given name.

  • "lastName" attribute (optional, recommended): Can be mapped from whatever attribute your IdP uses for last/family/surname.

  • Hive also accepts standard attribute names, such as "givenName" and "surname". Hive uses the name only when it creates a new user, or when the user does not have a name in Hive yet, and only when your IdP sends both a first name and a last name. Send both.

Certificates

Hive requires the SAML response or the assertion to be signed. You'll need to paste a valid X.509 certificate into the Certificate field in Hive to verify your identity. This is different from your SSL certificate. Most IdPs will provide this for you when setting up a new application.

Sample custom configuration with Okta

The section that follows will walk you through configuring a custom SAML SSO application with Okta as your IdP.

Before you begin

In order to use SAML SSO with Hive, you must:

  • Be a System Admin in the Hive workspace. If your workspace has no System Admins, a workspace Admin can do the setup.

  • Have the Enterprise Security add-on

Setting up the sample application

  1. Go to the Okta Admin dashboard

  2. Select "Applications"

  3. Click "Add application"

4. Select "Create New App"

5. Choose "Web" as your platform and "SAML 2.0" as your sign on method

6. Name your application, in this case we're calling it "My custom application"


7. Paste in your ACS URL according to your workspace ID. In this example we're using "https://app.hive.com/sso/saml/9W72AGwBUhYeKSpiS" where "9W72AGwBUhYeKSpiS" should be replaced with your actual workspace ID. Set the "Audience URI" to be "https://hive.com", the "NameID Format" to be "EmailAddress", the "Application username" to be "Email".


8. (Optional, recommended) Add the "firstName" and "lastName" attribute statements:

9. Hit "Next"
10. Specify the app to be "I'm an Okta customer adding an internal app" and check the checkbox stating that "This is an internal app that we have created":


11. Click "Finish"
12. Go to the "Sign on" tab under your new app and click the "View setup instructions" button to view details which you'll need to paste into Hive:

13. From the setup instructions page, copy the "Identity Provider Single Sign-On URL", "Identity Provider Issuer", and "X.509 Certificate" into Hive:

14. Paste the 3 copied values from Okta into Hive. Open Workspace settings. Under Advanced, select Security, then select Authentication. Paste them into the SAML SSO URL, Identity Provider Issuer, and Certificate fields.

15. Hive saves each field when you click out of it. You do not need to select a save button.

16. Assign user(s) in Okta to the application. To test the SSO, sign in from Okta (IdP-initiated sign-in), or select Sign in with SSO on the Hive sign-in page.

The first time a person with a Hive account signs in with SSO, Hive sends them an email to verify the link to your IdP. If a person does not have a Hive account yet, Hive creates the account, adds the person to your workspace, and sends them the same verification email.

If SSO sign-in fails, the error page shows a diagnostic code. See Fix sign-in errors with the diagnostic code.

Related Articles
Did this answer your question?