PowerAuth Networking JS SDK
Wultra PowerAuth Networking (WPN) is a high-level SDK built on top of our PowerAuth Mobile JS SDK that enables request signing and encryption.
[!NOTE] We currently support REACT NATIVE and APACHE CORDOVA development platforms.
You can imagine the purpose of this SDK as an HTTP layer (client) that enables request signing and encryption via PowerAuth SDK based on its recommended implementation.
Documentation Content
- SDK Integration
- Open Source Code
- Initialization and Configuration
- Endpoint Definition
- Creating an HTTP request
- Error Handling
- Language Configuration
- Logging
- Changelog
SDK Integration
Requirements
- React Native (0.73+) or Apache Cordova (>=12.0.0)
- PowerAuth Mobile JS SDK needs to be implemented in your project
PowerAuth JS SDK Dependency
The PowerAuth JS SDK is a required peer dependency of the SDK. You must install it in a compatible version.
Defining it as a peer dependency ensures that only a single instance of the PowerAuth SDK is used in your project, preventing issues with multiple npm clones.
- For React Native, install both
react-native-powerauth-mobile-sdk
andreact-native-powerauth-networking
usingnpm
oryarn
. - For Cordova, add
cordova-powerauth-networking
using thecordova plugin add
command. Thecordova-powerauth-mobile-sdk
will be automatically installed as a dependency.
Compatible PowerAuth Mobile JS SDK Versions
WPN Version | PowerAuth JS SDK |
---|---|
1.0.x |
^4.1.0 |
React Native Installation
Supported Platforms
The library is available for the following React Native (0.73+) platforms:
- Android 5.0 (API 21) and newer
- iOS 13.4 and newer
How To Install
1. Install packages via npm
# if not added yet, add powerauth mobile SDK first (compatible versions are at the top of this document)
npm i react-native-powerauth-mobile-sdk --save
npm i react-native-powerauth-networking --save
2. Install pods for iOS (if needed)
To make integration work with iOS, you might need to install Pods (needed for PowerAuth):
cd ios
pod install
Cordova Installation
Supported Platforms
The library is available for the following Apache Cordova (>=12.0.0) platforms:
- Android 7.0 (API 24) and newer (cordova-android version >=12.0.0)
- iOS 11.0 and newer (cordova-ios version >=7.0.0)
How To Install
1. Install plugin via the Cordova plugin installer
cordova plugin add cordova-powerauth-networking
2. Install pods for iOS (if needed)
To make integration work with iOS, you might need to install Pods (needed for PowerAuth):
cd platforms/ios
pod install
Open Source Code
The code of the library is open source, and you can freely browse it in our GitHub at https://github.com/wultra/networking-js
Initialization and Configuration
Everything you need is packed inside the single WPNNetworking
class that provides all the necessary APIs for your networking.
To successfully create an instance of the service, you need only 2 things:
- configured
PowerAuthSDK
object - configuration of the service (like endpoints base URL)
You can create as many instances of the class as you need for your usage.
Example:
let pa: PowerAuth = ... // your PowerAuthSDK instance
let baseURL = "https://my.backend.com/api/v3" // whene undefined, powerauth url will be used
const networking = new WPNNetworking(pa, baseURL)
Endpoint Definition
Each endpoint you will target with your project must be defined for the service as a WPNEndpoint
instance. There are several types of endpoints based on the PowerAuth signature that is required.
End To End Encryption
If the endpoint is end-to-end encrypted, you need to configure it accordingly. Default values are set to NOT_ENCRYPTED
.
Possible values are:
/** Configuration for end-to-end encryption. */
export enum WPNE2EEConfiguration {
/** Endpoint is encrypted with the application scope. */
APPLICATION_SCOPE,
/** Endpoint is encrypted with the activation scope. */
ACTIVATION_SCOPE,
/** Endpoint is not encrypted. */
NOT_ENCRYPTED
}
Whether an endpoint is encrypted or not is based on its backend definition.
Signed endpoint WPNEndpoint.signed()
For endpoints that are signed by a PowerAuth signature and can be end-to-end encrypted.
Example:
// signed endpoint with expected response data, not response config and end-to-end encryption disabled
const mySignedEndpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.signed("/path/to/the/signed/endpoint", "endpoint/identifier", undefined, WPNE2EEConfiguration.NOT_ENCRYPTED)
Signed endpoint with Token WPNEndpoint.signedWithToken()
For endpoints that are signed by token by PowerAuth signature and can be end-to-end encrypted.
More info for token-based authentication can be found here
Example:
// signed endpoint with token-based authentication with expected response data, not response config and end-to-end encryption disabled
const myTokenSignedEndpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.signedWithToken("/path/to/the/signed/endpoint", "tokenName", undefined, WPNE2EEConfiguration.NOT_ENCRYPTED)
// tokenName is the name of the token as stored in the PowerAuthSDK
// more info can be found in the PowerAuthSDK documentation
// https://github.com/wultra/powerauth-mobile-sdk/blob/develop/docs/PowerAuth-SDK-for-iOS.md#token-based-authentication
Basic endpoint (not signed) WPNEndpoint.unsigned
For endpoints that are not signed by PowerAuth signature but can be end-to-end encrypted.
Example:
// unsigned endpoint with expected response data, not response config and end-to-end encryption set to application scope
const myTokenSignedEndpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.unsigned("/path/to/the/signed/endpoint", undefined, WPNE2EEConfiguration.APPLICATION_SCOPE)
Creating an HTTP request
To create an HTTP request to your endpoint, you need to call the WPNNetworking.call
method with the following parameters:
endpoint
- an endpoint that will be calledrequestData
- request data that will be sent to the serverauthentication
-PowerAuthAuthentication
instance that will sign the request (if needed)- pass
undefined
for the basicunsigned
endpoint
- pass
requestProcessor
- optional request processor that can modify the request before it is sent to the server
The method is asynchronous and returns a Promise
with the response or an error.
Example:
// payload we will send to the server
interface MyRequest {
userID: string
}
// response of the server
interface MyResponse {
name: string
email: string
}
// endpoint configuration
const endpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.signed("/path/to/the/signed/endpoint", "endpoint/identifier", undefined, WPNE2EEConfiguration.ACTIVATION_SCOPE)
// Authentication (for example purposes) expect user PIN 1111
const auth = PowerAuthAuthentication.password("1111")
// WPNNetworkingService instance call
const response = await networking.call(
// specify endpoint
endpoint,
// specify request data
{ userID: "12345" },
// specify authentication
auth
)
if (response.status == "OK" && response.responseObject) {
// success, use response.responseObject
console.log(`User name is ${response.responseObject.name} and email is ${response.responseObject.email}`)
} else {
// error, use response.error
console.error(`Error: ${response.error}`)
}
We use fetch
under the hood.
Server Errors
When a server returns an error, the WPNResponse
object will contain the error information in the responseError
property. The status
property will be set to "ERROR"
.
The responseError
object will contain a code and a message that can be used to identify the error.
This is a known server codes:
Enum Value | Description |
---|---|
GenericError |
Generic error without specific reason |
AuthenticationFailure |
General authentication failure (wrong password, wrong activation state, etc…) |
InvalidRequest |
Invalid request sent - missing request object in request |
InvalidActivation |
Activation is not valid (it is different from configured activation) |
InvalidApplication |
Invalid application identifier is attempted for operation manipulation |
InvalidOperation |
Invalid operation identifier is attempted for operation manipulation |
ActivationError |
Error during activation |
AuthenticationError |
Error in case that PowerAuth authentication fails |
SecureVaultError |
Error during secure vault unlocking |
EncryptionError |
Returned in case encryption or decryption fails |
PushRegistrationFailed |
Failed to register push notifications |
OperationAlreadyFinished |
Operation is already finished |
OperationAlreadyFailed |
Operation is already failed |
OperationAlreadyCancelled |
Operation is cancelled |
OperationExpired |
Operation is expired |
OperationFailed |
Operation authorization failed |
ActivationCodeFailed |
Unable to fetch activation code |
Language Configuration
Before using any methods from this SDK that call the backend, a proper language should be set. A properly translated content is served based on this configuration. The property that stores language settings does not persist. You need to set acceptLanguage
every time that the application boots.
Note: Content language capabilities are limited by the implementation of the server - it must support the provided language.
Format
The default value is always en
. With other languages, we use values compliant with standard RFC Accept-Language.
Logging
You can set up logging for the library using the WPNLoggerConfig
class.
Verbosity Level
You can limit the amount of logged information via the verbosity
property.
Level | Description |
---|---|
NONE |
Silences all logs. |
ERROR |
Only errors will be logged. |
WARN (default) |
Errors and warnings will be logged. |
INFO |
Error, warning and info messages will be logged. |
VERBOSE |
All but debug messages will be printed into the console. |
DEBUG |
All messages will be logged. |
Log Time
You can enable or disable time logging via the includeTime
property. The default value is true
.
Logger Listener
In case you want to process logs on your own (for example log into a file or some cloud service), you can set WPNLoggerConfig.listener
.
Changelog
1.0.0
- Initial release