# 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.

1. **Connect**: Add your identity provider's details in Hourzero.
2. **Verify domain**: Add a DNS record that proves you own acme.com.
3. **Test**: Sign in through SSO yourself to check it works.
4. **Share**: Employees 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

1. Open **Workspace Settings → Single sign-on** and select **Set up SSO**.
2. Choose **Okta Workforce**, **Microsoft Entra ID**, **Google Workspace**, or **Custom SAML provider**. To pick a different one, select **Change**.
3. Check the **Connection name** (Hourzero fills in the provider's name) and enter your **Company domain**, such as `acme.com`. Don't include `https://` or an `@`.
4. 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.
5. 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.
6. 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 `givenName` and `surname`, Hourzero uses those for the name.
7. 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:

1. Go to **Applications → Applications → Create App Integration** and choose **SAML 2.0**.
2. Paste the ACS URL into **Single sign-on URL** and the Entity ID into **Audience URI (SP Entity ID)**. Set **Name ID format** to `EmailAddress` and **Application username** to `Email`.
3. Under **Attribute Statements**, add `email` = `user.email`, `givenName` = `user.firstName`, and `surname` = `user.lastName`.
4. Finish, then assign the people or groups who should sign in on the **Assignments** tab.
5. On the **Sign On** tab, open the **Metadata URL** and paste the XML into Hourzero.

### Microsoft Entra ID

In the Microsoft Entra admin center:

1. Go to **Enterprise applications → New application → Create your own application**, and choose to integrate an application you don't find in the gallery.
2. 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)**.
3. Keep the default **Attributes & Claims**. Hourzero's attribute names already match them.
4. Under **SAML Certificates**, download **Federation Metadata XML** and paste its contents into Hourzero.
5. Under **Users and groups**, assign the people or groups who should sign in.

### Google Workspace

In the Google Admin console:

1. Go to **Apps → Web and mobile apps → Add app → Add custom SAML app**, and name the app.
2. On **Google Identity Provider details**, select **Download Metadata** and paste the file's contents into Hourzero.
3. Under **Service provider details**, paste the ACS URL and the Entity ID. Set **Name ID format** to `EMAIL` and **Name ID** to **Primary email**.
4. Under **Attribute mapping**, map **Primary email** to `email`, **First name** to `givenName`, and **Last name** to `surname`.
5. 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

1. Open **Workspace Settings → Single sign-on** and select **Set up SSO**.
2. Choose **Custom OIDC provider**.
3. Enter a **Connection name** your team will recognise, such as `Acme Entra ID`, and your **Company domain**, such as `acme.com`.
4. 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.
5. 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.
6. 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**.

1. On the saved connection, select **Get verification token**. Hourzero shows a **TXT record host** and a **TXT record value**.
2. In your DNS settings for `acme.com`, add a new TXT record. Copy the host and value exactly as shown.
3. Wait for the record to go live. This can take from a few minutes to a few hours, depending on your DNS provider.
4. 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

1. On the verified connection, select **Test sign-in**. The **Sign in with SSO** page opens.
2. Enter your **Work email** and select **Continue with SSO**.
3. Sign in on your company's sign-in page.
4. 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](https://hourzero.dev/docs/workspace-management/members).

> [!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

1. Select **Edit connection**.
2. Change the details you need. Leave **Client secret** or **Identity provider metadata XML** blank to keep what's already saved.
3. 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

1. Select **Remove connection**.
2. Read the warning in **Remove SSO connection?**
3. 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:

1. The Redirect URI (OIDC) or ACS URL and Entity ID (SAML) in your identity provider match Hourzero's exactly.
2. The person is assigned to the app in your identity provider.
3. Their email address in the identity provider is on your company domain.
4. 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.

## Next steps

- [Members and invitations](https://hourzero.dev/docs/workspace-management/members): Change what each person can do after they join.
- [Account settings and 2FA](https://hourzero.dev/docs/security/account): Manage your own sign-in methods and two-factor authentication.
- [Billing](https://hourzero.dev/docs/workspace-management/billing): Compare plans and see what Enterprise includes.
