Skip to content

Documentation

Sign-in and single sign-on

Fixes for refused passwords, locked accounts, IP allowlist blocks, single sign-on (SSO) errors, lost multi-factor authentication (MFA) devices, early sign-outs and requests to verify it's you.

Where
Sign-in page · Security page (/security) · Admin → Settings → Organization settings → Security · Admin → Settings → Organization settings → Authentication · Admin → Users · Admin → Audit logs
Permission
Full administrator (sign-in and security policy) · MANAGE_USERS (passwords, MFA resets, enabling accounts)
Updated
October 2026

Before you start

Find the message the person saw in the headings below. Each one gives the likely cause, then what to check.

The sign-in page names a reason only after the right password. A wrong password, a locked account and a deactivated account all read “Email or password is incorrect.”

Every refused sign-in is recorded in Admin → Audit logs → Security events, with its reason. Choose Failures to see only refused attempts.

Failed SSO attempts are also in the Changes view as auth.sso.login_failed (OpenID Connect) or auth.saml.login_failed (SAML), with the reason.

Each person sees the workspace's lockout, idle sign-out and session length under Workspace policy on their Security page.

Problems and fixes

  1. 01

    “Email or password is incorrect” with the right password

    The account is probably locked after too many failed attempts, or it has been deactivated. The page answers the same way in both cases, so nobody can probe which accounts exist.

    • A locked account gets an email, “Your account was locked”, with the time access comes back
    • By default, 10 failed attempts within 15 minutes lock the account for 15 minutes
    • Wait for the lockout to end, or reset the password: a reset ends the lockout at once
    • Reset it with Forgot password? on the sign-in page, or have an admin set one in Admin → Users
    • A deactivated account can't sign in; an admin chooses Enable from its row menu in Admin → Users
    • Each refused attempt is in Admin → Audit logs → Security events
    1. Set a password:
    2. Admin → Users → row menu → Edit → Password reset → Reset password
    3. Change the lockout:
    4. Admin → Settings → Organization settings → Security
    5. Invalid attempts (3 to 10) · Attempt window (min) · Lockout duration (min)
  2. 02

    “This workspace requires single sign-on”

    An admin set Authentication mode to SSO required, so this person's password is refused. They sign in through the identity provider (IdP) instead.

    • Choose Continue with SSO on the sign-in page
    • Forgot password? sends nothing for an account that must use SSO
    • SSO required applies only while the SSO connection is on and its email domain is verified
    • If the connection is switched off or loses its domain verification, password sign-in comes back by itself
    • Admins change the mode under Authentication mode in Admin → Settings → Organization settings → Authentication
  3. 03

    “Sign-in from this network is not permitted”

    The workspace has a login IP allowlist, and the person's network address is outside it.

    • Sign in from an approved network, such as the office or the VPN
    • A full administrator edits Login IP allowlist on the Security tab
    • The list takes address ranges in CIDR form, IPv4 and IPv6
    • SSO sign-ins are checked against the same list
    • Saving a list that leaves out your own current address is refused, so you can't lock yourself out
    1. Admin → Settings → Organization settings → Security → Login IP allowlist
    2. 203.0.113.0/24
  4. 04

    “Your network address could not be verified”

    The workspace has a login IP allowlist and EvenTier could not read the person's address. On a self-hosted install, the proxy count usually doesn't match your reverse proxies.

    • EvenTier reads the address from the X-Forwarded-For header that your reverse proxy sets
    • TRUSTED_PROXY_HOPS is the number of proxies in front of the app that add to that header (default 1)
    • When it's wrong, the app log has a client-ip warning that the client address is unresolved
    • The same problem puts everyone in one shared sign-in rate limit
    • Set the right count and restart the app
    Self-hosted settings filebash
    # One reverse proxy, or one ingress, in front of EvenTier
    TRUSTED_PROXY_HOPS=1
  5. 05

    “This password has expired”

    The workspace's password rules include a maximum age, 90 days by default, and this password is older.

    • Choose Forgot password? on the sign-in page to set a new one by email
    • Or ask an admin to set one in Admin → Users → Edit → Password reset
    • A password an admin sets can be changed by its owner straight away
    • Admins change the maximum age with the password rules on the Security tab
  6. 06

    “Too many sign-in attempts”

    More than 20 sign-in attempts came from the same network address within 10 minutes.

    • Wait a few minutes, then try again
    • This limit counts attempts per network address, apart from the per-account lockout
    • Self-hosted: if everyone hits it at once, check TRUSTED_PROXY_HOPS (see above)
  7. 07

    “The single sign-on attempt failed”

    The identity provider answered, but EvenTier refused the result. The reason is in the audit log.

    • Open Admin → Audit logs and find auth.sso.login_failed or auth.saml.login_failed; the row holds the reason
    • “outside the verified workspace domain”: the email's domain isn't the SSO domain or another verified domain. Verify it, or verify it again after 90 days
    • “only allows invited SSO users”: the person has no account and Automatically create users after successful SSO is off. Invite them, or turn it on
    • “This account is inactive.”: enable the account in Admin → Users
    • “does not match the sign-in email”: the person typed a different email from the one their IdP account uses
    • “Token exchange failed.”: check the client ID, client secret and Token URL
  8. 08

    SAML sign-in fails

    EvenTier accepts a SAML response only when it is signed, was started from EvenTier's sign-in page, and carries an email address.

    • Set the IdP to sign both the response and the assertion
    • Entra ID: choose Sign SAML response and assertion. Google Workspace: choose Signed response
    • Start from EvenTier's sign-in page. A sign-in started from the IdP's app list fails with “SAML response is not bound to this browser session.”
    • “did not include an email address”: send an email or mail attribute, or an email-format NameID
    • Check the IdP SSO URL, IdP entity ID and X.509 signing certificate pasted into EvenTier
    1. https://<your host>/api/org-auth/saml/<workspace slug>/metadata
  9. 09

    “Single sign-on is not active” or “the attempt expired”

    “Not active” means the connection is off or missing settings. “Expired” means the sign-in took more than 15 minutes, or finished in a different browser from the one that started it.

    • Not active: tick the connection active in Authentication and save
    • OpenID Connect (OIDC) also needs the Token URL and User info URL
    • Expired: start again from the sign-in page, in the same browser
    • “Too many single sign-on attempts”: wait a minute, then start again
  10. 10

    Someone lost their MFA device

    They can sign in with a recovery code. If they have none left, an admin resets their MFA.

    • Each person gets 10 recovery codes when they set up MFA, and each works once
    • Enter a recovery code in the verification step of sign-in, in place of the six-digit code
    • Once signed in, choose Generate new codes under Recovery codes on the Security page
    • An admin with MANAGE_USERS chooses Reset MFA… from the person's row menu in Admin → Users, with a reason of at least 8 characters
    • The reset signs them out everywhere; if the workspace requires MFA, they set it up again at their next sign-in
    • Nobody can reset their own MFA from Admin → Users; another admin does it
    • No other admin can sign in? On a self-hosted install, run reset-mfa on the server (below). On EvenTier Cloud, EvenTier support resets it
    • reset-mfa signs the person out, emails them and records the reset in Security events; add --reason "..." to say why
    Self-hosted: reset MFA from the serverbash
    # Docker Compose, in the bundle folder
    docker compose exec app node_modules/.bin/tsx scripts/reset-mfa.ts admin@yourcompany.com
    
    # Kubernetes
    kubectl exec deployment/eventier -c web -- node_modules/.bin/tsx scripts/reset-mfa.ts admin@yourcompany.com
    
    # Linux server
    sudo /opt/eventier/current/bin/eventier reset-mfa admin@yourcompany.com
  11. 11

    The MFA code never arrives

    Email and text-message codes depend on outgoing email or a text-message provider. When sending fails, sign-in says “We couldn't send your MFA code right now.”

    • Use a recovery code to get in
    • Each code expires 10 minutes after it is sent; ask for a new one if it is older
    • Check the spam folder for emailed codes
    • Self-hosted: with email off (EMAIL_DELIVERY_MODE=off, or auto with no SMTP_HOST), emailed codes are never sent
    • To avoid delivery problems, switch to an authenticator app on the Security page
  12. 12

    A session ends sooner than expected

    Sessions end after a stretch of inactivity, and after a fixed lifetime however active the person is. Either way, the sign-in page says “Your session timed out due to inactivity.”

    • Idle sign-out defaults: 60 minutes for members, 30 minutes for anyone who can open the admin console
    • The shorter admin timeout applies on a custom role too, whenever it opens the admin console
    • Every session also ends at the absolute session lifetime, 12 hours by default
    • A password reset, by email or by an admin, and an MFA reset sign the person out everywhere
    • A full administrator changes the times on the Security tab
    1. Admin → Settings → Organization settings → Security
    2. User idle timeout (min) 5 to 60
    3. Admin idle timeout (min) 5 to 60
    4. Absolute session lifetime (min) 30 to 1440
  13. 13

    An action asks to “Verify it's you”

    Sensitive changes need a sign-in or a confirmation within the last 10 minutes. Without one, the server answers 403 RECENT_AUTH_REQUIRED: “Recent authentication is required for this action.”

    • Covered: roles and access, setting someone's password, API keys, erasing or exporting a person's data, workspace export and deletion
    • Also your own MFA changes, new recovery codes and signing out sessions
    • In Admin → Users, choose Confirm it's you in the error, verify in the new tab, then save again
    • Confirm with an MFA code or recovery code when MFA is on, otherwise with the password
    • In a workspace that requires SSO, confirm by signing in through the IdP again
    • A confirmation counts for 10 minutes
  14. 14

    Saving sign-in or security settings is refused

    The settings page checks each change so it can't lock the workspace out. The message names what to fix.

    • “Only a full administrator can change sign-in, security policy or security contact settings.”: delegated MANAGE_SETTINGS is not enough
    • “Verify the email domain before activating SSO.”: publish the TXT record and choose Verify first
    • “Turn on the SSO connection before requiring SSO.”: tick the connection active, save and test it, then require SSO
    • “Your email address is not on … or another verified domain”: sign in with an account on that domain, or keep SSO optional
    • “The login IP allowlist must include your current source IP”: add a range that covers your own address

Sign-in messages

The code behind each message on the sign-in page, for support tickets and the audit log.

CodeMessageWhat to do
SSO_REQUIREDThis workspace requires single sign-onChoose Continue with SSO
IP_NOT_ALLOWEDSign-in from this network is not permittedUse an approved network, or update the allowlist
IP_UNRESOLVEDYour network address could not be verifiedSelf-hosted: set TRUSTED_PROXY_HOPS
PASSWORD_EXPIREDThis password has expiredForgot password?, or an admin sets a new one
TOO_MANY_ATTEMPTSToo many sign-in attemptsWait a few minutes
MFA_INVALIDThat MFA code was not validUse a current code or an unused recovery code
MFA_DELIVERY_FAILEDWe couldn't send your MFA code right nowUse a recovery code
MULTIPLE_ORGSThis email belongs to multiple workspacesChoose the workspace first
sso_failedThe single sign-on attempt failedRead the reason in Admin → Audit logs
sso_configSingle sign-on is not active for this workspaceTurn the connection on
sso_stateThe single sign-on attempt expiredStart again in the same browser
sso_rate_limitedToo many single sign-on attemptsWait a minute

Good to know

  • While you roll out SSO required, keep one full administrator who can sign in with a password and MFA.
  • Test SSO changes in a second browser before you sign out of the first.
  • Ask people to store their recovery codes somewhere other than the phone that holds their authenticator app.