SAML & OIDC Single Sign-On

Pick Your Protocol

• OIDC: simpler config, modern, JSON-based. Good default if your IdP supports it.
• SAML 2.0: required by some enterprise IdPs and compliance regimes. Slightly more setup.

You can run both at once. HailBytes SAT shows whichever is enabled on the login page.

OIDC Setup

1. In your IdP, register an OIDC application.
2. Set the Redirect URI to: https://<your-sat-host>:3333/sso/callback/<provider_slug>
3. Capture the Client ID, Client Secret, and discovery URL (.well-known/openid-configuration).

POST /api/sso/
{
  "provider":      "entra",                      # appears as a button on the login page
  "display_name":  "Sign in with Microsoft",
  "type":          "oidc",
  "discovery_url": "https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration",
  "client_id":     "<your-client-id>",
  "client_secret": "<your-client-secret>",
  "scopes":        ["openid","email","profile"],
  "default_role":  "operator",
  "enabled":       true
}

Now https://<host>:3333/sso/login/entra redirects to Microsoft, and a successful callback drops the user into HailBytes SAT.

SAML Setup

In the IdP

• SP Entity ID / Audience: https://<your-sat-host>:3333/sso/saml
• ACS / Reply URL: https://<your-sat-host>:3333/sso/saml/acs
• Login URL: https://<your-sat-host>:3333/sso/saml/login
• NameID format: emailAddress.
• Map email, given_name, family_name as attributes.

In HailBytes SAT

PUT /api/saml/config
{
  "enabled":          true,
  "idp_metadata_url": "https://login.microsoftonline.com/<tenant>/federationmetadata/...",
  "idp_metadata_xml": null,                # alternative: paste XML directly
  "default_role":     "operator",
  "attribute_map": {
    "email":      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "last_name":  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
  }
}

HailBytes SAT exposes its SP metadata at /sso/saml/metadata for IdPs that consume it directly.

Just-In-Time User Creation

First login through SSO creates the user with the configured default_role. To pre-populate users (e.g. before rollout day), use SCIM.

Enforcing MFA

Push MFA enforcement upstream to your IdP whenever possible. HailBytes SAT also supports application-level TOTP MFA via /api/mfa/*, configurable per role under Settings → Security.

Login URLs

OIDC: https://<host>:3333/sso/login/<provider_slug>
SAML: https://<host>:3333/sso/saml/login

Troubleshooting

• Loop on login: clock skew between SAT and IdP exceeds the SAML clock tolerance. Check NTP.
• "User has no email": attribute mapping wrong. Pull the SAML response from the IdP debug log.
• 403 after callback: default_role missing or removed. Set it back via PUT /api/sso/{provider} or /api/saml/config.

Next Steps