Skip to content

End to end authentication flow

Jump to bottom
Greg Bowler edited this page Oct 13, 2019 · 22 revisions

This section describes each step of the authentication flow in detail.

Consumer application

The consumer application is the software that is being developed that requires authentication to be provided by Authwave. This could be any server-side web application.

For a consumer application to be able to communicate with Authwave, it needs to be configured within the Authwave host (typically www.authwave.com, unless self-hosting Authwave).

From the Authwave host configuration, you will be provided with:

  1. Application ID - this is chosen by the administrator as a name for the consumer application that is unique to the Authwave host.
  2. Redirect URIs - a pre-configured list of URIs of the consumer application to use for login success, or login cancellation.
  3. Application key - a randomly generated set of alphanumeric characters, unique to the application.
  4. Shared key - a randomly generated set of alphanumeric characters, unique to the administrator's organisation.

Authwave then needs to be installed on the server. For PHP applications this is done by installing using Composer. In the future, other languages are planned to be officially supported.

Authentication action

When the consumer application is ready to authenticate a user, a new instance of the Authwave Client must be instantiated:

$authwave = new \Authwave\Client("your-app-id");

The action that triggers authentication depends on what application is being developed, but it usually consists of submitting a form or following a link.

The $authwave object can be used to obtain the full link required to follow, which can be set to a link's href attribute:

$href = $authwave->getRedirectLink();

Alternatively, we can redirect the user's browser directly by calling the redirect function:

$authwave->redirect();

The URI that is used by the above two functions requires all necessary information for the Authwave Provider to handle Authentication. Once Authentication is complete, the user's browser will be redirected to your application's pre-configured redirect URI.

Provider application

When the user is redirected to the Authwave Provider, they are instantly greeted with a simple and recognisable login form, branded with the consumer application's colours and logo.

The user can choose to sign in with their existing details or create a new account. Whatever they choose, when they are successfully authenticated and return to the consumer application, the details will be available on the $authwave object.

Create account action

When the user chooses "Create account", they are presented with a recognisable and simple sign up form that contains the following fields:

  • Email address - this is a mandatory field, used as the primary identification method.
  • Mobile number - this is an optional field, used as an account recovery mechanism. Unless configured, this field is not available to the consumer application.
  • Identification choice - the user can choose between "magic link", "password", "token" or "third party" identification methods.
  • Password - if the "password" option is chosen, the user picks a secret password here.
  • Token - if the "token" option is chosen, the user will be instructed to set up their physical security token in the next screen.
  • Third party - if the "third party" option is chosen, the user picks their OAuth provider here (e.g. Google, Twitter, Facebook, Github, etc.).
  • Extra fields, configured by the administrator - optional fields can be chosen to display when configuring the application in the Authwave host. These fields' data are then available on the $authwave object within the consumer application.

After submitting the above details, the email address provided will require confirmation by following a link sent to it. This can be done on any device.

If the user has chosen "token" identification, the instructions for setting up a physical security token are displayed at this point.

If the user has chosen "third party" identification, the buttons for authenticating via a set of OAuth providers are available at this point.

The user can not progress back to the application until their email is confirmed, and any identification methods have been completed.

Using an already-registered email address

If the user attempts to create an account with an email address that is already used to identify a user, this will be made clear via email to the user, which prevents any information disclosure as to whether the email address has been used for the service in the past.

All attempts to add extra identification methods to an account require confirmation via email.

Sign in action

Existing users can sign in by typing their email address in the main text box and pressing "next". On the next screen, they are asked for their identification method (either magic link, password, token or other). If the user had previously stated that their account should use a magic link, the email will already have been sent out at this point.

If the user attempts to sign in to an account that hasn't been created yet, all authentication methods will display failure messages. For example, if the user attempts to sign in using a password, the message "Your password doesn't match for the account [email protected]". If the user chooses to sign in using the magic link, this is a valid path and following the magic link will redirect the user to the sign up form.

Cancelling authentication

A user can cancel the authentication flow at any time by using the standard browser controls. This means either clicking the back button, or closing the tab, whichever is appropriate. It is the choice of the consumer application whether or not to open the authentication in a new tab.

Successful authentication

Once a user has completed signing up a new account or signing into their existing account, the user's browser is redirected back to the preconfigured success URI within the consumer application, and the user's details are exposed via the $authwave object:

$authwave = new \Authwave\Client("your-app-id");
$id = $authwave->getId();
$email = $authwave->getEmail();

// Plus, any extra fields that have been configured in the Authwave host:
$shippingAddress = $authwave->getField("address");
$telephone = $authwave->getField("telephone");

When storing user information in the consumer application, it is important to use the ID to identify the user, rather than the email address, because the user can change their email address at any time.

Account settings

It is important to give the user the ability to edit their account settings in case they wish to update their email address, password, identification mechanism, or any other fields that have been configured by the consumer application.

This is done in a similar way to initialising the authentication flow:

$authwave = new \Authwave\Client("your-app-id");
$href = $authwave->getSettingsHref();
// or redirect in-place:
$authwave->settingsRedirect();
Clone this wiki locally