Skip to main content

SAML SSO — Troubleshooting

This page covers the most common SAML configuration errors, how to diagnose them, and how to fix them.

1. Certificate mismatch (signature validation fails)​

Symptom​

The Hober callback returns 401 UNAUTHORIZED with a message such as:

{ "code": "UNAUTHORIZED", "message": "SAML assertion validation failed" }

Auth service logs contain:

saml: signature verification failed: crypto/rsa: verification error

or:

saml: certificate in assertion does not match stored IdP certificate

Cause​

The signing certificate embedded in the SAML assertion does not match the certificate in the IdP metadata XML stored in Hober. This happens when:

  • The IdP has rotated its signing certificate (Okta and Azure AD do this automatically on a schedule).
  • The metadata XML was uploaded before the IdP finished the certificate rotation.

Fix​

  1. Download the latest IdP metadata XML from your IdP:
    • Okta: Admin Console → the Hober app → Sign On tab → Identity Provider metadata.
    • Azure AD: Enterprise application → Single sign-on → SAML Certificates → Download Federation Metadata XML.
  2. Re-upload the metadata in the Hober Dashboard under Settings → Security → SAML.
  3. Test SSO login again.

Preventive measure: subscribe to your IdP's certificate expiry notifications so you can update the metadata before the old certificate expires.

2. Clock skew (assertion rejected as expired or not yet valid)​

Symptom​

The Hober callback returns 401 UNAUTHORIZED. Auth service logs contain one of:

saml: assertion not yet valid: NotBefore 2026-04-12T14:00:05Z is in the future
saml: assertion expired: NotOnOrAfter 2026-04-12T13:59:55Z is in the past

Cause​

SAML assertions include time windows (NotBefore / NotOnOrAfter). If the clock on either the IdP or the Hober auth service is skewed by more than the assertion's validity window, the assertion will be rejected even though the SSO flow succeeded.

Typical validity windows:

  • Okta: 5 minutes
  • Azure AD: 5 minutes

Fix​

Immediate workaround: ask the user to retry immediately — transient NTP drift usually corrects itself within seconds.

Systematic fix:

  1. Verify that the Hober auth service host has NTP synchronization enabled: 
    # On the host or inside the container
    timedatectl status
    # Expected: "System clock synchronized: yes"
  2. Verify the IdP's clock (usually accurate for cloud IdPs like Okta/Azure AD).
  3. If the auth service is running in Kubernetes, check the node's NTP status: 
    kubectl get nodes -o wide
    # Connect to a node and check: sudo timedatectl status
  4. If you are using a self-hosted IdP (e.g., ADFS), ensure the ADFS server has NTP configured and synchronized.

3. Attribute not found (email missing from assertion)​

Symptom​

The Hober callback returns 401 UNAUTHORIZED. Auth service logs contain:

saml: required attribute "email" not found in assertion; checked claim: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Cause​

Hober cannot find the email attribute in the SAML assertion. Possible reasons:

  1. The IdP is not configured to send the email attribute.
  2. The IdP is sending the email under a different attribute name than what is in the tenant's attribute_mapping.
  3. The user's email is empty or not populated in the IdP's directory.

Fix​

Check what attributes the IdP is actually sending

Use a SAML tracer browser extension (e.g., SAML-tracer for Firefox/Chrome) to inspect the SAMLResponse. Decode the base64-encoded SAMLResponse POST body and look at the <saml:AttributeStatement> block.

Okta: Verify the attribute statement rows in Admin Console → the Hober app → Sign On tab → View SAML setup instructions. The preview at the bottom shows what attributes Okta will include. Ensure the emailaddress claim row is present (see Okta setup guide, Step 3).

Azure AD: In the enterprise application → Single sign-on → Attributes & Claims, confirm the emailaddress claim is listed and the source attribute (user.mail or user.userprincipalname) is populated for the user.

Custom attribute mapping

If your IdP uses a non-standard attribute name for email (e.g., Okta OID URN urn:oid:0.9.2342.19200300.100.1.3), the tenant's attribute_mapping must be updated to use that name. Contact Hober support to update the attribute_mapping JSON for your tenant, or use the config API directly:

PUT /v1/auth/saml/config?tenantSlug=<your-tenant-slug>
Content-Type: application/xml

<your IdP metadata XML>

The attribute_mapping field is currently managed server-side. Contact support at support@hober.io with your tenant slug and the exact attribute name string shown in the SAML assertion.

4. Audience mismatch (assertion rejected by SP)​

Symptom​

The Hober callback returns 401 UNAUTHORIZED. Auth service logs contain:

saml: audience restriction mismatch: got "https://idp.example.com/saml", expected "https://app.hober.io/saml/{tenantId}"

Cause​

The <saml:Audience> element in the assertion does not match the SP Entity ID stored in Hober for the tenant. This usually means:

  1. The Audience URI (Entity ID) in the IdP was set to the wrong value when registering Hober.
  2. The tenant ID in the SP Entity ID has changed (rare).

Fix​

  1. Retrieve the correct SP Entity ID from the Hober Dashboard under Settings → Security → SAML, or via the API:

    GET /v1/auth/saml/config?tenantSlug=<your-tenant-slug>

    Response:

    {
      "acs_url": "https://app.hober.io/v1/auth/saml/{tenantId}/acs",
      "sp_entity_id": "https://app.hober.io/saml/{tenantId}",
      "configured": true
    }

  2. Update the Audience URI / Entity ID in your IdP to match the sp_entity_id from step 1.

    • Okta: Admin Console → the Hober app → General tab → SAML Settings → Edit → Audience URI (SP Entity ID).
    • Azure AD: Enterprise application → Single sign-on → Basic SAML Configuration → Identifier (Entity ID).

  3. Save and re-test.

5. 403 Forbidden on SAML endpoints​

Symptom​

Any SAML endpoint returns HTTP 403:

{ "code": "FORBIDDEN", "message": "SAML SSO requires the Enterprise plan" }

Cause​

The tenant is not on the Enterprise plan.

Fix​

Contact sales at sales@hober.io to upgrade your subscription to the Enterprise plan.

6. "tenantSlug not found" (404) on login redirect​

Symptom​

GET /v1/auth/saml/login?tenantSlug=<slug> returns HTTP 404.

Cause​

Either the tenant slug is wrong, or the SAML configuration has not been saved for that tenant yet (i.e., no IdP metadata has been uploaded).

Fix​

  1. Verify the tenant slug by logging in to the Hober Dashboard and checking the URL or the Settings → General page.
  2. If the slug is correct, upload IdP metadata under Settings → Security → SAML (see the Okta guide or Azure AD guide).

7. Replay-attack rejection (assertion already used)​

Symptom​

A second attempt to use the same SAMLResponse returns 401 UNAUTHORIZED:

saml: assertion ID "_abc123" has already been used (replay detected)

Cause​

Hober stores assertion IDs for 24 hours to prevent replay attacks. If the same SAMLResponse is submitted twice (e.g., browser back button, automated retry), the second request is rejected.

Fix​

This is expected behavior, not a misconfiguration. The user should initiate a fresh SSO login:

https://app.hober.io/v1/auth/saml/login?tenantSlug=<your-tenant-slug>

Still stuck?​

  1. Enable debug logging on the Hober auth service (LOG_LEVEL=debug) to see the full XML assertion in the logs (do not leave debug logging on in production).
  2. Use a SAML tracer browser extension to capture and decode the SAMLResponse.
  3. Contact Hober support at support@hober.io with:
    • Your tenant slug
    • The error message returned by Hober
    • The assertion XML (redact any personally identifiable information)
    • The IdP type and version (Okta, Azure AD, ADFS, etc.)