From 067c2012ad9009f482c97f66307c1dc4678fa159 Mon Sep 17 00:00:00 2001 From: Marek Stransky Date: Fri, 10 Nov 2023 17:08:39 +0100 Subject: [PATCH] Add documentation --- docs/Error-Handling.md | 29 +++++------ docs/Using-Operations-Service.md | 85 ++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 14 deletions(-) diff --git a/docs/Error-Handling.md b/docs/Error-Handling.md index f72b3ca..60dc07a 100644 --- a/docs/Error-Handling.md +++ b/docs/Error-Handling.md @@ -7,17 +7,18 @@ Every `ApiError` consist of: ## Known API Error codes -| Error Code | Description | -|---|---| -|`ERROR_GENERIC`|When unexpected error happened| -|`POWERAUTH_AUTH_FAIL`|General authentication failure (wrong password, wrong activation state, etc...)| -|`INVALID_REQUEST`|Invalid request sent - missing request object in the request| -|`INVALID_ACTIVATION`|Activation is not valid (it is different from configured activation)| -|`PUSH_REGISTRATION_FAILED`|Error code for a situation when registration to push notification fails| -|`OPERATION_ALREADY_FINISHED`|Operation is already finished| -|`OPERATION_ALREADY_FAILED`|Operation is already failed| -|`OPERATION_ALREADY_CANCELED`|Operation is canceled| -|`OPERATION_EXPIRED`|Operation is expired| -|`ERR_AUTHENTICATION`|Error in case that PowerAuth authentication fails| -|`ERR_SECURE_VAULT`|Error during secure vault unlocking| -|`ERR_ENCRYPTION`|Returned in case encryption or decryption fails| +| Error Code | Description | +|------------------------------|---| +| `ERROR_GENERIC` |When unexpected error happened| +| `POWERAUTH_AUTH_FAIL` |General authentication failure (wrong password, wrong activation state, etc...)| +| `INVALID_REQUEST` |Invalid request sent - missing request object in the request| +| `INVALID_ACTIVATION` |Activation is not valid (it is different from configured activation)| +| `PUSH_REGISTRATION_FAILED` |Error code for a situation when registration to push notification fails| +| `OPERATION_ALREADY_FINISHED` |Operation is already finished| +| `OPERATION_ALREADY_FAILED` |Operation is already failed| +| `OPERATION_ALREADY_CANCELED` |Operation is canceled| +| `OPERATION_EXPIRED` |Operation is expired| +| `OPERATION_FAILED` |Default operation action failure| +| `ERR_AUTHENTICATION` |Error in case that PowerAuth authentication fails| +| `ERR_SECURE_VAULT` |Error during secure vault unlocking| +| `ERR_ENCRYPTION` |Returned in case encryption or decryption fails| diff --git a/docs/Using-Operations-Service.md b/docs/Using-Operations-Service.md index 6c5c774..0f7fbd3 100644 --- a/docs/Using-Operations-Service.md +++ b/docs/Using-Operations-Service.md @@ -11,6 +11,7 @@ - [Operations API Reference](#operations-api-reference) - [UserOperation](#useroperation) - [Creating a Custom Operation](#creating-a-custom-operation) +- [TOTP ProximityCheck](#totp-proximitycheck) ## Introduction @@ -407,6 +408,9 @@ class UserOperation: IOperation { // Accompanying information about the operation additional UI which should be presented such as // Pre-Approval Screen or Post-Approval Screen val ui: OperationUIData? + + // Proximity Check Data to be passed when OTP is handed to the app + var proximityCheck: ProximityCheck? = null } ``` @@ -439,6 +443,61 @@ Attributes types: - `IMAGE` image row - `UNKNOWN` fallback option when unknown attribute type is passed. Such attribute only contains the label. +Definition of `OperationUIData`: + +```kotlin +class OperationUIData: Codable { + /// Confirm and Reject buttons should be flipped both in position and style + val flipButtons: Boolean? + + /// Block approval when on call (for example when on a phone or Skype call) + val blockApprovalOnCall: Boolean? + + /// UI for pre-approval operation screen + val preApprovalScreen: PreApprovalScreen? + + /// UI for post-approval operation screen + /// + /// Type of PostApprovalScreen is presented with different classes (Starting with `PostApprovalScreen*`) + val postApprovalScreen: PostApprovalScreen? +} +``` + +PreApprovalScreen types: + +- `WARNING` +- `INFO` +- `QR_SCAN` this type indicates that the `ProximityCheck` must be used for authorization +- `UNKNOWN` + +PostApprovalScreen types: +`PostApprovalScreen*` classes commonly contain `heading` and `message` and different payload data + +- `REVIEW` provides an array of operations attributes with data: type, id, label, and note +- `REDIRECT` providing text for button, countdown, and redirection URL +- `GENERIC` may contain any object + +Definition of `ProximityCheckData`: + +```kotlin +class ProximityCheck: Codable { + + /// Tha actual Time-based one time password + val totp: String + + /// Type of the Proximity check + val type: ProximityCheckType + + /// Timestamp when the operation was scanned (QR Code) or delivered to the device (Deeplink) + val timestampRequested: ZonedDateTime = ZonedDateTime.now() +} +``` + +ProximityCheckType types: + +- `QR_CODE` TOTP was scanned from QR code +- `DEEPLINK` TOTP was delivered to the app via Deeplink + ## Creating a Custom Operation In some specific scenarios, you might need to approve or reject an operation that you received through a different channel than `getOperations`. In such cases, you can implement the `IOperation` interface in your custom class and then feed created objects to both `authorizeOperation` and `rejectOperation` methods. @@ -461,5 +520,31 @@ interface IOperation { * Data for signing */ val data: String + + /** + * Additional information with proximity check data + */ + var proximityCheck: ProximityCheck? } ``` + +## TOTP ProximityCheck + +Two-Factor Authentication (2FA) using Time-Based One-Time Passwords (TOTP) in the Operations Service is facilitated through the use of ProximityCheck. This allows secure approval of operations through QR code scanning or deeplink handling. + +- QR Code Flow: + +When the `UserOperation` contains a `PreApprovalScreen.QR_SCAN`, the app should open the camera to scan the QR code before confirming the operation. Use the camera to scan the QR code containing the necessary data payload for the operation. + +- Deeplink Flow: + +When the app is launched via a deeplink, preserve the data from the deeplink and extract the relevant data. When operations are loaded compare the operation ID from the deeplink data to the operations within the app to find a match. + +- Assign TOTP and Type to the Operation + Once the QR code is scanned or match from the deeplink is found, create a `WMTProximityCheck` with: + - `totp`: The actual Time-Based One-Time Password. + - `type`: Set to `ProximityCheckType.QR_CODE` or `ProximityCheckType.DEEPLINK`. + - `timestampRequested`: The timestamp when the QR code was scanned (by default, it is created as the current timestamp when the object is instantiated). + +- Authorizing the ProximityCheck + When authorizing, the SDK will by default add `timestampSigned` to the `ProximityCheck` object. This timestamp indicates when the operation was signed.