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