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:
- Open Hawiyati Admin Console → Service Providers → find the registered SP entry.
- Compare the registered SP Entity ID with your SDK configuration:
- Java:
hawiyati.saml.sp.entity-id - .NET:
SamlSpConfig.EntityId - PHP:
SamlSpConfig::$entityId
- Java:
- 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:
- Download the current IdP signing certificate from Admin → IdP → Certificates → Download PEM.
- Replace the certificate file at the path referenced by
idp.signing-cert-paths(Java),IdpSigningCertPath(.NET), or$trustedIdp->signingCertPem(PHP). - 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:
- Synchronize both servers with NTP (e.g.,
chronyorsystemd-timesyncd). - As a temporary workaround only, increase
clock-skew-secondsup 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:
- Verify Redis is running:
redis-cli ping - Check the connection configuration in
hawiyati.saml.sp.redis.*(Java) or the Redis client constructor (PHP). - 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:
- Enable debug logging:
logging.level.io.hawiyati.saml=DEBUG(Java). - Add a temporary pass-through to isolate whether the resolver is the cause: comment out your custom resolver and check if authentication succeeds.
- Check your user store — confirm the test user exists and is active.