New APIs are created for Swift users of the iOS SDK. For more details, refer to the Xcode API documentation on OnlineActivationParameters and OnlineActivationDelegate.
The activation process must be initiated by calling the startActivation method of the Orchestrator object.
An OnlineActivationParams object must be provided as an input parameter of the startActivation method, and this OnlineActivationParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- Activation password. Secret data shared between the Customer Application Server and the user.
- (OPTIONAL) Cryptographic Application Index. The index of the cryptographic application that must be used to sign the instance activation message. The default value is 1.
- An object implementing the OnlineActivationCallback interface.
The OnlineActivationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the activation process. It exposes the following methods:
- onActivationStepComplete. Called upon activation step success, the provided command must be sent to the server.
- onActivationSuccess. Called upon activation process success.
- onActivationInputError. Called upon activation process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
- onActivationAborted. Called when the activation process is canceled.
For more information about this feature, see Activation.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on NotificationRegistrationParameters and NotificationRegistrationDelegate.
The Customer Mobile Application can initialize a notification registration process by calling the startNotificationRegistration method of the Orchestrator object.
A NotificationRegistrationParams object must be provided as an input parameter of the startNotificationRegistration method; this NotificationRegistrationParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- Notification identifier. Uniquely identifies an app on a given device in the context of push-notification-based authentication. Defined by the notification service (i.e. Apple or Google).
- An object implementing the NotificationRegistrationCallback interface.
The NotificationRegistrationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the notification registration process. It exposes the following methods:
- onNotificationRegistrationStepComplete: Called when a step of the notification registration process is complete. The provided orchestration command must be sent to the server.
- onNotificationRegistrationSuccess: Called upon successful notification registration.
For more information about this feature, see Notification registration.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on RemoteAuthenticationDelegate.
The Customer Mobile Application must call the setRemoteAuthenticationCallback method and provide an implementation of the RemoteAuthenticationCallback interface to process a remote authentication flow.
The RemoteAuthenticationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the remote authentication process. It exposes the following methods:
- onRemoteAuthenticationDisplayData. Called when the Orchestration SDK needs the RemoteAuthenticationCallback interface implementation to display data for approval by the user.
- The Customer Mobile Application must call the onDataApproved method of the DisplayDataCaller object if the user approves the authentication request.
- The Customer Mobile Application must call the onDataRejected method of the DisplayDataCaller object if the user rejects the authentication request.
- onRemoteAuthenticationStepComplete. Called when a step of the remote authentication process is complete. The provided orchestration command must be sent to the server.
- onRemoteAuthenticationSuccess. Called upon remote authentication success. It can also be called to notify the Customer Mobile Application that the rejected request has been taken into account by the Customer Application Server.
- onRemoteAuthenticationSessionOutdated. Called when the remote authentication session is outdated (expired, already approved, or already rejected).
- onRemoteAuthenticationAborted. Called when remote authentication is canceled.
- onRemoteAuthenticationPasswordError. Called upon remote authentication process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
For more information about this feature, see Remote authentication.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on RemoteTransactionDelegate.
The Customer Mobile Application must call the setRemoteTransactionCallback method and provide an implementation of the RemoteTransactionCallback interface to process a remote transaction flow.
The RemoteTransactionCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the remote transaction process. It exposes the following methods:
- onRemoteTransactionDisplayData. Called when the Orchestration SDK needs the RemoteTransactionCallback interface implementation to display data for approval by the user.
- The Customer Mobile Application must call the onDataApproved method of the DisplayDataCaller object if the user approves the transaction request.
- The Customer Mobile Application must call the onDataRejected method of the DisplayDataCaller object if the user rejects the transaction request.
- onRemoteTransactionStepComplete. Called when a step of the remote transaction process is complete. The provided orchestration command must be sent to the server.
- onRemoteTransactionSuccess. Called upon remote transaction success. It can also be called to notify the Customer Mobile Application that the rejected request has been taken into account by the Customer Application Server.
- onRemoteTransactionSessionOutdated. Called when the remote transaction session is outdated (expired, already approved, or already rejected).
- onRemoteTransactionAborted. Called when remote transaction is canceled.
- onRemoteTransactionPasswordError. Called upon remote transaction process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
For more information about this feature, see Remote transaction.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on LocalAuthenticationParameters and LocalAuthenticationDelegate.
The Customer Mobile Application can initialize a local authentication process by calling the startLocalAuthentication method of the Orchestrator object.
A LocalAuthenticationParams object must be provided as an input parameter of the startLocalAuthentication method; this LocalAuthenticationParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- Cryptographic Application Index. The index of the cryptographic application which must be used to generate the OTP.
- (OPTIONAL) Challenge. A string which can be used to diversify the OTP generation. If the crypto-app index is related to a Challenge/Response application, a challenge parameter must be provided.
- Protection Type. The authentication method which must be used to authenticate the user before the OTP is generated (see Authentication methods for more information).
- An object implementing the LocalAuthenticationCallback interface.
The LocalAuthenticationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the local authentication process. It exposes the following methods:
- onLocalAuthenticationSuccess: Called upon local authentication success. It returns the generated OTP and, depending on the Digipass configuration, a host code (used to authenticate the authentication server on which the OTP has been submitted).
- onLocalAuthenticationAborted: Called when local authentication is canceled.
- onLocalAuthenticationPasswordError: Called upon a local authentication process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
For more information about this feature, see Local authentication.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on LocalTransactionParameters and LocalTransactionDelegate.
The Customer Mobile Application can initialize a local transaction process by calling the startLocalTransaction method of the Orchestrator object.
A LocalTransactionParams object must be provided as an input parameter of the startLocalTransaction method; this LocalTransactionParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- Cryptographic Application Index. The index of the cryptographic application which must be used to generate the signature.
- Data Fields. The transaction data to sign. A list of max. 8 data fields; the length of the data fields is limited to 16 characters.
- Protection Type. The authentication method which must be used to authenticate the user before signing the transaction (see Authentication methods for more information).
The LocalTransactionCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the local transaction process. It exposes the following methods:
- onLocalTransactionSuccess. Called upon local transaction success. It returns the generated signature and, depending on the Digipass configuration, a host code (used to authenticate the authentication server on which the signature has been submitted).
- onLocalTransactionAborted. Called when local transaction is cancelled.
- onLocalTransactionPasswordError. Called upon a local transaction process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
For more information about this feature, see Local transaction.
Customization of integrated authentication
The texts related to the authentication methods can be customized using the keys listed in Virtual keypad - Text customization keys in the configuration files of the Customer Mobile Application (i.e. string.xml for Android and Localizable.strings for iOS).
The color can be customized using the keys listed in Virtual keypad - Color customization keys in the configuration files of the Customer Mobile Application (i.e. color.xml for Android and Localizable.strings for iOS).
The font size can be customized using the keys listed in Virtual keypad - Font size customization keys in the configuration files of the Customer Mobile Application (i.e. dimens.xml for Android and Localizable.strings for iOS).
The other graphical elements are defined differently on iOS and Android.
For iOS, you can define these by customizing the keys listed in Virtual keypad - Graphical elements customization keys for iOS in the configuration files of the Customer Mobile Application (i.e. Localizable.strings).
For Android, the font can be customized by overriding the styles listed in Virtual keypad - Font customization for Android in the configuration files of the Customer Mobile Application (i.e. styles.xml).
For Android, the secure input and the backspace arrow can be customized by overriding the drawable elements listed in Virtual keypad - Drawable element customization for Android in the configuration files of the Customer Mobile Application (i.e. in the drawable folder).
For Android, the Virtual keypad background can be customized in multiple ways:
- by changing its background color, as indicated in the Virtual keypad color table
- by overriding its background image, as indicated in the Virtual keypad drawable table
- by overriding its layout in the configuration files of the Customer Mobile Application (i.e. in the layout folder)
Layout | Description |
---|---|
orch_pinpad_background_layout.xml | Layout of the Virtual keypad background; the background image can be changed by using the android:src key. |
Dark mode support for iOS
In the iOS sample, a file named PinPad.storyboard is available.
This file makes it possible to customize fonts, icon and colors. The Dark mode is managed by declaring named colors in the assets catalog (Assets.xcassets) or by using system colors.
The storyboard will take over the string customization as soon as it is added to the integrating project.
![PinPad.storyboard in XCode PinPad.storyboard in XCode](/sites/default/files/mobile-security-suite.orchestration/Images/Screenshots/Referential/Orchestration_SDK/Auth_Methods_Pin_Storyboard_521x370.png?timestamp=1725759036)
This storyboard contains a lot of links to outlets defined inside the OrchestrationSDK. These links can't be restored if they are removed.
The error you see in the storyboard is perfectly normal and doesn't make the compilation fail.
External user authentication
We also provide an option to override the user authentication. For example instead of displaying the integrated Virtual keypad, you can display your own password authentication.
The Customer Mobile Application must call the setUserAuthenticationCallback method and provide:
- an implementation of the UserAuthenticationCallback interface that will be called when an overridden user authentication is required.
- a list of UserAuthenticationType containing all the user authentication you want to override. For now only the UserAuthenticationType.PASSWORD can be overridden.
The UserAuthenticationCallback interface is used by the Orchestration SDK Client to interact with the Customer Mobile Application during the process of overridding the user authentication. It exposes the following methods:
-
onUserAuthenticationRequired. Called when the Orchestration SDK Client needs the UserAuthenticationCallback object to authenticate the end user.
- The Customer Mobile Application must call the onUserAuthenticationInputSuccess method of the UserAuthenticationInputCallback object if the user is authenticated. An input from the user is expected, it may be used to derive the secret store in the device.
- The Customer Mobile Application must call the onUserAuthenticationInputAborted method of the UserAuthenticationInputCallback object if the user aborts the user authentification.
- onUserAuthenticationInputError. This is called when the Orchestration SDK Client needs to inform the UserAuthenticationCallback method that there is an issue with the input.
For iOS, different names are used: UserAuthenticationCallback is called UserAuthenticationDelegate, and UserAuthenticationInputCallback is called UserAuthenticationInputDelegate.
For more information about this feature, see Authentication methods.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on ChangePasswordParameters and ChangePasswordDelegate.
The Customer Mobile Application can initialize a change password process by calling the startChangePassword method of the Orchestrator object.
A ChangePasswordParams object must be provided as an input parameter of the startChangePassword method.
The ChangePasswordParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- Cryptographic Application Index: The index of the cryptographic application which must be used to generate the OTP.
- An object implementing the ChangePasswordCallback interface.
The ChangePasswordCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the change password process. It exposes the following methods:
- onChangePasswordStepComplete. Called when a step of the change password process is complete. The provided orchestration command must be sent to the server.
- onChangePasswordSuccess. Called upon successful change of the password.
- onChangePasswordAborted. Called when changing the password is cancelled.
- onChangePasswordInputError. Called upon an error in the change password process due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
For more information about this feature, see Change password.
The Customer Mobile Application can initialize user enrollment for authentication via face recognition by calling the enrollFace method of the UserAuthenticationMethodManager object.
The UserAuthenticationMethodManager object must be retrieved using the getUserAuthenticationMethodManager method of the Orchestrator object.
A FaceEnrollmentParams object must be provided as an input parameter of the enrollFace method.
The FaceEnrollmentParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- An object implementing the FaceEnrollmentCallback interface.
The FaceEnrollmentCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the biometric enrollment process. It exposes the following methods:
- onFaceEnrollmentSucceed. Called upon a successful enrollment process.
- onFaceEnrollmentCanceled. Called when the enrollment process is canceled.
- onFaceEnrollmentError. Called upon an enrollment process error. The possible errors are listed in the OrchestrationErrorCodes class.
For more information about this feature, see Features of the Orchestration SDK.
New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on CDDCDataFeeder and CDDCMessageParameters.
Device data collection can be optionally configured with a CDDCParams object. The following parameters can be configured:
- Refresh interval. The interval (in seconds) at which device data is refreshed. Default: 60 seconds.
- Optional device data. The collection of certain device data types (i.e. geolocation, Bluetooth, and Wi-Fi) requires specific permissions. By default, these data types are not collected. For more information about required permissions on Android, see Integrating the Orchestration SDK.
Most of the device data is collected automatically by the Orchestration SDK. Device data which cannot be collected automatically can be provided by the Customer Mobile Application, by using the CDDCDataFeeder object.
The CDDCDataFeeder object must be retrieved using the getCDDCDataFeeder method of the Orchestrator object.
The Orchestrator object provides the getCDDCMessage method to transmit the collected device data to the OneSpan Trusted Identity platform without using an orchestration command.
A CDDCMessageParams object must be provided as an input parameter of the getCDDCMessage method.
The CDDCMessageParams object must be initiated with the following parameters:
- User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
- Encrypted. Indicates whether the data must be encrypted.
- Event Name. A string representing an event related to the collected data. For more information, refer to the Client Device Data Collector SDK Integration Guide.
- Application Data. A JSON string representing additional data to add in the CDDC message. For more information, refer to the Client Device Data Collector SDK Integration Guide.
For more information about this feature, see Device data collection.
The UserManager object provides the following methods:
- getUsers. Lists the activated users.
- isUserActivated. Checks whether the provided user identifier corresponds to an activated user.
- getUserInformation. Retrieves the information related to a specific user.
- deleteUser. Deactivates a specified user.
The UserManager object must be retrieved using the getUserManager method of the Orchestrator object.
For more information about this feature, see Multi-user management.