Bridge
Contact Us Terms of Use

Authentication

Bridge supports a variety of authentication methods. Each pathway requires different credentials and different forms of interaction from the user, so you will want to evaluate the approach that is best for your onboarding experience.

Email and Password Authentication

For backend system accounts and some studies, users can sign up with an email address and a password they supply themselves.

In the past, apps have cached user passwords to sign the user back into the server on session expiration. We discourage this pratice. The reauthentication token in the session can now be used to renew the session without user intervention. (Reauthentication must be enabled for your study to use this API and typically is for new studies.)

Sign-Up

On sign up for the study, the following steps must be executed:

  1. The user signs up for an account, entering an email address and password as part of the SignUp payload and the sign-up API. Your app should verify a password has been entered, otherwise the server will assume this account will be authenticated using the email-only pathway;
  2. The server will send an email with a link to verify the email address. This link does not need to be intercepted by the app, and the link can be opened in any web browser on any device. The link will open a web browser where the page fetched will verify control of the email address.

Sign-In

After verifying their email address, the user must manually sign in to the application. They can sign in using their email and password using the SignIn payload and the sign-in API. This request, when successful, returns a session. The status code will either be 200 or 412 (Precondition Required) if the user must consent to research in order to use the API.

See reauthentication below for how to refresh a session once it expires, without user intervention.

Email-Only Authentication

Users can authenticate using only their email address. The steps for this form of authentication are as follows:

Sign-Up

On sign up for the study, the following steps must be executed:

  1. Set the App.autoVerificationEmailSuppressed field to true using the Bridge App APIs;
  2. The user signs up for an account, entering an email address (but no password) as part of the SignUp payload using the sign-up API.

Sign-In

  1. The app requests an email to be sent to the user to sign in, using the EmailSignInRequest via the request email sign in API;
  2. The server will send an email with a link to sign in to the application;
  3. If the user clicks the link in the email. The link should be captured as a "deep link" by the app. The link contains a query string portion that has a token parameter the app should extract from the URL.
  4. The app sends the following information to the server using the EmailSignIn playload via the email sign in API:
    • email—the user's email address;
    • study—the study identifier of the study;
    • token—the token that was sent via email;
  5. If the token is valid and it has been submitted within 5 minutes of being generated by the server, a UserSessionInfo is returned to the app, with the same status codes as described for email/password authentication. If the email address hasn't been verified, it will be verified by sign in and the account will be activated.

If the user clicks the link on another device, you will need to capture the link on your website with an explanation that the link should be used via email on the phone.

See reauthentication below for how to refresh a session once it expires.

Phone-Only Authentication

Users can authenticate using only their phone number. The steps for this form of authentication are as follows:

Sign-Up

On sign up for the study, the following steps must be executed:

  1. Set the App.autoVerificationPhoneSuppressed field to true using the Bridge App APIs;
  2. The user signs up for an account, entering a telephone number (but no password) as part of the SignUp payload using the sign-up API.

Sign-In

  1. The app requests an SMS message to be sent to the user to sign in, using the PhoneSignInRequest via the request phone sign in API
  2. The server will send an SMS message with a link to sign in to the application;
  3. If the user clicks the link in the message. The link should be captured as a "deep link" by the app. The link contains a query string portion that has a token parameter the app should extract from the URL. The app sends the following information to the server using the PhoneSignIn playload via the phone sign in API:
    • phone—the user's phone number object;
    • study—the study identifier of the study;
    • token—the token that was sent via SMS message;
  4. Alternatively, the SMS message can instruct the user to enter the 6 digit code back into the app rather than intercepting a link in the SMS message, as part of fulfilling step #3;
  5. If the token is valid and it has been submitted within 5 minutes of being generated by the server, a UserSessionInfo is returned to the app, with the same status codes as described for phone/password authentication. If the phone number hasn't been verified, it will be verified by sign in and the account will be activated.

If you opt to use a link that is intercepted by the app, and the user clicks the link on another device, you will need to capture the link on your website with an explanation that the link should be used via SMS on the phone.

See reauthentication below for how to refresh a session once it expires.

External ID with Password

For clinical studies that wish to maintain the total anonymity of the study participant in Bridge, a user can authenticate using only an external ID. Unless the partner organization tracks the assignment of this external ID, this account is truly anonymous.

However, before users can access an account this way, a researcher must create an external ID and an associated account using the API. After this set up, the user will not need to sign up for an account. Instead, the app must be taken to the clinic.

Password Generation

  1. In the clinic, an unauthenticated app should provide a means for a researcher to sign in to the Bridge server.
  2. Once authenticated, the app should call the generate password API to generate and receive back a random password.
  3. The app signs the researcher out, and signs in the external ID using the newly retrieved password. The session that is returned to the app has the necessary token to reauthenticate the app periodically, as in any other authenticated session.
  4. The app now reauthenticates using the reauthentication API. If the app should no longer have a valid reauthentication token, due to a network error or the like, then the app will need to have another password set by the researcher, which involves bringing the app into the lab.

Reauthentication

If reauthentication is enabled for your study, the UserSessionInfo payload returned by the sign in process includes a reauthToken that can be sent to the reauthentication endpoint. The token is a one-time token that will be replaced when it is used to generate a new session for the client (that session includes a new token in order to chain these requests indefinitely). In effect, the reauthToken is like an auto-generated password that avoids the need for users to sign in again once we establish their identity.

As long as the application holds on to this reauthentication token, it will not need to re-involve the user in authentication. If the app loses this token, it will have to sign in again using its preferred authentication channel. It is best practice to involve the user in this sign in process, rather than trying to store the password on the device (for email-only and phone-only authentication, the app must involve the user).

Adding additional credentials

It is useful and important to collect further credentials than the minimum necessary to sign in. For example, if you prompt your user to enter only an email address, you may subsequently collect a telephone number, or password. The same is true of other credentials.

Additional credentials will make it possible for the user to authenticate with Bridge if a phone number is re-assigned (there are even rare examples where Yahoo and Microsoft have re-assigned email addresses that they did not believe were in use). In this situation, the user will want to change these credentials, but they will need another pathway to authenticate in order to make this change. Your app will also need to provide support for that alternative method of authentication.

Additional credentials can be added using the IdentifierUpdate payload via the updated identifiers API

Sign Out

When the sign out API is called, the client should include the Bridge-Session token with the current session token. This will delete the session and invalidate any outstanding reauthentication tokens.

Email and phone number verification

In all cases after sign up, the system will attempt to validate identifiers that uniquely identify the account:

For email addresses and phone numbers, the identifier can be verified immediately with a verification email message or SMS message. The account will be unverified (and sign ins will not be acknowledged) until this occurs.

For apps that send an email message or SMS text with a link to sign in, this verification step can be turned since the act of signing in will verify the validity of the identifier and activate the account. On the App object, emailVerificationEnabled should be set to false and/or autoVerificationPhoneSuppressed should be set to true, and verifyChannelOnSignInEnabled should be set to true.