Skip to main content

Offline authentication

About offline authentication​

Our offline authentication feature makes it possible to do PSD2-compliant authentications with mobile devices that are not connected to the internet. This gives you the ability to use Encap to generate one-time-codes for your authentication transactions.

Offline authentication methods can be activated as a 2-factor method using PIN or biometrics.

Example use case​

With authentication, you could allow your end-user's offline phone to authenticate to a web portal or a terminal connected to the internet, using a QR code to transfer transaction data to the mobile device.

Using this data, the device generates a one-time-code linked to the transaction data for the user to type into the web portal/terminal, to finalise a secure and PSD2 compliant authentication.

Diagram showing offline authentication use case

Diagram showing offline authentication use case

Integration​

The following needs to be modified in order to use this feature:

  • Server configuration
  • Service provider server integration
  • App SDK integration

Server configuration​

The service provider needs to configure their application configuration with the following properties to use the new offline authentication methods.

Allowed authentication methods​

The ALLOWED_AUTH_METHODS property needs to include the desired offline methods from the following list of methods:

  • OFFLINE
  • OFFLINE:PIN
  • OFFLINE:STRONG_TOUCH_ID
  • OFFLINE:IOS_FACE_ID
  • OFFLINE:ANDROID_FINGERPRINT
  • OFFLINE:ANDROID_BIOMETRIC_PROMPT

At least one of these methods are required for offline authentication to work.

Offline OTP length​

The length of the OTP must be set; it needs to be between 4 and 9. This is done by specifying the OFFLINE_OTP_LENGTH property in the same application configuration.

Service provider server integration​

The service provider needs to integrate the backend solution with the offline authentication REST APIs provided by the Encap server.

The available offline authentication REST methods are:

  • Begin offline authentication
  • Verify offline authentication
  • Cancel offline authentication
  • Get status for offline authentication
Note

For details about these methods, see the Encap API reference documentation.

App SDK integration​

The mobile app can be integrated with the offline authentication API provided in the Android & iOS SDK using the following flow:

  1. Scan the QR code. Let verificationData be the QR code scan result.
  2. Call startOfflineAuthentication(verificationData), returning StartOfflineAuthenticationResult.
  3. Display the context from StartOfflineAuthenticationResult to the end-user.
  4. Prompt the end-user for user input as required by the authMethod.
    1. If OFFLINE_DEVICE, then no end-user input is required.
    2. If OFFLINE_PIN, then prompt the end-user for PIN.
    3. If biometrics, then the Encap API will set up for biometric authentication.
  5. Call finishOfflineAuthentication() to let the end-user authenticate, using the AuthMethod/AuthParameter from StartOfflineAuthenticationResult.
  6. Display the oneTimePassword from FinishOfflineAuthenticationResult to the end-user.

Technical feature description​

There are several actors involved in an offline authentication use case. The mobile device with the application and embedded SDK do not need a network connection for this scenario.

The online terminal and all backend systems need to have a network connection to support the offline authentication data-flow.

Prerequisites​

To perform an offline authentication:

  • The end-user needs to have an enrolled device.
  • The end-user needs to activate a new offline authentication method on the device, using an existing two-factor authentication method (while the device is online).
  • Offline authentication methods must be activated after the initial enrolment request, in the same way as activating additional authentication methods.

Perform offline authentication​

The sequence diagram below shows the data flow for an offline authentication session.

The the device never communicates with the Encap server directly. Instead, it transfers all data through offline channels such as a QR code reader.

Sequence diagram showing data flow for an offline authentication session

Sequence diagram showing data flow for an offline authentication session

List of involved actors​

The following actors are involved in the authentication flow:

  • Service provider: The entity offering the authentication service including mobile apps.
  • Online terminal: The terminal that has a network connection to the service provider backend, and hence the Encap server. For example, this could be a PC connected through wired internet.
  • Encap server: The entity responsible for generating offline verification data and validating the authentication using the OTP from the client.
  • End-user: The end-user performing then offline authentication.
  • Application: The client application on the iOS/Android mobile device provided by the service-provider integrating the Encap SDK.
  • Encap SDK: The client SDK for iOS/Android that generates the OTP from the verification data provided by the Encap server.

Diagram steps 1-6​

Begin the offline authentication session.

  1. The offline authentication is initiated on the online terminal by the end-user.
  2. The online terminal calls the service provider, which triggers a begin offline authentication service provider call to the Encap server. This call must include:
    • The context of the transaction.
    • The specific offline authentication method.
    • The device ID.
  3. The server creates a session and generates verification data. This is a string containing encoded data that is needed for the Encap SDK on the mobile device to generate the OTP.

Steps 7-17​

Present the QR code to the device and calculate the OTP.

  1. The online terminal displays the offline verification data, typically as a QR code, from the Encap server.
    • The exact nature of how this is done is up to the service provider, but the solution is designed for the verification data to fit inside a version 10 QR code with medium error correction.
  2. If a QR code is used, then the app will use the camera to read the verification data and pass it to the SDK.
  3. The SDK then uses the authentication method selected in the verification data, prompts for PIN or biometrics if needed, and generates the OTP (one time pass code). This is displayed in the app.
Note

Due to capacity limitations in QR codes, the context of the transaction is limited to a UTF-8 encoded string of maximum 200 bytes.

The total length of the string in chars variable depending on how many region-specific and special characters it contains.

Steps 18-25​

Verify authentication sessions.

  1. The end-user then enters the OTP code displayed by the client device application into the online terminal.
  2. The terminal sends the OTP to the Encap server, using the verify function for the offline authentication REST API.
  3. The server responds with whether the authentication was a success or a failure.
Limit on allowed attempts for same authentication method

There is a limit on how many attempts are allowed for the same authentication method.

  • This limit is the same as the number of PIN attempts in an ordinary online authentication.
  • This is configurable in the application configuration.
  • The number of failed attempts carries over between sessions. This means that beginning a new session will not reset the number of remaining attempts. However, a successful authentication will reset this.

Check offline authentication status​

The REST API allows you to check the status of the offline authentication session.

Cancel offline authentication​

The REST API allows you to cancel the offline authentication session.

Locking offline methods​

A locked online authentication method will result in the entire device being locked. This means that if the end-user enters the wrong PIN three times when authenticating online, you will not be able to use fingerprint or any other method to perform an authentication.

However, for offline authentication, the threshold for doing malicious attempts is considerably lower than for online. Therefore, a locked offline authentication method will only lock that specific method. This means that if the end-user enters the wrong OTP more than three times in a row, they are still able to authenticate using online methods, or other offline methods.

To accommodate locking and unlocking of specific offline methods, we have introduced a new locking API for individual authentication methods. You can read more about this in the Encap API reference documentation.

Additional information​

The PINs for OFFLINE:PIN and DEVICE:PIN are separate, and they will have separate remaining attempts counters. There is no user restriction for setting the same PIN for both.

The OFFLINE authentication method in in the Encap server application configuration has a name deviation from the APIs. For the APIs, this method corresponds to AuthMethod OFFLINE_DEVICE in the client APIs for both the mobile SDK and the server REST APIs

Security considerations​

Because of the nature of offline authentication, there is no salt key rotation and hence no built in clone detection. Risk parameters (RiskParameters) are also not available for offline authentication.

Testing​

Prerequisites​

  • You must have an activated device in Encap.
  • It must have activated an offline authentication method (through auth and activate in the test app).
  • You must be familiar with using the Postman collection found on the Example Postman collection page, and you must have configured your test environment.
  1. Activate an offline authentication method on the device.
  2. Post a Start offline authentication call to the Encap server through Postman. Make sure to substitute the {device_id} in the request body with your actual device ID.
  3. Use any generic QR code generator to generate a QR code from the verification_data string from the response.
  4. On the test application on your device, start the offline authentication. You may need to enable offline authentication in the settings for this option to appear.
  5. Proceed to Finish offline authentication on the device. Use the authentication method specified. This will trigger a prompt, showing you a one time password.
  6. In the Postman collection, do a Verify offline authentication. Ensure that you substitute the OTP in the body with the OTP from your device, and UUID in the URL with the ID field from the previous call.
  7. If everything is configured correctly, this should result in a successful authentication.
Last updated:
On this page