SAML Single Sign-On

On the Pro plan and above, an organization can connect its identity provider (IdP) so team members sign in to GeckoGuard through your existing SSO — Okta, Microsoft Entra ID, Google Workspace, JumpCloud, or any SAML 2.0 IdP. The API resolves this entitlement from the organization's owner-backed plan. If the organization downgrades below Pro, new SSO sign-ins stop until the plan is restored; administrators can still inspect or remove the saved connection.

GeckoGuard acts as the service provider (SP). Sign-ins are SP-initiated: a user goes to the SSO page, we redirect them to your IdP, and on success the IdP posts a signed SAML assertion back to us. We verify the signature, find or create the user, add them to your organization, and issue a session.

How it works

A user visits /auth/sso and enters your organization ID (or opens the login link you distribute).
GeckoGuard redirects to your IdP's SSO URL with a SAML AuthnRequest.
The user authenticates with your IdP.
The IdP POSTs a signed SAML response to our Assertion Consumer Service (ACS).
We verify the XML signature against your IdP's certificate, then sign the user in (creating the account just-in-time if enabled).

Prerequisite: verify your email domain

Before SSO will sign anyone in, your organization must DNS-verify the email domain it applies to (e.g. yourcompany.com) under Organization → Domains.

This is a hard security requirement, not a convenience: because each org configures its own IdP and certificate, a validated signature only proves "this org's IdP said so." Requiring proven domain ownership is what stops one organization from asserting someone@anothercompany.com and hijacking that person's account. GeckoGuard rejects any SSO assertion whose email domain the org hasn't verified. Assertions are also bound to a per-org audience, so an assertion issued for one org can't be replayed against another — even when both use the same identity provider tenant.

Configure it

Settings → SAML SSO (organization Admin or Owner).

1. Register GeckoGuard with your IdP

Create a new SAML application in your IdP and paste these values (shown on the settings page for your org):

IdP field	Value
SP Entity ID / Audience	`https://api.geckoguard.net/v1/sso/<orgId>`
ACS / Reply URL (HTTP-POST)	`https://api.geckoguard.net/v1/sso/<orgId>/acs`
Login URL (SP-initiated)	`https://api.geckoguard.net/v1/sso/<orgId>/login`
SP metadata URL	`https://api.geckoguard.net/v1/sso/<orgId>/metadata`
NameID format	Email address

Make sure the IdP is configured to sign assertions — GeckoGuard rejects unsigned or tampered assertions.

2. Enter your IdP details in GeckoGuard

Field	What to enter
IdP Entity ID (Issuer)	Your IdP's issuer / entityID
IdP SSO URL	Your IdP's SAML SSO (redirect) endpoint
IdP Signing Certificate	The IdP's public X.509 signing certificate (PEM)
Restrict to email domain	(optional) only allow assertions for this domain
Just-in-time provisioning	Auto-create accounts on first SSO login
Default role	Org role for new SSO members (defaults to Viewer)

Then check Enable SSO and save.

When editing an existing connection, leave the certificate field blank to keep the stored certificate. Paste a new certificate only when rotating or replacing it.

Security notes

Assertion signatures are verified with the well-audited @node-saml/node-saml library — no hand-rolled XML crypto.
JIT-provisioned members default to Viewer (read-only); raise their role from Team afterward.
Optionally restrict logins to a verified email domain so only your employees can be provisioned.
Session tokens are handed off via a one-time, single-use exchange code and set as httpOnly cookies — they never appear in a URL.

Give your team the login link from the settings page (…/v1/sso/<orgId>/login) — put it on your intranet or IdP dashboard — or point them to /auth/sso and have them enter the organization ID.