Email-based sign in (aka "magic link" sign in)

We're going to add a feature that will allow apps to work without the user needing to create or enter a password.

How it will work on the client

First install

1. Participant installs the app
2. After consent process, app generates password to sign up user
3. User consent is submitted, app has session
4. When session expires, the app uses the generated password to re-authenticate

Reinstalls

1. Participant installs the app on new device or deletes/reinstalls 
2. Participant opens app, says “hey I already have an account, here’s the email address” 
3. App tells server “send me a magic link to this email address" 
4. App tells participant “check your email for a magic link” 
5. Participant has to go to email on phone and tap magic link, which takes them to the app to sign them in 
6. The app generates a new random password and includes it in the magic link sign-in call

How it will work on the server

Two new endpoints will be introduced:

{ "email": "<email.address>", "study": "<studyId>" }

This endpoint will reject calls to send another email while the prior email request has not timed out (currently 60 seconds). If this is abused, we may need to do further rate limiting. It will also need to verify the email is active in the study before sending an email.

{ "email": "<email.address>", "study": "<studyId>", "password": "<password>", "token" : "<token>" }

{ "statusCode": 404, "entityClass": "Account", "message": "Account not found.", "type": "EntityNotFoundException" }

If the token has been issued, retrieve the user's identity and return a session. Optionally, if a password value has also been submitted, reset the password before returning the session.

Study

Study will have a new email template, the emailSignInTemplate, which will allow researchers to create a message and the message can include a link. If the app needs, for example, to have a link with a subdomain, like https://myApp.sagebridge.org/mobile/verify.html?token=<sometoken>, they will be able to add that. There should be a default using webservices.sagebridge.org.

Verify the template has a ${token} string in it somewhere to substitute the token.

We will also be able to enable/disable this functionality with the emailSignInEnabled flag.

AuthenticationService