URL: /nnlgateway/nnl/<tenant_id>/auth Method: POST |
Digipass S3 Authentication Software provides operations under the /nnlgateway/nnl/<tenant_id>/auth endpoint to manage FIDO out-of-band (OOB) user authentication. Although authentication is triggered from a device (usually a desktop browser) that starts OOB authentication, it is actually completed on a second device (usually a cell phone).
The second device sends the requests to initiate OOB authentication and finish OOB authentication. The second device can also cancel the OOB authentication. There are also 2 status operations: one for authentication and the other for cancellation.
The following operations implement OOB with adaptive authentication. Note that you must call INIT_ADAPTIVE before calling INIT_VERIFY:
OOB authentication operation | Called by |
|---|---|
First device | |
Second device | |
Second device | |
Second device | |
First device | |
First device |
The following operations implement OOB authentication without the adaptive flow:
OOB authentication operation | Called by |
|---|---|
First device | |
Second device | |
Second device | |
Second device | |
First device | |
First device |
You can choose one or more of the following mechanisms so the user can authenticate on the second device. This document refers to these mechanisms as OOB mode.
Send a push notification to the second device
Display a QR code on the first device that the user scans via an app on the second device.
Use a custom mechanism that you implemented (Implementing a custom OOB mode is outside the scope of this documentation.)
While push notifications are convenient for end users, there is no guarantee that the end user will receive the push. For example, the user may have disabled push notifications for the app on their device. Or a push notification is sent but fails to reach the user's device due to technical issues. Your client app on either the first or the second device can call LIST_OOB_AUTH to get a list of pending OOB authentications to address these situations. Your app then presents this list to the user so they can complete OOB authentication.
To determine the FIDO policy to use, the API Server does the following:
IF the request contains a value for optionsData.policyType THEN use that to retrieve the FIDO policy name from default_config.app_specified_policies.policy_type_mappings.<policyType>.
As an example, let's use the default_config above. If optionsData.policyType = "QuickAuthPolicy" then the API Server passes the FIDO policy name "AcmeQuickAuth" to the Authentication Server.ELSEIF the REST API operation performs authentication, THEN retrieve the value of default_config.authentication_policy_name.
Using the example above, this is "AcmeAuthentication".ELSEIF the REST API operation performs transaction confirmation, THEN retrieve the value of default_config.transaction_policy_name.
Using the example above, this is "AcmeTransaction".ELSEIF the REST API operation performs 2nd-factor authentication, THEN retrieve the value of default_config.2nd_factor_policy_name.
Using the example above, this is "AcmeSecondFactor".ELSE use the FIDO policy named "default".
To perform OOB authentication, the Authentication Server uses the FIDO authentication policy to determine the valid UAF and FIDO2 authenticators that can be used. For UAF authenticators, the Auth Server refers to the allowed UAF authenticators specified by the FIDO policy and device information to create a list of permitted UAF authenticators from which an end user can select to verify their identity.
For FIDO2 authenticators, the Auth Server compares the authenticator's characteristics to the desired FIDO2 authenticator characteristics specified by the authentication policy. The client uses these as hints to prompt the end user for the authenticator. The Auth Server enforces user verification and attestation preference during FINISH_OOB_AUTH based on the policy configuration.
Refer to Create FIDO Policies to create an authentication policy.
INIT_VERIFY
Called from the first device, this operation initiates the verification process for FIDO OOB authentication methods when you use the Adaptive Authentication flow. You must call INIT_ADAPTIVE before calling INIT_VERIFY.
INIT_VERIFY expects to receive data specific to the method in the method.data request attribute, this is summarized below. For complete details about method.data as it pertains to INIT_VERIFY, see the specific sections for each authentication method under Data Field Contents by Authentication Method.
FIDO OOB: The OOB mechanism to use for authentication (oobMode). You can optionally specify the OOB reference ID (oobRefId). For FIDO OOB using push notifications, you can specify the dynamic, customized authentication prompt (authNotificationText).
Request
Attribute | Description |
|---|---|
operation | Required. The string INIT_VERIFY. |
callerOrigin | Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
id | Optional. The correlation ID, a unique id that ties together different API requests that comprise a FIDO operation, like authentication. An alphanumeric string, maximum 255 characters. No special characters are allowed. If not provided, the Server generates a unique id and returns it. |
locale | Optional. The Server uses locale, in subsequent calls to email OTP and SMS OTP, to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US. |
method | Required. The FIDO authentication method that the Server will use to verify the user. See the description for INIT_VERIFY above. |
optionsData | Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
sessionData | Optional. An object containing the user's session information. See SessionData. If you send sessionData in the request to INIT_ADAPTIVE, you must also include it in the request to INIT_VERIFY. |
sessionData.pushHandle | Optional. Identifies the device that receives a push notification and then initiates a FIDO OOB authentication. |
sessionData.userName | Optional. For an improved FIDO OOB authentication experience, provide the username so it is known up front. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
id | The unique id that correlates different requests comprising an operation. Must be identical to the id returned from INIT_ADAPTIVE. A Base64-URL encoded string. If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown. |
method | Result of method that will be used for verification. Authentication Method. Check the following fields in Method for results:
|
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by INIT_VERIFY. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4005 | OK. Operation in progress. | Request has been created successfully. But the authentication methods are in AWAITING_USER_ACTION so it is in progress. |
4401 | Operation expired | The user can't complete all the methods in the sequence within the time period specified by maxTimeAllowedInSeconds. This attribute is configured in the succeeding rule used for Adaptive Authentication. |
4403 | PolicyVerificationException | One of the following occurred:
|
4404 | Internal Server Error | Internal server error. Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Unacceptable content in request | The mandatory attribute, method, is missing or empty |
4454 | Operation failed. | When the method processing fails with an error code. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/authSample request with FIDO OOB method
{
"operation":"INIT_VERIFY",
"needDetails":2,
"sessionData": {
"userName":"zsmith@noknok.com"
},
"id":"MNx4lXzXVIEg1D0dPOVopg",
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"data":{
"oobRefId":"SE27946",
"authNotificationText":"Hello Mr. Smith, Please sign in",
"oobMode":{
"qr":"true",
"rawData":"true",
"push":"true"
}
}
}
}Sample response For INIT_VERIFY with FIDO OOB method
{
"statusCode":4005,
"id":"MNx4lXzXVIEg1D0dPOVopg",
"additionalInfo":{
"elapsedTime": 38,
"oobRefId":"SE27946"
},
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"state":"PENDING",
"data":{
"modeResult":{
"qrCode":{
"qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC2klEQVR42u2aS3IDIQxEdYO+/y11A0I/4VSF8SKrEQtsx5/xSxUI1GqRxPjPLeNiF7vYxS52sTOwjIhMfwil36Qvcbkf8yPFa4QkGHG5HfOgNX/mt0PzHv4lcfkILOQgewIKPuQ5WBJcx5c94LdHYH7ULFaEM+fCf90hr2OVMo/b98x6F+Pt3IVOFUeVxwptN5ZOF3JkjTtKcvbwdmCfJJ7TECIT3pYz5NIBmEiQsT7OGcxnGe/HSvdQ6UmwAxxlbeHtwJCXZDumVTBr4TNH9GMevwhxEuZSRm+GfiySa665lkHXYK3d0I3ZpkgfhZl54wiz8mrHqpz52zkRYaiYiWtIP4Y3GSZcSCw6rnRcacYMkclefY88shL57xR6sFA5FTLFwqzaopsMdmDsw6jYWgZLFivS3RiL7IS27PmJ4lZFpBtLBk8qe8mr/EoaB2DYT4973pmJ3ShNULRj+CdW2mtPFXGt+41vK6ZqJ+b6E2XEOfJRZVqwgfmcoV3OALMS5UKbMWraKri0PAE/tnasB4v8jPlzJmF53pe+B2MKND22VNgBvEGcgJWyJIclogFy7c295enAbKU4OMk1cr+I1O7G8Cd1gpNudSjA+INsx5wlrhxizG7LvPwWH/VjNYvSaLsULfOZox+jzNqpROW2PYJ3w8MNvo9lXamWAjOapIy2tqIFq2ZaHIEBOdDLWrVjWeeaiIxlx6U3QnkAlpwC04mNsitJGm3WvQfjPNgR5hKl18cnW9fWghFRK42LBwooGsa95enBaHYcZKlEh/L7OGl8HxuxOllWXZxdf07Y2zF8E1HGvdeMrNY6AKu0iep0qveJsqXdWJ3pV+dKKnvZ9evcezHKrhDDKH9g6XlMoQWrTocT/oi1N/NbR9mEDTZj/ZFQmBamdQI26Cjoc0Cc4fEsH+9jZEydCbvero2KTrdjJS3VlgWH1RbrHBrt2P3niotd7GIXu9j52A/tCkObH6CezQAAAABJRU5ErkJggg=="
},
"rawData":"https://localhost:8443/tutorial/auth|a|a2V5aGFuZGxlAAAAAUFOHwxqsSaKOZzNgoZoEaYQFYPUyTfbjjtMJeOjSIRBnWimRnM6A5_dAbWmR7mo-27p_B2GORitEqNAQCjuQwb3ufSndZj_omErnbGKqO7rwbf3FXlIk1q2ou_xoKgPV9bnJD56Tyg-syJ9hxW2UCHo|SE27946|"
}
},
"statusHandle":"chVFAHsKhe5001ahACOXPFptjuui2hqOVqyjn3b_cRg",
"lifetimeMillis":180000
}
}START_OOB_AUTH
Start out-of-band (OOB) authentication from the first device, which is usually a browser. Use this operation when you are not using the adaptive authentication flow. Authentication must be completed on a second device (usually a cell phone) performing the INIT_OOB_AUTH and FINISH_OOB_AUTH operations in order to complete OOB authentication on the initiating device.
Request
Attribute | Description |
|---|---|
| Required. The string START_OOB_AUTH. |
| Optional. Dynamic push notification text sent in the push payload to the second device during OOB. Requires that you assign the value dynamic to oob.auth.notification.text.mode, a tenant property. For instructions on how to set this property, refer to oob.auth.notification.text.mode in Configure Dynamic Authentication Text. |
| Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
| Optional. The correlation ID. An alphanumeric string with a maximum length of 255 characters. No special characters are allowed. Because OOB authentication involves 2 devices, this is a unique identifier that associates the START_OOB_AUTH, INIT_OOB_AUTH, and FINISH_OOB_AUTH operations for the same user. Use id to identify the desired OOB authentication when you call STATUS_OOB_AUTH and CANCEL_OOB_AUTH. If not provided, the Server generates a unique id and returns it in the response. |
| Required. Object with 5 attributes: qr, qrType, webURL, push, and rawdata. To specify the OOB mechanism to use in order to authenticate on the second device, you must provide at least one of oobMode.qr, oobMode.push, or oobMode.rawData. |
| Optional. String. Enter true or false as follows:
|
| Optional. String. Enter true or false as follows:
|
| Optional. String. Directs the Auth Server to generate the specified QR code. One of the values listed below, these are ordered by the size of the QR code they generate, from largest to smallest.
|
| Optional. String. Enter true or false as follows:
|
| Required if oobMode.qrType is either UNIVERSAL_RP_SPECIFIC or UNIVERSAL_ANY_RP. The web page URL that handles OOB authentication. The Server encodes this web page URL in the generated QR code. String. |
| Optional. ID provided by the RP app to retrieve contextual information from the RP server that can be displayed to the app user. This helps maintain continuity when a user is performing a transaction or task. The oobRefId sent in this request is packaged inside the oobData. oobData is incorporated into the QR code displayed by the app running on the first device or sent via a push notification. The app running on the second device accesses oobRefId when it scans the QR code or receives the push. An alphanumeric string, maximum of 512 characters. |
| Optional. An object used to pass additional attributes, such as the transaction text and FIDO policy name, to REST API operations. See OptionsData for a complete description. |
| Optional. An object containing the user's session information. See SessionData. |
| Optional. Identifies the device that receives a push notification and then initiates an OOB authentication. |
| Optional. To perform step-up authentication, assign a valid JWT session token to sessionData.sessionKey. |
| Optional. For an improved authentication experience, provide the username so it is known up front. |
| Optional. Object representing a transaction. |
| Required if the request contains the optionsData.transactionText attribute. Transaction ID provided by your client app to track a transaction. String. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
| The unique id that correlates START_OOB_AUTH, INIT_OOB_AUTH, and FINISH_OOB_AUTH operations for the same user. String. If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown. |
| Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server status of 4000).
Attribute | Description |
|---|---|
| An object containing information returned by the Authentication Server. Contains the 2 attributes listed below. In order for the API Server to return this information,
|
| The amount of time, in milliseconds, to process the request. |
| ID provided by the RP app to retrieve contextual information from the RP server. String. |
| Lifetime of the oobStatusHandle in milliseconds. Long. |
| An object containing the server-generated QR code and/or raw data needed for your custom OOB mode. Has 3 attributes: qrCode.qrImage, push.status, and rawData. |
| Status of the push notification. Integer. Returned if oobMode.push is true. See Push Notification Status Codes below for possible push status code values. |
| The server-generated QR Code. String (Base64-encoded PNG image). Returned if oobMode.qr is true. |
| Raw data to send to the second device when you are using your own mechanism in place of a QR code. String. Returned if oobMode.rawData is true. |
| Uniquely identifies this OOB authentication operation. An alphanumeric string, maximum 4000 characters. Pass oobStatusHandle to STATUS_OOB_AUTH to get this OOB authentication’s status. Any operations using oobStatusHandle must be completed within lifetimeMillis. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by START_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | The authentication request was successfully created. |
4404 | Internal Server Error | Internal server error. Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Payload Exception | An error occurred with one or more of the following attributes:
|
4430 | Invalid userName | Failed to locate the user in the Server. |
4431 | NotificationException | Failed to notify the registered device. |
Push notification status codes
The following are the status codes that the Auth Server returns to report the outcome of its attempt to send a push notification. The push notification status is contained in the modeResult.push.status attribute in the response. For example, a successful push notification status is delivered within the response payload as:
"modeResult":{
"push":{
"status":4000
}
}Push status is independent of the overall status of the response.
Server Status Code | Description | Examples |
|---|---|---|
4000 | PushNotification Success | The Server successfully sent the push to a push notification network, such as APNs or GCM. |
4402 | Security Exception | Push Handle is invalid. Failed to validate pushHandle data. |
4404 | Internal Server Error | Internal server error. Failed to read from process push handle/results. |
4421 | Unknown Credentials | The Server was supposed to send a push but didn't because it doesn't know the device that should receive the push (the device details were not available). |
4451 | PushNotification Exception | The Server was unable to send the push to the push notification network, such as GCM or APNs. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/authSample QR code request
{
"operation": "START_OOB_AUTH",
"id": "sample",
"additionalInfo": {
"oobRefId":"12345"
},
"oobMode": {
"qr": "true"
}
}Sample QR code response
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode": 4000,
"id": "sample",
"lifetimeMillis": 180000,
"additionalInfo": {
"oobRefId": "12345"
},
"oobStatusHandle":"a2V5aGFuZGxlAAAAARsHPdvkDrauL7yzqIrpRghoHhGhIcO0rzhEzmPuJ_yRKowlHGEksj1n7qSze_SLHkIcd-B6vF6LU1peyPH-DwxcpHg2v8ct7ryOzv--9UepW1fU0amaQbEKvBQ",
"modeResult": {
"qrCode": {
"qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC2UlEQVR42u2aS3bbQAwEcYO+/y1xAwRdGDkJ7UVWwSwoy5LFKb6nAfFpgI76l0fGi73Yi73Yi73YHVhGREVWqiqkzD6mnMPrWD97TU02XlIo+pxkZRvLMBT9LhbUO+lN+PANWHNKm7PtK6/3oVuw8k94I+FX2cBXYJA2qKB7WZxYF2Dhy/798UNk/XeMR1/xE9T2Tf25tIn1d+2/bM2wa4b5/qNP1Drm/OevLVIgsY1n1t9uuYL1myOljzn7kaexdKrWMY4n2Y9M48DmpId5V7Bej6H8zN8f9zHKLblG/gApbBv72NQNmxSD+stj4dA+VkgV4rlXqBpO03psYQOzNHHUOJhdOcgzoxDWMUeLYzdH4hEp4cqrXMfsk1SMxDN7H96SMrMuwPzd/RvE8lQOcvYFGLrE8umEjD2hPopgFUtsS+rzTgL6018sY64emDMpbDmOqY8CXcVYpJMQkTJR7X1oHzuCwA5gJaWTDSNzH3PPmvqSUqNXTre4jLlWpI9Z3SHZfdZ3KbWB5em9RPSQATUdmtaxmu6GVsJOQIJGldY+NsFBlOCONYU3H+3YBubUJ6RTYOGYFK1nit7BnAen20EbY9u5+NsYSdk5JjFs0Yfl1JV1LKbuOtuYZdqUNGTrmMcQ1gM2svvXkaT0Z/uYLStmAIw1GdExB9AFGKNMnUbMRiYz6jn5WcAcJOgVapwveJ5UU+sYtjwFl+EJaTrrCsyijgST81rTm3lyvY2NOGZxHOHMmZTax84IUTPkxzljwmgdI5Sd+qi/DBRzJti1jjFmirn1YE1gjUfMPHa6ghVZ0JL9jF5RfBF5AzbDr/oavWLkekqCDeyM+otYcakV4v05mtjBphEjSce44wzYpX1s5F1y+4bmP+Ym2A93x5Ywd//2AFrFkcp1B8Zwn0EYH8cBch87vQS3lZQzPAHRPkbIBJd9sl/OnYmodez954oXe7EXe7EXux/7BUOP2/Rn/TGKAAAAAElFTkSuQmCC"
}
}
}Sample request with user name and rawData=true
You can push a request with a known userName. In the response, you get the rawData and a QR-code image.
{
"operation":"START_OOB_AUTH",
"sessionData":{
"userName":"zsmith@noknok.com"
},
"id":"sample",
"oobRefId":"12345",
"oobMode":{
"qr":"true",
"rawData":"true"
}
}Sample response for user name and rawData=true
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode":4000,
"id":"sample",
"lifetimeMillis":180000,
"additionalInfo":{
"oobRefId":"12345"
},
"oobStatusHandle":"a2V5aGFuZGxlAAAAAtOIzX55EaWZxowB5lIeMHtxFlnc7aU8nv9STVVBpwsPCu3NG1kWMfrVPtRsJGctdlA__HOPEvIuom-0xeTvIBr53hlyX_pqki_sOVjHYChcqkiQlL6eXWGGsTQ",
"modeResult":{
"qrCode":{
"qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC6UlEQVR4Xu2XS24jMQxEdQPe/5a8gaZeqb0wx0CySnkhuuMI0mtA/JXktX9jvebMR7vYsIsNu9iwiw272LCLDXuwXmt17eajmVXVXYzXaz2I6Wkt1qoWr49hpvOYFnuvvYBqm934sb4EwwUt6dliNNdfg23lmeyvVxmsMx3HIFlp8o03+s/Ehwr5c4xtf7DZMgnMVk9patunAs7205j7V72iyBYVQAEUvTM8TWDa/3Y9YlSA3KE4a+cxBZLUa+9aR55xRl4Q8DQm4dMK8T1jBvrS4N3TCMZuUWQlfKOFSjmDR2mymONKZRJjXlFg+X6WsxibPQ81ULTMeqbzGNcBmpoJ7RypeTVMFmNyO/GIIEcJsbX+5DH951aw0b/jDyecfUpjnBqoiq8ARWXiS+NXHGv2vWkacYzg3NPvnmYwrgSvBbe2nViPMkYxLTF5JAc/9JIqEzaO0TKIXrHYbLxQHMo1jlGTbH6Du3GKt/jEMa4phBKRoQo0RqY9F8ZYNoAxWUTXc3GMYvSFxdcAUg9zwDTmWZfmxoVTmTTOh/D+OeaEE00tMHRNepDH2P2TcfyRDw97LIlpkRODweIHrLyxS3zlMZUjAi2YvHMOFy9MRQpgdAob5p8odg+tmI/URzAuA0QVVebSTi/TNcOFAObosmSdKQd6GxyKFMA2v8ccXKqTakRqFsqTxxAZkk3mnXqeorXjGE1CWEk2X/hxbn1vLkSwzTI6bYE+2GmiL8DQwYU815EYkq/QwqYxDg/HuB+p4WkuUnmMgCKFNk02oaY+qcww1iaoSF7gHSTxP6mJYETRmYdtDriiQgl4HnPqBT8lic7Yq9nOEYwh7eLzTbM+eXnimDXFm4cDXRx0qHYe08PRSzz7KVKOta/A2DotY7VZuHIGQwZTmDvX/OnnxQ+gkfoY5rNWf7RL26OXCmYxSG8bYDvATFmD0hjzDaZkc2fRBMKoBo9jP9nFhl1s2MWGXWzYxYZdbNhvsX8ud5FsW8bqogAAAABJRU5ErkJggg=="
},
"rawData":"https://www.example.com:8443/nnlgateway/nnl/auth|a|a2V5aGFuZGxlAAAAAkCWEmuOzp0StfICmXfaiCG6WplW-ytyf_0LWO7whMrbymL4L7NTlT860PoQErhuRrEntibmy9i64j37JhtcvT5nXiCLDIV3_z5th2xVyU5QaCwM9h999XUMZ5ufLioUVqg|12345|"
}
}Sample request with qrType=UNIVERSAL_ANY_RP
{
"operation":"START_OOB_AUTH",
"sessionData":{
"userName":"zsmith@noknok.com"
},
"id":"sample",
"oobRefId":"12345",
"oobMode":{
"qr":"true",
"rawData":"true",
"qrType":"UNIVERSAL_ANY_RP",
"webUrl":"https://www.example.com:8443/"
}
}Sample response when qrType=UNIVERSAL_ANY_RP
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode": 4000,
"id": "sample",
"lifetimeMillis": 180000,
"additionalInfo": {
"oobRefId": "12345"
},
"oobStatusHandle": "a2V5aGFuZGxlAAAAARTf5y_9RPAF8HqOSjXQkMnvOihxoKmS5ClnFj0FvPPCml2dMiYEdIdY1rb9i9SMhbL4A-K1kbagi5V7oL4PIfOSNNyPUx7lxBqfFgjX6VkT7xLUlMu5LVPVYfs",
"modeResult": {
"qrCode": {
"qrImage": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADjklEQVR42u2aUY4bQQhEuQH3vyU3INQrHI2TjRTlY8mHrUQeT7+RpukGCnqj/+ZT8cE+2Af7YH/CKmK+oquzq3Q709/hoUts/s3tuRMZ1TVMVWakfmn0EisG5311mQPPJIobDF1j/Bwgx8RzoQnMjOq/wFr/A8PKyNi7ZOhrzEs/5tRra3vO1Xzm4osd8s2YDfnl5xfP+nas13M1B93ZZ8ep47eI9N3YvKe+E2MGSx/anSWPzrzF5Ce6mtEZH28OP8LdW6wJfbhJAGhTapjH4habQXx5ljqwKQaflQ959Cmm1NHEPSU1GTa5o0ehLrEZ08sPo6yhjajNyQaIxxQusFnlYM1Js3Lj1FTSjhSnmP0Czw2ug8f4lQ/PusFyM1g6m+Er6R1RdYvNIDKAz4ZEsvAOXWIZjigMy3eYSnD5SLsXmH1Dy6x56DLtxlYwtxgpY9OuNqi+e+dVcYspmZHgyLcW7GzKNfoh5qyWxVt3+duboPIRLU+wLSHiJdpVjmFxJ7ZTTAGlvCdRUEkwLEz+cOcTTHUhW1DioO05llJs0EvMNXahAJTRJFIUnGMD9iUmLSAHEejiUOoFd1mvOcSoWINSLF29WiEnDYFTTFlWivNnRavpoPl8fYtRUCcTSKKOtZRrxVOseNU0zANo0Hq1oC6x7l12i4DY4oKq8bn0FxjVdG9xI4s2sYcaTZH6EkOf22m0OxUVybrWUXGMkV+D5W9ah+4zJT9OMfkF0WWTWblfR4viTUUfYC7BKBXZik2rgs3ABC4xSQIrvdoetarsJMNlxjEW1ijx0lCKgFbxbxnwAls3wcCUO+4PV1oqX2IKNEQU7UInNAs9e9AphmZiR5Yt+2r01PsxxAnGiuerqohtcvYa+BRzFFRsKUsp/dYEOmzwSwy1XitQXFxTPtLuz1tMPsK6E2tk1d5mopvZhxgxUHkiMXBtHnbR07eY+4T4tMPMVhN0Xx/l2AlGtzA5vEzrPRoAdAQe7aYTDN/lOBMhoGZ/xUqD94ry27EtDpOA4whDtPYhdR5j6UNLN06sRIsmXTwz4AXWG6Y3BnJGbcXi8ucS81Fmuyvcbki0ow9NilOsfeobNDZfp17RLrf7FitmUE6y4aPMtnSPN4V/hG0nQq0wmvyaTLoIOsf8pyP4dFPnlE++8hh7VWSutouzJSpYlMstxgq/zm04Q+fNg+PDOMU+fzz2wT7YB/tX7AdrHDK/ySj3JAAAAABJRU5ErkJggg=="
},
"rawData": "https://www.example.com:8443/#nnl-oobdata=https%3A%2F%2Fexample.com%3A8443%2Fnnlgateway%2Fnnl%2Fauth%7Ca%7Ca2V5aGFuZGxlAAAAAcVhwZ3uHYh29W0So8k_3moWKOt0vOKQnV7YywzlRpDJ4h5Sp600zT5qIUW8qSWWGYlncyaE2BlTMHSXkk-Do3lFi9BqsNi3EZv38yiBQiwSM97qLCjL2tliL5ds0mhPIWE%7C12345%7C"
}
}Sample request with qrType=UNIVERSAL_RP_SPECIFIC
{
"operation":"START_OOB_AUTH",
"sessionData":{
"userName":"zsmith@noknok.com"
},
"id":"sample",
"oobRefId":"12345",
"oobMode":{
"qr":"true",
"rawData":"true",
"qrType":"UNIVERSAL_RP_SPECIFIC",
"webUrl":"https://www.example.com:8443/"
}
}Sample response when qrType=UNIVERSAL_RP_SPECIFIC
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode":4000,
"id":"sample",
"lifetimeMillis":180000,
"additionalInfo":{
"oobRefId":"12345"
},
"oobStatusHandle":"a2V5aGFuZGxlAAAAAtOE0qZFy2zr5kSoFMrZoy8IvnTnE0_-1WdtVuKrgvVJJTs3w-sT9Vybl6dB5d717RCa8XhMm5ga7bKmH-dfligvEb-D4WwM7ZDXwZ3J9t0ZUaK_byzmpDxmZH4",
"modeResult":{
"qrCode":{
"qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC7ElEQVR4Xu2WS47jMAxEeQPe/5a6gaZeycEgnAamd+WFFCex5GdA/BVV+zdj1Vz5cVxsjIuNcbExLjbGxca42BgPtqpqtcaqtXZVb269nMe4WuTevcTrC+zlOMbWWTTJXC/xRr0Ea4yQDRs75GHefAu2HXpdZW6Xl/MY1/Iz4UpMwl9nOY5RMj+MWTIJ7NwT9lY6yhan5N9nSYyIE338uVCaamzqGfoEZuUjD08qljPU7+SxR1m04WpcrJlSk4+VJ4vJvygyOz/QsYFPGgMUtC2DT8wxqiyKWYy1wgLPKRrUWunweZ7EymLjOgHivUVJj7SMYMyUkcvFszgVtA0Z7o1g8m65geincDXpiSoOSxPY5nDnEmmKp1FCjJpVH8CckNrztmPxNnVTn84WxbSMCVQJjaOpZ0q5X4Cxd9y7YZycuNeqHceOV5vIk5JAJ/yzfUQwHoqzHArHr0UvzmPMOBBo42Tldr/Fpu9yjmAuD3wqN1MoEmhlwMmGNMb/59L3WCQX00zSGD1s4VcykV5ymtt6A+ZqoadpeoSaauZ/pGUAA0L/kBdHvkgD5nmMGZdmqCAEtVNPxUQxYmyZwZ1NEnC4WiRnHiuql0fsG5BKJjFfgGmzoGWHmkWx7e80dpQF6aN5+GjMdH9in8XYPc9Iyz71bPH5LpkIRlISesuhNo7GePvfJkQwK6DR8w7r1pknNYKYdszZE7op6cUNaTkkOoGxe5jFnjGgUJrFbxxbHAS8bodSO9Q3qfoCTLt30dgI7shNB/8F2CbmPoAS9bN5LMljR2meUEO7fTwFk8WY2wrCbyH0HaeYPGataV8QlLIPVf8oeQLTLTnodusGjIf3Q0UxKpf4Kw0RHOoYY9xF4pgtaE7t8LyG1hyz0hgpSAUjNgTc3cOGvQIj4D618EyK4xQdUhPD+LV/tbZ8OnDpxDFI+dM+BUWrtwUxjxXxVvjZMoeDgiAv89j/xsXGuNgYFxvjYmNcbIyLjfFb7A/rZ87UWFxV+gAAAABJRU5ErkJggg=="
},
"rawData":"https://www.example.com:8443/#nnl-oobdata=%7Ca%7Ca2V5aGFuZGxlAAAAArpGFXO6n1GlqUDaopwTCU4VK6q-QcNG52EJ2RIXjvmeau0nNgQXdH8OsdL1EQQIhByodJruhFYDgUlhXeoPr0QBem05wqoSitWCKESsZ358siDZrLPxtnh0q3_pIXp3lzU%7C12345%7C"
}
}Sample request with qrType=APP_ANY_RP
{
"operation":"START_OOB_AUTH",
"sessionData":{
"userName":"zsmith@noknok.com"
},
"id":"sample",
"oobRefId":"12345",
"oobMode":{
"qr":"true",
"rawData":"true",
"qrType":"APP_ANY_RP",
}
}Sample response When qrType=APP_ANY_RP
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode":4000,
"id":"sample",
"lifetimeMillis":180000,
"additionalInfo":{
"oobRefId":"12345"
},
"oobStatusHandle":"a2V5aGFuZGxlAAAAApAAc6HTXLTZ3k6RIalnWhWvwK0DGx0-myq0ldgEA5MgnNPzI2RZisjcuGMhm42aAsnnerJtBGZXd_NkJ-y__R7AbAB57VC3eIlQI_jZMUmRCEd7ux_dynhBrF4",
"modeResult":{
"qrCode":{
"qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC9klEQVR4Xu2XW3LDMAhF2QH73yU7oBxQ0omcmeanuf4Qybi2OO4gnorlJxK2r7yVg21ysE0OtsnBNjnYJgfbZGFhZmnpHuZWl8jweu5lOVbfKKCu4VxL7+Es6zGsditF2ezFWPHpvXwHrGxvqpycWTtw0Jtgo0vsr4e6jbWsxiBxa11KW3/qpehlPQbxRuxaWTuC/CvWQpHYVLETef9VKbGytb8Fcl8JWutOog4rxbK7DI/cshE6IgV9AyzJyG42SUGvEsrlYilWWqPvGRnA7BgN9a3HbFKREikXczdN5wYY6ZjjWpofJG9M4LXYOgwkwQ/6M1mZvRE5VqYCkAAkJzmKt1nWY1hPMjqb6dBXRccl9AqMiUvzo4wJ+ozdS6sRYaQi9sbsxBi9NMIRJdYjIzoRuc40qX3FZcp8H5siHsd2q6E94/JVz1IMY3uJEm63Fol+D70A40i3CKbvQN129FgznQEkZ3+s7X8NvQZjqGE/uE3oeWvplVjMrOWxv4/ioWnLMaLcBqNmjjiXWGo11jXMI4bTeYy119BLMG6I+CQA3rU5trxuQYMxxaZYWIAr3S+nxGJacjJrSxsoGHH9khhb1vMjDDUxz54fW+g12GoquNn7hAecl9GmwHp1jlKko1M2wWc4JdYFPHdJ8PF0MEDmn2ixpEmXV+tK7XCLw1lRY4lbff4Q/hX3HiZqLBhhDAvvvKS2qaBLq1Fg2TYnk8Op4mfUnzvUYXS+HrbMM+M2Z55M5MWY4+FyKDU9vq1N8EtDjnHgZJwFbgUnRZlsj38jxLrV0PaMQmE7HKVKNwkgxUi/Hhp4GBVMF85wUozmx+ETq42aCZbY1w0wbilidoC6PsbjQ6fDMHu6YBXLpCP1TVnrMb6kYXYH5Exgs4XhpFi04Z2bbAfIeyut1mNB3yM9+3Q3pcMsvgOGZzv0BfMCp77XktFgkGjwLllAT4zVq9WYdclU84vpfgSdmn5bWd/F/pKDbXKwTQ62ycE2OdgmB9vkU+wH9pOdJCn6pBIAAAAASUVORK5CYII="
},"rawData":"https://www.example.com:8443/|a|a2V5aGFuZGxlAAAAAuvrtu9ocPVOCInmCAeXweMb7o50qkizvMDqxjnb6udKQ4UdhpYxg8jQVDRDVHwRVLnk52Iid1gAvUmejh9Kou4lnE93zLiJDiHYl2_GC1wZ6PPMGyYulteUZnFnfmpFJkI|12345|"
}
}Sample request with qrType=APP_RP_SPECIFIC
{
"operation":"START_OOB_AUTH",
"sessionData":{
"userName":"zsmith@noknok.com"
},
"id":"sample",
"oobRefId":"12345",
"oobMode":{
"qr":"true",
"qrType":"APP_RP_SPECIFIC",
}
}Sample response when qrType=APP_RP_SPECIFIC
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode":4000,
"id":"sample",
"lifetimeMillis":180000,
"additionalInfo":{
"oobRefId":"12345"
},
"oobStatusHandle":"a2V5aGFuZGxlAAAAAtc_3252Hfjzi8pQyhwFsMykzjWNLo7yMEf-1uOcgE4D6zoCxLlplnUpqvO9kXZMi0vmKKYtPrSccAmWp-lVpQaQfwFVd2EoOsTt49ep0TmFgmCLkbDCwG-HoLI",
"modeResult":{
"qrCode":{
"qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADe0lEQVR4Xu2ZS47qQAxFjRhkyBJqJ7CxSEHKxshOsgSGNUD43eOC7nTU0nvDsh4lNZ3PYeD259pu8385d9s/+fV8sN35YLvzwXane2w1s+Pqiy7t4A/zmx7406a1GlcZMP3M+vFrGfg16LENi1+tXtrb/rFqp3mth0aMRdZNXs82mj6OiTCz06PUyz2eX4v8NJZkmC9yUXzY+UTQnRxzk2BOvA1Pnit5XOZOuI2r9rZ/zMj6eibodh96A9E91g7xJmfJZvlO8SaPlfe77rFVFVcpc9GVPHZVvCnrFXmjDc9tvPWM6eUD0+YoXEbtLdKQSWqi2xSY7qwMmEaAFR43BdQXZHMCTAmPVFB2leaSwZvizbiVDKqiJcC4U44cVKlCug2W2psIk15gcCvAijzT7XALt9FZZcAwktgiPRR5lfBzHGgoeRLMHyVMQ/ya4XyreSwDRpTNK3XWX7kuF8UX0mBo9avORurDtgEjMigDJseQ5kuLPCt0g0UYuWSbPqRnrE0UiwqXdG+kcD2amhh/ggzYilREGxuNOckTvtOt47sEmKYHpTlWrWoJCTAKV2PxYgYMp1g04bJZl60dpy/UyATQP4alrZ+CUPjdo3rN5L9szoBhEBk+oRzzu596W58CC5VAycn6YxSBL0u/e/KesfCJtaHoQDeIkKhwGfEWE17/mLwjtaMTb7X3zJUzWyzb6aNnjFwnwMZSWXSQPMaO4yUpCTCUY6SNRT5ig3mP5Hkg7JuU6RnzELpbq1mKPA8XtQ3mpg/pGGOGi37KmYw05l08rFcBxoE5MLrBgU6cvGFlKY/xVZJnY2nPGAapZvESZy30ITgrqnAGrCV3rJAZsa114ksQP3Y1HWNKlBFnecPYEkQrVQBKCkyi8ZqHyJY16lj0IcZaOQVmzKL15SIVW4aiIYy8/ei4OsZ4hHTPBJ2DGUs/ehPbOKtnTJaSNx7DBB4jg+inZPj3xqxnbGVRySPqLDaHDJL1P+KtZyzO2nrZMNLUEsaH0+RmwMIgVDtakCM7QBx4j8lo66yOMf9aHEs5jm1pEDNr7M5SYEqUaDzCWYYCTqRR/Mv6u3B1j8mqlvAQKlwSxFCTjbO6x+L/JwNLpso+PIQ9Zr0UmLMRwMg1FFCd1cSHlDyW4hkwo8RWdjUhH7zw0O9KMcuA/f18sN35YLvzwXbnP8L+AARrKC5863B/AAAAAElFTkSuQmCC"
}
}
}Sample request with user name and push=true
You can push a request with a known userName. In the response, you get the rawData and a QR-code image.
{
"operation":"START_OOB_AUTH",
"sessionData": {
"userName":"zsmith@noknok.com",
"pushHandle":"a2V5aGFuZGxlAAAAAm0vSdDUyruH_--jrbLvlPEWhtlLeRKXTCCzBPPB2haRaxQ2mo7dSSXR4gOrhX64LXCKFY9sciN069_-yFrF_tS_2zjsIupxSkE_qq2vlJgpFKMK1jJmAKJ8wGbIt5ahmv54SiaSLZhY4aWh4nzD4CU0RODheJIOiIkLuk2JsqajCSs8vhPFpIWeHm1ENfl0Oh8tvQ"
},
"oobMode":{
"push":true
},
"oobRefId":"Authorize the user with FIDO2 authenticator",
"authNotificationText":"Hello ZSmith, Please SignIn"
}Sample response with user name and push=true
A developer updated the response filter configuration so the API Server returns the OOB Reference ID in additionalInfo.
{
"statusCode":4000,
"id":"ue4tdqxkb5nZWMueI2CLvw",
"lifetimeMillis":180000,
"additionalInfo":{
"oobRefId":"Authorize the user with FIDO2 authenticator"
},
"oobStatusHandle":"a2V5aGFuZGxlAAAAAufDDq73ZVoeM0yNQrXcrFXly832ahAXnBWX1ib10TpZ7KaF_SnLe4e_LInPhoArwItlbB9TMy5nUk4FfzBGXWXntOYpyvLpqPmCKQWCwbLChR05q7AC4_2K1hcb580yk8XapmaNF11WbahU",
"modeResult":{
"push":{
"status":4000
}
}
}LIST_OOB_AUTH
Use LIST_OOB_AUTH to fetch a list of pending OOB authentications. This is useful in situations where the end user was supposed to receive a push notification to authenticate, but never did. For example, the user may have disabled push notifications for the app on their device. Or a push notification is sent but fails to reach the user's device due to technical issues. Your client app on the second device can call LIST_OOB_AUTH to get a list of pending OOB authentications and then present this list to the user so they can continue OOB authentication.
Call LIST_OOB_AUTH after calling START_OOB_AUTH from the first device (or a backend service) but before calling INIT_OOB_AUTH on the second device. The end user must have a valid session on the client app running on the second device. You can specify that you only want pending OOB authentications filtered for the user's device and app by including the device.id, app.id, and app.name attributes in the request. An app running on a device that is neither the first nor second device can call LIST_OOB_AUTH.
You must set the SYSTEM tenant property oob.list.auth.enabled to true in order for LIST_OOB_AUTH to return pending authentications. Use nnl-mgmt.sh, as shown below. This requires restarting the Auth Server. Otherwise, this operation fails and returns 4406.
./nnl-mgmt.sh properties set -name oob.list.auth.enabled -value true ‑tenantid SYSTEMFor more information about this command, see Set Property.
Request
Attribute | Description |
|---|---|
| Required. The string LIST_OOB_AUTH. |
| Optional. An object representing the user's client app running on the second device. App. |
| Required if device.id is provided. Identifies the client app by its ID. |
| Required if device.id is provided. Identifies the client app by name. |
| Optional. An object representing the device intended to receive the push notification(s). Device. |
| Required if app.name is provided. Uniquely identifies the device. |
| Optional. The correlation ID. An alphanumeric string with a maximum length of 255 characters. No special characters are allowed. If not provided, the Server generates a unique id and returns it in the response. |
| Required. An object containing the user's session information. See SessionData. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
| An alphanumeric string. If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown. |
| Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server statusCode of 4000).
Attribute | Description |
|---|---|
| An array of objects containing the pending OOB authentications for the userName present in the provided sessionData. Contains the attributes listed in the rows below. |
| String. Raw data to send to the second device when you are using your own mechanism instead of a QR code or push notification. |
| Present if the user is performing OOB authentication to confirm a transaction. Object with 2 attributes:
|
| The amount of time, in milliseconds, that the user has to complete OOB auth. Long. |
| Information about the second device that should have received the push notification. DeviceDetail. Present if a push notification was attempted during START_OOB_AUTH. |
| An object containing information about the client app that should have received the push notification. App. Present if a push notification was attempted during START_OOB_AUTH. |
| Status of the Authentication Server's attempt to send the push notification. See Push Notification Status Codes for the list of status codes. Present if a push notification was attempted during START_OOB_AUTH. |
Response status codes
The following are the descriptions of the Server status codes returned by LIST_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | The OOB authentication list request was successfully created. |
4404 | Internal Server Error | Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Payload Exception | An error occurred with one or more attributes. For example, the username extracted from sessionData.sessionKey has an invalid length. This error also occurs if the SYSTEM tenant property oob.list.auth.enabled is false. |
Push notification status codes
The following are the status codes that the Auth Server returns to report the outcome of its attempt to send a push notification. The push notification status is contained in the pendingAuths[].push.status attribute in the response. For example, a successful push notification status is delivered within the response payload as:
"pendingAuths": [
{
"push":{
"status":4000
}
}...Push status is independent of the overall status of the response.
Server Status Code | Description | Examples |
|---|---|---|
4000 | PushNotification Success | The Server successfully sent the push to a push notification network, such as APNs or GCM. |
4402 | Security Exception | Push Handle is invalid. |
4404 | Internal Server Error | Internal server error. |
4421 | Unknown Credentials | The Server was supposed to send a push but didn't because it doesn't know the device that should receive the push (the device details were not available). |
4451 | PushNotification Exception | |
Samples
Sample request to fetch pending OOB authentications
{
"operation": "LIST_OOB_AUTH",
"sessionData": {
"sessionKey": "<session JWT>"
}
}Sample response for pending push OOB authentication(s)
{
"statusCode": 4000,
"id": "5Mg4XBrwWwZ_ai81xCdM7w",
"additionalInfo": {},
"pendingAuths": [
{
"rawData": "https://<myserver>/nnlgateway/nnl/Admin/auth|a|a2V5aGFuZGxlAAAAAXX8BJnKOHqORA-hN36a1kcyH_TTBCipmEnWIF7eLgrVyk6PkYqKcXvuLstg_-LsBf1XZVNmQOCMcoRhTFlFMcJET7O1WjfSfIuafk4bCQwipi7t5xTU2hrZuiTJin-i2iv9MOplYaJpx7JqFHLYFJ3NWz9AEjtbZaUMjMNavS7TWI9BX2Wjl2TPgJ93-j9mi34f291PM0B41lRI0d4Q6_EFscM|US32631|",
"push": {
"status": 4000,
"device": {
"id": "WJ8E5nuyrAlQWVPvWp2N8gdRP8Ky3YMMQImPolvYydg",
"deviceType": "android",
"info": "OnePlus OnePlus5",
"model": "ONEPLUS A5000",
"os": "ONEPLUS A5000",
"manufacturer": "OnePlus"
},
"app": {
"id": "android:apk-key-hash:Bc9rEk16GTEpN3bbD+4zV/H3Msk",
"name": "android:com.noknok.android.passport2",
"qrSupported": true
}
},
"transaction": {
"id": "23458542351874875",
"text": "VGhpcyBpcyBhIHRlc3Q="
},
"remainingTimeMillis": 133000
},
{
"rawData": "https://<myserver>/nnlgateway/nnl/Admin/auth|a|a2V5aGFuZGxlAAAAAc8T7968-kRCYFDkz6qpofCV1xvJklDBTK5YzdnwMdLsprpDsR38wjSikbcBG3_YGaFiNcxIeDlLf10NhPAN2jiJ9oLdmXOMN9ZzfswfRRl5E6BfqM9El84Nvd-aJx83q97uIRpdlS7IM-GVTuMNTpDlkKk1WDgYOA|US32631|",
"push": {
"status": 4000,
"device": {
"id": "WJ8E5nuyrAlQWVPvWp2N8gdRP8Ky3YMMQImPolvYydg",
"deviceType": "android",
"info": "OnePlus OnePlus5",
"model": "ONEPLUS A5000",
"os": "ONEPLUS A5000",
"manufacturer": "OnePlus"
},
"app": {
"id": "android:apk-key-hash:Bc9rEk16GTEpN3bbD+4zV/H3Msk",
"name": "android:com.noknok.android.passport2",
"qrSupported": true
}
},
"remainingTimeMillis": 140000
},
{
"rawData": "https://<myserver>/nnlgateway/nnl/Admin/auth|a|a2V5aGFuZGxlAAAAAUCXzSzOUN36xBly7h61yCGRxSf_B9s9kD5e2NDH1bDwKaPlcndz_b8VXBz8yo48uyB6fcLsp2xbsGB55JNQmLBn8GirtCyaC_kFcBQN3yOHkI5ei2xTYJxqGwYtuYx0okAiT2nPDdMgpMjTqUABrvAKBzIVS-WhQw|US32631|",
"remainingTimeMillis": 177000
}
]
}Sample request for pending push OOB authentications filtered by device.id and app.name
{
"operation": "LIST_OOB_AUTH",
"sessionData": {
"sessionKey": "<session JWT>"
},
"device": {
"id": "WJ8E5nuyrAlQWVPvWp2N8gdRP8Ky3YMMQImPolvYydg"
},
"app": {
"id": "android:apk-key-hash:Bc9rEk16GTEpN3bbD+4zV/H3Msk",
"name": "android:com.noknok.android.passport2"
}
}Sample response for pending push authentications filtered by device.id and app.name
{
"statusCode":4000,
"id":"f6Uwy4c4iAixliWk3ZU_4Q",
"additionalInfo":{
},
"pendingAuths":[
{
"rawData":"https://<mysserver>/auth|a|a2V5aGFuZGxlAAAAAVLmzjB5-vC0-5otZIKMyPGy883gJQO_ma1bGXx8jDUGegfZFDCflu3IkQXOA949JT0tImH-5hImcO7K2b0ZLhX4sYcswnH3uUdqC9YCOcjdGCUFGV9axsHlluj_iOHdztJmV9E6Lojsf5NBPgcmpJIp5qsDvk7R40-Fyk-wd4oEQAsW3GOOHNjKphr4YPQrYacAa6Ys-ZCrcctjXTUOOmhk2-o|US32631|",
"push":{
"status":4000,
"device":{
"id":"WJ8E5nuyrAlQWVPvWp2N8gdRP8Ky3YMMQImPolvYydg",
"deviceType":"android",
"info":"OnePlus OnePlus5",
"model":"ONEPLUS A5000",
"os":"ONEPLUS A5000",
"manufacturer":"OnePlus"
},
"app":{
"id":"android:apk-key-hash:Bc9rEk16GTEpN3bbD+4zV/H3Msk",
"name":"android:com.noknok.android.passport2",
"qrSupported":true
}
},
"transaction":{
"id":"23458542351874875",
"text":"VGhpcyBpcyBhIHRlc3Q="
},"remainingTimeMillis":56000
},
{
"rawData":"https://<myserver>/nnlgateway/nnl/Admin/auth|a|a2V5aGFuZGxlAAAAAVNPgjuCkkcFsiP0nvutBxMwNGVmfuvR3PIXZ49EGJrStHhzUZxuYPoZY4bJOR5obnLfrhXQP90i21xT4rbqRMyge0WpjnhEESk_UCpmWDYfe86tJIOe84Rcg-Z4aNh1XrsIGSQ3oBILolidOBJA8b_KZlOd8hzHNA|US32631|",
"push":{
"status":4000,
"device":{
"id":"WJ8E5nuyrAlQWVPvWp2N8gdRP8Ky3YMMQImPolvYydg",
"deviceType":"android",
"info":"OnePlus OnePlus5",
"model":"ONEPLUS A5000",
"os":"ONEPLUS A5000",
"manufacturer":"OnePlus"
},
"app":{
"id":"android:apk-key-hash:Bc9rEk16GTEpN3bbD+4zV/H3Msk",
"name":"android:com.noknok.android.passport2",
"qrSupported":true
}
},
"remainingTimeMillis":64000
}
]
}INIT_OOB_AUTH
Initiates the OOB authentication process on the second device.
The Server uses the allowed UAF authenticators specified by the FIDO authentication policy and device information to create a list of permitted UAF authenticators from which an end user can select to authenticate. The FIDO authentication policy was sent in the START_OOB_AUTH request.
For FIDO2 authenticators, the Server compares the authenticator's characteristics to the desired FIDO2 authenticator characteristics specified by the FIDO authentication policy. The client uses these as hints to prompt the end user for the authenticator. The Server enforces user verification and attestation preference during FINISH_OOB_AUTH based on the policy configuration. If you have not configured the authentication policy for FIDO2 authenticators, then INIT_OOB_AUTH fails with a 4403 when a user of a web app tries to authenticate with a FIDO2 authenticator.
Refer to Create FIDO Policies to create a FIDO policy.
Request
Attribute | Description |
|---|---|
| Required. The string INIT_OOB_AUTH. |
| Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
| Required. Generated by the App SDK on the client. This is an opaque value. The client app is responsible for sending message. This is a base64-URL encoded string. |
| Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
| Optional. An object containing session information for the user. See SessionData. This is for the user who is logged in on the second device. This person must be the same user logged in on the primary device. Omit if the user is not logged in on the second device. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
| The unique id that correlates START_OOB_AUTH, INIT_OOB_AUTH, and FINISH_OOB_AUTH operations for the same user. String. |
| Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server status 4000).
Attribute | Description |
|---|---|
| An object containing information returned by the Authentication Server about the second device. Contains the 5 attributes listed in the rows below. In order for the API Server to return this information:
|
| A DeviceDetail object containing information about the second device, such as the device’s unique ID, model, and manufacturer. |
| The amount of time, in milliseconds, to process the request. |
| Message payload extensions received by the Server in INIT_OOB_AUTH request. List<Extension>. |
| ID provided by the RP app to retrieve contextual information from the RP server that can be displayed to the app user. Only returned if oobRefId was included inside oobData in the scanned QR code or push notification. |
| The protocol used by the Authentication Server. String. One of UAF or Web. |
| Lifetime of message in milliseconds. Long. Your application can use this to tell a user how much time they have to complete the operation or warn the user that the Server does not accept a response once lifetimeMillis has expired. |
| message must be sent to the App SDK. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by INIT_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | Authentication request created successfully. |
4401 | Challenge Expired Exception | Bindata has expired. |
4402 | Security Exception | Replay attack detected. Mismatch of usernames in input and DB. |
4403 | PolicyException | Requested policy is not available on Server. |
4404 | Internal Server Error | Internal server error. Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Payload Exception | An error occurred with one or more attributes. For example, message has an invalid type or username extracted from sessionData.sessionKey has an invalid length. |
4408 | UnsupportedClient MessageException | The message parameter cannot be handled. Unacceptable client capabilities - invalid protocol version. |
4409 | ClientMessage Exception | The message parameter is invalid (for example a JSON syntax error). The message parameter from the App SDK is malformed (base64URL decode failed). |
4430 | UserNotFound Exception | Failed to locate the user in the Server. |
4450 | UserCancelledException | Cancellation initiated by the user. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/authSample Request
{
"operation": "INIT_OOB_AUTH",
"message": "<base64url-encoded-data>"
}Sample response
A developer updated the response filter configuration so the API Server returns the protocol and OOB Reference ID in additionalInfo.
{
"id": "dEgViadKjxcleujKbpfi6g",
"statusCode": 4000,
"message": "<base64url-encoded-data>",
"additionalInfo": {
"protocol":"uaf_1.0",
"oobRefId":"12345",
"device": {
"id": "123456789abcdef1234567890",
"type": "android",
"info": "OneSpan's device"
}
},
"lifetimeMillis": 300000
}FINISH_OOB_AUTH
Processes the authentication response provided by the caller and completes the OOB authentication process on the second device.
Request
Attribute | Description |
|---|---|
| Required. The string FINISH_OOB_AUTH. |
| Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
| Optional. Channel binding data available from the TLS endpoint. ChannelBinding. |
| Required. Generated by the App SDK on the client. This is an opaque value. The client app is responsible for sending message. This is a base64-URL encoded string. |
| Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
| Optional. An object containing session information for the user. See SessionData. This is for the user who is logged in on the second device. This person must be the same user logged in on the primary device. Omit if the user is not logged in on the second device. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
| The unique id that correlates START_OOB_AUTH, INIT_OOB_AUTH, and FINISH_OOB_AUTH operations for the same user. A Base64-URL encoded string. |
| Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server status 4000).
Attribute | Description |
|---|---|
| An object containing information about the client app and device from the second device. Contains the attributes listed in the rows below. In order for the API Server to return this information,
|
| List of the authenticators that succeeded or failed to complete authentication. List<AuthenticatorResult>. |
| A DeviceDetail object containing information about the second device, such as the device’s unique ID, model, and manufacturer. |
| The amount of time, in milliseconds, to process the request. |
| Message payload extensions received by the Server in FINISH_OOB_AUTH and INIT_OOB_AUTH requests. List<Extension>. |
| Protocol-specific header extensions. List<HeaderExtension>. |
| ID provided by the RP app to retrieve contextual information from the RP server that can be displayed to the app user. Only returned if oobRefId was included inside oobData in the scanned QR code or push notification. |
| FIDO authentication policy used for the operation. String. |
| Protocol used by the Server based on information from the request. String. One of UAF or Web. |
| RulesResult populated as a result of policy rules processing giving out the matched rules details. RulesResult. |
| Transaction ID provided by the client app to track a transaction. String. The transaction ID is provided in the request payload of START_OOB_AUTH. |
| message must be sent to the App SDK. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by FINISH_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | Authentication completed successfully. |
4001 | OK. Credential variance | UVI is different uaf.exact.match=true |
4002 | OK. Optional security checks failed | Failed to validate ChannelBinding. |
4400 | Registration NotFound Exception | Failed to authenticate because the user registration does not exist on the Server. |
4401 | Challenge Expired Exception | The request challenge has expired. |
4402 | Security Exception | Failed to validate the attestation. Failed to validate Server challenge. Failed to validate the Server data. Failed to locate authenticator metadata. Challenge replay detected. Failed to validate extension data. |
4403 | Policy Exception | Failed to locate authenticator metadata. Failed to match policy. Policy not supported. UVI is different uaf.exact.match=true |
4404 | Internal Server Error | Internal server error. Failed to write to the database. Failed to read from the database. Failed to connect to the database. Failed to read properties. |
4406 | Payload Exception | Parameter message has an invalid type. |
4408 | UnsupportedClient Message Exception | Parameter message cannot be handled. Unacceptable Client Capabilities - invalid protocol version. |
4409 | ClientMessageException | Parameter message is invalid (for example, a JSON syntax error). The message parameter from the App SDK is malformed (base64URL decode failed). |
4450 | User Cancelled Exception | Operation has been canceled. |
4455 | Authenticator suspended | The FIDO2 authenticator is suspended. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/authSample request
{
"operation": "FINISH_OOB_AUTH",
"message": "<base64url-encoded-data>"
}Sample response
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, OOB Reference ID, FIDO policy used, post operation rule results, client app information, and payload extensions in additionalInfo.
{
"statusCode":4000,
"id":"5pTt3uv1Xumk6iBeEpxBrA",
"message":"eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7ImFhaWQiOiJBQkNEI0FCQ0QiLCJrZXlJRCI6ImU5SWlPNVVDcHAzQS1WaGdtQ0h1cTJKZXVwODJXNlYwaHc2bzVldGFtYkkiLCJzdGF0dXMiOjQwMDB9XSwiYXBwSUQiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL1NhbXBsZUFwcCJ9LCJ1c2VyTmFtZSI6Im8zIiwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9PT0JfQVVUSCIsInByb3RvY29sIjoidWFmXzEuMCJ9",
"additionalInfo":{
"device":{
"id":"123456789abcdef1234567890",
"type":"android",
"info":"NokNok Emulator",
"model":"NokNok-AE 8.0",
"os":"NokNokOS .0",
"manufacturer":"NokNok",
"supportsPlatformAuthenticator":true
},
"protocol":"uaf_1.0",
"authenticatorsResult":[
{
"handle":"WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiZTlJaU81VUNwcDNBLVZoZ21DSHVxMkpldXA4Mlc2VjBodzZvNWV0YW1iSSJd",
"uvi":"iIYTYK3xxj--osjWS0ZpK6A5txRD2-qL5KIeRICFGfg",
"uviStatus":4,
"status":4000,
"aaid":"ABCD#ABCD",
"authenticatorVersion":1,
"transactionResult":{
"hash":"xE7sNci-TFI7leurVFxrTqW3CTh_1qinfzm61ySXFDg",
"hashAlgorithm":"SHA-256"
},
"attachmentHints":[
"internal"
]
}
],
"oobRefId":"123456789",
"policyName":"default",
"rulesResult":{
"action":"ALLOW",
"matchedRules":[
{
"name":"LocationVelocity",
"riskScore":0,
"template":"DummyRule",
"group":"dummy group"
}
]
},
"app":{
"id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
"name":"android:com.noknok.test.client",
"qrSupported":false
},
"extensions":[
{
"id":"noknok.ipaddress",
"data":"192.168.0.102",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.ipaddress",
"data":"192.168.0.102",
"operation":"INIT_OOB_AUTH"
},
{
"id":"noknok.wifi.ssid",
"data":"Oviya",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.wifi.ssid",
"data":"Oviya",
"operation":"INIT_OOB_AUTH"
},
{
"id":"noknok.uaf.location",
"data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.uaf.location",
"data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"operation":"INIT_OOB_AUTH"
},
{
"id":"noknok.uaf.jailbreak",
"data":"{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.uaf.jailbreak",
"data":"{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"operation":"INIT_OOB_AUTH"
}
]
}
}CANCEL_OOB_AUTH
Cancels OOB step-up authentication operation from the second device (authenticating device) on the Server.
Request
Attribute | Description |
|---|---|
operation | Required. The string CANCEL_OOB_AUTH. |
callerOrigin | Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
nnlData | Required. Data required to cancel the operation from the second device. The second device is used for OOB authentication. This data is contained in the message attribute returned in the response from INIT_OOB_AUTH. String. |
optionsData | Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
sessionData | Optional. An object containing session information for the user logged in on the primary device. See SessionData. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
id | The unique id that correlates START_OOB_AUTH, INIT_OOB_AUTH, and FINISH_OOB_AUTH operations for the same user. A Base64-URL encoded string. |
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server status code 4000).
Attribute | Description |
|---|---|
additionalInfo | An object containing information returned by the Authentication Server. Contains the 2 attributes listed below. In order for the API Server to return this information:
|
additionalInfo.elapsedTime | The amount of time, in milliseconds, to process the request. |
additionalInfo.oobRefId | ID provided by the RP app to retrieve contextual information from the RP server. Alphanumeric string. The API Server only returns this attribute if you sent oobRefID in either START_OOB_AUTH's or INIT_ADAPTIVE's request. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by CANCEL_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | Authentication Request created successfully |
4401 | Challenge Expired Exception | The request challenge has expired. |
4402 | Security Exception | Username mismatch. NNLData validation failed. |
4404 | Internal Server Error | Internal server error. Failed to read required properties. |
4406 | Payload Exception | Parameter nnlData is empty. |
4453 | Operation already completed | Unable to cancel because the operation has been executed. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/authSample request
{
"operation":"CANCEL_OOB_AUTH",
"nnlData":"-sRSN2V1lZ4rWDaoJXKdCqQ9UaSTHc1EZUgLVlPy1h5bceUys1HoE2YHOkQXCV7jWA0O-w83gEAklsoC4uc-vezfe7kziiRWmdN8YZKlGK-HIs2tepk3RzB7WpA"
}Sample response
{
"id":"dEgViadKjxcleujKbpfi6g",
"statusCode":4000
}STATUS_OOB_AUTH
Checks the OOB authentication status on the device. This occurs on the first device that starts the OOB authentication operation.
Request
Attribute | Description |
|---|---|
operation | Required. The string STATUS_OOB_AUTH. |
callerOrigin | Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps with a Different Origin. |
oobStatusHandle | Required. An identifier for a specific OOB authentication operation. An alphanumeric string, maximum 4000 characters. Use the oobStatusHandle attribute returned in START_OOB_AUTH’s response. |
optionsData | Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
sessionData | Optional. An object containing the user's session information. See SessionData. |
sessionData.sessionKey | Optional. To perform step-up authentication, assign a valid JWT session token to sessionData.sessionKey. |
sessionData.userName | Optional. For an improved authentication experience, provide the username so it is known up front. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
id | The unique id that correlates INIT_OOB_AUTH and FINISH_OOB_AUTH operations for the same user. String. If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown. |
remainingTimeMillis | Lifetime of oobStatusHandle in milliseconds. A negative value means the lifetime has expired. Long. |
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server status 4000).
Attribute | Description |
|---|---|
additionalInfo | An object containing information about the client app and device from the second device. Contains the attributes listed in the rows below. In order for the API Server to return this information,
|
additionalInfo.authenticatorsResult | Authenticators that succeeded or failed to complete the OOB authentication operation. List<AuthenticatorResult>. |
additionalInfo.device | A DeviceDetail object containing information about the client. |
additionalInfo.elapsedTime | The amount of time, in milliseconds, to process the request. |
additionalInfo.extensions | Message payload extensions received by the Server in FINISH_OOB_AUTH and INIT_OOB_AUTH requests. List<Extension>. |
additionalInfo.headerExtensions | Protocol-specific header extensions. List<HeaderExtension>. |
additionalInfo.oobRefId | ID provided by the RP app to retrieve contextual information from the RP server that can be displayed to the app user. Only returned if oobRefId was included inside oobData in the scanned QR code or push notification. String.
|
additionalInfo.authNotificationText | Dynamic push notification text. If this text is sent in the payload to START_OOB_AUTH and the push was successful, then this string is returned via this attribute if authentication succeeds. String. |
additionalInfo.policyName | FIDO authentication policy used for the operation. String. |
additionalInfo.protocol | The protocol used by the Authentication Server based on information from the request. String. One of UAF or Web. |
additionalInfo.transaction.id | Transaction ID provided by the RP to track a transaction. String. The transaction ID is provided in START_OOB_AUTH’s request. |
push | An object containing information about the push notification. Contains the 4 attributes listed below. |
push.createdTimeStamp | Creation date and time of push handle in UTC format. String |
push.handleLifetimeDays | Remaining lifetime of the push handle in days. Long. |
push.pushHandle | Identifies the device that receives a push notification and then initiates an OOB authentication. A Base64-encoded string, maximum 4000 characters. |
push.status | Result of the push notification. Integer. Also indicates status when the Server is unable to generate a new pushHandle because the maximum number of push notifications has been reached. This could be due to delivery or processing failures. Does not generate a new push handle. This happens when the maximum number of push notifications has been reached, such as delivering or processing failures have occurred. |
sessionData | An object representing the authenticated user's session information. See SessionData. |
userName | Authenticated user name. String. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by STATUS_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | Authentication Request created successfully. |
4004 | OK. Operation in progress | The OOB Auth operation is still in progress. |
4005 | OK. Operation is pending | The OOB Auth operation is pending. |
4401 | Challenge Expired Exception | The request challenge has expired. Unable to process poll request. oobStatusHandle has expired. |
4402 | Security Exception | Poll input validation has failed against DB. |
4404 | Internal Server Error | Internal server error. Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Payload Exception | An error occurred with one or more of the following attributes.
|
4430 | UserNotFound Exception | Failed to locate the user in the Server. |
4450 | UserCancelledException | Operation is canceled. The status code is the same as the one for INIT_OOB_AUTH. |
4455 | Authenticator suspended | The FIDO2 authenticator is suspended. |
Push notification status codes
The following are the status codes that the Auth Server returns to report the outcome of its attempt to send a push notification. The push notification status is contained in the push.status attribute in the response. For example, a successful push notification status is delivered within the response payload as:
"push":{
"status":4000
}Push status is independent of the overall status of the response.
Server Status Code | Description | Examples |
|---|---|---|
4000 | PushNotification Success | The Server successfully sent the push to a push notification network, such as APNs or GCM. |
4402 | Security Exception | Push Handle is invalid. Failed to validate pushHandle data. |
4404 | Internal Server Error | Internal server error. Failed to read from process push handle/results. |
4452 | PushMaxAttemptsReached Exception | The maximum number of consecutive failures was reached for the pushHandle. This is configured in the properties file. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/authSample request
{
"operation": "STATUS_OOB_AUTH",
"oobStatusHandle": "AgAgqVJEOKqGBs21PtD09-d7wjHNKMYfBazNyTthD5fFTikDAAgAAAFPGhnJ0QQAAQIBACAdr_wViqU1SXGvQ4Go3MxzbJZCK_X8ysq5NGPYJaoWUw"
}Sample response
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, protocol-specific header extensions, FIDO policy used, OOB Reference ID, post operation rule results, client app information, and payload extensions in additionalInfo.
{
"statusCode":4000,
"id":"wpd-guKGapoYnu8RjTmWgA",
"userName":"zsmith@noknok.com",
"sessionData":{
"sessionKey":"<session JWT>"
},
"additionalInfo":{
"device":{
"id":"123456789abcdef1234567890",
"type":"android",
"info":"NokNok Emulator",
"model":"NokNok-AE 8.0",
"os":"NokNokOS 8.0",
"manufacturer":"NokNok"
},
"protocol":"uaf_1.0",
"authenticatorsResult":[
{
"handle": "WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiR0xXcThRdms0a0JlZGdJeWltNnYxSFJCZG9najFXYjNUQmhXWldSaXpUTSJd",
"uvi":"W_JcFbGZ7Lm5VnQx2iD56xxw6RX94kpyvkKI5E6AjWA",
"uviStatus":4,
"status":4000,
"aaid":"ABCD#ABCD",
"authenticatorVersion":1
}
],
"headerExtensions":[
{
"id":"noknok.uaf.jailbreak",
"data":"{\"status\":0,\"isJailbroken\":false}",
"failIfUnknown":false
}
],
"oobRefId":"US3263",
"authNotificationText":"Hello ZSmith, Please SignIn",
"policyName":"default",
"rulesResult":{
"action":"ALLOW",
"matchedRules":[
{
"name":"LocationVelocity",
"riskScore":0,
"template":"DummyRule",
"group":"dummy group"
}
]
},
"app":{
"id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
"name":"android:com.noknok.test.client"
},
"extensions":[
{
"id":"noknok.wifi.ssid",
"data":"Oviya",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.wifi.ssid",
"data":"Oviya",
"operation":"INIT_OOB_AUTH"
},
{
"id":"noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.uaf.ipaddress",
"data":"192.168.0.102",
"operation":"FINISH_OOB_AUTH"
},
{
"id":"noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"operation":"INIT_OOB_AUTH"
},
{
"id":"noknok.uaf.ipaddress",
"data":"192.168.0.102",
"operation":"INIT_OOB_AUTH"
}
]
},
"push":{
"status":4000,
"handleLifetimeDays":30,
"createdTimeStamp":"2020-09-08T06:16:10.140Z",
"pushHandle": "a2V5aGFuZGxlAAAAAWyLuE2STktsPwSze03zNKRfQHY-h_YA-y_1seI419B-VqMQAdLTT3gLA1NVxAn1XYqLvHLkua_Pz4TV4c4ft3l-YnfGo7euiOE4XC2kg7bhbMO0PIOYqcU"
}
}CANCEL_STATUS_OOB_AUTH
Cancels OOB step-up authentication operation from the first device (initiating device) on the Server.
Request
Attribute | Description |
|---|---|
operation | Required. The string CANCEL_STATUS_OOB_AUTH. |
callerOrigin | Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
oobStatusHandle | Required. Uniquely identifies the OOB authentication operation you want to cancel on the first device. Use the oobStatusHandle returned in the response from START_OOB_AUTH. An alphanumeric string, maximum 4000 characters. |
optionsData | Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
sessionData | Optional. An object containing the user's session information. See SessionData. |
sessionData.sessionKey | Optional. To perform step-up authentication, assign a valid JWT session token to sessionData.sessionKey. |
sessionData.userName | Optional. The user who is canceling the operation. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
id | A unique id that correlates different requests comprising an operation for the same user. A Base64-URL encoded string. By using this ID, your app can query to get the details of this operation |
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
Response Status Codes
The following are the descriptions of the Auth Server status codes returned by CANCEL_STATUS_OOB_AUTH. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | Authentication request canceled successfully. |
4402 | Security Exception | Cancel input validation against DB. Data failed. Failed to validate extension data. |
4404 | Internal Server Error | Internal server error. Failed to read required properties. |
4406 | Payload Exception | Parameter oobStatusHandle is empty. |
4453 | OperationAlreadyCompleted | Unable to cancel even if the operation is completed. |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/authSample request
{
"operation":"CANCEL_STATUS_OOB_AUTH",
"sessionData":{
"userName":"zsmith@noknok.com"
},
"oobStatusHandle":"AgAgHd-r9hUWNDFQvMjztYqRSuWiKuY_FzwpWoCY1mxoRwgDAAgAAAFPiWEc8AQAAQIBACAdZXnNBsqG-uSgW8ORh90Lw9qkPbmVcMzUN25xEq7LGw"
}Sample response
{
"id":"CANCEL_STATUS_OOB_AUTH_1439254148310",
"statusCode":"4000"
}VERIFY
Completes FIDO authentication method verification using the provided method data. If there are pending methods in the authentication sequence to process, VERIFY transitions the verification process to the next step. Call this operation from the first device.
VERIFY expects to receive data specific to the method in the method.data request attribute.
FIDO authentication: An opaque message generated by the App SDK. Assign to method.data.message.
For more details about method.data, see Data Field Contents by Authentication Method.
VERIFY returns 4000 if authentication was successful and the method was the last one in the authentication sequence. Otherwise, if authentication is successful and there are pending methods, VERIFY returns 4005.
Request
Attribute | Description |
|---|---|
operation | Required. The string VERIFY. |
callerOrigin | Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
locale | Optional. The Server uses locale, in subsequent calls to email OTP and SMS OTP, to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US. |
method | Required. Authentication method being verified. Authentication Method. method.data contains fields specific to the authentication method. See the description for VERIFY above. |
optionsData | Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
sessionData | Optional. An object containing the user's session information. See SessionData. If you send sessionData in the request to INIT_ADAPTIVE, you must also include it in the request to VERIFY. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
id | The unique id that correlates different requests comprising an operation. A Base64-URL encoded string. If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown. |
method | Result of method that was used for verification. Authentication Method. Check the following fields in Method for results:
|
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
The following attributes are present in the response upon a successful operation (Server status of 4000).
Attribute | Description |
|---|---|
additionalInfo | An object containing information about the client app and device that is initiating authentication. See AdditionalInfo. In order for the API Server to return this information,
|
completedMethods | Contains the methods that were completed during the Adaptive Authentication. List<Authentication Method> Present in the response when Adaptive Authentication is completed (statusCode = 4000). |
authSequences | Present when there are pending methods in the authentication sequence to complete verification. Map<String, AuthSequence> Not present when one of the following occurs:
|
claims | Returned if the successful Authentication Rule has claims defined for it and the user authenticated successfully using one of the rule's authentication sequences. Claims are an arbitrary name-value pair of information that the client wants returned on successful authentication, like "MariposaIndex: 55". Map<String,String> Present in the response when Adaptive Authentication is completed (statusCode = 4000). |
ruleSetResult | ruleSetResult contains information about the Authentication Rule that succeeded such as its name and action. If ruleSetResult.action was TRIGGER_AUTHENTICATION, then it also contains the authentication sequence ID that the user successfully authenticated with. AdaptiveRuleSetResult |
sessionData | An object representing the authenticated user's session information. See SessionData. |
userNames | Contains a value when Quick Authentication is performed. The name(s) of the authenticated user(s). Set<String> Contains a single username when Quick Authentication is performed for a built-in authentication method. In the future, this could be a list of users, if required by a custom authentication method. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by VERIFY. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | Request has been created successfully. |
4002 | OK. Optional security checks failed | Failed to validate ChannelBinding |
4005 | Operation in progress. | Request has been created successfully. Use Correlation ID (id returned from this operation) when retrying an authentication method if the state is failed or trying the next method as determined by the FIDO policy if the state is succeeded. |
4401 | Operation expired | An operation expires when:
|
4402 | Security Exception |
|
4403 | PolicyVerificationException | The user does not have any registered methods that can be used to complete authentication with the remaining methods in the authentication sequence. |
4404 | Internal Server Error | Internal server error. Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Unacceptable content in request | One or more mandatory attributes are missing. |
4452 | Maximum attempts reached | maxRetriesAllowedPerMethod configured for the method was reached. For FIDO methods the retry count is restricted to 1 |
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/authSample request for the FIDO OOB method
{
"operation":"VERIFY",
"sessionData": {
"userName":"zsmith@noknok.com"
},
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"statusHandle":"chVFAHsKhe5001ahACOXPFptjuui2hqOVqyjn3b_cRg"
}
}Sample response before INIT_OOB_AUTH
{
"statusCode":4005,
"id":"MNx4lXzXVIEg1D0dPOVopg",
"additionalInfo":{
},
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"state":"IN_PROGRESS",
"statusHandle":"chVFAHsKhe5001ahACOXPFptjuui2hqOVqyjn3b_cRg",
"lifetimeMillis":144000
}
}Sample response after INIT_OOB_AUTH
A developer updated the response filter configuration so the API Server returns the protocol and app information in additionalInfo.
{
"statusCode":4005,
"id":"MNx4lXzXVIEg1D0dPOVopg",
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"state":"PENDING",
"statusHandle":"chVFAHsKhe5001ahACOXPFptjuui2hqOVqyjn3b_cRg",
"lifetimeMillis":89000,
"data":{
"additionalInfo":{
"device":{
"id":"123456789abcdef1234567892",
"type":"android",
"info":"OneSpan's device",
"model":"Galaxy S20",
"os":"Android 12",
"manufacturer":"Samsung"
},
"protocol":"uaf_1.0",
"app":{
"id":"com.noknok.android.Passport",
"name":"Passport"
}
}
}
}
}Sample response after FINISH_OOB_AUTH
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, protocol-specific header extensions, OOB Reference ID, FIDO policy used, post operation rule results, client app information, and payload extensions in additionalInfo.
{
"userNames":[
"zsmith@noknok.com"
],
"statusCode":4000,
"id":"4Ozvsvlokjh5ivfGpsnnJQ",
"additionalInfo":{
"elapsedTime": 48,
"extensions":[
{
"id":"noknok.uaf.location",
"data":"{\"status\":0,latitude\":18.579626,\"longitude\":73.7375278}",
"operation":"INIT_ADAPTIVE"
}
]
},
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"state":"SUCCEEDED",
"data":{
"push":{
"status":4000,
"pushHandle":
"a2V5aGFuZGxlAAAAAcsNoC48Y7h_5ZbGF9d7jJDwzeA2TudBcl33rzxIq9rqh35bDQML-21Nb60YFjBqSvtVs8YC-bHoEWGEk9KQfxQeR-zTUOizANjzW4Ilzn8oRgzLZlr_vEA",
"handleLifetimeDays":30
},
"statusCode":4000,
"additionalInfo":{
"elapsedTime": 38,
"device":{
"id":"123456789abcdef1234567890",
"type":"android",
"info":"NokNok Emulator",
"model":"NokNok-AE 7.0",
"os":"NokNokOS 7.0",
"manufacturer":"NokNok"
},
"protocol":"uaf_1.0",
"authenticatorsResult":[
{
"handle":
"WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiMTB4NmJNMlp3MFRlZUI0U0RWbk9uSktjd3RTYXZ5M2V0UDJpUXV3MWNSayJd",
"uvi":"ddyeQOkRepDpAnEh_27mvLwwjlt_WNg4BvzI2St0poA",
"uviStatus":4,
"status":4000,
"aaid":"ABCD#ABCD",
"authenticatorVersion":1
}
],
"headerExtensions":[
{
"id":"noknok.uaf.jailbreak",
"data":"{\"status\":0,\"isJailbroken\":false}",
"fail_if_unknown":false
}
],
"oobRefId":"US3263",
"authNotificationText":"Hello Mr. Smith, Please SignIn",
"policyName":"default",
"rulesResult":{
"action":"ALLOW",
"matchedRules":[
{
"name":"LocationVelocity",
"riskScore":0,
"template":"DummyRule",
"group":"dummy group"
}
]
},
"app":{
"id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
"name":"android:com.noknok.test.client"
},
"extensions":[
{
"operation":"FINISH_OOB_AUTH",
"id":"noknok.uaf.location",
"data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,
\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown":false
},
{
"operation":"INIT_OOB_AUTH",
"id":"noknok.uaf.location",
"data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,
\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown":false
}
]
}
},
"statusHandle":"lOEHifV1cNPmRexktdcdqC56ftTUrIY4v7xrx7X2A4s"
},
"ruleSetResult":{
"action":"TRIGGER_AUTHENTICATION",
"ruleSetName":"adaptive",
"ruleName":"transactionAmountLessThanEqualTo30AndroidOOB",
"authSequenceId":"authSequence12"
}
}CANCEL_VERIFY
Called from the first device, this operation cancels verification of the provided method. This is often used for FIDO OOB to allow the user to cancel out of scanning a QR code. Authentication fails when this happens.
Request
Attribute | Description |
|---|---|
operation | Required. The string CANCEL_VERIFY. |
callerOrigin | Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin. |
locale | Optional. The Server uses locale to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US. |
method | Required. The method whose authentication is being cancelled. Authentication Method. |
optionsData | Optional. An object used to pass additional attributes to REST API operations. See OptionsData for a complete description. |
sessionData | Optional. An object containing the user's session information. See SessionData. If you send sessionData in the request to INIT_ADAPTIVE, you must also include it in the request to VERIFY. |
Response
The following attributes are always present in the JSON payload of the response.
Attribute | Description |
|---|---|
id | The unique id that correlates different requests comprising an operation. A Base64-URL encoded string. If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown. |
method | Result of method that was used for verification. Authentication Method. Check the following fields in Method for results:
|
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. See Response Status Codes below for the status and error codes. |
Response status codes
The following are the descriptions of the Auth Server status codes returned by CANCEL_VERIFY. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.
Server Status Code | Description | Examples |
|---|---|---|
4000 | OK. Operation completed | The authentication method was successfully cancelled. |
4401 | Operation expired | An operation expires when:
|
4402 | Security exception | The wrong value was entered for statushandle. |
4404 | Internal Server Error | Internal server error. Failed to read from the database. Failed to connect to the database. Failed to read required properties. |
4406 | Unacceptable content in the request | One or more of the following mandatory attributes are missing:
|
Samples
Sample request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/authSample request with FIDO OOB method
{
"operation":"CANCEL_VERIFY",
"sessionData": {
"userName":"zsmith@noknok.com"
},
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"statusHandle":"Ptcnfxx1Wm1BzWUoTkx9FnAPXL3Ns4muvp5M1NE7WpE"
}
}Sample response with FIDO OOB method
{
"statusCode":4000,
"id":"Rk6vEG0-OjzzwUGYV_beHw",
"method":{
"type":"FIDO OOB Auth",
"name":"default",
"state":"CANCELLED",
"statusHandle":"Ptcnfxx1Wm1BzWUoTkx9FnAPXL3Ns4muvp5M1NE7WpE"
}
}