Single sign-on (SSO)
Let employees sign in to Hourzero with their company account, using one OIDC or SAML connection on an Enterprise plan.
Single sign-on (SSO) lets your employees sign in to Hourzero with the same company account they use for email and other work tools. Your IT team controls who can get in, and people have one less password to remember.
You only need this page if your company uses an identity provider, such as Okta, Microsoft Entra ID, or Google Workspace, and you're on an Enterprise plan. If that's not you, your team can sign in with email and password or Google. Setting up SSO is usually a job for your IT administrator.
Where to find it: open Workspace Settings → Single sign-on.
How it works
You connect Hourzero to your identity provider once, then prove you own your company's email domain. After that, anyone with an email address on that domain can sign in through your company's sign-in page and join the workspace.
- 01ConnectAdd your identity provider's details in Hourzero.
- 02Verify domainAdd a DNS record that proves you own acme.com.
- 03TestSign in through SSO yourself to check it works.
- 04ShareEmployees choose Sign in with SSO and use their work email.
Before you begin
Check that you have all of these:
- An Enterprise team workspace. SSO isn't available on Free, Hobby, Standard, or Pro, or in a personal workspace. On other plans, the page shows Enterprise SSO with a View plans button.
- The Owner or Admin role in that workspace. Members see Administrator access required.
- Admin access to your identity provider, so you can create an app there.
- Access to your company's DNS settings (where your domain's records are managed), or someone who can add a record for you.
- One company email domain, such as
acme.com. Each workspace has one SSO connection, and each domain can belong to only one connection.
Note
The domain must match exactly. A connection for acme.com accepts maya@acme.com but not maya@eu.acme.com.
Choose your identity provider
When you select Set up SSO, Hourzero asks which identity provider you use:
| Group | Choice | Use it for |
|---|---|---|
| SAML | Okta Workforce | Okta |
| SAML | Microsoft Entra ID | Microsoft Entra ID (formerly Azure AD) |
| SAML | Google Workspace | Google Workspace |
| SAML | Custom SAML provider | Any other provider that supports SAML 2.0, such as OneLogin or JumpCloud |
| OpenID Connect (OIDC) | Custom OIDC provider | Any provider that supports OpenID Connect |
For Okta, Microsoft Entra ID, and Google Workspace, Hourzero shows where each value goes in that provider's admin console and fills in the attribute names it sends. Pick SAML if you're unsure: every provider above supports it, and you exchange a metadata file instead of typing values. OIDC is simpler if your IT team already uses it for other apps.
You can't switch providers or protocols on a saved connection. To change it later, remove the connection and create a new one.
Set up a SAML connection
- Open Workspace Settings → Single sign-on and select Set up SSO.
- Choose Okta Workforce, Microsoft Entra ID, Google Workspace, or Custom SAML provider. To pick a different one, select Change.
- Check the Connection name (Hourzero fills in the provider's name) and enter your Company domain, such as
acme.com. Don't includehttps://or an@. - Follow the steps Hourzero shows for your provider. They tell you where to paste the Entity ID / audience and ACS URL values shown below the steps. The sections below repeat them.
- Paste your provider's metadata into Identity provider metadata XML. It must include the signing certificate and the single sign-on address. Hourzero fills in Identity provider SSO URL from it.
- Check Email attribute and Name attribute. They match the provider you chose; for a custom provider, change them to the attribute names it sends. If the email attribute is missing, Hourzero uses the Name ID. If the provider sends
givenNameandsurname, Hourzero uses those for the name. - Select Save connection. You see SSO connection saved. Verify your domain to enable sign-in.
Your provider must sign its assertions. Hourzero rejects unsigned assertions and older signing methods.
Okta Workforce
In the Okta Admin Console:
- Go to Applications → Applications → Create App Integration and choose SAML 2.0.
- Paste the ACS URL into Single sign-on URL and the Entity ID into Audience URI (SP Entity ID). Set Name ID format to
EmailAddressand Application username toEmail. - Under Attribute Statements, add
email=user.email,givenName=user.firstName, andsurname=user.lastName. - Finish, then assign the people or groups who should sign in on the Assignments tab.
- On the Sign On tab, open the Metadata URL and paste the XML into Hourzero.
Microsoft Entra ID
In the Microsoft Entra admin center:
- Go to Enterprise applications → New application → Create your own application, and choose to integrate an application you don't find in the gallery.
- Open Single sign-on and choose SAML. Under Basic SAML Configuration, add the Entity ID as Identifier (Entity ID) and the ACS URL as Reply URL (Assertion Consumer Service URL).
- Keep the default Attributes & Claims. Hourzero's attribute names already match them.
- Under SAML Certificates, download Federation Metadata XML and paste its contents into Hourzero.
- Under Users and groups, assign the people or groups who should sign in.
Google Workspace
In the Google Admin console:
- Go to Apps → Web and mobile apps → Add app → Add custom SAML app, and name the app.
- On Google Identity Provider details, select Download Metadata and paste the file's contents into Hourzero.
- Under Service provider details, paste the ACS URL and the Entity ID. Set Name ID format to
EMAILand Name ID to Primary email. - Under Attribute mapping, map Primary email to
email, First name togivenName, and Last name tosurname. - Under User access, turn the app on for everyone, or for the groups or organizational units who should sign in.
Set up an OIDC connection
- Open Workspace Settings → Single sign-on and select Set up SSO.
- Choose Custom OIDC provider.
- Enter a Connection name your team will recognise, such as
Acme Entra ID, and your Company domain, such asacme.com. - In your identity provider, create a web application (a confidential client) that signs in with OpenID Connect. Paste the Redirect URI that Hourzero shows as its sign-in redirect (or callback) address.
- Back in Hourzero, enter the app's Issuer URL, Client ID, and Client secret. The Issuer URL must start with
https://. For example:- Microsoft Entra ID:
https://login.microsoftonline.com/<tenant-id>/v2.0, using the Directory (tenant) ID from the app's overview. - Google:
https://accounts.google.com. Create the OAuth client in Google Cloud and set its user type to Internal so only people in your Google Workspace can sign in.
- Microsoft Entra ID:
- Select Save connection. You see SSO connection saved. Verify your domain to enable sign-in.
Hourzero asks your identity provider for each person's email address and name (the openid, email, and profile scopes). It always uses PKCE, an extra security check during sign-in, so leave PKCE allowed in your provider's app settings.
Microsoft Entra ID and Google work right away. Other OIDC providers, including Okta, need the Hourzero team to allow the provider's address first: until then, saving shows Hourzero doesn't accept this provider's OpenID Connect address yet. Contact us, or use SAML instead.
After saving, you can open View service provider metadata if your identity provider prefers to import Hourzero's details from a file.
Important
Employees must start sign-in from Hourzero. Starting from an app tile on your identity provider's dashboard doesn't work.
Verify your company domain
Verifying the domain proves your company owns it. SSO sign-in stays off until this step is done, and the connection shows Verification required.
- On the saved connection, select Get verification token. Hourzero shows a TXT record host and a TXT record value.
- In your DNS settings for
acme.com, add a new TXT record. Copy the host and value exactly as shown. - Wait for the record to go live. This can take from a few minutes to a few hours, depending on your DNS provider.
- Select Verify domain. You see Domain verified. SSO sign-in is ready. and the badge changes to Verified.
Tip
If verification fails with "Unable to verify domain ownership", the record isn't visible yet or doesn't match. Check for extra spaces or a missing underscore at the start of the host. If your DNS provider adds your domain to the host automatically, don't type acme.com on the end yourself. Wait a little longer, then try again.
The verification token is valid for one week. If it expires, select Get verification token again for a new one, and update the DNS record.
Test sign-in
- On the verified connection, select Test sign-in. The Sign in with SSO page opens.
- Enter your Work email and select Continue with SSO.
- Sign in on your company's sign-in page.
- Hourzero brings you back to the Single sign-on settings page.
Always test before you tell your team. A saved connection and a verified domain don't prove that the identity provider sends the right details.
Tell employees how to sign in
Share one of these with your team:
- The sign-in page: go to the Hourzero sign-in page, select Sign in with SSO, enter their Work email, and select Continue with SSO.
- The direct link: copy the SSO sign-in link from the connection and share it. It opens the Sign in with SSO page already tied to your company's connection.
After signing in, employees land in your company workspace.
What happens the first time someone signs in
- People who aren't in the workspace yet join it as a Member. If they don't have a Hourzero account, one is created for them.
- People already in the workspace keep their current role, including owners and admins.
- Someone with a pending invitation needs to accept that invitation to join. The invitation decides their role.
- People who already have a Hourzero account with the same work email sign in to that same account, so they keep their profile and other workspaces.
To give someone more access, change their role in Members and invitations.
Note
SSO is an extra way to sign in. It doesn't turn off email and password or Google sign-in for your team.
Edit a connection
- Select Edit connection.
- Change the details you need. Leave Client secret or Identity provider metadata XML blank to keep what's already saved.
- Select Save connection. You see SSO connection updated.
Some changes need extra steps:
- Changing the company domain resets verification. Add a new DNS record and verify again.
- Changing the OIDC issuer isn't possible. Remove the connection and create a new one.
Remove a connection
- Select Remove connection.
- Read the warning in Remove SSO connection?
- Select Remove connection again to confirm. You see SSO connection removed.
Employees stay in the workspace and stay signed in, but they can no longer sign in through your identity provider.
Warning
Before you remove a connection, make sure everyone has another way to sign in. People who only ever used SSO can create a password under Account settings while they're still signed in.
If you leave the Enterprise plan
If the workspace moves off Enterprise, the connection shows Inactive and SSO sign-in stops working. Owners and admins can still remove the inactive connection. Switch back to Enterprise to turn it on again.
Troubleshooting
"SSO is not available for this workspace"
The employee's email domain doesn't match a verified connection, or the workspace isn't on Enterprise. Check the domain is verified and spelled exactly as in their email address.
"Your SSO sign-in could not be completed"
The identity provider didn't send what Hourzero expects. Check, in this order:
- The Redirect URI (OIDC) or ACS URL and Entity ID (SAML) in your identity provider match Hourzero's exactly.
- The person is assigned to the app in your identity provider.
- Their email address in the identity provider is on your company domain.
- For SAML: assertions are signed, the certificate hasn't expired, and the email and name attribute names match.
The connection won't save
Read the message under the form. Common causes are a domain with https:// or an @ in it, a domain that already has a connection, or an Issuer URL or SSO URL that doesn't start with https://. If the message says Hourzero doesn't accept your provider's OpenID Connect address, or can't reach your identity provider, contact the Hourzero team or connect with SAML instead.