Team plan

Set up single sign-on

hiccup speaks OpenID Connect, so it connects to Microsoft Entra ID, Okta, Google Workspace, Keycloak, or any other IdP that offers an OIDC application type. Once it is on, colleagues on your claimed email domains sign in with "Continue with SSO" and join your team automatically — no invite link needed. Configuration lives on your team page, visible only to the team owner.

What hiccup needs from your IdP

Three values, all pasted into the SSO card on your team page:

Field	Where it comes from
Issuer URL	Your IdP's OIDC issuer — must serve a discovery document at `<issuer>/.well-known/openid-configuration` over https. hiccup fetches this itself to find your IdP's real sign-in and token endpoints, and refuses anything that is not a public https address.
Client ID	Issued when you register hiccup as an application in your IdP.
Client secret	Issued alongside the client ID. Stored server-side, write-only — hiccup never displays it back, not even to you. Leaving it blank on a later save keeps whatever is already stored.

Redirect URI. One fixed value, the same for every team: https://hiccup.monster/api/auth/sso/callback (a self-hosted instance uses its own domain instead — the exact value for yours is shown, ready to copy, on the SSO card itself). Register this as the app's redirect/callback URI in your IdP.

Setup, step by step

In your IdP's admin console, register a new application: type OpenID Connect / Web application, grant type Authorization Code.
Set its redirect URI to the value in the box above.
Copy the issuer URL, client ID and client secret it gives you.
On hiccup, open your team page → Single sign-on, and paste the three values in.
List the email domains this IdP is authoritative for (up to 10) — e.g. acme.com. A domain can only be claimed by one team; consumer providers (Gmail, Outlook.com and similar) can never be claimed by any team.
Click Test connection — hiccup fetches your discovery document and confirms it can find real authorization and token endpoints, before you save anything.
Save. Sign-in is live immediately; enforcing it for everyone else is a separate step below.

Notes for specific providers

Microsoft Entra ID (Azure AD). Use your tenant-specific issuer — https://login.microsoftonline.com/<tenant-id>/v2.0 — not /common or /organizations; either of those fails issuer validation, since hiccup checks the discovery document's own issuer field against exactly what you configured. When creating the client secret, copy the Value column, not the Secret ID.

Okta. Create an OIDC Web Application with the Authorization Code grant. The issuer is your org URL (https://<org>.okta.com), or a custom authorization server's URL if you use one. Okta enforces its own app-assignment rules before a sign-in attempt ever reaches hiccup — an unassigned user sees an Okta error page, not one of hiccup's.

Google Workspace. The issuer is always https://accounts.google.com. Set the OAuth consent screen to Internal so it is limited to your Workspace organisation. This is a separate application registration from hiccup's own "Continue with Google" button — that one links one person's individual account; this one routes your whole domain.

Who can sign in

Three cases, in order:

Already on your team, email on a claimed domain: their first SSO sign-in links their identity provider to their existing account. Nothing else about the account changes — a password they already had keeps working too.
Nobody on hiccup has that email yet: an account is created automatically on first sign-in and added to your team, exactly as if you had sent them an invite link.
The email belongs to an account that already exists, but not on your team: refused, always. Your identity provider is never allowed to pull someone else's existing hiccup account into your team — invite them properly instead, or ask them to sign in with their own credentials.

Requiring SSO

"Require SSO for members" turns off password and Google sign-in for everyone except you, the team owner. You always keep password access — a misconfigured or temporarily broken IdP must never be able to lock you out of your own team. If hiccup's operator ever needs to disable single sign-on platform-wide, enforcement switches off automatically everywhere at the same moment, so nobody is stranded while it is fixed.

What each sign-in error means

Message	What happened
Enter a valid work email address.	The address typed on the sign-in page was not a usable email shape.
Single sign-on is not configured for this email domain.	No team has claimed that email's domain — or hiccup deliberately gives this exact message whether no team claimed it, or a team's config is switched off, so nobody can use it to probe which companies use hiccup.
Your organisation's sign-in service is not responding. Contact your administrator.	hiccup could not fetch or validate your IdP's discovery document. Check the issuer URL, and that it is reachable from the public internet — hiccup refuses to call anything on a private network.
Sign-in session expired — please try again.	More than 10 minutes passed between starting sign-in and the identity provider redirecting back, or the link was already used once.
Sign-in token validation failed.	The identity token from your IdP failed a required check (issuer, audience, timing, or the one-time nonce). Usually a clock skew beyond two minutes, or a misconfigured client ID.
Your identity provider did not supply an email address.	Neither the identity token nor a userinfo lookup returned an email claim — check the app registration requests the `email` scope.
Your identity provider reports this email as unverified.	The IdP explicitly marked the address unverified. hiccup will not sign someone in on an address their own provider will not vouch for.
An account already exists for this email. Ask your team owner to invite it, or sign in with your existing credentials.	The "who can sign in" refusal above, case three — working as designed, not a bug.
Your email is outside this workspace's SSO domains. Sign in with your password instead.	An existing team member's email is not on any domain the team has claimed for SSO.
Your account is no longer on this team. Contact your administrator.	This identity signed in before, but the person was since removed from the team.
Your team requires single sign-on. Use "Continue with SSO" on the sign-in page.	Enforcement is on for your team and this account is not the owner — password sign-in is deliberately blocked.
This team already has the maximum of 50 members.	A brand-new sign-in would need a new seat, and the team is full.

What isn't supported yet

hiccup speaks OIDC only today, not SAML, and there is no SCIM de-provisioning feed — removing someone from your directory does not yet automatically remove them from hiccup. If either of those is a hard requirement for you, say so at [email protected].

← back to your team page