Custom authenticators

The OneWelcome Identity Platform has standard support for authentication via PIN or fingerprint. There are many other ways to authenticate a user, for example via NFC, voice, or face recognition. These methods have their own APIs. With the custom authenticators feature, you can implement the logic to authenticate the user via scripts. These scripts are maintained via the admin console.

Custom authenticator registration

Prerequisite: The user has authenticated with one of the standard authenticators. They can then register for your custom authenticator.

1. The Mobile SDK passes the user identifier and registration request data to the OneWelcome Identity Platform.

2. The OneWelcome Identity Platform validates the request.

3. The registration script is executed. It can call an external API to register the user. This depends on your implementation.

4. The API returns the result of the registration.

5. The registration script returns a status code that indicates whether the registration succeeded. It can also return registration data and a response payload (optional).

6. The OneWelcome Identity Platform saves the registration response data. It returns the optional response payload.

Custom authenticator authentication

Prerequisite: The user has already registered with this custom authenticator.

1. The Mobile SDK passes the authentication request data to the OneWelcome Identity Platform.

2. The OneWelcome Identity Platform validates the request.

3. The authentication script is executed. It can call an external API to authenticate the user. This depends on your implementation.

4. The API returns the result of the authentication.

5. The authentication script returns a status code that indicates whether the authentication succeeded. It can also return a response payload (optional).

6. The OneWelcome Identity Platform returns an access token if the authentication is successful, otherwise it returns an error. It also returns the optional response payload.

Customer authenticator deregistration

Prerequisite: The user has already registered with this custom authenticator and is authenticated in the mobile app.

1. The Mobile SDK passes the deregister request to the OneWelcome Identity Platform.

2. The OneWelcome Identity Platform validates the request. It removes the reference to the custom authenticator for this user.

If the user wants to use the custom authenticator in the future, they need to register again.

For more information, see Configuration and Example scripts.

Custom authenticator configuration

Custom authenticators is an optional component of the OneWelcome Identity Platform. If you want to use it, enable the Custom Authenticators option described in Configure system features.

Create a custom authenticator

To add or edit a custom authenticator, on the admin console, go to Configuration > App configuration > Custom Authenticators.

Enter the scripts for each step of the custom authentication flow in the fields under the Scripts section. For examples of each step, see the Custom Authenticator Example. The script fields are optional because the scripts might not be available during the development stage.

Application configuration

In the OneWelcome Identity Platform, you can enable custom authenticators per application.

To add or edit an application, go to Configuration > App configuration > Applications.

Mobile authentication

To use mobile authentication via a custom authenticator, configure a mobile authentication type like it is done for any other type. Select Push with Custom Authenticator as authentication method and fill out all other required fields.

Custom authenticator examples

The example scripts for a custom authenticator show the minimum response to complete the step in the process.

Registration script

This is an example for registration that accepts all incoming requests. It returns the requestPayload from the request as registrationData in the response. The registrationData is saved in the OneWelcome Identity Platform for future requests to this custom authenticator. The (empty) responsePayload is returned via the Mobile SDK.

The format of the requestPayload parameter is defined by the mobile application. It is sent as a string parameter to the execute function. The script developer is responsible for parsing this string and implementing the logic to either register the user or reject the registration.

function execute(requestPayload, userIdentifier) {
  LOG.debug("Registration of Example Custom Authenticator for user: {}", userIdentifier);

  return {
    status: 2000,
    registrationData: requestPayload,
    responsePayload: ""
  };
}

Authentication script

This is an example for authentication. It compares the requestPayload from the current request with the registrationData that was saved during registration. When it succeeds, it returns a status code 2000 (Success), otherwise 4000 (Failure, user can try again). The (empty) responsePayload is returned via the Mobile SDK.

The format of the requestPayload is defined by the mobile application. Both requestPayload and registrationData are sent as string parameters to the execute function. The script developer is responsible for parsing this string and implementing the logic to either authenticate the user or reject the authentication.

function execute(requestPayload, userIdentifier, registrationData) {
  LOG.debug("Authentication of Example Custom Authenticator for user: {}", userIdentifier);

  var validUserKey = requestPayload.equals(registrationData);
  var statusCode = validUserKey? 2000 : 4000;

  return {
    status: statusCode,
    responsePayload: ""
  };
}

Status codes

The execute function of the script is responsible for returning a status that can be interpreted by the OneWelcome Identity Platform. The OneWelcome Identity Platform performs different actions (such as issuing or revoking tokens) based on the returned status, and returns only selected status codes to the Mobile SDK. Extreme care must be taken that they are correct.

There are different ranges of status codes, each with a particular meaning:

• 2xxx: Success

• 3xxx: Configuration error

• 4xxx: Recoverable client error

• 5xxx: Non-recoverable client error

The script should return a status code of 2000, 4xxx, or 5000. A 3xxx status is returned by the OneWelcome Identity Platform when the script could not be executed.

The following table contains an overview of the status codes and their meaning.