SAML SSO — Overview
Plan required: Enterprise
What is SAML SSO?
Security Assertion Markup Language (SAML) 2.0 Single Sign-On lets your employees log in to the Hober Dashboard using your company's existing Identity Provider (IdP) — such as Okta or Azure AD — without creating a separate password for Hober.
Benefits:
- Centralized access control: provisioning and deprovisioning users happens in your IdP.
- No password sprawl: credentials live only in your IdP.
- MFA enforcement: your IdP's multi-factor authentication policy applies automatically.
- Audit trail: all authentication events are logged in your IdP.
Plan requirement
SAML SSO is available on the Enterprise plan only. Attempting to configure or use
SAML is available on the Enterprise and Agency plans (the saml feature); other plans return HTTP 403 FORBIDDEN.
Contact sales at sales@hober.io to upgrade your plan.
How SP-initiated SSO works in Hober
Hober acts as the Service Provider (SP). Your company's IdP (Okta, Azure AD, etc.) acts as the Identity Provider (IdP). Hober always uses the SP-initiated flow: the login sequence begins at Hober, not at the IdP portal.
User Hober (SP) IdP (Okta / Azure AD)
| | |
| GET /v1/auth/saml/login | |
| ?tenantSlug=acme | |
|------------------------->| |
| | Build AuthnRequest (SAML 2.0) |
| | HTTP-Redirect binding |
| 302 → IdP SSO URL | |
|<-------------------------| |
| |
| Browser follows redirect ─────────────────────────────────────────>|
| |
| User authenticates (password / MFA) |
| |
| POST /v1/auth/saml/callback?tenantSlug=acme |
| (SAMLResponse form field) |
|<────────────────────────────────────────────────────────────────────|
| | Validate assertion |
| | Map attributes to Hober user |
| | Issue JWT access + refresh tokens |
| 200 { access_token, refresh_token } |
|<-------------------------| |
Endpoint reference
| Endpoint | Method | Description |
|---|---|---|
/v1/auth/saml/login | GET | SP-initiated login; redirects to IdP SSO URL. Query param: tenantSlug (required), relayState (optional). |
/v1/auth/saml/callback | POST | ACS endpoint; receives SAMLResponse from IdP, validates assertion, returns JWT tokens. |
/v1/auth/saml/config | GET | Returns SP metadata (ACS URL, entity ID) for the tenant. |
/v1/auth/saml/config | PUT | Uploads IdP metadata XML; body is the raw XML document, Content-Type: application/xml. |
SP metadata values
When registering Hober in your IdP, use these values:
| Field | Value |
|---|---|
| ACS URL (Reply URL) | https://app.hober.io/v1/auth/saml/{tenantId}/acs |
| SP Entity ID (Identifier) | https://app.hober.io/saml/{tenantId} |
| Name ID format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Binding | HTTP-POST (for ACS); HTTP-Redirect (for AuthnRequest) |
Replace {tenantId} with your tenant UUID. The exact values for your tenant are shown
in the Hober Dashboard under Settings → Security → SAML.
Attribute mapping
Hober maps SAML assertion attributes to user fields using a configurable
attribute_mapping JSON stored per tenant. The default mapping is compatible with
both Okta and Azure AD out of the box:
| Hober user field | Default SAML attribute name |
|---|---|
email | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
given_name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
family_name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname |
groups | http://schemas.microsoft.com/ws/2008/06/identity/claims/groups |
The email attribute is required. If it is absent from the assertion, the
callback returns 401 UNAUTHORIZED.
See the IdP-specific guides for the exact claim names to configure in each IdP:
Next steps
- Choose your IdP guide:
- If you encounter problems, see the Troubleshooting guide.