Troubleshooting

Start from what you see. Each section names the likely causes in the order worth checking them.

Check	Where
Is your tenant published, and is its licence active?	Dashboard. A blocked licence stops new sign-ins in every mode.
Can VERISCO reach your directory?	Identity Source. Run the connection test.
In connector mode, is the agent running?	`systemctl status verisco-connector`, or `docker logs verisco-connector`.
Is the captcha working?	Open your sign-in page. An error on the widget itself, such as "Invalid key type", stops everyone. See Captcha.

Open Sign-in Activity and find their attempt. The reason is recorded with it. The usual ones, in order:

An address block. Repeated failures from their address, possibly by colleagues behind the same office connection. Check IP Blocks first: it is the most common cause of "it worked yesterday" for one person while everyone else is fine.
An account lockout. Too many wrong passwords. It expires by itself, or a member of your team unlocks it.
Your network policy, in enforce mode: a country, a VPN, a new network.
Your device policy, in enforce mode: a machine below the bar.
Their password. In read-only mode it is the one in your own application.

"Invalid username or password" for a correct password#

Cause	Fix
The password is not stored as a bcrypt hash	Only bcrypt hashes can be verified.
The wrong column is mapped	Check the username and password columns on Identity Source.
The user signs in with their email, and the username column holds something else	Map the column your users actually type.
The account is temporarily locked	A correct password is still refused during a lock. See Lockout policy.

Factor	Check
Authenticator code	The phone's clock. Codes depend on the time, and a clock a minute out produces codes that are refused. Also: a code works once, so wait for the next one.
Email code	Your identity source has an email column mapped, and the message is not in the spam folder.
SMS code	The user's record has a phone number.
Passkey	The passkey was registered on this device, or on a security key that is plugged in. A passkey is bound to your sign-in page's address.

Symptom	Cause
`req.user` is undefined	The middleware is mounted after your routes. Mount it before them.
Signature verification fails	The public key file is not your tenant's current key. Download it again. After a key rotation the old file no longer verifies new tokens.
The token is "expired" immediately	Your server's clock is wrong.
The header is missing	The request did not come through VERISCO. Check that your hostname resolves to VERISCO, and that you are not calling your backend directly.
A redirect loop after sign-in	Your application still sends unauthenticated users to its own login page. Remove that redirect, or seal the old login.

Run verisco-analyzer verify. It names the failing check and the next thing to do.

Verify has not confirmed both the middleware and your public key. The response says which is missing. Fix it, run verify again, then go live.

Mode	Check
Gateway	Your backend address is reachable from VERISCO, and your application is listening on that port.
Connector	The agent is running, and the local address you gave is correct from the agent's machine.
Any	Your hostname's DNS record points at VERISCO. A certificate can only be issued once it does.

Mode	Expect
Gateway and connector	A few seconds.
SDK	Up to 30 seconds. Your console shows when each instance last called in; one that has not called in recently is running on old state.

Symptom	Cause
Users are signed out after a few minutes of reading	The idle timeout is short.
Users are signed out when they change network	Session binding is set to terminate. Step up is gentler.
In SDK mode, every request looks like a new network	Your application reports its load balancer's address. Set its proxy trust.

Your endpoint must answer 2xx within the timeout.
It must be reachable from the internet. Private addresses are refused.
Your plan must include webhooks.
If it arrives and is rejected by your own code: verify the signature over the raw body. See Webhooks.

Tell us what you see, with your tenant ID and the time of the attempt. With those two we can find the event.

Something missing or wrong on this page? Tell us and we will fix it.