H· Hawiyati Documentation

Diagnostics Guide

Ten most common misconfiguration errors, their symptoms, root causes, and fixes.

Privacy note: No SAML assertion content, session cookies, or personal attributes should appear in diagnostic output or server logs. Log only entity IDs, error codes, and non-sensitive metadata.

1. Wrong SP or IdP entity ID

Symptom: The IdP responds with an error page immediately after the SP redirects to the SSO URL. Hawiyati error: "Unknown service provider" or "SP not registered".

Cause: The entity-id configured in the SDK does not match the entity ID registered in Hawiyati Admin Console.

Fix:

  1. Open Hawiyati Admin Console → Service Providers → find the registered SP entry.
  2. Compare the registered SP Entity ID with your SDK configuration:
    • Java: hawiyati.saml.sp.entity-id
    • .NET: SamlSpConfig.EntityId
    • PHP: SamlSpConfig::$entityId
  3. Entity IDs are case-sensitive URIs — they must be byte-for-byte identical.

Log entry: SamlValidationException: Issuer does not match trusted IdP entity ID

2. Signing certificate mismatch

Symptom: ACS callback returns HTTP 403 — "Signature validation failed". SSO completes on the IdP side but fails at the SP.

Cause: The IdP signing certificate loaded by the SDK does not match the private key the IdP used to sign the assertion. Usually happens after a certificate rotation on the IdP that was not propagated to the SP.

Fix:

  1. Download the current IdP signing certificate from Admin → IdP → Certificates → Download PEM.
  2. Replace the certificate file at the path referenced by idp.signing-cert-paths (Java), IdpSigningCertPath (.NET), or $trustedIdp->signingCertPem (PHP).
  3. Restart the SP application to reload the certificate.

3. Clock skew exceeds tolerance

Symptom: Authentication fails with "Assertion is expired" or "Assertion is not yet valid". Works when retried immediately.

Cause: SP server time is more than clock-skew-seconds away from IdP server time.

Fix:

  1. Synchronize both servers with NTP (e.g., chrony or systemd-timesyncd).
  2. As a temporary workaround only, increase clock-skew-seconds up to 300. Do not use this as a permanent fix.

Log entry: SamlValidationException: Assertion expired: notOnOrAfter=...

4. ACS URL not registered in Hawiyati

Symptom: IdP redirects back to an error page after authentication. Hawiyati error: "Invalid ACS URL" or "ACS URL not registered for this SP".

Fix: In Hawiyati Admin Console → Service Providers → edit the SP entry → update the ACS URL to exactly match hawiyati.saml.sp.acs-url. The URL must start with https:// and include the path.

6. Missing CSRF token on logout

Symptom: Logout returns HTTP 403 — "CSRF token missing or invalid".

Fix: Always include a CSRF token in the logout POST form. For Spring Security, use <input type="hidden" name="_csrf" th:value="${_csrf.token}"/>. For .NET, use builder.Services.AddAntiforgery() and validate in the logout handler.

7. Redis replay/pending store connection failure

Symptom: SP startup fails with "Cannot connect to Redis" or authentication fails intermittently.

Fix:

  1. Verify Redis is running: redis-cli ping
  2. Check the connection configuration in hawiyati.saml.sp.redis.* (Java) or the Redis client constructor (PHP).
  3. For multi-instance deployments only: switch from InMemory* stores to Redis adapters. Never use in-memory stores in a cluster — they do not share state across instances.

8. Correlation cookie rejected (SameSite=None without HTTPS)

Symptom: Authentication fails at the ACS step with "Correlation cookie not found" or "Invalid state". Only happens on HTTP (not HTTPS).

Fix: Always deploy the SP over HTTPS in production. If testing locally, use mkcert to issue a trusted local certificate. The correlation cookie requires Secure; SameSite=None because the IdP POST comes cross-origin.

9. Destination URL mismatch

Symptom: ACS callback returns HTTP 400 — "Destination does not match ACS URL".

Cause: The Destination attribute in the SAML response from the IdP does not match the ACS URL the SP expects.

Fix: In Hawiyati Admin Console → Service Providers, update the ACS URL to exactly match hawiyati.saml.sp.acs-url, including scheme, hostname, port, and path.

10. LocalAccountResolver returning 403 for all users

Symptom: All SSO attempts end in HTTP 403 immediately after the ACS callback.

Cause: A custom LocalAccountResolver is throwing LocalAccountResolutionException for every user, or the resolver is misconfigured to always reject.

Fix:

  1. Enable debug logging: logging.level.io.hawiyati.saml=DEBUG (Java).
  2. Add a temporary pass-through to isolate whether the resolver is the cause: comment out your custom resolver and check if authentication succeeds.
  3. Check your user store — confirm the test user exists and is active.