This guide outlines common SAML 2.0 Single Sign-On (SSO) error conditions, their root causes, and step-by-step remediation procedures.

Common Error Messages and Resolutions

1. “SAML Certificate not found!”

  • Symptom: During login, Atatus redirects the user to /login-sso-failed with the error message: SAML Certificate not found!.
  • Cause:
    • The uploaded IdP metadata XML contains multiple active signing certificates (for example, during an Microsoft Entra ID or Okta certificate rollover). Atatus requires exactly one active signing certificate in the metadata descriptor.
    • Alternatively, the metadata URL was unreachable or returned an empty descriptor.
  • Resolution:
    1. Open your Identity Provider management console (such as Microsoft Entra ID or Keycloak).
    2. Verify that only one active signing certificate is present in the application’s SAML configuration. Remove or unpublish inactive or rollover certificates.
    3. Download a fresh metadata XML file.
    4. In Atatus, navigate to Settings » Account Settings » Single Sign-on.
    5. Select SAML Metadata XML, upload the new file, and click Save SSO.

2. “Invalid Audience” / Entity ID Mismatch

  • Symptom: The IdP successfully signs the user in, but Atatus displays an audience or entity mismatch error upon redirection.
  • Cause: The Audience / Entity ID configured in your Identity Provider does not match your 24-character Atatus Account ID.
  • Resolution:
    1. In Atatus, go to Settings » Account Settings » Single Sign-on and copy the Atatus Account Id.
    2. In your IdP’s SAML settings, paste this value into the Audience URI / Entity ID field.
    3. Ensure there are no accidental spaces or newline characters before or after the ID.

3. “You can’t login via password!”

  • Symptom: A user tries to sign in with a username/password or request a password reset at app.atatus.com/login and receives the message: You can't login via password!.
  • Cause: This user was created automatically through SAML Just-In-Time (JIT) provisioning. For security, Atatus enforces strict SSO on all SAML-provisioned users, permanently blocking local password authentication and password resets.
  • Resolution:
    • The user must sign in via your Identity Provider or through your organization’s custom SSO login URL (https://app.atatus.com/login/saml/<ACCOUNT_ID_OR_ALIAS>).
    • If password access is specifically required for that user, an administrator must remove the user under Settings » Users and send a standard email invitation.

4. “403 Forbidden” or “User Not Assigned” (IdP Error)

  • Symptom: When attempting to sign in, the browser displays an error on the Identity Provider’s domain stating that the application is not assigned.
  • Cause: The user has not been granted an assignment or group membership for the Atatus application in your IdP.
  • Resolution:
    1. Open your IdP administrative console.
    2. Navigate to your Atatus application settings.
    3. Go to the Assignments or User Access section and add the user or their group.
    4. In Google Workspace, ensure User access is set to ON for everyone (or active for the user’s Organizational Unit).

5. Missing or Invalid Email Attribute

  • Symptom: Authentication fails immediately after the IdP posts the assertion to Atatus.
  • Cause: The SAML assertion does not contain a valid email address, or the attribute name is not recognized by Atatus.
  • Resolution:
    1. Verify that your IdP releases the user’s primary email address under one of the following recognized attribute names:
      • User.email
      • email
      • mail
      • SAML Subject NameID
    2. Ensure the attribute value is a syntactically valid email format (user@example.com).
    3. Note that Atatus does not parse WS-Federation claim URIs (such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). Use simple attribute keys.

6. “Clock Skew” / Assertion Not Yet Valid

  • Symptom: Atatus rejects the SAML assertion with a timestamp validation error (NotBefore or NotOnOrAfter).
  • Cause: The system clock on your Identity Provider server differs from the Atatus authentication servers by more than the allowed tolerance window.
  • Resolution:
    1. Ensure your IdP server clock is synchronized with an authoritative Network Time Protocol (NTP) server.
    2. If using an on-premise IdP (such as Keycloak), check that system time synchronization services are running properly.

7. Native 2FA Prompt Not Appearing

  • Symptom: A user has two-factor authentication enabled under Atatus Settings » My Profile » Two Factor Authentication (2FA), but is never asked for a 2FA code when signing in via SSO.
  • Cause: This is expected behavior. When users authenticate through SAML SSO, Atatus completely suppresses native in-app 2FA and delegates all multi-factor authentication to your Identity Provider.
  • Resolution:
    • Enforce MFA, WebAuthn/FIDO2, or conditional access policies directly within your Identity Provider.

Diagnostic Checklist

If you need to contact Atatus Support for SSO assistance, collect the following information:
  1. SAML Tracer Capture: Use a browser extension (such as SAML-tracer for Chrome or Firefox) to export the SAML transaction XML.
  2. Atatus Account ID: Your 24-character identifier from the Single Sign-on settings tab.
  3. User Email: The exact email address of the authenticating user.
  4. Timestamp: The UTC date and time of the failed login attempt.