Admin guide Guide 5 of 5

Company sign-in (SSO) with Okta, Microsoft Entra ID or Google Workspace

Your people sign in to HourSquare with the account your company already runs — Okta, Microsoft Entra ID, Google Workspace or any OpenID Connect provider — under your own MFA policy. This guide is for the IT admin doing the setup. It takes about twenty minutes plus one DNS change, and nothing is switched on for your people until you say so.

How it works

Company sign-in uses OpenID Connect, the standard every major provider supports. When someone types a work e-mail on the HourSquare login page, the page checks whether that domain belongs to a company with sign-in switched on and sends the browser to your provider. Your provider checks the password and runs MFA under your policy, then sends the browser back to HourSquare with a signed proof of who just signed in. HourSquare never sees or stores a password.

People are matched by e-mail on their first company sign-in, and only inside domains you have verified. From then on they are recognised by the permanent id your provider assigns, so a renamed mailbox does not break anything. HourSquare never creates accounts on the spot: HR adds people first, exactly as today.

Before you start

Company sign-in is a plan feature that HourSquare switches on per company. If Settings › Sign-in shows "available on request", contact us first.
In HourSquare you need the SuperAdmin role or the Manage single sign-on permission. Only a SuperAdmin can change who is exempt.
At your provider you need admin access to create an application (Okta, Entra ID) — or nothing at all for Google Workspace.
You need to add one TXT record at the DNS host of your e-mail domain.

Step 1 — Verify your domain

In the Hub open Settings › Sign-in and, in the Domains box, click Add domain. Enter the domain your people's e-mail addresses end with, for example acme.com.
Copy the TXT record HourSquare shows: hoursquare-domain-verification=… followed by a random value.
At your DNS host (Cloudflare, GoDaddy, Route 53, your registrar) add a TXT record for that exact name — the domain itself, or the subdomain label if you verify a subdomain — with the copied value as its content. Keep any other TXT records you already have.
Back in HourSquare click Verify. The check asks your domain's own nameservers directly, so it succeeds as soon as the record is published — usually within a minute. If it says the record was not found yet, wait a moment and try again.

The record at your DNS host

Type   TXT
Name   acme.com            (the domain itself; "hr" for hr.acme.com)
Value  hoursquare-domain-verification=<value shown in the Hub>
TTL    Auto

One verified domain belongs to one company on HourSquare. Shared mailbox domains such as gmail.com or outlook.com cannot be verified.
HourSquare re-checks the record every day and again before company sign-in becomes required; if the record disappears, the domain lapses and you are told.
You can verify several domains. Company sign-in applies to people whose e-mail is on any of them; everyone else keeps their password.

Step 2 — Connect your identity provider

In the Identity provider box click Connect and pick your provider card. Each card asks only for what that provider needs.

Okta

In the Okta Admin Console go to Applications › Applications › Create App Integration. Sign-in method OIDC – OpenID Connect, application type Web Application.
Name it HourSquare. Grant type: Authorization Code. Sign-in redirect URI: the redirect URI above. Leave the sign-out redirect URI empty.
Under Assignments assign the people or groups who should have HourSquare (or Everyone). Save.
Client authentication must be Client secret. Copy the Client ID and the Client secret.
In HourSquare, on the Okta card, paste the Client ID and secret. For the discovery URL paste your org URL such as https://acme.okta.com (the default authorization server, https://acme.okta.com/oauth2/default, also works) — HourSquare completes it to the /.well-known/openid-configuration document and pins the issuer it finds there.

Microsoft Entra ID

At entra.microsoft.com go to Identity › Applications › App registrations › New registration. Name it HourSquare, supported account types "Accounts in this organizational directory only" (single tenant), platform Web, redirect URI: the redirect URI above. Register.
On the Overview page copy the Application (client) ID and the Directory (tenant) ID.
Under Certificates & secrets click New client secret, pick an expiry (24 months at most) and copy the Value immediately — it is shown once.
In HourSquare, on the Microsoft Entra ID card, paste the tenant ID, client ID and secret, and enter the secret's expiry date. The discovery URL is built for you from the tenant ID; HourSquare refuses the multi-tenant common and organizations endpoints on purpose.
Conditional Access and your MFA policies apply automatically. People sign in with their Entra user principal name, which must be on a domain you verified in Step 1.

Google Workspace

Nothing to configure in the Google Admin console. Verify your Workspace domain in Step 1, pick the Google Workspace card and save. HourSquare uses its own Google integration and accepts only accounts whose hosted domain is one of your verified domains; a personal @gmail.com account is refused even if it is invited to your Workspace.

Other OpenID Connect providers

Create an OpenID Connect web application at your provider (JumpCloud, OneLogin, Auth0, Keycloak, AD FS and others) with the redirect URI above and the authorization code grant.
Copy the client ID, the client secret and the provider's issuer or discovery URL. Pasting the issuer alone, such as https://login.example.com, is enough — HourSquare completes it to /.well-known/openid-configuration.
The provider must publish a discovery document over https on a public host, sign tokens with an asymmetric key, and send the email and email_verified claims for people on your verified domains.

On the Identity provider box click Run a test sign-in. Your browser goes to your provider and comes back to the same page with the result; nothing is linked and no session is created. You must run it yourself, and sign in at the provider with the same work e-mail as your HourSquare account — the test is refused if the provider signs in anyone else, which is what stops a mistyped configuration from ever locking your company out. A passed test is remembered for the current configuration; change the provider details and you test again.

The page says	What it means	What to do
The discovery URL was refused	The address is not an https discovery document on a public host, or it carries a query string.	Paste the issuer or the exact `…/.well-known/openid-configuration` URL. Private hosts and IP addresses are never accepted.
The provider signed in an account HourSquare cannot match	The e-mail your provider sent is not on a verified domain, or no HourSquare account has it.	Verify the domain in Step 1; make sure your HourSquare account uses your work e-mail; run the test with that account.
The provider signed in a different account than yours	You are signed in at the provider as someone else.	Sign out at the provider (or pick "use another account") and run the test again with your own account.
redirect_uri mismatch (shown by the provider)	The redirect URI registered at the provider differs from the one above.	Register it exactly, https, no trailing slash, then run the test again.

Step 4 — Switch it on

Company sign-in has three settings, changed in the Sign-in policy box.

Setting	What your people see
Off	Nothing changes. Passwords, passkeys and Google sign-in work as before.
Optional	People on a verified domain get a "Continue with company sign-in" button next to the password field. Both ways in work. This is the setting to start with.
Required	For people on a verified domain the password field disappears and company sign-in is the only way in. Their existing sessions are ended so everyone re-enters through your provider. Forgotten-password links stop for them, and new hires get an invitation without a set-password link.

Required can only be switched on when a domain is verified, the test sign-in has passed for the current configuration, and every SuperAdmin has two-factor authentication or a passkey. That last rule exists because SuperAdmins keep a break-glass password login under Required; every use of it is recorded and the other SuperAdmins are notified.

Exemptions: a SuperAdmin can exempt individual people — a contractor without a provider account, someone whose account is still being created — so they keep their password under Required. The exempt list is written to the change history.
Sessions: a company sign-in session lasts 12 hours from the sign-in at your provider, however active the person is. Someone you disable at the provider therefore loses HourSquare within the working day; offboarding them in HourSquare ends the session at once.
Idle timeouts and Log out ask your provider to re-authenticate on the next sign-in, so an unattended machine cannot be re-entered by typing an e-mail.
Switching back to Optional or Off never locks anyone out: passwords work again immediately.

Keeping it healthy

Client secrets expire (Entra ID enforces this). Enter the expiry date on the card and HourSquare reminds the admins 30, 14, 7 and 1 days ahead; rotate the secret from the card without downtime.
The change history on the Identity provider box records every configuration change, mode change, exemption change and test run, with who did it.
If a verified domain's TXT record disappears, the domain lapses at the next daily check and the admins are told; company sign-in keeps working for people already linked.
To stop using company sign-in, set the mode to Off. The configuration is kept, so you can switch it back on later without setting up again.