Skip to content
HamstikHamstik Docs

SAML single sign-on

Hamstik supports Organization-scoped SAML 2.0 sign-in with service-provider (SP)-initiated login. One identity provider (IdP) connection per Organization; people bind their existing Hamstik account deliberately — Hamstik never links accounts by email, and there is no automatic enrollment.

Protocol references: SAML 2.0 and metadata.

Availability

SAML sign-in requires Enterprise coverage for the Organization. When coverage lapses, enforcement stays on — losing coverage never silently removes a security control — but configuration changes are blocked until coverage is restored.

Configure the identity provider

In Organization Settings → Security & sign-in:

  1. Upload IdP metadata (paste the EntityDescriptor XML) or enter the entity ID, HTTPS SSO endpoint, and verification certificate directly. Hamstik never fetches metadata from a URL.

  2. Set the Hamstik SP metadata/ACS values on your IdP side. They are shown in the section and also served from your SP metadata endpoint:

    SP metadata: https://hamstik.com/api/auth/saml/<organization>/metadata
    ACS URL:     https://hamstik.com/api/auth/saml/<organization>/acs
    Entity ID:   https://hamstik.com/api/auth/saml/<organization>

  3. Test the connection: a bound organization admin completes a real SSO round trip. Leaving Disabled requires this successful test.

  4. Choose the mode:

    • Disabled — password and social sign-in only.
    • Optional — people with a bound account may also sign in through your IdP.
    • Enforced — Organization access requires a current single sign-on grant. Enforcement needs a designated recovery owner (see below).

The first interoperability profile accepts RSA-SHA256/384/512 signatures with SHA-256/384/512 digests and RSA keys of at least 2048 bits. SHA-1/MD5 responses are rejected explicitly. Response and metadata inputs are capped at 1 MiB (2 MiB decoded), unsigned or replayed responses, wrong issuer/audience/destination, unsolicited or ambiguous subjects are all rejected with safe, non-enumerating errors.

How accounts bind

A binding is the stable link between the IdP’s subject identifier and one Hamstik account. It is created only when the person:

  1. completes a fresh, validated SSO round trip, and
  2. proves their existing Hamstik account (password or social sign-in) — recent sign-in counts; otherwise Hamstik asks for proof.

Email matches never link or overwrite anything, existing credentials and OAuth identities are never taken over, and no Hamstik account is created by SSO. Provisioned (but unbound) accounts come from invitations — see user provisioning — or from normal account creation.

Once bound, the person signs in through the IdP. If their account has MFA enabled, the standard MFA challenge still applies before the session is issued; a successful SAML assertion never bypasses account MFA.

Enforcement and the recovery path

Enforced sign-in additionally requires a recovery owner: a different active Organization owner with credential sign-in and verified account MFA, who has tested the recovery path (local credential + MFA proof) recently.

  • The recovery owner alone is exempt from the Organization’s SAML gate.
  • The recovery owner can disable enforcement through the security settings after authenticating locally — for example during a provider outage. This is audited, and there is no public bypass URL.
  • The last eligible recovery owner cannot be demoted or removed while enforcement is on; Hamstik refuses the membership change with actionable guidance.

Session behavior

A successful SAML sign-in satisfies the Organization’s sign-in gate for the lifetime of the normal session, capped at 12 hours. After that (and after every enforcement change, binding removal, recovery-owner change, or certificate change — each bumps the Organization’s authorization generation), the next Organization access requires a new assertion. Unrelated Organizations are unaffected: an assertion bound to one Organization never satisfies another. Personal Access Tokens are noninteractive — they keep working under their scopes and current membership and never perform a SAML or MFA challenge.

Certificate rotation

Add the next certificate while the current one stays active; your IdP can then start signing with it immediately. Replace the current certificate to complete the rotation — this retires the old trust, requires a fresh test before enforcement can rely on it, and increments the authorization generation.

Administration APIs

Public API v1 exposes authorized configuration and status operations (scopes identity:read / identity:write; no raw assertions, secrets, or certificate contents are ever returned):

GET /api/v1/organizations/<org>/identity/saml   # status
PUT /api/v1/organizations/<org>/identity/saml   # configuration + mode

Use the CLI passthrough (hamstik api request …) for these operations. Configuration changes require Enterprise coverage; enforcement preconditions (tested connection, eligible recovery owner) are enforced server-side for both the UI and the API.