URL: /nnlgateway/nnl/<tenantID>/auth Method: POST |
The category of FIDO authentication includes both FIDO2 and UAF authenticators. This section covers FIDO authentication when it is performed on the first - and only - device. See FIDO Out-of-Band Authentication to see how to implement FIDO authentication on the first device but actually authenticate the user on a second device.
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.
VERIFY expects to receive data specific to the method in the method.data request attribute. Photo ID is the only exception.
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 FIDO auth request
{
"operation": "VERIFY",
"sessionData": {
"userName":"zsmith@noknok.com"
},
"method": {
"type": "FIDO Auth",
"name": "default",
"data": {
"message": "..."
},
"statusHandle": "UGHctLm3PmwjX_WMWKtosefpPZVn7TjKUBYQhqTdXQA"
}
}Sample response for FIDO Auth using the UAF protocol
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, transaction information, and operation rule results in additionalInfo.
{
"userNames":[
"zsmith@noknok.com"
],
"statusCode":4000,
"id":"3iktkgVslhHRiXhuuEyyDw",
"sessionData": {
"sessionKey": "<session JWT>"
},
"method":{
"type":"FIDO Auth",
"name":"default",
"state":"SUCCEEDED",
"data":{
"statusCode":4000,
"message":
"eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7ImFhaWQiOiJBQkNEI0FCQ0QiLCJrZXlJRCI6Il9INVVHRkZacmMxbklicnpFQ3otMlItdVgtX2dMT2xQMHhUMlpTMkZFbkkiLCJzdGF0dXMiOjQwMDB9LHsiYWFpZCI6IkFCQ0QjMDAwMSIsImtleUlEIjoiWS1GY3RhMThRRXRrQmxHWUpNMDZsRHdxazdCenhYQi14emVldzktSW9YbyIsInN0YXR1cyI6NDAwMH0seyJhYWlkIjoiQUJDRCMwMDAyIiwia2V5SUQiOiIxSHVCbm1VUHEwSTIxRkZ1NlZYU3BGVzRmaDdQNE1MVVViUE44RHVtVkZrIiwic3RhdHVzIjo0NDAwfV0sInByb3RvY29sTWVzc2FnZSI6Ilt7XCJoZWFkZXJcIjp7XCJ1cHZcIjp7XCJtYWpvclwiOjEsXCJtaW5vclwiOjB9LFwib3BcIjpcIkRlcmVnXCIsXCJhcHBJRFwiOlwiaHR0cHM6Ly8xMjcuMC4wLjE6ODQ0My9TYW1wbGVBcHBcIn0sXCJhdXRoZW50aWNhdG9yc1wiOlt7XCJhYWlkXCI6XCJBQkNEIzAwMDJcIixcImtleUlEXCI6XCIxSHVCbm1VUHEwSTIxRkZ1NlZYU3BGVzRmaDdQNE1MVVViUE44RHVtVkZrXCJ9XX1dIiwiYXBwSUQiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL1NhbXBsZUFwcCIsIm5ld09wZXJhdGlvbiI6IkRFTEVURV9SRUcifSwibm90aWZ5Ijp7InN0YXR1cyI6NDAwMH0sInZlcnNpb24iOiIxLjAiLCJvcGVyYXRpb24iOiJGSU5JU0hfQVVUSCIsInByb3RvY29sIjoidWFmXzEuMCJ9"
},
"additionalInfo":{
"protocol":"uaf_1.0",
"authenticatorsResult":[
{
"handle":
"WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiX0g1VUdGRlpyYzFuSWJyekVDei0yUi11WC1fZ0xPbFAweFQyWlMyRkVuSSJd",
"uvi":"Dmdyjz_UJxwMCUwoeFyGj0CvMkeFvrOSmrSnMeF87-o",
"uviStatus":4,
"status":4000,
"aaid":"ABCD#ABCD",
"authenticatorVersion":1
},
{
"handle":
"WyJ1YWZfMS4wIiwiQUJDRCMwMDAxIiwiWS1GY3RhMThRRXRrQmxHWUpNMDZsRHdxazdCenhYQi14emVldzktSW9YbyJd",
"uvi":"VBX9HaWNRSXTlXpw1JMz1aSjxNswfw5y2bxlIOjERWw",
"uviStatus":4,
"status":4000,
"aaid":"ABCD#0001",
"authenticatorVersion":1,
"transactionResult":{
"hash": "xE7sNci-TFI7leurVFxrTqW3CTh_1qinfzm61ySXFDg",
"hashAlgorithm":"SHA-256"
}
},
{
"handle":
"WyJ1YWZfMS4wIiwiQUJDRCMwMDAyIiwiMUh1Qm5tVVBxMEkyMUZGdTZWWFNwRlc0Zmg3UDRNTFVVYlBOOER1bVZGayJd",
"status":4400,
"aaid":"ABCD#0002",
"authenticatorVersion":1
}
],
"transaction":{
"id":"23458542351874875"
},
"policyName":"default",
"rulesResult":{
"action":"ALLOW",
"matchedRules":[
{
"name":"LocationVelocity",
"riskScore":0,
"template":"DummyRule",
"group":"dummy group"
}
]
}
},
"statusHandle":"_X4Vhn1yZl3wvxYPCfE37lLeRCDnAuYNA7Ro9ZMjxAU"
},
"ruleSetResult":{
"action":"TRIGGER_AUTHENTICATION",
"ruleSetName":"adaptive",
"ruleName":"transactionAmountBigAndroid",
"authSequenceId":"authSequence1",
"riskScore":5
},
"claims":{
"enable3DSBlob":"true",
"claim":"claimValue"
}
}Sample response for a FIDO auth method using the web protocol
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, post operation rule results, and payload extensions in additionalInfo.
{
"userNames":[
"zsmith@noknok.com"
],
"statusCode":4000,
"id":"x0datRt1xZO1K44Xc0ZJMg",
"sessionData":{
"sessionKey":"<session JWT>"
},
"method":{
"type":"FIDO Auth",
"name":"default",
"state":"SUCCEEDED",
"data":{
"message":
"eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7InN0YXR1cyI6NDAwMH1dfSwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9BVVRIIiwicHJvdG9jb2wiOiJ3ZWJfMS4wIn0"
},
"statusCode":4000,
"additionalInfo":{
"protocol":"web_1.0",
"authenticatorsResult":[
{
"handle":
"WyJ3ZWIiLCJhYmNkZWYxMi0zNDU2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJnNW15NjhBWTF5cWt6RHRnRklDYUtINTdoNDg5OThwN0xDbldibmlHYVFzIl0",
"status":4000,
"aaguid":"abcdef12-3456-7890-abcd-ef1234567890",
"attestationFormat":"packed",
"authenticatorAttachment": "cross-platform",
"authenticatorVersion":0,
"credentialID":"g5my68AY1yqkzDtgFICaKH57h48998p7LCnWbniGaQs",
"userPresence":false,
"userVerification":true,
"transactionResult":{
"hash":"xE7sNci-TFI7leurVFxrTqW3CTh_1qinfzm61ySXFDg",
"nonce":"GO-AgAXvdKF-Wr-0FVQ4-g",
"serverChallenge":"16PktuaFPMwrhLjmJ6OH3BMott5Trb4ZZHdgg75K008",
"hashAlgorithm":"SHA-256"
}
}
],
"rulesResult":{
"action":"ALLOW",
"matchedRules":[
{
"name":"LocationVelocity",
"riskScore":0,
"template":"DummyRule",
"group":"dummy group"
}
]
},
"extensions":[
{
"id":"noknok.uaf.location",
"data":
"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
"operation":"INIT_ADAPTIVE"
}
]
},
"statusHandle":"UGHctLm3PmwjX_WMWKtosefpPZVn7TjKUBYQhqTdXQA"
},
"ruleSetResult":{
"action":"TRIGGER_AUTHENTICATION",
"ruleSetName":"adaptive",
"ruleName":"customRuleName",
"authSequenceId":"authSequence1",
"riskScore":5
},
"claims":{
"enable3DSBlob":"true",
"claim":"claimValue"
}
}Sample response for FIDO auth method using the UAF protocol with additional pending methods
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, transaction information, protocol-specific header extensions, FIDO policy used, post operation rule results, client app information, and payload extensions in additionalInfo.
{
"statusCode":4005,
"id":"1UEgjQjQfbn_OtHQBOZxCQ",
"additionalInfo":{
},
"method":{
"type":"FIDO Auth",
"name":"default",
"state":"SUCCEEDED",
"data":{
"message":
"eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7ImFhaWQiOiJBQkNEI0FCQ0QiLCJrZXlJRCI6Il9xdVVfaXpDRk5vWlUxUFVHckdyZXhwa0xkRnNKTE1DR2ZPQWZ1c3ItWWMiLCJzdGF0dXMiOjQwMDB9XSwiYXBwSUQiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL1NhbXBsZUFwcCJ9LCJub3RpZnkiOnsic3RhdHVzIjo0MDAwfSwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9BVVRIIiwicHJvdG9jb2wiOiJ1YWZfMS4wIn0",
"statusCode":4000,
"additionalInfo":{
"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":
"WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiX3F1VV9pekNGTm9aVTFQVUdyR3JleHBrTGRGc0pMTUNHZk9BZnVzci1ZYyJd",
"uvi":"PtCR3Ib8j1n9MHkBtA8vxe4FJQ4zzXcLa89eN3Q_s-Q",
"uviStatus":4,
"status":4000,
"aaid":"ABCD#ABCD",
"authenticatorVersion":1
}
],
"transaction":{
"id":"23458542351874875"
},
"headerExtensions":[
{
"id":"noknok.uaf.jailbreak",
"data":"{\"status\":0,\"isJailbroken\":false}",
"fail_if_unknown":false
}
],
"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":"VERIFY",
"id":"noknok.uaf.location",
"data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-125.482,\"status\":0}",
"fail_if_unknown":false
}
]
}
},
"statusHandle":"Y66k0XLMYQxQHNLP38pRJi2460Y6YPjLuKLsaoQlyws"
},
"authSequences":{
"authSequence5":{
"methods":[
{
"type":"Email OTP",
"name":"OTP Using Email",
"statusHandle":"a2V5aGFuZGxlAAAAAkJimA6d-mU-F34FVXt0OUXEWo0jkSZ6DytGEtKa3f6z4CNOnPIjaztJ0EMRyfZJ7QdIn1ASJXrvtdM3hugycA",
"data":{
"identifiers":[
"dixxxxxxxxx@noknok.com"
],
"reason": "Reason for prompting the user with Email OTP"
}
}
]
}
}
}Sample response for FIDO auth method using web protocol with an AppAttest that indicates the device/app is untrusted
A developer updated the response filter configuration so the API Server returns the protocol, additional authenticator details, post operation rule results, and payload extensions in additionalInfo.
{
"statusCode":4005,
"id":"x0datRt1xZO1K44Xc0ZJMg",
"sessionData":{
"sessionKey":"<session JWT>"
},
"method":{
"type":"FIDO Auth",
"name":"default",
"state":"SUCCEEDED",
"data":{
"message":"eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7InN0YXR1cyI6NDAwMH1dfSwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9BVVRIIiwicHJvdG9jb2wiOiJ3ZWJfMS4wIn0"
},
"statusCode":4000,
"additionalInfo":{
"protocol":"web_1.0",
"authenticatorsResult":[
{
"handle":"WyJ3ZWIiLCJhYmNkZWYxMi0zNDU2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJnNW15NjhBWTF5cWt6RHRnRklDYUtINTdoNDg5OThwN0xDbldibmlHYVFzIl0",
"status":4000,
"aaguid":"abcdef12-3456-7890-abcd-ef1234567890",
"attestationFormat":"packed",
"authenticatorAttachment":"cross-platform",
"authenticatorVersion":0,
"credentialID":"g5my68AY1yqkzDtgFICaKH57h48998p7LCnWbniGaQs",
"userPresence":false,
"userVerification":true,
"backUpEligible":true,
"backedUp":false,
"appAtt":{
"state":"TRUSTED",
"handle":"WyJ3ZWIiLCI2MTcwNzA2MS03NDc0LTY1NzMtNzQ2NC02NTc2NjU2YzZmNzAiLCJQc2RQYnFMZjZFc2REMkItanRXdlhyUFFZMDB0Y29jcFItbTBhZmFaY3pjIiwiV3lKM1pXSWlMQ0kyTVRjd056QTJNUzAzTkRjMExUWTFOek10TnpRMk5DMDJOVGMyTmpVMll6Wm1OekFpTENKUWMyUlFZbkZNWmpaRmMyUkVNa0l0YW5SWGRsaHlVRkZaTURCMFkyOWpjRkl0YlRCaFptRmFZM3BqSWwwIl0",
"status":4000,
"aaguid":"61707061-7474-6573-7464-6576656c6f70",
"attestationFormat":"apple-appattest",
"authenticatorVersion":0,
"credentialID":"PsdPbqLf6EsdD2B-jtWvXrPQY00tcocpR-m0afaZczc",
"userPresence":false,
"userVerification":false,
"backUpEligible":false,
"backedUp":false,
"attachmentHints":[
"internal"
]
}
}
],
"rulesResult":{
"action":"ALLOW",
"matchedRules":[
{
"name":"LocationVelocity",
"riskScore":0,
"template":"DummyRule",
"group":"dummy group"
}
]
},
"extensions":[
{
"id":"noknok.uaf.location",
"data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
"operation":"INIT_ADAPTIVE"
}
]
},
"statusHandle":"UGHctLm3PmwjX_WMWKtosefpPZVn7TjKUBYQhqTdXQA"
},
"ruleSetResult":{
"action":"TRIGGER_AUTHENTICATION",
"ruleSetName":"adaptive",
"ruleName":"customRuleName",
"authSequenceId":"authSequence1",
"riskScore":5
},
"authSequences":{
"authSequence5":{
"methods":[
{
"type":"Email OTP",
"name":"OTP Using Email",
"statusHandle":"a2V5aGFuZGxlAAAAAkJimA6d-mU-F34FVXt0OUXEWo0jkSZ6DytGEtKa3f6z4CNOnPIjaztJ0EMRyfZJ7QdIn1ASJXrvtdM3hugycA",
"data":{
"identifiers":[
"dixxxxxxxxx@noknok.com"
]
}
}
]
}
}
}Sample request for transaction confirmation using FIDO auth and SPC
Information specific to SPC is highlighted below. This information is supplied by the App SDK when it calls VERIFY.
{
"operation":"VERIFY",
"method":{
"type":"FIDO Auth",
"name":"default",
"state":"PENDING",
"data":{
"message":"<message body>",
"additionalInfo":{
"protocol":"web_1.0"
}
},
"statusHandle":"a2V5aGFuZGxlAAAAAlZ4kmk0km3_JMhpC1sx0pnCC5fvrYMHkw62G7-FziZ-4UsNg5O4qvEq6ZyMtvGa_LAELhN0v6TY69mtrrVcJ23kDBQR6h89Cn9QnxUm",
"lifetimeMillis":300000
},
"sessionData":{
"sessionKey":"<session JWT>"
},
"optionsData":{
"transactionText":"Authorize the total of USD 100 payment?"
},
"contextData":{
"payment.payeeName":"Tutorial App",
"payment.payeeOrigin":"https://example.com",
"payment.total.currency":"USD",
"payment.total.value":"100",
"payment.instrument.displayName":"U.S. Bank...1234",
"payment.instrument.icon":"https://example.com/gwtutorial/spc-instrument-icon.png",
"scenario":"Default",
"availableAuthenticationMethods":"FIDO2-AUTH",
"payment.isSPC":true
}
}Sample response for transaction confirmation using FIDO auth and SPC
{
"userNames":[
"zsmith@noknok.com"
],
"statusCode":4000,
"id":"b6fe37d7-34ee-4670-9ca4-2326f24d8c9a",
"method":{
"type":"FIDO Auth",
"name":"default",
"state":"SUCCEEDED",
"data":{
"message":"<message body>",
"statusCode":4000,
"additionalInfo":{
"device":{
"id":"fc23fb21-cbc8-4cdd-91c0-4bfd1ce04c6c",
"type":"browser",
"info":"Google Chrome on macOS",
"os":"macOS 13.2.0"
},
"authenticatorsResult":[
{
"handle":"WyJ3ZWIiLCJhZGNlMDAwMi0zNWJjLWM2MGEtNjQ4Yi0wYjI1ZjFmMDU1MDMiLCJ0eHdvMVR2Z2hXRmxZUXFDa1RaMnZiSjJkZDIwSFdPb2l4c1RmcUVOSkpFIl0"
}
]
}
},
"statusHandle":"a2V5aGFuZGxlAAAAAlZ4kmk0km3_JMhpC1sx0pnCC5fvrYMHkw62G7-FziZ-4UsNg5O4qvEq6ZyMtvGa_LAELhN0v6TY69mtrrVcJ23kDBQR6h89Cn9QnxUm"
},
"ruleSetResult":{
"action":"TRIGGER_AUTHENTICATION",
"ruleSetName":"tutorial",
"ruleName":"Default",
"authSequenceId":"authenticationSequence_1",
"riskScore":0
},
"claims":{
"enable3DSBlob":"true"
},
"sessionData":{
"emv3dsData":"<emv3dsData JWS>",
"tcToken":"<tcToken JWT>"
},
"additionalInfo":{}
}Sample Fido Protocol Response Showing metadata for UAF protocol when needDetails = 4. When the protocol is UAF, the response includes metadata-specific information in the additionalInfo.authenticatorsResult.metadata section.
{
"userNames": [
"user1"
],
"statusCode": 4000,
"id": "bvh_FPXJMC43HIkl2D1-SA",
"additionalInfo": {
"device": {
"id": "123456789abcdef1234567890",
"type": "android",
"info": "NokNok Emulator",
"model": "NokNok-AE 7.0",
"os": "NokNokOS 7.0",
"manufacturer": "NokNok",
"supportsPlatformAuthenticator": true
},
"app": {
"id": "android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
"name": "android:com.noknok.test.client",
"qrSupported": true
},
"extensions": [
{
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"operation": "INIT_ADAPTIVE"
},
{
"id": "noknok.wifi.ssid",
"data": "Oviya",
"operation": "INIT_ADAPTIVE"
},
{
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"operation": "INIT_ADAPTIVE"
},
{
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"operation": "INIT_ADAPTIVE"
}
],
"adaptiveAuthTime": 89495,
"statusMessage": "Ok"
},
"method": {
"type": "FIDO Auth",
"name": "default",
"state": "SUCCEEDED",
"data": {
"message": "eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7ImFhaWQiOiI0ZTRlI2FiY2QiLCJrZXlJRCI6IlFSLUZDNWRsbGE0eW1yRkE5d1FhVkY5MkFGZG5DeUp3dGhXcS1NOHlzNzgiLCJzdGF0dXMiOjQwMDB9XSwiYXBwSUQiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL1NhbXBsZUFwcCJ9LCJ2ZXJzaW9uIjoiMS4wIiwib3BlcmF0aW9uIjoiRklOSVNIX0FVVEgiLCJwcm90b2NvbCI6InVhZl8xLjAifQ",
"additionalInfo": {
"device": {
"id": "123456789abcdef1234567890",
"type": "android",
"info": "NokNok Emulator",
"model": "NokNok-AE 7.0",
"os": "NokNokOS 7.0",
"manufacturer": "NokNok",
"supportsPlatformAuthenticator": true
},
"protocol": "uaf_1.0",
"authenticatorsResult": [
{
"handle": "WyJ1YWZfMS4wIiwiNGU0ZSNhYmNkIiwiUVItRkM1ZGxsYTR5bXJGQTl3UWFWRjkyQUZkbkN5Snd0aFdxLU04eXM3OCJd",
"status": 4000,
"aaid": "4e4e#abcd",
"authenticatorVersion": 1,
"appAtt": {
"state": "NOT_APPLICABLE"
},
"attachmentHints": [
"internal"
],
"metadata": {
"aaid": "4e4e#abcd",
"description": "4e4e#abcd description",
"authenticatorVersion": 1,
"userVerificationMethods": [
[
{
"userVerificationMethod": "passcode_internal"
}
],
[
{
"userVerificationMethod": "fingerprint_internal"
}
]
],
"keyProtectionsList": [
"KEY_PROTECTION_TEE"
],
"matcherProtection": [
"MATCHER_PROTECTION_ON_CHIP"
],
"isKeyRestricted": true,
"isFreshUserVerificationRequired": true,
"attestationTypes": [
self
],
"authenticatorSpecCustomAttributes": {
"authenticatorFidoCertificationLevel": "FIDO_CERTIFIED_L1",
"authenticatorFipsCertificationLevel": "FIPS140_CERTIFIED_L1_PHY_2"
}
}
}
],
"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": true
},
"extensions": [
{
"operation": "VERIFY",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
}
]
},
"statusCode": 4000
},
"statusHandle": "AAAAAAAAAAEF0Q9T0atKW6mL7ACFekhgLq78kD03UaLf98THwLRU2S6SPaeOabpNdJogCUgv7OvKZhtlO46EvIYqOTTJqCg"
},
"completedMethods": [
{
"type": "FIDO Auth",
"name": "default",
"state": "SUCCEEDED",
"data": {
"message": "eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7ImFhaWQiOiI0ZTRlI2FiY2QiLCJrZXlJRCI6IlFSLUZDNWRsbGE0eW1yRkE5d1FhVkY5MkFGZG5DeUp3dGhXcS1NOHlzNzgiLCJzdGF0dXMiOjQwMDB9XSwiYXBwSUQiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL1NhbXBsZUFwcCJ9LCJ2ZXJzaW9uIjoiMS4wIiwib3BlcmF0aW9uIjoiRklOSVNIX0FVVEgiLCJwcm90b2NvbCI6InVhZl8xLjAifQ",
"additionalInfo": {
"device": {
"id": "123456789abcdef1234567890",
"type": "android",
"info": "NokNok Emulator",
"model": "NokNok-AE 7.0",
"os": "NokNokOS 7.0",
"manufacturer": "NokNok",
"supportsPlatformAuthenticator": true
},
"protocol": "uaf_1.0",
"authenticatorsResult": [
{
"handle": "WyJ1YWZfMS4wIiwiNGU0ZSNhYmNkIiwiUVItRkM1ZGxsYTR5bXJGQTl3UWFWRjkyQUZkbkN5Snd0aFdxLU04eXM3OCJd",
"status": 4000,
"aaid": "4e4e#abcd",
"authenticatorVersion": 1,
"appAtt": {
"state": "NOT_APPLICABLE"
},
"attachmentHints": [
"internal"
],
"metadata": {
"aaid": "4e4e#abcd",
"description": "4e4e#abcd description",
"authenticatorVersion": 1,
"userVerificationMethods": [
[
{
"userVerificationMethod": "passcode_internal"
}
],
[
{
"userVerificationMethod": "fingerprint_internal"
}
]
],
"keyProtectionsList": [
"KEY_PROTECTION_TEE"
],
"matcherProtection": [
"MATCHER_PROTECTION_ON_CHIP"
],
"isKeyRestricted": true,
"isFreshUserVerificationRequired": true,
"attestationTypes": [
Self
],
"authenticatorSpecCustomAttributes": {
"authenticatorFidoCertificationLevel": "FIDO_CERTIFIED_L1",
"authenticatorFipsCertificationLevel": "FIPS140_CERTIFIED_L1_PHY_2"
}
}
}
],
"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": true
},
"extensions": [
{
"operation": "VERIFY",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
}
]
},
"statusCode": 4000
},
"statusHandle": "AAAAAAAAAAEF0Q9T0atKW6mL7ACFekhgLq78kD03UaLf98THwLRU2S6SPaeOabpNdJogCUgv7OvKZhtlO46EvIYqOTTJqCg"
}
],
"ruleSetResult": {
"action": "TRIGGER_AUTHENTICATION",
"ruleSetName": "default",
"ruleName": "defaultRule",
"authSequenceId": "authenticationSequence_1"
}
}
Sample Fido authentication response for metadata field for web protocol with needDetails = 4. When the protocol is web, the response includes metadata-specific information in the additionalInfo.authenticatorsResult.metadata section.
{
"userNames": [
"user1"
],
"statusCode": 4000,
"id": "d-om1cvqbYKXe-s293zRuw",
"additionalInfo": {
"device": {
"id": "abcde12345fghij",
"type": "browser",
"info": "NokNok Emulator",
"model": "NokNok-AE 7.0",
"os": "NokNokOS 7.0",
"manufacturer": "NokNok",
"supportsPlatformAuthenticator": true
},
"app": {
"id": "android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
"name": "android:com.noknok.test.client",
"qrSupported": true
},
"extensions": [
{
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"operation": "INIT_ADAPTIVE"
},
{
"id": "noknok.wifi.ssid",
"data": "Oviya",
"operation": "INIT_ADAPTIVE"
},
{
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"operation": "INIT_ADAPTIVE"
},
{
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"operation": "INIT_ADAPTIVE"
}
],
"adaptiveAuthTime": 42465,
"statusMessage": "Ok"
},
"method": {
"type": "FIDO Auth",
"name": "default",
"state": "SUCCEEDED",
"data": {
"message": "eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7InN0YXR1cyI6NDAwMH1dfSwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9BVVRIIiwicHJvdG9jb2wiOiJ3ZWJfMS4wIn0",
"additionalInfo": {
"device": {
"id": "abcde12345fghij",
"type": "browser",
"info": "NokNok Emulator",
"model": "NokNok-AE 7.0",
"os": "NokNokOS 7.0",
"manufacturer": "NokNok",
"supportsPlatformAuthenticator": true
},
"protocol": "web_1.0",
"authenticatorsResult": [
{
"handle": "WyJ3ZWIiLCIwNjBiMmIwNi0wMTA0LTAxODItZTUxYy0wMTAxMDQwNDEyMDQiLCJIajdIWWpzcmxuS0ZnNFNCdWtlWXd4RGJhaDZsekhLbUtsNUFRc2NzZW9VIl0",
"status": 4000,
"aaguid": "060b2b06-0104-0182-e51c-010104041204",
"attestationFormat": "packed",
"authenticatorVersion": 0,
"credentialID": "Hj7HYjsrlnKFg4SBukeYwxDbah6lzHKmKl5AQscseoU",
"userPresence": true,
"userVerification": true,
"backUpEligible": true,
"backedUp": false,
"dpk": {
"state": "UNAVAILABLE"
},
"appAtt": {
"state": "NOT_APPLICABLE"
},
"attachmentHints": [
"internal"
],
"authenticatorAttachment": "platform",
"metadata": {
"aaguid": "060b2b0601040182e51c010104041204",
"description": "Generic webauthn authenticator",
"authenticatorVersion": 0,
"userVerificationMethods": [
[
{
"userVerificationMethod": "presence_internal"
}
]
],
"keyProtectionsList": [
"KEY_PROTECTION_HARDWARE",
"KEY_PROTECTION_TEE"
],
"matcherProtection": [
"MATCHER_PROTECTION_TEE",
"MATCHER_PROTECTION_ON_CHIP"
],
"isKeyRestricted": true,
"isFreshUserVerificationRequired": true,
"attestationTypes": [
null
],
"authenticatorSpecCustomAttributes": {
"authenticatorFidoCertificationLevel": "FIDO_CERTIFIED_L1",
"authenticatorFipsCertificationLevel": "FIPS140_CERTIFIED_L1_PHY_2"
}
}
}
],
"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": true
},
"extensions": [
{
"operation": "VERIFY",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
}
]
},
"statusCode": 4000
},
"statusHandle": "AAAAAAAAAAGaIjeyH5qN4LKaS6txr3U8Bf4pTFul1mrPwP3fTfIaiv58z5xAH5qStoGOOueU7oWNvZYS1p0tMylHTc4-pPw"
},
"completedMethods": [
{
"type": "FIDO Auth",
"name": "default",
"state": "SUCCEEDED",
"data": {
"message": "eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7InN0YXR1cyI6NDAwMH1dfSwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9BVVRIIiwicHJvdG9jb2wiOiJ3ZWJfMS4wIn0",
"additionalInfo": {
"device": {
"id": "abcde12345fghij",
"type": "browser",
"info": "NokNok Emulator",
"model": "NokNok-AE 7.0",
"os": "NokNokOS 7.0",
"manufacturer": "NokNok",
"supportsPlatformAuthenticator": true
},
"protocol": "web_1.0",
"authenticatorsResult": [
{
"handle": "WyJ3ZWIiLCIwNjBiMmIwNi0wMTA0LTAxODItZTUxYy0wMTAxMDQwNDEyMDQiLCJIajdIWWpzcmxuS0ZnNFNCdWtlWXd4RGJhaDZsekhLbUtsNUFRc2NzZW9VIl0",
"status": 4000,
"aaguid": "060b2b06-0104-0182-e51c-010104041204",
"attestationFormat": "packed",
"authenticatorVersion": 0,
"credentialID": "Hj7HYjsrlnKFg4SBukeYwxDbah6lzHKmKl5AQscseoU",
"userPresence": true,
"userVerification": true,
"backUpEligible": true,
"backedUp": false,
"dpk": {
"state": "UNAVAILABLE"
},
"appAtt": {
"state": "NOT_APPLICABLE"
},
"attachmentHints": [
"internal"
],
"authenticatorAttachment": "platform",
"metadata": {
"aaguid": "060b2b0601040182e51c010104041204",
"description": "Generic webauthn authenticator",
"authenticatorVersion": 0,
"userVerificationMethods": [
[
{
"userVerificationMethod": "presence_internal"
}
]
],
"keyProtectionsList": [
"KEY_PROTECTION_HARDWARE",
"KEY_PROTECTION_TEE"
],
"matcherProtection": [
"MATCHER_PROTECTION_TEE",
"MATCHER_PROTECTION_ON_CHIP"
],
"isKeyRestricted": true,
"isFreshUserVerificationRequired": true,
"attestationTypes": [
self
],
"authenticatorSpecCustomAttributes": {
"authenticatorFidoCertificationLevel": "FIDO_CERTIFIED_L1",
"authenticatorFipsCertificationLevel": "FIPS140_CERTIFIED_L1_PHY_2"
}
}
}
],
"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": true
},
"extensions": [
{
"operation": "VERIFY",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.ipaddress",
"data": "192.168.0.102",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.wifi.ssid",
"data": "Oviya",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.location",
"data": "{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
"fail_if_unknown": false
},
{
"operation": "VERIFY",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
},
{
"operation": "INIT_ADAPTIVE",
"id": "noknok.uaf.jailbreak",
"data": "{\n \"status\" : \"0\",\n \"isJailbroken\" : \"false\"\n}",
"fail_if_unknown": false
}
]
},
"statusCode": 4000
},
"statusHandle": "AAAAAAAAAAGaIjeyH5qN4LKaS6txr3U8Bf4pTFul1mrPwP3fTfIaiv58z5xAH5qStoGOOueU7oWNvZYS1p0tMylHTc4-pPw"
}
],
"ruleSetResult": {
"action": "TRIGGER_AUTHENTICATION",
"ruleSetName": "default",
"ruleName": "defaultRule",
"authSequenceId": "authenticationSequence_1"
}
}
CANCEL_VERIFY
Cancels verification of the provided method. 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>/auth