Core operations

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. You must:

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 input with the toUIKeyboardType method.

Although this call is optional, it 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 StartActivationResult object is returned as the successResult. This contains authMethodsForActivation, which is a set of authentication methods (AuthMethod) 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 AuthMethod.pin, 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 pinCodeType.toUIKeyboardType() 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 pinCodeType.isValidFor(string: "") method. The SDK 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 (AuthMethod.device) 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

EncapController.shared.startActivation(withCode: activationCode) { startResult in
    switch startResult {
    case .success(let activationResponse):
            
        EncapController.shared.finishActivation(withAuthMethod: .faceID) { finishResult in
              switch finishResult {
              case .success(let finishActivationResponse):
                  // Success
              case .failure(let error):
                  // Error
              }
        }  
        
    case .failure(let error):
       // Error
    }
}

Note

AuthMethod.device will always be activated when activating a two-factor authentication method such as pin, touchID and faceID.

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().get()
} 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.
   About the clientOnly parameter

   • 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 StartAuthenticationResult object is returned in the .success case. This object has the following properties:

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 FinishAuthenticationResult object is returned in the .success case.
3. Your app's UI can use this object to determine how to proceed after the authentication has been completed.
   • Similar to the ActivateResult, this result provides a responseType and contextContent property.

Example: How to authenticate with Face ID

EncapController.shared.startAuthentication(clientOnly: false) { startResult in
    switch startResult {
    case .success(let startAuthResponse):
        
        EncapController.shared.finishAuthentication(withAuthMethod: .faceID) { finishResult in
            switch finishResult {
            case .success(let finishAuthResponse):
                // Success
            case .failure(let error):
                // Error
            }
        }
        
    case .failure(let error):
        // Error
    }
})

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 startAddOrUpdate.
3. If the operation is successful, finishAddOrUpdate 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 finishAddOrUpdate with the AuthMethod for the authentication method that you want to activate. For example, this could be AuthMethod.strongTouchID, and then authorise this operation with PIN.
   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.

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

About implementation

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

EncapController.shared.startAddOrUpdate { startResult in
    switch startResult {
    case .success(let startAddOrUpdateResponse):
        EncapController.shared.finishAddOrUpdate(authMethodToActivate: .faceID, authMethodToAuthenticate: .pin(value: pincode)) { finishResult in
            switch finishResult {
            case .success(let finishAddOrUpdateResponse):
                // Success
            case .failure(let error)
                // Error
            }
        }
    case .failure(let error):
        // Error
    }
}

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

EncapController.shared.deactivate(onlyLocally: false) { result in
    switch result {
    case .success:
        // Success
    case.failure(let error):
        // Error
    }
}

Deactivate a specified authentication method

1. Run the deactivate method and pass the authMethod 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 (AuthMethod.device) is used for authentication towards the server, and cannot be deactivated by this method.

Example: How to deactivate Face ID

EncapController.shared.deactivate(authMethod: .faceID) { result in
    switch result {
    case .success:
        // Success
    case .failure(let error):
        // Error
    }
})

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

EncapController.shared.cancelSession { cancelResult in
    switch cancelResult {
    case .success:
        // Success
    case .failure(let error):
        // Error
    }
})