DeviceAuthentication external object usage examples

This document shows some scenarios for which the Device Authentication external object was created; these scenarios were solved through basic examples.

Scenarios

The main scenario we want to solve is being able to check that the person using the application is the owner of the device.

Going into more detail, these use cases could be solved using Local Authentication mechanisms:

Allow the user to show sensitive information, for example, health information stored in the device.
Allow the user to interact with sensitive information in the device, for example, transferring money to a third party.
Remember user's credentials to authenticate with another system, for example, an application that uses GAM may ask the user if they want to remember the username and password information, and may ask the user for the fingerprint or other Local Authentication mechanisms to securely store the information provided by the user.

Examples:

Event 'AuthenticateLocalUser'
    composite
        &auth = DeviceAuthentication.Authenticate(DeviceAuthenticationPolicy.Biometrics, "Please authenticate")
        if (&auth)
            // user authenticated
        else
            // error condition
        endif
    endComposite
EndEvent

In the previous example, the result is assigned to a variable and then checked in an if command.

In the following example, if the user cannot be authenticated, the message is never shown because the event is canceled upon authentication failure.

Event 'AuthenticateLocalUser'
    composite
        DeviceAuthentication.Authenticate(DeviceAuthenticationPolicy.Any, "Please authenticate")
        msg('User is valid!')
    endComposite
EndEvent

Solving the proposed scenarios

1. Allow the user to show sensitive information

The following code could be used to restrict access to a given Panel:

Event ClientStart
    Composite
        &Policy = DeviceAuthenticationPolicy.Any
        &Available = DeviceAuthentication.IsAvailable(&Policy)
        if &Available
            &Authenticated = DeviceAuthentication.Authenticate(&Policy, "Please authenticate")
            if not &Authenticated
                Actions.Cancel()
            endif
        endif
    EndComposite
EndEvent

2. Allow the user to interact with sensitive information in the device

This scenario is similar to the first one, but could also be used in any user event.

Event 'ButtonTapped'
    Composite
        &Policy = DeviceAuthenticationPolicy.Biometrics 
        &Available = DeviceAuthentication.IsAvailable(&Policy)
        if &Available
            DeviceAuthentication.Authenticate(&Policy, "Please authenticate")
        endif
        PerformSensitiveOperation() 
    EndComposite
EndEvent

3. Remember user's credentials

What we want in this case, is to remember the username and password after a successful login, so that the user will not have to type them again.

Event 'Login'
    Composite
        Actions.Login(&user, &pass)
        if DeviceAuthentication.IsAvailable(DeviceAuthenticationPolicy.Biometrics)
            Confirm('Do you want to use biometrics to log in in the future?')
            DeviceAuthentication.Authenticate(DeviceAuthenticationPolicy.Biometrics, "Please authenticate to store your credentials")
            ClientStorage.SetSecure(!'user_name', &user)
            ClientStorage.SetSecure(!'user_pass', &pass)
        endif
    EndComposite
EndEvent

And to log in without asking for the credentials to the user:

Event ClientStart
    Composite
        if DeviceAuthentication.IsAvailable(DeviceAuthenticationPolicy.Biometrics)
            DeviceAuthentication.Authenticate(DeviceAuthenticationPolicy.Biometrics, "Please authenticate to log in")
            &user = ClientStorage.Get(!'user_name')
            &pass = ClientStorage.Get(!'user_pass')
            Actions.Login(&user, &pass)
            Return
        endif
    EndComposite
EndEvent