SSO with OIDC

Overview

Connect any OpenID Connect provider — Okta, Microsoft Entra ID (Azure AD), Auth0, Keycloak, Authentik, and others — as your organization's identity provider.

Prerequisites:

• Owner role in the organization (sso.edit)
• Admin access to your IdP to register an application

That's all — the client ID, client secret, and issuer URL 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.

Step 1 — Register UptimeHunt in Your IdP

Create an OIDC web application (confidential client, Authorization Code flow) in your identity provider with:

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

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

{
  "data": {
    "provider_type": "oidc",
    "urls": {
      "login": "https://auth.uptimehunt.io/accounts/oidc/acme/login/?process=login",
      "callback": "https://auth.uptimehunt.io/accounts/oidc/acme/login/callback/"
    }
  }
}

urls.callback is the redirect URI to register; urls.login is the direct member sign-in URL.

Note the client ID, client secret, and your IdP's issuer / discovery URL (the URL that serves /.well-known/openid-configuration).

Step 2 — Configure the Organization

UI: Organization → Authentication → OIDC — fill in the discovery URL, client ID, and client secret.

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": "oidc",
    "config": {
      "server_url": "https://idp.acme.com",
      "client_id": "uptimehunt-prod",
      "client_secret": "{client_secret}"
    },
    "jit_provisioning": true,
    "jit_requires_invitation": false,
    "default_role": "member",
    "enabled": true
  }'

Provider credentials and endpoints go inside the config object; the top-level fields are the organization-side toggles.

Shared multi-tenant issuers

If server_url points at an issuer that authenticates every tenant's accounts — https://accounts.google.com, or Microsoft's multi-tenant https://login.microsoftonline.com/common, /organizations, or /consumers endpoints — then "your IdP authenticated the user" no longer means "the user belongs to your organization": anyone with a Google or Microsoft account can complete the flow. A JIT-enabled configuration against such an issuer must therefore declare its own scope:

• Set config.workspace_domains to your hosted domain(s), e.g. ["acme.com"]. For Google-issued sign-ins, the ID token's hd claim must match one of them (consumer accounts, which carry no hd, are always rejected). This list is declared in the configuration — no DNS verification involved.
• Alternatively, use a tenant-specific issuer URL (e.g. https://login.microsoftonline.com/{tenant-id}/v2.0) — a single-tenant issuer scopes itself and needs no workspace_domains.

The API refuses (400) to save a JIT-enabled configuration against a known shared issuer without a declared scope. For Google Workspace specifically, prefer the dedicated Google Workspace provider type.

Step 3 — Test

Validate the stored configuration against your IdP:

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

This checks that the discovery document (derived from server_url, at {server_url}/.well-known/openid-configuration) is reachable and well-formed, and that its issuer matches the configured server_url — response shape and check details in Testing the Configuration.

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

Role Mapping (claim → role)

Map the groups your IdP asserts 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 OIDC-specific part: where the group values come from.

• The source is the OIDC claim name that carries group membership (default groups). UptimeHunt reads it from the userinfo response first, falling back to the ID token — so the claim only has to appear in one of them.
• Each rule value is matched verbatim (case-sensitive) against the claim's array values.

UI: Organization → Authentication → OIDC → Role mapping — set the Groups claim (source), then add rules pairing a group value with a role, ordered most-privileged first.

API (inside the OIDC config):

{
  "role_mapping": {
    "source": "groups",
    "rules": [
      {"value": "platform-admins", "role": "owner"},
      {"value": "sre",             "role": "admin"},
      {"value": "engineering",     "role": "member"}
    ],
    "unmapped_policy": "member"
  }
}

Additional OAuth scopes

Some IdPs gate the groups claim behind an extra OAuth scope. config.additional_scopes is appended to the always-requested openid profile email base — it never replaces it, so a typo here can never drop a required base scope. Provide a list (["groups"]) or a space-separated string ("groups").

• Okta (custom authorization server) needs the groups scope, and that scope must exist on the custom auth server (create it if absent).
• Microsoft Entra ID, authentik, and GitLab do not need an extra scope — the groups claim rides the default scopes once the IdP-side mapper/claim is configured.
• Keycloak depends on where the Group Membership mapper is attached:
  • Attached directly to the client (a dedicated client mapper) — no extra scope; the claim rides the default scopes.
  • Attached to a named client scope (a common pattern — e.g. a reusable groups client scope) — that scope is only requested if its name is asked for. If the client scope is Default, Keycloak includes it automatically; but if it is Optional, you must add the client-scope name to config.additional_scopes (e.g. ["groups"]) or the mapper never runs and no groups claim is emitted — a silent no-match with no error. When in doubt, add the scope name; the base openid profile email scopes are never dropped.

Per-IdP claim guidance

Set source to the claim name your IdP emits, and configure that IdP to emit it:

How Identity Is Resolved

• The identity anchor is the OIDC sub claim, scoped to your organization's IdP configuration (identity realm). Email and profile claims are display attributes — changing a user's email at the IdP does not create a new UptimeHunt account.
• ID tokens are validated per the OIDC spec: issuer, audience, expiry, nonce, and signature against the IdP's published keys.
• There is no email-domain gate by default: whoever your IdP authenticates is admitted (JIT gating). The one mandatory exception is a shared multi-tenant issuer, where the declared workspace_domains scope applies; optionally, the declared allowed_email_domains allowlist filters JIT provisioning by asserted email domain.

Troubleshooting

Related Documentation

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