Let visitors turn on two-step sign-in
Goal
Let somebody who signs in to your portal turn on two-step sign-in: an authenticator app on their phone that is asked for a six-digit code every time they sign in.
Before you start
- A portal that asks visitors to sign in. See Ask visitors to sign in.
The whole of it is one button
Draw a button on any screen of your portal and give it this handler:
openAccountSecurity();
That is everything. The platform opens its own panel over your page, and the visitor scans a code, types six digits and saves their recovery codes without you drawing any of it.
Or draw it yourself
If you would rather the page looked like the rest of your site, draw a screen of your own — behind the sign-in, since it is about the visitor's account — and give it these calls, in this order:
| When | Call |
|---|---|
| The screen loads | loadAccountSecurity("mfa") — state.mfa.enabled says whether it is on |
| Turn it on is pressed | startAuthenticator("enrol") |
| Check the code is pressed | verifyAuthenticator(getState("code"), "codes") |
| I have saved them is pressed | completeAuthenticator("done") |
| Turn it off is pressed | disableAuthenticator(getState("offCode")) |
- The QR code is
state.enrol.qrCode— add an image and bind its source to it. Putstate.enrol.sharedKeybeside it for anybody whose camera will not read the code. - The recovery codes land in
state.codesas a list; repeat a line over it showingrow.code. - Two-step sign-in is not on until
completeAuthenticator. Checking the code only proves the app works. So draw the codes with a sentence telling the visitor to save them now — they will not be shown again — and a button that says they have. If your page forgot that step, the factor would simply stay off rather than turn on with codes nobody saw.
The QR code is drawn in the visitor's own browser; it is never sent anywhere to be turned into a picture, because it carries the secret their app will use.
The portal-landing-page sample has this as its Sign-in security screen.
What the visitor sees
The panel says which way their account is set, and offers the one thing that is available:
| Their account | What the panel offers |
|---|---|
| Two-step sign-in off | Turn on two-step sign-in — scan, prove, save the codes |
| Two-step sign-in on | How many recovery codes are left, and a box to turn it off with a current code |
The order is scan → prove → write the codes down, and the factor is not switched on until the codes have been acknowledged. Somebody who closes the tab half way has changed nothing about their account, which is the point of doing it in three steps rather than one.
Turning it off needs a code
A visitor can turn their own two-step sign-in off — it is their account — but only by typing a current code, or one of their recovery codes. That is deliberate: turning off a second factor is exactly the act somebody who had stolen a session would perform.
People who sign in to the Parsware Shell and the Admin Control Center must hold a second factor, and are offered a way to move it to a new phone instead. That is a decision about the surface holding every customer's records; it is not one we make on your customers' behalf.
What happens at the next sign-in
Nothing you have to draw. The platform's sign-in form asks for the code itself, beside the address and the password, and accepts a recovery code in the same box — a recovery code is not six digits, so the platform can tell which it is being given.
If you drew your own sign-in page, it needs a code box that
appears when signIn says the account wants one — that page shows how.
What this does not do
- It does not move an authenticator to a new phone in one step. A visitor whose phone is gone turns the factor off with a recovery code and turns it on again, which is one extra step and loses nothing.
- It does not force anybody. Two-step sign-in is offered to your visitors and never required of them. If your portal needs to require it, that is a conversation to have with us rather than a screen to draw.
- It does nothing on a portal anyone can open. There is no account for a second factor to belong to, so the button reports that rather than appearing to work.
Try it
The portal-sign-in-and-accounts sample solution has this on a
screen called Sign-in security, with a How this sample works page that walks through it.