Skip to main content

Setting Up SAML SSO with Hive Using CAS (Central Authentication Service)

Written by Ellen Kajca

This article tells you how to set up SAML single sign-on (SSO) between Hive and CAS, or another identity provider (IdP) that supports SAML 2.0. It also tells you how to fix common sign-in errors.

1. Overview

Hive supports SAML 2.0 single sign-on. Each Hive workspace has its own SAML address. You set this address in your identity provider.

This guide is for IT admins and IdP owners who:

  • Use CAS or another SAML 2.0 identity provider

  • Set up SAML SSO for a Hive workspace

  • See an error page when users sign in with SSO

To edit the SSO settings in Hive, you must be a System Admin of the workspace. If the workspace has no System Admin, a workspace Admin can edit them.

SAML SSO is part of the Enterprise Security features. If the Security page shows Get Enterprise Security, contact Hive support.

2. Hive SAML Service Provider Details

To find the Hive values, open Workspace settings. Under Advanced, select Security, then select Authentication. The URLs and IDs have a copy button.

Values to give your identity provider

  • SP metadata URL:
    ​https://app.hive.com/sso/saml/[YOUR_WORKSPACE_ID]/sp_metadata.xml
    If your IdP can import SAML metadata, give it this URL. You can also select Download XML and upload the file to your IdP. The metadata is available only after you fill in the SAML SSO URL field (see below).

  • Your ACS URL (Assertion Consumer Service URL, also called reply URL):
    ​https://app.hive.com/sso/saml/[YOUR_WORKSPACE_ID]
    Your IdP must send the sign-in response to this exact URL.

  • Service Provider Issuer (Entity ID), also called Audience:
    ​https://hive.com
    If you select Use unique Service Provider Entity ID, the value changes to https://app.hive.com/workspace/[YOUR_WORKSPACE_ID]. Use this option only if your IdP needs a different value for each Hive workspace.

  • NameID format:
    ​urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    This is the default value of the Identifier format field in Hive.

  • Binding for the sign-in response:
    ​HTTP-POST

Your Workspace ID shows the ID of your workspace. Replace [YOUR_WORKSPACE_ID] with this value. The ID has 17 letters and digits.

Values from your identity provider to put in Hive

  • SAML SSO URL (required): the SAML 2.0 sign-in URL of your IdP. For CAS, this is the SAML 2.0 SSO endpoint.

  • Certificate (required): the signing certificate of your IdP. See section 4.

  • Identity Provider Issuer (optional): the entity ID of your IdP. It is necessary for single logout.

  • SAML SLO URL (optional): the single logout URL of your IdP.

Hive saves each field when you move out of it. There is no Save button.

3. NameID and User Accounts

Hive uses the SAML NameID to find the user who signs in.

  • The NameID must be the email address of the user.

  • Use an email address that can receive email. At the first SSO sign-in, Hive sends a code to this address.

  • Upper case and lower case letters do not matter. Other differences do. For example, jöhn@example.com and john@example.com are different addresses.

What Hive does when a user signs in

  • If no Hive account has this email address, Hive creates the account and adds the user to the workspace. You do not have to invite users first.

  • If a Hive account has this email address, Hive uses that account. If the account is not in the workspace, Hive adds it.

  • The first time a user signs in with SSO, Hive shows the page Link your SAML account. The user enters the 6-digit code that Hive sends to the email address. The code expires in 15 minutes. The user sees this page again only if the email address or the identity provider changes.

  • Hive can refuse to add a user to the workspace, for example when the plan of the workspace is at its member limit. See section 6.3.

Optional: send the first name and the last name of the user as attributes, for example givenName and surname, or firstName and lastName. Hive uses them for the name of a user who has no name in Hive yet.

4. Certificate Requirements

Hive uses the signing certificate of your identity provider to verify each sign-in response.

4.1 Which certificate to use

In the Certificate field on the Authentication page, paste:

  • The IdP signing certificate for SAML responses

  • Not your HTTPS/TLS certificate

Your IdP must sign the SAML response, the assertion, or both. One valid signature is sufficient.

If your IdP changes its signing certificate, paste the new certificate in Hive at the same time.

4.2 Certificate format

You can paste the certificate in one of these 2 formats:

  • The full certificate text as your IdP gives it, from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. The BEGIN line and the END line must each be on a line of their own.

  • Only the encoded text between those 2 lines.

Spaces and empty lines before or after the certificate are not a problem. Do not join the full certificate text into one line. Do not add or remove characters.

If you are not sure, copy the certificate again from your IdP. You can also open the certificate file in a plain-text editor and copy all of the text.

5. Testing the SAML SSO Flow

Under Force SSO, keep Do not force SSO selected until the test is successful. Then users can still sign in with their Hive password.

After you set up your identity provider and Hive:

  1. Open a private browser window. Go to:
    ​https://app.hive.com/sso/saml/[YOUR_WORKSPACE_ID]

  2. Hive opens the sign-in page of your IdP (for example, your CAS sign-in page).

  3. Sign in with a test user. The email address of the user must be the NameID in the SAML response.

  4. If this is the first SSO sign-in of the user, Hive shows Link your SAML account. Enter the 6-digit code from the email.

  5. Hive opens the workspace.

Sign-in that starts from your IdP (IdP-initiated sign-in) also works.

If Hive shows a page with the heading Authorization Error, see section 6.

6. Common Errors and How to Fix Them

When an SSO sign-in fails, Hive shows a page with the heading Authorization Error. The page shows an error line, for example Error 401, and a Diagnostic code. For most errors, it also shows the cause and the next step. The first part of the code tells you the cause. For a list of all codes, see Fix sign-in errors with the diagnostic code.

6.1 SAML-RESPONSE-INVALID (invalid signature)

The page shows Error 401. Hive could not verify the sign-in response from your IdP. Do these checks:

  1. Certificate type: use the IdP signing certificate, not the HTTPS certificate.

  2. Current certificate: if your IdP changed its signing certificate, paste the new certificate in Hive.

  3. Certificate format: see section 4.2.

  4. Signature: make sure that your IdP signs the response or the assertion.

  5. Clock: make sure that the clock of your IdP server is correct. Hive accepts a difference of up to 3 minutes.

Then test again (section 5).

6.2 SAML-RECIPIENT-MISMATCH

The page shows Error 401. Your IdP sent the sign-in response to a different Hive address.

  • Set the ACS URL (reply URL) in your IdP to the exact value of Your ACS URL in Hive.

  • If you connect more than one Hive workspace, each IdP app must use the ID of its own workspace.

6.3 NameID and account errors

  • SAML-NAMEID-MISSING (Error 401): your IdP did not send a NameID. Set the NameID to the email address of the user.

  • SAML-MEMBER-REFUSED with Error 403: Bad input: the NameID is not a valid email address. Set the NameID to the email address of the user.

  • SAML-MEMBER-REFUSED with a different message: Hive could not add the user to the workspace. The message tells you why. For example, Cannot invite on a free plan means that the plan of the workspace is at its member limit. Contact Hive support if you need more seats.

  • SAML-ACCOUNT-MISMATCH (Error 403): the email address from your IdP is almost the same as the email address of a Hive account, but not exactly the same. For example, one letter has an accent. Use the exact email address of the Hive account.

6.4 Workspace ID errors

The workspace ID in your IdP and in the sign-in URL must be the same as Your Workspace ID in Hive. The page shows Error 404. Use the start of the code to find the cause:

  • Code starts with SAML-NOT-CONFIGURED: no Hive workspace has the ID in the URL. Copy Your ACS URL again and paste it in your IdP.

  • Code starts with ERROR, and the page says Not found: the workspace ID in the URL does not have the correct format. Copy the URL again.

  • Code starts with ERROR, and the page says SAML is not configured for this workspace: the SAML SSO URL field or the Certificate field in Hive is empty. Fill in the 2 fields.

6.5 SAML-RESPONSE-REPLAYED

The page shows Error 401. Hive already used this sign-in response. This usually occurs when the user reloads the page or goes back in the browser. Go to the Hive sign-in page and sign in again.

6.6 Error 429: Too many requests

Hive limits the number of sign-in attempts, email codes and new accounts in a short time. This can occur when you test many times, or when many new users sign in for the first time at the same time. Wait some minutes, then try again.

6.7 Request signing

By default, Hive does not sign its SAML requests.

  • If your IdP requires signed requests, select Use signed SAML requests on the Authentication page. Your IdP then needs the public certificate of Hive. Contact Hive support to get this certificate.

  • If you do not need signed requests, clear this option in Hive and turn off the requirement in your IdP.

6.8 If the error continues

Contact Hive support. Send:

  • The diagnostic code from the error page, or a screenshot of the page

  • The date and time of the sign-in attempt, with your time zone

  • The email address that the user uses for Hive

Do not send passwords.

7. Advanced: RequestedAuthnContext setting

By default, Hive asks your identity provider to use password sign-in (the PasswordProtectedTransport authentication context). Some IdPs do not accept this request, for example when they use multi-factor or Windows sign-in. Then the IdP can show an error before the user gets back to Hive.

To stop Hive from asking for a sign-in method:

  1. On the Authentication page, find Disable `RequestedAuthnContext`.

  2. Select Disable `RequestedAuthnContext` metadata. Hive saves the change at once.

  3. Test the SSO sign-in again (section 5).

If the problem continues, contact Hive support with the information in section 6.8.

Related Articles
Did this answer your question?