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 on a Basic or Growth plan returns 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.