Help CenterAdmin: sign-in and hive settings

Single sign-on: what your IT team needs

This page is for the person who runs your organisation’s sign-in. Your Hives Admin has started the setup in Hives and needs you to add Hives to your identity provider. It takes about ten minutes. Hives’ side of the setup is described in Setting up single sign-on (SAML).

What Hives supports

  • SAML 2.0, with one identity provider per hive.
  • Sign-in started by your provider (from a portal, intranet or app tile) and started by Hives (a button on the hive’s sign-in page). Both end in the same account.
  • The response, the assertion or both signed with SHA-256 or stronger. SHA-1 is refused.
  • Up to two signing certificates at once, so you can roll a certificate over without downtime.
  • Two minutes of clock difference.

Hives doesn’t sign its requests and doesn’t use single logout. Signing out of Hives signs out of Hives only.

The values from Hives

Your Hives Admin copies these from Admin > Hive > Single sign-on and sends them to you. Each hive has its own.

Hives calls it Your provider may call it Looks like
Sign-in address (ACS URL) Reply URL, Assertion Consumer Service URL, Single sign-on URL https://api.hives.co/auth/saml/<id>/acs
Entity ID Identifier, Audience URI, SP Entity ID https://api.hives.co/auth/saml/<id>/metadata
Metadata link Service provider metadata the same address as the Entity ID

Hives asks for an unspecified Name ID format, so any Name ID your provider sends is fine.

What to send back

Give your Hives Admin one of these:

  • a metadata link for the Hives application (best: it carries a new certificate when you renew), or
  • the metadata file, or
  • the Issuer (Entity ID), the sign-in address of your provider, and the signing certificate in PEM.

The attributes Hives reads

Send these as SAML attributes. The names on the left are what Hives expects by default. If you use other names, your Hives Admin changes them in Hives.

Attribute What it holds Needed
first_name First name Yes
last_name Last name Yes
email Work email address Yes, unless people are known by employee ID
employee_id Employee number or another ID that never changes When people are known by employee ID
job_title Job title When the hive uses this profile field
department Department When the hive uses this profile field

If you send no email attribute, Hives reads the email address from the Name ID when it is one.

Choose with your Hives Admin what identifies a person: their email address, or their employee ID. Use employee ID when people have no work email or share one login, and make sure it’s always sent and never changes.

Names are set when a person first signs in. Employee ID, job title and department follow what you send at every sign-in.

Who gets in

Assign Hives in your provider to the people or groups who should use it. Hives lets in everyone your provider lets through, as a Member of the hive. Roles in Hives are given in Hives.

Entra ID

  1. In the Microsoft Entra admin center, open Enterprise applications > New application > Create your own application, name it Hives, and choose to integrate an application that isn’t in the gallery.
  2. Open Single sign-on and choose SAML.
  3. Under Basic SAML Configuration, set Identifier (Entity ID) to Hives’ Entity ID and Reply URL to Hives’ Sign-in address (ACS URL). Leave Sign on URL empty.
  4. Under Attributes & Claims, the given name, surname and email claims are there already, and Hives reads them under their usual Microsoft names. Add the claims Hives needs beyond those, with no namespace: for example employee_id from user.employeeid, job_title from user.jobtitle, department from user.department.
  5. Under SAML Certificates, copy App Federation Metadata Url and send it to your Hives Admin. Use this address, not your tenant’s general federation metadata.
  6. Under Users and groups, assign the people or groups who should use Hives. Hives then also shows up in their My Apps portal.

Okta

  1. Open Applications > Create App Integration and choose SAML 2.0. Name it Hives.
  2. Set Single sign-on URL to Hives’ Sign-in address (ACS URL) and Audience URI (SP Entity ID) to Hives’ Entity ID.
  3. Set Name ID format to EmailAddress and Application username to Email, or to what fits how people are known.
  4. Under Attribute Statements, add first_name (user.firstName), last_name (user.lastName), email (user.email), and as needed employee_id (user.employeeNumber), job_title (user.title) and department (user.department).
  5. Finish, open the Sign On tab and copy the Metadata URL. Send it to your Hives Admin.
  6. Assign the people or groups who should use Hives.

Google Workspace

  1. In the Google Admin console, open Apps > Web and mobile apps > Add app > Add custom SAML app. Name it Hives.
  2. Download the IdP metadata and send the file to your Hives Admin.
  3. Set ACS URL to Hives’ Sign-in address (ACS URL) and Entity ID to Hives’ Entity ID. Name ID format: EMAIL, Name ID: primary email.
  4. Under Attribute mapping, map First name to first_name, Last name to last_name, Primary email to email, and as needed Employee ID to employee_id, Job title to job_title and Department to department.
  5. Turn the app on for the people or organisational units who should use Hives. Google says this can take a while to reach everyone.

Hives also has its own Sign in with Google, which needs no setup. Use the custom SAML app when you want employee IDs, job titles or departments in Hives, or a sign-in your organisation controls.

Other SAML 2.0 providers

Create a SAML application with Hives’ Sign-in address (ACS URL) and Entity ID, send the attributes in the table above, and give your Hives Admin your metadata link, metadata file, or issuer, sign-in address and certificate.

Testing it

Your Hives Admin runs a test sign-in from Hives. It shows every attribute your provider sent and which Hives field each one fills, so you can check the names together. Nobody else can sign in until the test has worked and your Admin switches single sign-on on.

When something goes wrong

Your Hives Admin sees each attempt in the sign-in log with what happened. The most common causes:

  • Not meant for this hive: the Entity ID or the sign-in address in your provider doesn’t match Hives’ values exactly.
  • Signature not accepted: the certificate changed. Send the new metadata or certificate, or use a metadata link so it follows by itself.
  • No identity sent: the attribute that identifies people (email or employee ID) isn’t sent for this person.
  • Link expired: the clocks are more than two minutes apart, or the person took too long.

Questions about Hives’ side: help@hives.co.