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.

# 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 EncapController 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 LoadConfig result object with information about the activation code length and type, so that the app can present the right keyboard and UI to input with the UIKeyboardTypeFromEncapInputType method.

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 the EncapStartActivationResult object is returned as the successResult. This contains authMethodsForActivation, which is a set of authentication methods (EncapAuthMethods) available for this 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.
    • In the case of EncapAuthMethodPIN, you can use the pinCodeType, pinCodeLengthMin and pinCodeLengthMax properties to determine how to present an input form to your end-user for their PIN code entry.
    • Similar to the activation code, you can use UIKeyboardTypeFromEncapInputType to obtain the type of keyboard that is best suited for entering a PIN code of the type expected by the Encap server.
    • You can check whether the end-user's input conforms to the PIN code policy using the IsValidForEncapInputType method. The EncapAPI will also perform this check on the PIN code when the app tries to perform the next step.

# 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.

Explore supported authentication methods

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

The device as an authentication method

The device as an authentication method (EncapAuthMethodDevice) will always be activated when activating a two-factor authentication method, such as PIN code, Touch ID or Face ID.

How to activate a registration with Face ID

# Check if activation data is present

You can use isActivatedLocally to check if the activation data is present on the device. This method will return a boolean value.

This can be useful to determine flows in the application, such as whether the application should proceed with the activation flow.

Note

The isActivatedLocally method will not perform any call to the Encap server to check the status of current activation.

Example: Check if the registration is activated locally

do {
    let isActivated = try EncapController.shared().isActivatedLocally().boolValue
} catch {
    // Handle error, the operation has failed due to an unexpected error. 
}

# Fetch the registrationId

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

Example: Fetch the registrationId

EncapController.shared.registrationId

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 EncapController 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

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

    Note

    clientOnly is a legacy concept and should never be set to true. It will be removed in a future release.

    • For all authentication sessions, you have to pass false in the clientOnly parameter.

  2. If the startAuthentication operation is successful, then the EncapStartAuthenticationResult object is returned as the successResult. This object has the following properties:

Property name Description
lastAttempt Contains a date which indicates the last time somebody tried to authenticate themselves as the identification's end-user.
totalAttemptsPIN The total amount of invalid authentication attempts for EncapAuthMethodDevicePIN permitted by the server before the end-user’s account is locked down by the server. This is to prevent brute-force entry.

Note: Locked accounts need to be unlocked by contacting the Encap server operator or by using the administration web services of the Encap server from the Encap service provider.
remainingAttemptsPIN The amount of remaining invalid authentication attempts for EncapAuthMethodDevicePIN that the end-user has left before their account is locked down by the server.
contextTitle A short topical or categorical description of the end-user's authentication context.
contextContent Data in a form indicated by contextMIME, that can be used by the service provider to add some context to the authentication attempt.

For example, if the end-user needs to authenticate themselves to allow a payment transaction to proceed, you could use the operation context to provide useful information to the end-user about the transaction.

Note: It could be plain text, a web page, a PDF document, an image, or any other kind of contextual information.
contextMIME The MIME type of the contextContent.
authenticationMethod Indicates the type of authentication method used.
pinCodeLengthMin The minimum PIN code length.
pinCodeLengthMax The maximum PIN code length.
pinCodeType The type of PIN code, so that the correct keyboard type can be displayed to the end-user.

# Finish the authentication

  1. Once the startAuthentication operation has been completed successfully, you can finish the process by running the finishAuthentication operation.
    • If a PIN code was used for the authentication, then you should include this in the PIN code authentication parameters.
      Note: You should not store the end-user's PIN code anywhere else.
    • If Touch ID was used for the authentication, then you should provide the touchIdPrompt value for the Touch ID popup UI. For example, this could be a context message that is sent from the server.
  2. If the authentication operation is successful, then the EncapFinishAuthenticationResult object is returned as the successResult.
  3. Your app’s UI can use this object to determine how to proceed after the authentication has been completed.
    • Similar to the EncapActivateResult, this result provides a responseType and contextContent property.

Example: How to authenticate with Face ID

# Add or update

# Overview

The addOrUpdate operation enables you to:

  • Add (activate) another authentication method to an existing registration.
  • Update an existing authentication method.

# 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 Touch ID authentication methods.

To do this, you could:

  1. Activate the first authentication method (PIN code) as described in the Activation section.

  2. The end-user activates the second authentication method (Touch ID) from within your app using the Add or Update method.

# How to implement

# Add another authentication to an existing registration

  1. Activate the PIN code as described in the Activation section.
  2. The end-user activates Touch ID in your app by calling startAddOrUpdateOfAuthMethod.
  3. If the operation is successful, then the EncapStartAddOrUpdateResult object is returned, similar to the result from a StartAuthentication operation.
  4. Use the allowedAuthMethodsToActivate parameter from the response object to select which authentication method to add.
  5. Once the start call has been successfully executed, call finishAddOrUpdateOfAuthMethod with the activationParameters for the authentication method that you want to activate. For example, this could be StrongTouchID and the parameters for the PIN code.

Find activation and authentication parameters

To find the right activation parameters (activationParameters) and authentication parameters (authenticationParameters), 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 can not 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.

When you activate a two-factor authentication method, Encap will always activate the device as well.

There are only a few use cases where activating only the device makes sense, such as with a pure authenticator app.

Other use cases

Another common use case is to update the end-user’s PIN code.

To do this, you must follow the same steps as indicated above, however, you set PIN instead of StrongTouchID for the activationParameters in the finish call.

Example: How to add Face ID when PIN code is activated

# Deactivate

# Overview

The EncapController provides two different deactivation methods.

  • Deactivate the registration. 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.

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 onlyLocally parameter is set to false, then the registration is removed both from the Encap server and locally.
  • If the onlyLocally 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

# Deactivate a specified authentication method

  1. Run the deactivateAuth method to deactivate a specific authentication method. The registration will stay intact.
  2. The end-user performs a device authentication.
  3. The specified authentication method (authMethod) is removed both from the Encap server and locally.

Limitations

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

Example: How to deactivate Face ID

# 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

# Handling

When an operation on the EncapController fails, the onError callback will be invoked with an EncapErrorResult.

The EncapErrorResult object describes the cause of the problem, and optionally how the state of the authentication has changed.

The errorCode property uniquely identifies the type of problem. Its value is a value of the EncapError enum, that can be checked using a switch statement. The sample application that comes along with the EncapAPI shows what messages can be displayed to the end-user for the different errors.

The error is described by a technical description, from the technicalDescription property. This can help you to determine what went wrong.

The underlyingError property can also be useful for finding what caused the error. underlyingError is an NSError object is typically generated by the operating system. For example, connection or storage errors with more detailed information. It is only set when an underlying error is available.

The remainingAttempts property is not always set, only when the authentication fails. This property indicates how many more times an end-user may try to perform an authentication before a failure will result in their registration being locked down by the Encap server.

Example: Error handling

switch error.errorCode {
	case EncapError.serverErrorLockedByAdmin:
      message = "The registration was locked down by by admin / customer support"
    @unknown default:
      message = "An unexpected error has occurred"
}

// Example of getting the underlyingError from the EncapErrorResult
if let underlyingError = error.underlyingError {
    Log(underlyingError.code)
    Log(underlyingError.localizedDescription)
}
Last updated: 11/04/2024 07:47 UTC

← Authentication methods →