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
- 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.
- Open Single sign-on and choose SAML.
- 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.
- 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_idfromuser.employeeid,job_titlefromuser.jobtitle,departmentfromuser.department. - 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.
- Under Users and groups, assign the people or groups who should use Hives. Hives then also shows up in their My Apps portal.
Okta
- Open Applications > Create App Integration and choose SAML 2.0. Name it Hives.
- Set Single sign-on URL to Hives’ Sign-in address (ACS URL) and Audience URI (SP Entity ID) to Hives’ Entity ID.
- Set Name ID format to EmailAddress and Application username to Email, or to what fits how people are known.
- Under Attribute Statements, add
first_name(user.firstName),last_name(user.lastName),email(user.email), and as neededemployee_id(user.employeeNumber),job_title(user.title) anddepartment(user.department). - Finish, open the Sign On tab and copy the Metadata URL. Send it to your Hives Admin.
- Assign the people or groups who should use Hives.
Google Workspace
- In the Google Admin console, open Apps > Web and mobile apps > Add app > Add custom SAML app. Name it Hives.
- Download the IdP metadata and send the file to your Hives Admin.
- 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.
- Under Attribute mapping, map First name to
first_name, Last name tolast_name, Primary email toemail, and as needed Employee ID toemployee_id, Job title tojob_titleand Department todepartment. - 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.