HowlOps
FeaturesHow it worksPricingIntegrationsDocsChangelogContact
Log inStart free
DOCS

SAML SSO debugging

Advanced diagnostics for SAML single sign-on failures.

Overview of the SAML flow

1. User clicks "Sign in with SSO"
2. HOWLOPS redirects to IdP (Identity Provider) with SAMLRequest
3. User authenticates at IdP
4. IdP posts SAMLResponse back to HOWLOPS ACS URL
5. HOWLOPS validates response signature, extracts NameID (email)
6. HOWLOPS creates or looks up the user account (JIT provisioning)
7. User is logged in

Failures can occur at any step. This guide covers the most common failure points.

Prerequisites

  • Access to your Identity Provider admin console (Okta, Entra ID / Azure AD, Google Workspace, etc.).
  • SAML SSO must be configured in HOWLOPS: Settings > Security > Single sign-on.

Common errors and fixes

"SAML response invalid signature"

The SAML response signature does not match the certificate configured in HOWLOPS.

Fix:

  1. Download the current IdP metadata or certificate from your IdP admin console.
  2. In HOWLOPS (Settings > Security > SSO > Edit), re-upload or re-paste the IdP certificate.
  3. Ensure the certificate is in PEM format (starts with -----BEGIN CERTIFICATE-----).
  4. Check for clock skew: the NotBefore / NotOnOrAfter timestamps in the SAMLResponse must be within 5 minutes of HOWLOPS server time. Use NTP on your IdP.

"NameID not found in SAML response"

The IdP is not sending the expected attribute.

Fix:

  1. In your IdP, open the HOWLOPS application configuration.
  2. Ensure the NameID format is EmailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).
  3. Map the user's email address to the NameID attribute.

"JIT provisioning failed — email domain not allowed"

The email domain in the SAML response is not in the allowed domain list.

Fix:

  1. Go to Settings > Security > SSO.
  2. Under Allowed email domains, add the domain (e.g. example.com).
  3. Retry the login.

"Request ID mismatch" or "Response expired"

The SAMLResponse arrived too late (more than 5 minutes after the SAMLRequest was issued), or an old response was replayed.

Fix:

  • Check IdP and HOWLOPS server clock synchronisation (NTP).
  • Do not cache or replay SAMLResponse values.

"ACS URL mismatch"

Your IdP is sending the SAMLResponse to the wrong Assertion Consumer Service URL.

Fix:

  1. In HOWLOPS (Settings > Security > SSO), copy the ACS URL (e.g. https://api.example.com/api/v1/sso/callback).
  2. Paste this exact URL into the ACS / Reply URL field in your IdP application configuration.

Decoding a SAMLResponse for inspection

If you have access to browser developer tools:

  1. Open DevTools > Network tab.
  2. Attempt the SSO login.
  3. Find the POST request to the ACS URL.
  4. In the request body, copy the SAMLResponse parameter value (URL-decoded).
  5. Base64-decode it:
echo "<paste_here>" | base64 -d | xmllint --format -

Inspect the XML for <NameID>, <Conditions NotBefore= NotOnOrAfter=>, and <Signature>.

IdP-specific notes

Okta

  • Set Name ID format: EmailAddress
  • Attribute statement: not required if NameID is email
  • ACS URL: paste from HOWLOPS SSO settings
  • Audience URI (SP Entity ID): paste from HOWLOPS SSO settings

Microsoft Entra ID (Azure AD)

  • Identifier (Entity ID): paste from HOWLOPS SSO settings
  • Reply URL (ACS URL): paste from HOWLOPS SSO settings
  • User Attributes: set user.mail or user.userprincipalname as the NameID source
  • Download the Certificate (Base64) and upload to HOWLOPS

Google Workspace

  • ACS URL: paste from HOWLOPS SSO settings
  • Entity ID: paste from HOWLOPS SSO settings
  • Name ID: Basic Information > Primary email
  • Download the IdP certificate and upload to HOWLOPS

See also

Was this page helpful?