To proceed with Okay integration using our SaaS platform, you are required to create an account using this link. Once you are successfully signed up, login in with the credentials that you used to create the account here. Once you are logged in to your dashboard, click the Tenants tab on the left navigation bar as shown below.
All the one's and zeros
Integrate Okay app with your service
1.1 Getting Started
The Tenants web page is where you will register your service which will communicate directly with Okay secure servers, initiating authentications and authorising secure transactions. Your tenant page should present a table that is similar to the table below.
Overview of the Tenant table
If you check the tenants’ page, you will see that you already have an entry in the Tenants table. The contents of that row are essential in understanding how to integrate Okay into your server.
The first column under the table is what we refer to as your Tenant ID.
In the image above, my Tenant Id is:
150001
It is crucial that you take note of this value, as we will be using it for our transactions/ authentication.
Name
The text under the Name column in the Tenants table is the name of the company you provided at the time of your sign up.
Status
Specifies the status of your tenant.
Trial Expiration
Shows your tenant trial expiration date, if you are still on trial mode.
Actions
The Action column has two buttons that allow us to manage our tenant credentials.
Adding Credentials to your Tenant
To make our tenant useful, we will be adding more information to the tenant to connect properly/securely to Okay servers. Click on the pencil icon under Actions to complete the tenant registration.
To be able to receive feedback from Okay servers, you will need to add a valid callback URL. This is an endpoint on your server that will be used as a point of communication by Okay to notify your server about the status of transactions/authentication to the Callback input field.
To verify all your requests, we will need to generate a secret secure token (or secret) that will be used to verify all transactions by Okay secure servers. This token acts as an auth token The token could be any alphanumeric secure string that contains about 30 characters (or more) and must always be kept secret.
Note: we will be referring to this Token as secret token in further illustrations.
1.2 Linking Guide
Provide a Unique Value Generator
Before we can authorise transactions using Okay, we need to link our users to Okay. This enables us to identify all unique transactions being initiated by different unique users.
Before we proceed to link users to Okay, we need to generate and store a Unique Identifier for every end-user in order to differentiate all your users. You can use any alpha-numeric character to compose this value, for example, a UUID. We will be using this value in all our requests as User Unique Identifier. This normally serves as value to the "userExternalId" key/property in our payload.
This is a typical structure of our JSON payload for linking users
{ "tenantId": "<your tenant id>", "userExternalId": "User Unique Identifier", "signature": "BASE64[SHA256(tenantId | userExternalId | secret)]" }
The tenantId key in our payload above is the ID we got from our Tenants table. Please refer to the Getting Started section of this documentation if you don't already have your tenant ID.
The userExternalId key in our payload above is the User Unique Identifier you created for your users in order to differentiate them as described in the Provide a Unique Value Generator section of this documentation above.
The signature key in our payload above is a hash that is generated from concatenating your tenantId + userExternalId + secret token (also known as the Token you added to your tenant), then passing the concatenated string as value to SHA256() algorithm. We encode whatever value or string we got from the SHA256() algorithm in BASE64.
const crypto = require('crypto')
const axios = require('axios')
const PSS_BASE_URL = 'https://demostand.okaythis.com';
const tenantId = 150001; // replace with your tenantId
const userExternalId = 'uid406jkt'; // replace with your unique user id
const secret = 'securetoken'; // replace with your secret
const hashStr = `${tenantId}${userExternalId}${secret}`;
const signature = createHashSignature(hashStr);
console.log(signature) // returns zqVmg24iAeAqhKdyFOClJdmaB1NBE4lm4K/xnZUwg7M=
function createHashSignature(hashStr) {
return crypto
.createHash('sha256')
.update(hashStr)
.digest('base64')
}
...
To link a user, we need to send our JSON payload as a POST request to this endpoint below:
https://demostand.okaythis.com/gateway/link
You can see a detailed explanation of the signature generation algorithm on the Signature Generation page.
User Linking Sample Code
const crypto = require('crypto')
const axios = require('axios')
const PSS_BASE_URL = 'https://demostand.okaythis.com';
const tenantId = 150001; // replace with your tenantId
const userExternalId = 'uid406jkt'; // replace with your unique user id
const secret = 'securetoken'; // replace with your secret
const hashStr = `${tenantId}${userExternalId}${secret}`;
const signature = createHashSignature(hashStr);
axios({
method: 'post',
headers: {
'Content-Type': 'application/json'
},
url: `${PSS_BASE_URL}/gateway/link`,
data: {
tenantId,
userExternalId,
signature
}
})
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.log(error.response.data)
});
function createHashSignature(hashStr) {
return crypto
.createHash('sha256')
.update(hashStr)
.digest('base64')
}
When your request is correct you'll get a response with the following body
{ "linkingCode": "unique short-living code", "eg 416966" "linkingQrImg": "base64-encoded image of QR code", "status": { "code": 0, "message": "OK" }, }
Sample Response:
{ "linkingCode": "980565", "linkingQrImg": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABhUlEQVR42u3aQXKDMAwFUGVYsOQIHIWjhaPlKBwhSy8yqLIkm9CUNMae6XTme0XMW8WqLCkl/mTdCQwMDAzsb1ggW0PomIkm2e5W3+vAqpk+8zLwg+xYgjDeXoHVsfidT8JY3s5+Cjz7uYA1Y7KE2SmAtWaPC9OVFyKwlizlkF2QH6casCK23YDKliH8clGCFbC89O31Nt7t7VGZB1bEAl3YcwgpY4321yAHO8UsRcsn8ZKZRw37mKK/lcdgZ5itm+WQHORixh/+FsCKWYxtmnKuHjXs4524PwWwU0w35eKjPtZvwtIpEPUMVs/Iyrb+Odr9AayeWdOhzZ0FudVvqdIAq2J+A3r9Jtu9VxpgTVicSOROWY4j5+pdeQx2iu27j9zTzWkWBFbFcu8cmw4NcvIm+uUGBDvBtqm7VRoW7TYCAqtnPrdM02BfyYO1YpyajtXbELB2TH+Ss9SxHk4wwIrZU11hD7G5ixO2AFbPdlP32NOxNdHvhvNgnzL8Xw0YGBjYP2ZfZfRH9E/qf44AAAAASUVORK5CYII=", "status": { "code": 0, "message": "OK" } }
An end-user needs the linking code to accomplish linking.
When you receive a response from the Okay service, check if it was successful by examining the status object. All valid codes are listed on the Server Response Status Codes page.
The purpose of the linking is explained here.
1.3 Linking With Okay Mobile App
STEPS TO LINKING ON MOBILE APP
After installation, proceed to granting these permissions:
Click the check box on this screen to grant permission, then press the back button twice to return the app:
Grant all permissions:
To proceed with linking, click the white button on this screen below:
You will be redirected to a camera screen. Click the button at the bottom of the camera screen to proceed to the linking screen shown below:
Enter the six digits linkingCode you received from your linking response into the mobile app's input field, then click Link me on the app. In our case, the linkingCode was 980565:
If there were no errors, you will be presented with a similar screen that looks like the one below:
After linking a user, we can now authenticate that user or authorise the user's action.
Just like linking a user, we will be sending a JSON payload as a POST request to Okay using the link below
https://demostand.okaythis.com/gateway/auth
This is a typical structure of our JSON payload for authenticating users/authorizing user actions
{ "tenantId": "<your tenant id>", "userExternalId": "User Unique Identifier", "type": "<Authorization type>", "authParams": { "guiText": "message that is shown in the Okay application", "guiHeader": "header of the message that is shown in the Okay application" }, "signature": "BASE64[SHA256(tenantId | userExternalId | guiHeader | guiText | type | secret)]" }
For this request, we will be adding two new fields, the type and authParams fields.
The type key in our JSON payload is a field that allows us to clearly specify the kind of authorisation/authentication we choose to initiate. The type key can take as value any of these authentication types listed below.
AUTH TYPE | AUTH CODE
--------------------------------
AUTH_CANCEL | 101
AUTH_PIN | 102
AUTH_OK | 103
DEVICE_INFOR | 104
SET_PIN | 105
USER_FORGOT_PIN | 106
BIOMETRIC_OK | 107
FALLBACK | 108
All possible authentication codes/types are listed on the Session Types page.
The authParams just contains a message (guiText) and the message header (guiHeader) that will be displayed on Okay app. The message is intended for the user to read, to approve, or to decline a transaction/authentication request.
We can now send our request to Okay secure server using the sample code below.
const crypto = require('crypto')
const axios = require('axios')
const PSS_BASE_URL = 'https://demostand.okaythis.com';
const tenantId = 40007; // replace with your tenantId
const userExternalId = 'uid406jkt'; // replace with your unique user id
const secret = 'securetoken'; // replace with your secret
const authParams = {
guiText: 'Do you okay this transaction',
guiHeader: 'Authorization requested'
};
const AUTH_TYPES = {
OK: 101,
PIN: 102,
BIOMETRIC_OK: 105,
}
const type = AUTH_TYPES.OK
const hashStr = `${tenantId}${userExternalId}${authParams.guiHeader}${authParams.guiText}${type}${secret}`;
const signature = createHashSignature(hashStr);
axios({
method: 'post',
headers: {
'Content-Type': 'application/json'
},
url: `${PSS_BASE_URL}/gateway/auth`,
data: {
tenantId,
userExternalId,
type,
authParams,
signature
}
})
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.log(error.response.data)
});
function createHashSignature(hashStr) {
return crypto
.createHash('sha256')
.update(hashStr)
.digest('base64')
}
If your request was processed without errors, you'll get a response with the following structure:
{ "status": { "code": "<status code>", "message": "status message" }, "sessionExternalId": "unique session identifier" }
Sample Response:
{ "status": { "code": 0, "message": "OK" }, "sessionExternalId": 100227 }
If a secure communication channel was succcessfully established, Okay presents the authorization screen.
Click the "OKAY" button to grant authorization.
Click "Start Now" on the modal popup shown below to proceed:
If there were no errors processing your confirmation action, Okay will present a success screen like the one below to notify you that your response to the transaction authorisation request was processed successfully.
For better reference to all possible status code and messages you can receive from the Okay server, please refer to this link.
The sessionExternalId can be used to check the status of this request. We will see shortly, in the Check Authentication/Authorisation Status section, how we can use the sessionExternalId value retrieved from the response to check the status of our transaction.
After authorising a transaction or authenticating a user, we can check the status of that request by sending a JSON payload as a POST request to this endpoint:
Note: You may not need to call this endpoint as Okay secure server will send a callback request with the status of your transactions.
https://demostand.okaythis.com/gateway/check
This is a typical structure of our JSON payload for checking the authentication/authorisation status
{
"tenantId": "<your tenant id>",
"sessionExternalId": "Unique session Identifier",
"signature": "BASE64[SHA256(tenantId | userExternalId | secret)]"
}
Send a request to check the status of your transaction (Sample Code)
const crypto = require('crypto')
const axios = require('axios')
const PSS_BASE_URL = 'https://demostand.okaythis.com';
const tenantId = 150001; // replace with your tenantId
const sessionExternalId = 100227; // "replace with your 'sessionExternalId' from previous Auth request
const secret = 'securetoken'; // //replace with your secret
const hashStr = `${tenantId}${sessionExternalId}${secret}`;
const signature = createHashSignature(hashStr);
axios({
method: 'post',
headers: {
'Content-Type': 'application/json'
},
url: `${PSS_BASE_URL}/gateway/check`,
data: {
tenantId,
sessionExternalId,
signature
}
})
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.log(error.response.data)
});
function createHashSignature(hashStr) {
return crypto
.createHash('sha256')
.update(hashStr)
.digest('base64')
}
If your request was processed without errors, you'll get a response with the following body structure:
{
"status": {
"code": "<status code>",
"message": "status message"
},
"authResult": {
"dataType": "<result data type code> eg. 101, 102, 103",
"data": "user response eg. CANCEL, PIN, OK"
}
}
The authResult field may contain any of these values from the table below, as a user response from the mobile app:
AUTH RESULT TYPE | AUTH RESULT CODE
--------------------------------
CANCEL | 101
PIN | 102
OK | 103
Check out the AuthData Types page to see all available values for the dataType.
A detailed explanation can be found here.
1.6 Device Biometric Sensor Check
The Okay secure server allows tenants to check if devices running their application built with Okay SDK has a biometric sensor enabled.
To get this information, you are required to send a POST request to Okay secure server at this endpoint:
https://demostand.okaythis.com/gateway/session
The body of the request should be as shown below:
{
"userExternalId": "<user_external_id>",
"tenantId": "<tenant_id>",
"type": "DEVICE_INFO",
"sessionParams": {
"deviceData": "isBioEnabled"
},
"signature": "<signature_hash>"
}
1.7 Callbacks
When an end-user clicks the Okay(Approve) or Cancel button in Okay Application, the result is sent to an Okay service that links the user device with your identifier for that user. Whenever a user is linked successfully on Okay’s secure server, a callback is sent to your service as a notification.
Some actions might take the user a while to accomplish. To prevent long-lasting requests and overloading the Okay server with an enormous amount of Check Requests, the Okay server sends callbacks when a long-lasting action is completed. The target URI should be configured with the Okay website on the Tenant Settings page.
Note: Every callback has a signature value. It is important to verify this signature value to ensure that the callback data has not been tampered with.
Link User Callback
When an end-user completes linking, the Okay server sends the following JSON data to the callback URL that was specified on the tenant settings page:
{
"status": {
"code": <status code>,
"message": "status message"
},
"type": 101,
"userExternalId": "unique user identifier",
"signature": "callback signature"
}
Authentication (Authorization) Callback
Okay sends this JSON body when a transaction response from the Okay mobile application is received.
The authResult key in the response above has the same structure as the authResult returned from Check Authentication/Authorization Status request.
{
"status": {
"code": <status code>,
"message": "status message"
},
"type": 102,
"userExternalId": "unique user identifier",
"signature": "callback signature"
}
Unlink User Callback
When an end-user removes your service from the list of connected services from Okay (i.e. unlinks your tenant), Okay sends to your server via the callback URL a JSON response having the structure below:
{
"status": {
"code": <status code>,
"message": "status message"
},
"type": 103,
"userExternalId": "unique user identifier",
"signature": "callback signature"
}
Device Biometric Sensor Check Callback
If your request to check if a valid biometric sensor is available on the device running your app was processed successfully, you should receive an invocation of your callback endpoint with a similar JSON object like the one below as the request body.
{
"sessionResult": {
"dataType": "104",
"data": "isBiometryEnabled=1;isApnsEnabled=1;"
},
"userExternalId": "3137",
"sessionExternalId": "180001",
"type": "104",
"status": {
"code": "0",
"message": "OK"
},
"signature":"tMeg677BzEwheevEmv42aHgBtVQX8tBOj+6g+uuBVe0="
}
Every response and callback from Okay secure server contains a status field:
"status": {
"code": <status code>,
"message": "status message"
}
Here is the list of all possible codes:
Attribute | Type | Description
--------------------------------------------------------------------
INCOMPLETE | Const (-1) | Response Status code
SUCCESS | Const (0) | Successful result.
ERROR | Const (101) | Error result
If an error occurs while processing your request, Okay sends one of the following error messages as a message field in the response to your service:
- TenantInactive - Your tenant is not active.
- TenantExpired - Trial period has expired.
- BadApplication - Cannot find an app with the parameters within your request.
- BadLinkingCode - There are no linking records or more than one linking records exist with the linking code within your request.
- TenantLimitsNotDefined - There are no limits for the tenant.
- TenantReachedLimits - Tenant has exceeded limits for the requested type of operation.
- BadTenantSession - There is an active or existing session for the current user.
- TenantSessionNotFound - Could not find a session for the user
- UserNotLinked - The requested user is not linked.
- ProtocolError - Okay server could not decrypt the incoming request.
- NoUniqueLinkingCode - Cannot generate unique linking code within the specified time
- NoPendingLinking - Multiple users are completing linking simultaneously on the same device
- UnknownError - Unknown error
Okay requires certain information to correctly communicate with your service. Navigate to Tenants page and click on the action icon to alter your account settings.
Enter valid values for the following fields then click the update button:
- Name - While mandatory, this setting will have no impact on functionality.
- Callback - This must be filled with the URL that you will be using to handle callbacks from the Okay Service.
- Token - This can be an alphanumeric sequence that is used to create signatures and validate requests. This value must always be kept a secret and secure.
Every request and callback contains the signature field. Its value is based on the secret token that is set on the Okay website on the Tenant Settings page, and the data within the transferring object. As this token is known by you and Okay server only both servers can be sure that the request is received from trusted sender.
Java Developers Notice
You can use com.protectoria.gateway.tenant.signature.SignatureService that is shipped with multi-tenant-gateway-client artifact to generate signatures. Use an example from OkayRestClient.
Structure
To create a signature, concatenate all the fields from the request, response, or callback, and secret token. Then get its binary hash using the SHA-256 algorithm. After that, encode the binary data with Base64 encoding.
How you should generate your signature hash for linking a user
If your tenantId is 10000, userExternalId is "U12," and secret is "hollywood", you will need to calculate the value of BASE64(SHA256("10000U12hollywood")).
This result of the hash would be 2ZCK7nx/Gz2qvFlo/vPLk1H37H6g/IobIOgEJAOvQks=.
How you should generate your signature hash for authorizing user request
BASE64(SHA256(tenantId | userExternalId | guiHeader | guiText | type | secret))
If your tenantId is 12000, userExternalId is AATFR7851, type is 101, guiText is "Have you requested authorization request?", guiHeader is "Secure Service Request", and secret is "password",
You need to calculate the value of BASE64(SHA256('12000AATFR7851Secure Service RequestHave you requested authorization request?101password')).
The result of the hash will be BBtE0ixMwgVZ2U0XZCBGpGffwfQgu4S0ler0Ia2kwHQ=.
Link User Callback
BASE64[SHA256(userExternalId | status.code[attribute] | type | secret)]
If your userExternalId is 169U, status.code attribute is SUCCESS(the status.code result was 0 in the example but we use the Attribute value which in this case is SUCCESS from Response Status section below), type is 101, and secret is madonna, you need to calculate the value of BASE64[SHA256('169USUCCESS101madonna')]. The result of the hash will be W0mQ8vDb7Tm1AeFv8NDinnEgg8+rtvPEr6Dd8YsGBRY=.
Authentication (Authorization) Callback
BASE64[SHA256(userExternalId | sessionExternalId | status.code[attribute] | type | data | dataType | secret)]
Unlink User Callback
BASE64[SHA256(userExternalId | status.code[attribute] | type | secret)]
There are additional request types that allows your server to check transaction status at the time of execution.
5.1 Response Status
Every response from Okay contains a status. The table below represents the fields/attributes that are returned from Okay response to your server.
The structure of the status field in JSON format
"status": { "code": <status code>, "message": "status message" }
Response Status
Attribute | Type | Description -------------------------------------------------------------------- code | returns Response Status Code | Response Status code (see Response Status table below) message | String | Response Message
Response Status Codes
Attribute | Type | Description -------------------------------------------------------------------- INCOMPLETE | Const (-1) | Response Status code SUCCESS | Const (0) | Successful result. ERROR | Const (101) | Error result
Error messages associated with Response Status
Message | Description
--------------------------------------------------------------------
BadTenant | Requested Tenant does not exist
UnsupportedInstallation | Installation not supported. Application should start force update scenario.
BadApplication | App does not exist or must not exist on current step
NoActiveSession | Active Session is not found
BadSession | Session does not exist, There multiple suitable Sessions, Session must not exist on current step
SessionIncomplete | Previous Session is incomplete
SessionExpired | Timeout
CodeBlockError | Facing problems with CodeBlock generation
CodeBlockGenerationTimeout | Was not able to generate CodeBlock is specified time
CryptographyError | Key generation error
TextToSpeechError | TTS service is broken
WatermarkError | Cannot decode watermark
PushNotificationError | Problems with third-party push notification service
VoipError | Problems with third-party VoIP service
CallNoAnswer | The call was originated but no one answered
IntegrityError | Critical error while processing integrity checks
ProtocolError | Error while encoding/decoding client request/response
LicenseError | Server license is not valid and any client action requests are rejected
5.2 Session Type
The Session Type table represents all authorisation or transaction types that Okay currently support. You can review the getting started guide to see how we used AUTH_OK in our demo for authorisation.
Types
Attribute | Type | Description
-------------------------------------------------------------
AUTH_OK | 101 | OK button authorization session
AUTH_PIN | 102 | PIN authorization session
AUTH_BIOMETRIC_OK | 105 | Bio-metric confirmation authorization session
Info about Session Types
AUTH_OK - An end-user is asked to accept or deny a request by simply pressing OKAY or CANCEL button in a mobile application. Simple scenario with YES/NO possible answers.
AUTH_PIN - An end-user is asked to enter a pin in a mobile application input field or cancel the authorisation request.
AUTH_BIOMETRIC_OK - An end-user is asked to identify themselves using the biometric solution of their smartphone. When the biometric identification is not supported or disabled the AUTH_PIN is executed instead.
