Single sign-on for your organisation

Single sign-on lets people on your organisation's verified domains sign in to 50heads with the account they already use at work. Their company sign-in page (your identity provider, such as Okta, Microsoft Entra ID or Google Workspace) checks who they are, then sends them back to 50heads signed in. It works with OpenID Connect or SAML 2.0: you choose the one your identity provider app uses.

We're rolling single sign-on out to organisations gradually. If you don't see Single sign-on in Settings, then Organisation, it isn't on for your organisation yet. Contact us if you'd like it.

Before you start

• Your organisation needs at least one verified domain. Only people whose email address is on a verified domain can use single sign-on. See Your organisation and its domains.
• You need to be an owner or admin of one of the organisation's teams, signed in on the website.
• Your own email address should be on the verified domain, with an account at your identity provider. You'll need it for the test sign-in.

OpenID Connect or SAML

Both do the same job, and the people signing in see no difference. Pick the one that suits your identity provider:

• OpenID Connect needs a client ID and a client secret from your identity provider. Most modern set-ups use it.
• SAML 2.0 needs no secret. You give your identity provider three values from 50heads, and it gives you back a metadata file or URL. Choose it if your IT team prefers SAML apps, or already runs other SAML apps.

In Settings, then Organisation, choose OpenID Connect or SAML 2.0 at the top of Your identity provider. You can switch later. A switch counts as a change to the provider settings, so single sign-on stays off until a new test works. After a switch, people who signed in before confirm their account once more with an emailed 6-digit code.

With OpenID Connect: what to register

Create one web application (sometimes called a client) at your identity provider, with these settings. The settings page shows the exact redirect URI to copy.

From the application, copy three things into 50heads: the issuer URL, the client ID and the client secret.

Okta (OpenID Connect)

1. In the Admin Console, go to Applications, then Create App Integration. Choose OIDC – OpenID Connect and Web Application.
2. Use the Authorization Code grant only, and add the redirect URI as the sign-in redirect URI.
3. Assign the people or groups who may use 50heads.
4. Copy the Client ID and Client secret from the General tab.
5. The issuer URL is your Okta domain, such as https://example.okta.com, or a custom authorisation server, such as https://example.okta.com/oauth2/default.

Microsoft Entra ID (OpenID Connect)

1. In the Entra admin centre, go to App registrations, then New registration. Choose single tenant, and add the redirect URI with the Web platform.
2. Under Certificates & secrets, create a client secret and copy its Value (not its ID). Note when it expires.
3. Copy the Application (client) ID and the Directory (tenant) ID.
4. The issuer URL is https://login.microsoftonline.com/<tenant ID>/v2.0. Don't use the common or organizations addresses.
5. Under Token configuration, add the optional claims email and xms_edov. Entra doesn't say an email address is verified any other way, so without xms_edov every sign-in is refused.

Google Workspace (OpenID Connect)

1. In the Google Cloud console, in a project owned by your Workspace organisation, set the OAuth consent screen to Internal.
2. Create an OAuth client ID of type Web application, with the redirect URI as an authorised redirect URI.
3. Copy the Client ID and Client secret.
4. The issuer URL is https://accounts.google.com. Only accounts in your Workspace can sign in this way, never personal Gmail accounts.

With SAML: what to register

Create one SAML app for 50heads at your identity provider. The settings page shows the exact values to copy, and you can download them as a metadata file with Download our metadata.

The Name ID should be the person's work email address. If your identity provider sends a different Name ID, also send an attribute called email with the address.

From the app, give 50heads its metadata: a URL (we read it when you save, and only over https) or the metadata file. The metadata names your identity provider, its sign-in URL and its signing certificate.

Okta (SAML)

1. In the Admin Console, go to Applications, then Create App Integration, and choose SAML 2.0.
2. Set Single sign-on URL to the ACS URL and Audience URI (SP Entity ID) to the entity ID. Leave Use this for Recipient URL and Destination URL ticked.
3. Set Name ID format to EmailAddress and Application username to Email.
4. Optional: under Attribute Statements, add email with the value user.email.
5. Assign the people or groups who may use 50heads.
6. On the Sign On tab, copy the Metadata URL into 50heads.

Microsoft Entra ID (SAML)

1. In the Entra admin centre, go to Enterprise applications, then New application, then Create your own application. Choose Integrate any other application you don't find in the gallery (Non-gallery).
2. Under Single sign-on, choose SAML. In Basic SAML Configuration, set Identifier (Entity ID) to the entity ID and Reply URL (Assertion Consumer Service URL) to the ACS URL. Leave Sign on URL and Relay State empty.
3. Under Attributes & Claims, set the unique user identifier (Name ID) to the user's email address, with the format Email address. Entra already sends the email address as the claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
4. Under SAML Certificates, leave the signing option as Sign SAML assertion and the algorithm as SHA-256. Copy the App Federation Metadata URL into 50heads.
5. Under Users and groups, assign the people or groups who may use 50heads.

Google Workspace (SAML)

1. In the Google Admin console, go to Apps, then Web and mobile apps, then Add app, then Add custom SAML app.
2. On the Google Identity Provider details page, choose Download metadata. You'll give this file to 50heads.
3. Set ACS URL to the ACS URL and Entity ID to the entity ID. Leave Signed response off: Google signs the assertion, which is what 50heads checks.
4. Set Name ID format to EMAIL and Name ID to Basic Information > Primary email.
5. Turn the app on for the people or organisational units who may use 50heads.
6. In 50heads, paste the contents of the metadata file, or choose the file.

Set it up in 50heads

1. Open Settings, then Organisation, and choose Confirm it's you if asked. Every change needs that check, and it lasts 10 minutes.
2. In Single sign-on, choose the protocol. For OpenID Connect, enter the issuer URL, client ID and client secret. We store the secret encrypted and only ever show its last four characters. For SAML, enter the metadata URL, or paste or choose the metadata file. We show your identity provider's entity ID, its sign-in URL and when its certificate expires.
3. Choose the team people join when they first sign in, and their role: member, viewer or admin. Never owner or billing. People already in one of the organisation's teams stay where they are.
4. Choose Save settings. We read your identity provider's settings straight away, so a mistyped issuer URL or a wrong metadata file shows up now, not when people try to sign in.

Test sign-in

Choose Test sign-in. You go to your identity provider, sign in as yourself, and come back to the settings page with the result.

• Nobody can use single sign-on until a test works.
• Any change to the issuer URL, client ID, client secret or how the secret is sent needs a new test. With SAML, so does a new identity provider entity ID, sign-in URL or a certificate that replaces the current one.
• Test as yourself. A test that signs you in as you also links your 50heads account to your company sign-in.

Turn it on

Once a test has worked, choose Turn on. People with an email address on your verified domains now see Use your company sign-in when they enter their email on the sign-in page. They can still use email codes, Apple, Google and passkeys.

The first time someone signs in this way:

• If they have no 50heads account, we make one and add them to the team you chose, with the role you chose.
• If they already have a 50heads account with that email address, we never merge them on the email alone. We email a one-time 6-digit code to that address. They enter it once, and from then on their company sign-in opens their existing account.

Require single sign-on

Choose Require it to make your identity provider the only way in for addresses on your verified domains. Before you can, you must have run a test that worked, signed in as yourself, since the last change. This stops you locking yourself out.

While single sign-on is required:

• We don't send email codes to addresses on your verified domains. The sign-in page sends them to your company sign-in instead.
• Apple, Google and passkey sign-in stop working for those addresses, except for break-glass owners.
• When you turn it on, members of your teams on those domains who signed in another way are signed out, and sign in again with your identity provider. Break-glass owners stay signed in, and so does the session you used to turn it on.
• The provider settings are locked, except for SAML certificate changes made with Keep the current certificate as well (see below). To change anything else, stop requiring single sign-on, make the change and test again.

You can stop requiring single sign-on at any time, and email codes work again straight away. If one of your domains stops counting as verified, the requirement stops for that domain at once, so nobody is locked out.

SAML certificate changes

Your identity provider signs every SAML sign-in with a certificate, and certificates expire. The settings page shows when each one expires, and warns you 30 days before.

To change certificates without a break in sign-ins:

1. Get the new certificate's metadata from your identity provider. Most identity providers let you add a new certificate before you make it the active one.
2. In 50heads, enter the metadata URL again (or the new file) and tick Keep the current certificate as well. 50heads now accepts both, and single sign-on stays on, even while it's required.
3. Make the new certificate active at your identity provider.
4. In 50heads, choose Stop accepting next to the old certificate.

50heads accepts up to 2 certificates at once. Replacing a certificate without keeping the old one counts as a change to the provider settings: it needs a new test, and isn't possible while single sign-on is required.

Sign-in from your identity provider's app list (SAML)

With SAML, people can also start from the 50heads tile in their company app list (sometimes called IdP-initiated sign-in). This is off unless you turn on Allow sign-in from the identity provider's app list.

Sign-ins that start at your identity provider can't be matched to a request from 50heads, so we're stricter with them. Each one is accepted only once, only within 5 minutes of your identity provider making it, and always lands on the 50heads home page, whatever the app asks for. Leave it off unless your people need the tile. Sign-ins that start on the 50heads sign-in page work either way.

Break-glass owners

Break-glass owners can still sign in with a passkey while single sign-on is required. They're there for when your identity provider is down or set up wrongly.

• You can have up to 2. They must be owners of one of the organisation's teams, with a passkey on their 50heads account.
• Only owners can add or remove them.
• Every break-glass sign-in is recorded in the activity log and emailed to every admin.
• Changes to single sign-on made after a break-glass sign-in need a fresh check with a passkey or authenticator app.

The 50heads app

On the app, people enter their work email as usual. If their organisation uses single sign-on, the app opens their company sign-in page in a secure browser window and brings them back signed in. If their account needs linking, the app asks for the 6-digit code from the email.

The sign-in log and activity

Sign-in log lists single sign-on sign-ins and tests that failed or needed a code, newest first, with the error code. We never keep the tokens your identity provider sends. Activity records every change: setting up, tests, turning on and off, requiring, linking accounts and break-glass.

Every single sign-on event is in the audit log too, where admins can filter and export it.

Fixing errors

The sign-in log and the test result show a code. Here's what each one means.

SAML has its own codes:

Related

• Your organisation and its domains
• Provisioning and security policies
• Sign-in options
• The audit log