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

  • SAML SSO requires a paid plan (any paid capability: Uptime S+, paid On-call, or Status Starter+). Confirm your workspace holds at least one paid capability before debugging.
  • 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.

"SSO login rejected" or "email domain not authorized"

The full error is "this email domain is not authorized for SSO on this organization" (HTTP 403). SSO only allows a user to sign in when their email domain matches an organization's DNS-verified SSO domain. This happens when the domain has not been verified yet, or the user's email is on a different domain.

Fix:

  1. Go to Settings > Security > SSO and confirm the SSO domain shows as verified.
  2. If it is not verified, copy the DNS TXT record shown (host _howlops-sso-verify.<yourdomain>, value howlops-domain-verification=<token>), publish it in your DNS zone, then click Verify.
  3. Ensure the signing-in user's email domain exactly matches the verified SSO domain — a mismatched domain is always rejected.
  4. If verification reports "already claimed by another organization", the domain is verified on a different workspace and cannot be claimed twice.

"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.howlops.com/api/v1/auth/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:
bash
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?