Before you go live

Security checklist

OT Auth proves that a real person on an enrolled phone approved. Your server turns that into a session. These are the places where an integration can undo that guarantee, and how to close each one.

  1. Accept only callbacks OT Auth signed, for your own keyCalls to /otlogin and /otregister sign people in. OT Auth signs every call with its own key: check the signature, the timestamp and the nonce before anything else, as in Checking the signature, using OT Auth's public key from the OT Auth console. Without this, anyone who can reach the URL can claim an approval for any user. Then check the call's APIKey is yours: OT Auth signs every app's calls with the same key, so without this check another app's approval could sign someone in on your site. Refuse the rest with a 401 and a JSON body, and log each refusal: a wrong key or a drifting clock then shows up at once instead of as failed sign-ins.
  2. Make RequestIDs on your server, random and single useGenerate each one with a secure generator (122 bits or more) and ignore any ID the sign-in page offers. Delete a request the moment it succeeds, is rejected or expires, and answer invalidRequestID to any later call for it.
  3. Deliver the result only to the page that askedThe RequestID is printed in the QR code, so treat it as public. Keep the WebSocket that asked with each request and push the outcome down that socket only. Never let another connection claim a request by its RequestID, and drop a page's requests when its socket closes.
  4. Open the sign-in socket only for your own pageCheck the WebSocket's Origin header against your sign-in page's origin, and close any other. Otherwise a page on another site can open your socket from its visitor's browser: the phone shows that visitor's own IP and city, they approve, and that site's script receives the session. Keep messages small (maxPayload) and ignore any that aren't a JSON request, so one bad message can't take the server down.
  5. Expire on the server90 seconds is enough to scan and approve. Enforce it in your request store, not just in the page countdown, and refuse late calls with expireRequestID.
  6. Report the browser honestlyThe IP and Location you send from /qrvalidate are what the person checks before approving. Send the IP your server saw on the connection (behind a proxy, from your own proxy's header only) and a city-level location you looked up. Never pass on an IP or location the page reported about itself: a phishing page would report whatever matches its victim.
  7. Behind a proxy, trust only your ownBelieve X-Forwarded-For only on connections from your own proxy, and have the proxy overwrite the header rather than append to it. Otherwise the caller chooses the address the person is shown. Proxy setup →
  8. Sign sessions with real secretsKeep the keys that sign your session tokens in the environment, and refuse to start without them. A default written in the code is a key everyone who can read the code can forge sessions with.
  9. Keep your Private Key on your serverIt signs your calls to OT Auth for code sign-in. Keep it in the environment, never in a page, a mobile app or your source code. If it may have leaked, replace the key on the console's API Keys page.
  10. Link accounts by UserIDStore OT Auth's UserID on your user record and match on it. Phone numbers change hands; the UserID doesn't. Use the name, email and address people share only to fill in their account, never to find or merge an existing one: they are details from the person's profile, not proof of who they are. To link an account someone had before you added OT Auth, use the verified PhoneNo of /otlogin, once, and only for an account with no UserID yet (how).
  11. Answer within 5 secondsLook up, decide, reply. Send emails, sync profiles and warm caches after replying.
  12. Log every callbackRequestID, call, outcome and time, and every call you refused. Watch for rejects: several /otreject calls for one account mean someone is trying to get in.

What OT Auth guarantees

Your server can rely on these without checking them itself:

  • The approval came from the person's own phone. The app signs each approval with a key that never leaves the phone, and OT Auth refuses edited or replayed approvals before it calls you.
  • The UserID and PhoneNo are verified. The phone number was confirmed by SMS, and OT Auth forwards only the identity that belongs to the phone that approved.
  • Your name can't be borrowed. The app shows the name registered for your API key, never one a website sends. A key works for everyone only once its domain is verified, and a name that looks like a well-known brand is reviewed first.
  • Calls come only from OT Auth, only to your URL. OT Auth signs every call it makes, and calls only the public https URL registered for your key.
  • The phone is unlocked by its owner. OT Auth opens only after the phone's own unlock, and people can require an extra check before every approval.
  • A lost phone can be cut off. The person signs it out of OT Auth from another of their phones. From then on it can't approve sign-ins, and its codes are refused. OT Auth doesn't end sessions you've already started: offer your own way to sign out on other devices.