SSO with SAML 2.0

Overview

Connect any SAML 2.0 identity provider as your organization's identity provider.

Prerequisites:

• Owner role in the organization (sso.edit)
• Admin access to your IdP to create a SAML application

That's all — the IdP entity ID, SSO URL, and signing certificate below are a complete, working configuration. Verifying your email domain is optional: it makes the login page advertise your IdP to anyone typing an email under that domain, but members can always sign in through the organization sign-in link without it.

Service Provider (SP) Values

When you select SAML in Organization → Authentication, UptimeHunt displays your organization's SP values — before the configuration is first saved, so you can register them at your IdP up front. They are served from the UptimeHunt authentication host and have these forms (always copy the exact values from the settings page):

Most IdPs can consume the SP metadata URL directly, which configures the ACS endpoint, entity ID, and bindings in one step.

The same values are available programmatically: GET /api/v1/orgs/{slug}/sso/urls?provider_type=saml (requires sso.view) computes the SP endpoints from the organization slug alone — no saved configuration required, so automation (Terraform, Ansible, scripts) can create the IdP application before the first PUT:

curl "https://app.uptimehunt.io/api/v1/orgs/acme/sso/urls?provider_type=saml" \
  -H "Authorization: Bearer {access_token}"

{
  "data": {
    "provider_type": "saml",
    "urls": {
      "login": "https://auth.uptimehunt.io/accounts/saml/acme/login/?process=login",
      "acs": "https://auth.uptimehunt.io/accounts/saml/acme/acs/",
      "sp_metadata": "https://auth.uptimehunt.io/accounts/saml/acme/metadata/",
      "sp_entity_id": "https://auth.uptimehunt.io/accounts/saml/acme/metadata/"
    }
  }
}

(sp_entity_id here is the pre-save default — the SP metadata URL.)

Step 1 — Create the SAML Application in Your IdP

Configure your IdP application with the SP values above, and set:

• NameID format: persistent (a stable, opaque identifier). The persistent NameID is the identity anchor — do not use email as the NameID, since email changes would otherwise look like new users.

• Attribute mapping: assert the user's email (and optionally first/last name) as attributes. UptimeHunt reads these attribute names by default (first match wins):

  Field	Accepted attribute names
  Email	urn:oid:0.9.2342.19200300.100.1.3 · http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  First name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname · urn:oid:2.5.4.42
  Last name	urn:oid:2.5.4.4
  Subject ID	urn:oasis:names:tc:SAML:attribute:subject-id (falls back to the persistent NameID when absent)

  Different names can be configured via the API-only config.attribute_mapping object (see Step 2).

• Assertion signing: assertions must be signed. Unsigned or tampered assertions are rejected.

Collect from your IdP: the IdP entity ID, SSO URL, and X.509 signing certificate. Most IdPs publish all three in their SAML metadata XML — you can paste that XML directly into UptimeHunt and it will fill the three fields for you (see Paste IdP metadata XML below); UptimeHunt does not fetch IdP metadata URLs automatically.

Step 2 — Configure the Organization

UI: Organization → Authentication → SAML — enter the IdP entity ID, SSO URL, and signing certificate (or paste the metadata XML to fill them automatically).

Paste IdP metadata XML

The SAML credentials form has an Import IdP metadata box: paste your IdP's metadata XML and UptimeHunt extracts the three values into the fields below it —

• IdP entity ID ← the <EntityDescriptor entityID="…">,
• IdP SSO URL ← the <SingleSignOnService> Location (the HTTP-POST binding, falling back to HTTP-Redirect),
• IdP X.509 certificate ← the signing <X509Certificate>, with all whitespace stripped.

The parsing happens entirely in your browser — nothing is sent to UptimeHunt until you Save, so importing only pre-fills the form; it is not itself a save. Review the filled-in values and then save as usual. Invalid XML, or metadata missing any of the three elements, is reported inline and fills nothing.

API:

curl -X PUT https://app.uptimehunt.io/api/v1/orgs/acme/sso \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "saml",
    "config": {
      "idp_entity_id": "https://idp.acme.com/saml/metadata",
      "idp_sso_url": "https://idp.acme.com/saml/sso",
      "idp_x509cert": "MIIC..."
    },
    "jit_provisioning": true,
    "default_role": "member",
    "enabled": true
  }'

The IdP values go inside the config object; the top-level fields are the organization-side toggles.

Step 3 — Test

Validate the stored configuration:

curl -X POST https://app.uptimehunt.io/api/v1/orgs/acme/sso/test \
  -H "Authorization: Bearer {access_token}"

This checks that the IdP SSO URL answers HTTP and that the stored signing certificate parses as X.509 and is inside its validity window — response shape and check details in Testing the Configuration.

Then sign in from a private browser window with a corporate email: enter the email on the login page and choose the organization route.

Role Mapping (attribute → role)

Map the groups your IdP asserts in the SAML assertion to UptimeHunt roles, instead of giving every member the same default_role. The shared mechanics — ordered rules, first-match-wins, the unmapped-members policy (including Refuse sign-in), the Owner warning, the last-Owner guard, re-sync on every sign-in, and the audit events — are documented once under SSO → Role Mapping. This section covers only the SAML-specific part: where the group values come from.

• The source is the SAML attribute Name (the exact, case-sensitive Name="…" on the <Attribute> element — not its FriendlyName) that carries group membership. Groups always travel in an AttributeStatement <Attribute> with one <AttributeValue> per group — never in the NameID.
• Each rule value is matched verbatim against the attribute values your IdP emits. Configure your IdP to send one <AttributeValue> per group, not a single comma-joined value.

UI: Organization → Authentication → SAML → Role mapping — set the SAML attribute name (source), then add rules pairing an attribute value with a role, ordered most-privileged first.

API (inside the SAML config):

curl -X PUT https://app.uptimehunt.io/api/v1/orgs/acme/sso \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "saml",
    "config": {
      "idp_entity_id": "https://idp.acme.com/saml/metadata",
      "idp_sso_url": "https://idp.acme.com/saml/sso",
      "idp_x509cert": "MIIC...",
      "role_mapping": {
        "source": "groups",
        "rules": [
          {"value": "platform-admins", "role": "owner"},
          {"value": "sre",             "role": "admin"},
          {"value": "engineering",     "role": "member"}
        ],
        "unmapped_policy": "member"
      }
    }
  }'

Per-IdP attribute guidance

The attribute Name and the value format differ per IdP — set source to the exact Name your IdP emits, and write each rule value in the format that IdP sends:

Security Properties

• SP-initiated flow only. IdP-initiated SSO (unsolicited assertions posted to the ACS) is disabled — sign-ins always start at the UptimeHunt login page.
• Assertions are validated per the SAML 2.0 spec: signature, audience restriction, NotBefore/NotOnOrAfter validity window, and replay protection (each assertion ID is accepted once).
• The persistent NameID is scoped to your organization's IdP (identity realm) — the same person arriving via another organization's IdP is a separate account.
• There is no email-domain gate by default: whoever your IdP authenticates is admitted (JIT gating) — asserted emails are display attributes. Use jit_requires_invitation for invitation-gated provisioning, or the declared allowed_email_domains allowlist to filter JIT by asserted email domain.

Troubleshooting

Related Documentation

• SSO Overview
• OIDC · Google Workspace · GitHub
• Email Routing & Auto-Join