Setting up a method

Give signed-in users a Two-step sign-in section in their settings. Offer what getMethods allows.

Note

Before changing or removing a method, ask the user to prove it’s them again: a current code, an approval, or their password. Otherwise anyone with a stolen session could turn the second step off.

Authenticator codes

1. enrollTotp(userId, label) returns qrCode (a PNG data URI for an <img>), secret (to type in by hand) and the method, still PENDING.
2. The user scans it with Tenon Authenticator or any authenticator app, and types the first code.
3. activateFactor(userId, factorId, code): the method is active, and it replaces their previous one. A wrong code throws InvalidCode: let them try again. After 15 minutes or 5 wrong codes, start again (enrollment_expired).

Java

TotpEnrollment totp = tenonAuth.enrollTotp(user.id(), "Customer portal");
// Page: <img src="${totp.qrCode()}">, totp.secret(), a field for the first code.
tenonAuth.activateFactor(user.id(), totp.factor().id(), code);

TypeScript

const totp = await tenonAuth.enrollTotp(user.id, 'Customer portal');
// Page: <img src={totp.qrCode}>, totp.secret, a field for the first code.
await tenonAuth.activateFactor(user.id, totp.factor.id, code);

Python

totp = tenon_auth.enroll_totp(user.id, "Customer portal")
# Page: <img src="{{ totp.qr_code }}">, totp.secret, a field for the first code.
tenon_auth.activate_factor(user.id, totp.factor.id, code)

.NET

var totp = await tenonAuth.EnrollTotpAsync(user.Id, "Customer portal");
// Page: <img src="@totp.QrCode">, totp.Secret, a field for the first code.
await tenonAuth.ActivateFactorAsync(user.Id, totp.Factor.Id, code);

Sign-in approval (Tenon Authenticator)

1. enrollPush(userId, label) returns qrCode, enrollmentUri (a link that opens the app on the same phone) and activationNumber.
2. The user scans the QR code with Tenon Authenticator, and types the activation number your page shows.
3. Poll listFactors every 3 seconds until:
   • the method is ACTIVE: done, and it replaced their previous one;
   • it is gone: they typed a wrong number, so start again;
   • expiresAt has passed.

Email codes

Only when getMethods().emailAllowed, and only for the listed domains when there are any.

1. enrollEmail(userId, email, label, language) sends a code to the address. Take the address from your own records, e.g. the company directory, rather than letting users type any.
2. The user types the code: activateFactor.

Errors:

• EmailRefused with email_codes_not_allowed or email_domain_not_allowed;
• TooManyRequests;
• EmailUnavailable: no email could be sent, so try later.

Then: recovery codes

Right after a method becomes active, call createRecoveryCodes(userId) and show the 10 codes once, with Download and Print. They replace any older codes. Show getRecoveryCodes(userId).remaining in the settings, and offer new codes when few are left.

Turning it off

deleteFactor(userId, factorId) removes the method. The user’s remembered devices and recovery codes stop working with it. Whether a user may turn the second step off at all is your policy.