Single sign-on

Point the workspace at your company's OIDC identity provider, verify the domain, and let your team in.

What SSO does here#

Connect your company's identity provider and your team signs in to Harpoon through it — the same login they already use for everything else. Someone signing in for the first time is created and added to your workspace as a member, so there's no invitation to send.

SSO is additional, not exclusive: email/password, magic links and Google/GitHub sign-in all keep working. There is deliberately no "force everyone through SSO" switch yet — if you need one, tell us and it moves up the list.

Who can set it up#

SSO is on the Fleet plan, and only a workspace owner or admin can configure it — it decides who can get into the workspace, which puts it firmly on the manage side of the role boundary.

One identity provider per workspace. Connecting again replaces the previous one, which is how you rotate a client secret.

If your plan lapses, sign-in keeps working. Locking a team out of their own workspace over a card that expired is not a paywall, it's an outage — so an unentitled workspace can still sign in and still disconnect, it just can't change the configuration.

Setting it up#

Harpoon speaks OpenID Connect. In Okta that's an OIDC — OpenID Connect app integration of type Web Application; other providers call the same thing a "web app" or "confidential client". SAML is not supported yet.

In your IdP, create a web application. Leave the redirect URI blank or put a placeholder in for now — Harpoon gives you the real one in step 3.
In Harpoon, go to Settings → Single sign-on and fill in the four fields below. Saving makes Harpoon fetch your provider's OpenID configuration, so a wrong issuer fails immediately with your provider's own error rather than silently later.
Copy the sign-in redirect URI Harpoon now shows and allow it in your IdP application. It has to match exactly.
Publish the TXT record Harpoon shows, then press Verify. Until that succeeds, SSO sign-in is switched off (see below).
Test it: sign out, go to the login page, choose Sign in with your company SSO and enter an email on your domain.

Field	What to enter
`Email domain`	The domain your team's addresses end in, e.g. `acme.com` — no `@`. This is what routes someone to your IdP at sign-in. Comma-separate several if your team uses more than one.
`Issuer URL`	Your provider's issuer, e.g. `https://acme.okta.com/oauth2/default`. Harpoon appends `/.well-known/openid-configuration` to discover the rest.
`Client ID`	From the application you created in your IdP.
`Client secret`	Also from that application. It's encrypted at rest and never sent back to the browser — the settings page only ever shows the last four characters of the client ID.

Where to find the issuer in your IdP#

The four fields exist in every OIDC provider; only the names move around. Create a confidential web application with the authorization code grant — not a SPA, and not a machine-to-machine client, because Harpoon's server does the code exchange with a client secret.

Provider	What to create	Issuer URL
Okta	`OIDC — OpenID Connect` → `Web Application`	`https://acme.okta.com/oauth2/default` — the Issuer URI under Security → API → Authorization Servers. The org server is just `https://acme.okta.com`.
Microsoft Entra ID	App registration → Web	`https://login.microsoftonline.com/<tenant-id>/v2.0`
Google Workspace	Google Cloud console → OAuth client ID → Web application	`https://accounts.google.com`
Auth0	Regular Web Application	`https://<your-tenant>.auth0.com/`
Keycloak	Client with `Client authentication` ON	`https://<host>/realms/<realm>`
Ping Identity	OIDC Web App	Your environment's issuer, from its OIDC discovery document.

Whichever issuer you pick, opening <issuer>/.well-known/openid-configuration in a browser must return JSON. That is exactly the URL Harpoon fetches when you save, so it's a complete test of the value before you paste it. If it only resolves on your VPN, your IdP isn't reachable from our servers — a self-hosted provider on a private network needs a Harpoon operator to allow-list its origin, so contact support.

Why we ask for a DNS record#

The email domain you claim is powerful: it's what decides that someone@acme.com belongs in your workspace. So we don't take your word for it. Until a TXT record we generate is visible under that domain, the provider is inert — sign-in refuses it, and the domain does nothing.

The record name looks like _harpoon-sso-hp-a1b2c3d4e5f6.acme.com and the value is a one-time token. Both are shown in the settings panel.
Re-opening the panel shows the same record rather than issuing a new one, so a record you already published doesn't stop working while you wait for DNS.
DNS propagation is usually minutes but can be longer. Press Verify again; nothing is lost by retrying.
Changing the domain later resets verification — the new domain has to prove itself in its own right.

How people sign in#

On the login page there's a Sign in with your company SSO option: someone enters their work email and presses Continue. If its domain matches a verified provider they're sent to that IdP and come back signed in. They never need to know a workspace-specific URL, and there's nothing for you to distribute — the domain does the routing.

First-time users are created and joined to the workspace as members. That consumes a seat, and the seat check happens before the trip to your IdP — so a full workspace gives a clear "no seats left" message on the login page rather than a confusing failure on the way back.

What SSO does not do#

Worth knowing before you plan a rollout around it — each of these is a deliberate limit today, not a bug, and telling us which one you need moves it up the list.

Not supported	What that means for you
No SAML	OpenID Connect only. If your IdP policy restricts you to SAML app integrations, we can't connect yet — tell us, because demand is what schedules it.
No enforcement	SSO is an additional door, not the only one. Email/password, magic links and Google/GitHub sign-in keep working for your workspace. There is no "require SSO" switch yet, so SSO alone won't satisfy a policy that says every login must pass through your IdP.
No directory sync (SCIM)	Users are created on their first SSO login, just-in-time. Nobody is pre-provisioned from your directory, and — the important half — deactivating someone in your IdP does not remove them from Harpoon. It stops them signing in via SSO, but if they already have a password or a linked Google account they keep that route in. Off-boarding means removing them under Settings → Members as well.
No role mapping	Everyone arriving through SSO joins as a member. IdP groups and claims are not read. Promote people to admin or owner deliberately, inside Harpoon.

Rotating the secret, and turning SSO off#

To rotate a client secret, create the new secret in your IdP, then press Replace in the settings panel and re-enter all four values. Because a replacement mints a new provider, the sign-in redirect URI changes and the domain needs verifying again — update the URI in your IdP and re-publish the TXT record. SSO sign-in is unavailable in between, so do it in a quiet window rather than on a Monday morning.

To turn SSO off, press Disconnect. Nobody loses their account or their membership; they simply sign in another way — a password reset, a magic link, or Google/GitHub. Disconnecting is always available, even on a lapsed plan, so you can never end up stuck with a configuration you're not allowed to remove.

The provider belongs to the workspace, not to the admin who set it up — but if that person deletes their Harpoon account entirely, the provider goes with it and SSO stops. Register it again with the same values; you'll get a new redirect URI to allow in your IdP.

When it doesn't work#

What you see	What it usually means
Saving fails with a discovery error	The issuer URL is wrong, or your IdP isn't reachable from the public internet. Check it resolves `/.well-known/openid-configuration` in a browser. A self-hosted IdP on a private network needs an operator to allow-list its origin.
Verify keeps failing	The record isn't visible yet, or it's published at the wrong name — some DNS UIs append the domain for you, which turns `_harpoon-sso-x.acme.com` into `_harpoon-sso-x.acme.com.acme.com`.
The IdP rejects the redirect	The redirect URI in your IdP doesn't match Harpoon's exactly — no trailing slash, no `http` where it should be `https`. Copy it from the settings panel again.
Sign-in says there are no seats	Your plan's seat count is used up. Remove a member, cancel a pending invitation, or move up a plan — see plans and billing.
SSO vanished from settings	The subscription lapsed, so configuration is read-only. Existing sign-ins are unaffected.
The form isn't there at all	You're a member rather than an owner or admin. SSO decides who can get into the workspace, so it sits on the manage side of the role boundary.
Saving is refused with SAML is not available yet	You sent a SAML configuration. Harpoon is an OIDC relying party only — create an OIDC/web-application integration in your IdP instead.
Sign-in says the domain has not been verified	The DNS step hasn't completed. This is the deliberate behaviour rather than a fault: an unverified provider can't be used to sign in, because the domain claim is what routes strangers into your workspace.
Someone lands in the wrong workspace	Two workspaces have claimed the same email domain, and only one can hold it verified. Disconnect the stale one.

How we handle your credentials#

The client secret is encrypted at rest with AES-256-GCM — the same sealed store that protects every other credential you give Harpoon — and never comes back to the browser. It's decrypted only for the instant an authorization code is exchanged. The settings panel shows the last four characters of the client ID and nothing more, so if you need a secret's value, read it from your IdP.
Domain verification is the trust boundary. A verified domain also decides which workspace a Google or GitHub sign-in from that domain joins — which is exactly why it can't be claimed without DNS proof.
PKCE is on for the authorization code exchange.
We trust your IdP's identity assertion, not its email_verified claim — the verified domain is the signal that matters. Your IdP remains the source of truth for who exists and what they must pass to get in: password policy, MFA, device trust, all of it stays yours.
Access control is your app assignment. Harpoon admits whoever your IdP vouches for, so scope the Harpoon application to the right groups or people on your side.

More on what Harpoon stores overall is in security & your data.

Still stuck? Contact us or browse all guides.