Developer Pages

# Core operations

Page contents

# Introduction

On this page, you can learn about the different core operations that you can make with the SDK.

The activate and authentication processes are divided into multiple steps, which are performed as individual method calls on a controller.

Most calls are asynchronous, and the application is required to provide a block of code to be executed once each call has finished.

# Activation

# Overview

Activation is the first thing that your application will guide your end-user through when using Encap.

This process creates a link between your end-user’s device and the Encap authentication server. This will later be used to establish trust.

To activate the end-user’s device, your application will invoke three methods on the Controller in succession. The process is as follows:

  1. Optional: Retrieve settings from the Encap server, such as activation code length and type.
  2. Register the end-user's device on Encap server. The Encap server will then pass information back which the API will use to establish trust.
  3. Activate the registration, using a selected authentication method and the information that was passed back in the previous step.

Note

Following these steps, the registration can now be used to authenticate the end-user that created it.

# How to implement

# Retrieve settings from Encap server (optional)

To begin the process, you can invoke loadConfig().

Note

It will return a LoadConfigResult object with information about the activation code length and type, so that the app can present the right keyboard and UI to be input.

Although this call is optional, it can can improve the end-user’s experience.

# Register the end-user's device on the Encap server

  1. Run the startActivation() operation.
  2. If the startActivation() operation is successful, then a StartActivationResult object is returned. This contains getAuthMethodsForActivation(), which is a list of authentication methods (AuthMethod) available for the device.
    • The list of authentication methods is filtered so that only those configured for this applicationId and enabled on the device are returned.
    • If more than one method is available, your app may let the end-user choose what authentication method to use.

# Activate the the registration

Once the startActivation() operation has been completed successfully, you can finish the process. To do this, run the finishActivation() operation with the desired authentication method.

Use the correct type of ActivationParameter for the authentication method, and fill in the required data.

Explore supported authentication methods

For supported authentication methods and additional details, see the Authentication methods page in our Encap SDK developer documentation.

Note

The device as an authentication method (AuthMethod.DEVICE) will always be activated when activating a two-factor authentication method, such as PIN code and Biometric Prompt.

Example: How an activation could look like

// The activation code should come from another source, such as a web page.
controller.startActivation(activationCode, new AsyncCallback<StartActivationResult>() {
    public void onFailure(final ErrorCodeException exception) {
        // Handle the failure.
    }
    public void onSuccess(final StartActivationResult result) {
        // Ready to continue to finishActivate. See result on how to proceed.
        ActivationParameter activationParameter = new ActivationParameter(); // Use the right type here for the auth method you want.
        controller.finishActivation(activationParameter, new AsyncCallback<FinishActivationResult>() {
            public void onFailure(final ErrorCodeException exception) {
                // Handle the failure.
            }
            public void onSuccess(final FinishActivationResult result) {
                // The auth method is activated.
            }
        });
    }
});

# Fetch the registrationId

After a successful activation, the registrationId is stored on the controller.

Example: Fetch the registrationId

 controller.getRegistrationId()

Note

The registrationId is the same as the deviceId and device_id which is used in the REST APIs.

# Authentication

# Overview

Authentication is a process used to prove that the current end-user is the same as the one who performed the initial activation.

To authenticate the end-user, your application will invoke two methods on the Controller in succession. The process is as follows:

  1. Identify who your end-user claims to be to the Encap server.
  2. The Encap server sends a challenge to the client API and a response is calculated.
  3. If the authentication succeeds, then the Encap server has indicated trust that you are interacting with the correct end-user.

# How to perform an authentication

# Start the authentication

To begin the process, you need to run the startAuthentication() operation.

If the startAuthentication() operation is successful, then a StartAuthenticationResult object is returned. This has the following methods:

Method Description
getAuthMethodsForAuthentication() A list of authentication methods that you can use for this operation.

The list of authentication methods is filtered so that only those configured for this applicationID, enabled on the device and activated are returned.
getServerConfiguredAuthMethods() A list of authentication methods configured in the applicationId.

This list is not filtered based on the capabilities of the mobile device, nor on what authentication methods are activated.

Example: You could use this to see if the mobile device has forgotten to add Fingerprint.

# Finish the authentication

  1. Once the startAuthentication operation has been completed successfully, you can finish the process by running the finishAuthentication() operation.
    • You have to pass in the desired AuthParameter for one of the authentication methods returned from getAuthMethodsForAuthentication().
  2. If the authentication operation is successful, then a FinishAuthenticationResult object is returned.

Example: How an authentication could look like

controller.startAuthentication(new AsyncCallback<StartAuthenticationResult>() {
    public void onFailure(final ErrorCodeException exception) {
        // Handle the failure.
    }
    public void onSuccess(final StartAuthenticationResult result) {
        // Ready to continue to finishAuthenticate. See result on how to proceed.
        AuthParameter authParameter = new AuthParameter(); // Use the right type here for the auth method you want.
        controller.finishAuthentication(authParameter, new AsyncCallback<FinishAuthenticationResult>() {
            public void onFailure(final ErrorCodeException exception) {
                // Handle the failure.
            }
            public void onSuccess(final FinishAuthenticationResult result) {
                // Successfully authenticated with auth method.
           }
       });
    }
});

# Add or update

# Overview

The addOrUpdate operation enables you to:

  • Add (activate) another authentication method to an existing registration.
  • Update an existing authentication method using the same authentication method. This is a special use case for updating the PIN code.

# Example use case

Your end-user wants add another authentication method to their existing registration. For example, they want to activate both the PIN code and the Biometrics authentication methods.

To do this, you could:

  1. Activate the first authentication method (PIN code) as described in the PIN code activation section on our Authentication methods page.

  2. Activate the second authentication method (Biometrics) from within your app using the addOrUpdate operation.

# How to implement

# Add another authentication to an existing registration

  1. Activate the PIN code as described in the PIN code activation section on our Authentication methods page.
  2. The end-user activates Biometrics in your app by calling startAddOrUpdate.
  3. If the operation is successful, then a StartAddOrUpdateResult object is returned, similar to the result from the StartAuthentication() operation.
  4. Use the getAllowedAuthMethodsToActivate() parameter to select which authentication method to add, and look at getAllowedAuthMethodsForAuthentication to find an authentication method that is supported for authenticating in this case.
  5. Once the start call has been successfully executed, call finishAddOrUpdate with the AuthParameter for the authentication method that you want to authenticate with, and the ActivationParameter for the authentication method you want to activate.

Find activation and authentication parameters

To find the right activation parameters (ActivationParameter) and authentication parameters (AuthenticationParameter), see the Authentication methods page in our Encap SDK developer documentation.

  1. Upon a successful result, the new authentication method has now been activated and is ready to be used to authenticate the end-user.

Note

A single-factor authentication method cannot be used to add a two-factor authentication method.

You need to configure on the server which two-factor authentication methods can be used to add other two-factor authentication methods.

Other use cases

Another common use case is to update the end-user’s PIN code. You can read more about this in the Add or update (change PIN code) section on our Authentication methods page.

Example: How an add or update could look like

controller.startAddOrUpdate(null, new AsyncCallback<StartAddOrUpdateResult>() {
    public void onFailure(final ErrorCodeException exception) {
        // Handle the failure.
    }
    public void onSuccess(final StartAddOrUpdateResult result) {
        // Ready to continue to finishAuthenticate. See result on how to proceed.
        AuthParameter authParameter = new AuthParameter(); // Use the right type here for the auth method you want.
        ActivationParameter activationParameter = new ActivationParameter(); // Use the right type here for the auth method you want.
        controller.finishAddOrUpdate(authParameter, activationParameter, new AsyncStateChangedCallback<FinishAuthenticationResult>() {
            public void onFailure(final ErrorCodeException exception) {
                // Handle the failure.
            }
            public void onSuccess(final FinishAuthenticationResult result) {
                // Successfully added auth method to registration.
            }
            public void onStateChanged(EncapController.State state) {
                // Possibility to update UI.
            }
        });
    }
});

# Deactivate

# Overview

The Controller provides two different deactivation methods.

  • Deactivate all authentication methods. This could be useful if:
    • Your end-user no longer wants to have an account in your app and wants their data deleted.
  • Deactivate a specified authentication method. This could be useful if:
    • Your end-user no longer wants to use Biometrics. Your app could then allow the end-user to deactivate that authentication method.
    • Your app no longer wants to support an authentication method. Your app could then call deactivate on that authentication method method.
      Note: Typically, you may consider to rewrite the app instead, so that this does not end up in the flow.

You may require deactivation or reactivation if the end-user forgets the PIN code from their first activation. The scenario will then be identical to that of a first time activation.

# How to implement

# Deactivate the registration

Run the deactivate method to delete all registration data for the given registration, including all of the authentication methods.

  • If the localOnly parameter is set to false, then the registration is removed both from the Encap server and locally.
  • If the localOnly parameter is set to true, then the registration will only be removed locally.

Our recommendation

It is advised to always try to deactivate towards the server.

If the server is down or an other abnormality prevents you from deactivating towards the server, you can perform a local deactivation as a fallback.

Example: How to deactivate the registration

final boolean deactivateOnlyLocally = false;
controller.deactivate(deactivateOnlyLocally, new AsyncCallback<DeactivateResult>() {
    public void onFailure(final ErrorCodeException exception) {
        // Handle the failure.
    }
    public void onSuccess(final DeactivateResult result) {
        // Successfully deactivated.
    }
});

# Deactivate a specified authentication method

  1. Run the deactivate(AuthMethod,...) method to deactivate a specific authentication method. The registration will stay intact.
  2. The specified authentication method (authMethod) is removed both from the Encap server and locally.

Limitations

The device as an authentication method (AuthMethod.DEVICE) is used for authentication towards the server, and cannot be deactivated by this method.

Example: How to deactivate a specified authentication method

controller.deactivate(AuthMethod.DEVICE_PIN, new AsyncCallback<DeactivateResult>() {
    @Override
    public void onFailure(@NonNull ErrorCodeException errorCodeException) {
        // Handle the failure.
    }

    @Override
    public void onSuccess(@NonNull DeactivateResult result) {
        // Successfully deactivated.
    }
});

# Cancel session

# Overview

You can use the cancelSession operation to cancel the activation or authentication session on the server.

For example, you could use this when the client has been notified of a new transaction, but the user rejects it by pressing the cancel button.

# How to implement

  1. Run the cancelSession() operation.
  2. The current activation or authentication session will now be cancelled on the server.

Example: How to cancel a session

controller.cancelSession(new AsyncCallback<CancelSessionResult>() {
    @Override
    public void onFailure(@NonNull ErrorCodeException errorCodeException) {
        // Handle the failure.
    }

    @Override
    public void onSuccess(@NonNull CancelSessionResult result) {
        // Successfully deactivated.
    }
});
Last updated: 11/04/2024 07:47 UTC

← Authentication methods →