Out-of-band registration

Although registration is triggered from a first device (usually a desktop browser) that starts OOB registration, it is actually completed on a second device (usually a cell phone). The second device sends the requests to initiate OOB registration and finish OOB registration. The second device can also cancel the OOB registration. There are also 2 status operations: one for registration and the other for cancellation.

The following operations are available:

Out-of-band registrations always use the FIDO protocol, which includes both UAF and FIDO2. In most cases you need to start the OOB registration process by calling INIT_ADAPTIVE_REG, but then you call the operations listed above instead of the corresponding operations in the section FIDO Registration. Once a FIDO OOB registration is completed, manage it just like any other FIDO registration, using the operations in Manage FIDO registrations.

You can choose one or more of the following mechanisms so the user can register an authenticator on the second device to use for future authentication. This document refers to these mechanisms as OOB mode.

• Display a QR code on the first device that the user scans using the second device.

• Use a custom mechanism that you implemented

Implementing a custom OOB mode is outside the scope of this documentation.

You can only register a FIDO authenticator by scanning a QR code or using your custom OOB mode. Any of the three OOB modes (QR code, push notification, or custom OOB) can be used to authenticate.

See FIDO Registration to understand how the API Server determines the FIDO policy to use for OOB registration. To perform OOB registration, the Authentication Server uses the FIDO registration 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 registration 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_REG based on the policy configuration.

Refer to Create FIDO Policies to create an authentication policy.

START_OOB_REG

Starts out-of-band registration from the first device.

Use the boolean attributes defined on the oobMode object to specify the OOB mode you want registration to use. You must specify at least one OOB mode.

• oobMode.qr - to generate a QR code

• oobMode.rawdata - to use your own custom OOB mode.

If successful, START_OOB_REG generates and returns a string for the QR code image that the first device displays to initiate registration.

Request

Response

The following attributes are always present in the JSON payload of the response.

The following attributes are present in the response upon a successful operation (Server status code 4000).

Response status codes

The following are the descriptions of the Auth Server status codes returned by START_OOB_REG. 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.

Samples

Sample request URL

https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/reg

Sample request

{
    "operation":"START_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"sample",
    "oobRefId":"12345",
    "oobMode":{
        "qr":"true"
    }
}

Sample 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":"a2V5aGFuZGxlAAAAAj-qU25O-OOk3m308NX9CPlEVKJkR6q0447dLIszkI9uoln1U0TEi0DU1Arnc7CPNxDdNebgltEAHogj2DQ2yt2XNVPcVlclVV47-LzAV1aZyCUN38hA_Tof5O8",
  "modeResult":{
    "qrCode":{
      "qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC9ElEQVR4Xu2YUW4DIQxEuYHvf0vfgM4bSKvQSu1XZz/wRskufonA9hjaMf9iPc6RH+1ih13ssIsddrHDLnbYxQ7bWI8xZhWPLdsPaziO6aWxHl2zphg91CiG85iAWaNFzS5dkxWUh5+AMWuRTFqxHXoR6GdgjqTWoHR3EVvK4AkYZDN57kXx5i8+AGPeP9gpmQRmK1KuwK6ZK8BfriRmKW+Ue2DdlSyOKfF2FNJpiWVSloXC85ianqbOAug2WyvK++tXgpinK9b9xe2vXJDfspDAmDVy5lE36Hmyg6DvOOa2N2iD7dmv1K/vhTFpZDi29GWTrsntjmJbutYNAD1HiyDqcYyoIpBCMMa9oMFHGgNkiOiy7254cmiJY+5/mjNnASqTBwpzUVGM2dpBsuF4GyjozML/Y9w1MybjqgDHVtTePbIYgllemqC8n895DOfqMUxbq9g777GECIZC2NMAUY5yPng8lZXAercV2h93xRbCoWq7gxg9kCUsBRPVItBEPY7hkYtx6pIY77uXO4c1F0783JP1wed7R4pgJJztFqUMDlDcEPRlSYxFTJJP91uKRsvtUk1jVrN79Eq310CI948kscbheDLAk3shh4I05v7sJehC08R5xTiPDSJMb6Y0mXt7f6MI0hiNufGL4shuirftTmKruRQNZroFomXm/60jBbDVY9guiDLt0KXw0kwSY/cv/tmqVaAdd0SK8kx9AqOvsIpaCgagK+4VZDFRmjU1Sba1HnmoVBdDFtOHJQM1HGi6jajxXpYRjJaMlntBOJs/yb5+JogBkXtaM7Xoo9Qr81GMZ/ze39rC5qtceWxPuS3m4fHitHK0mgxGiNEHb2vbtaJPZQUwa5dhGGqRrkNhLsVkMV7sIQgZNwryEh6AMXHH1gkHZvNlXc/A6M3uNGy7VCVpX2uIYzTp8qbbvtiD37fdDGZy0qGRNccVFuG1xLHhPZaEczLgjm+OXZVR7De72GEXO+xih13ssIsddrHD/op9AHTt+9RovXr6AAAAAElFTkSuQmCC"
    }
  }
}

Sample request with qrType=UNIVERSAL_ANY_RP

{
    "operation":"START_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"sample",
    "oobRefId":"12345",
    "policyName":"default",
    "oobMode":{
        "qr":"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":"a2V5aGFuZGxlAAAAApz53PPjA9gP61uUhwFZsseZ2q7po5LRzfIQz42Ci4CYO-NY5mTEUiz2JIejaE8l-DtIZpiE79Q76q2OzzAjge5nVc8iiTkGP75xLdUWQXAJ9xDjpHsMnh08HtQ",
  "modeResult":{
    "qrCode":{
      "qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADS0lEQVR4Xu2XbW4bMQxEeQPe/5a8ATtvZBTZTYD0l8dAV3W8svQEiB9Dbmv/ZUzdV34cD3YbD3YbD3YbD3Yb/xs2VbW9zGf0rNa0dtobYYztqjHTw7Y2dJKNNKbl7S6P5t9qYThRn4DB9XGmJ/raT8G0plVN5ecG1c5HYJD6xgKtaEpuFrNvGfJ2rJyTPwzYLOYhhyoRm3yUU7VtUZ8RxLTIhMpit5KVeLsZYYwC6FUJmA9HOEjYv4Q+grkWU6MtEG7NIds1Xy2NYBIMFdkNRLLmo3MDeoAgttx3qcsyxn5eZyUFMY35oq5+WlACeMbxu+oTmP1YczQy/Oqzegl9CKPZct3ChKKridAyeZrF+gT6xB+vagUEN4cxwHPdpvW6BoK6KKYxqgwOtS3cXqfw9LXUZDBcu7yckJNYQfUhO2HDGEG3aMrRljX1ylNbkMQsGc1cXqh8be3IsjqaCWL8dhZydQJPr2NVLr6G/v0YWuHTzkqmJAKABR7F9PMVeXsW4fCKTPhJ0SgmraCRIvj42NXGJJMsBgdI4D315ZE3tTqMrb2piA/3P/WQLLU5YYx9+sZgjQu1l42HMRD+3De4OfLBFhl2ScsApge6JfLIxqF3ih4JZTGqDDlIacHFa9cur3rHxhw2/OfGl7dSGtpCPs6NYuv+gSPd4ViURbwcuI1EMZtQVL7BBv44wX+ALq0tgUkvNkEQfYTo84SyYVGMUoMznYSDU3V12prf3qMY3772cMB+dVPTmqkwxp0RDMqhJi5ubr+7pLFmG3/ScC0XZSgCOv0jiO1pIItLm9Y2LjUnV9OYXzx5ByAxHXVnJm7/mxsxzEWGB333+NZ6edXoIMa3Yiw75GV2oTDHxTGMLWXGluBYsPIh/B7Gli7BihOSNJAJxc+9RCGBIWPfG1VzwM2N1sH5MIYwcCwO5ZQlQ4q6CEUxT5yHi2QK2SxtpFBOHHvF+Ai5MYhKyOkwpqsWNlCoeRD6xRr9vkYhgPGhIp872ww8zIP9KObAE+yyPRayLo9pF2WlsGXDO85OtxO8/AkYwWeXSs31x5vf3Pt2DLLdQvCmGpqLDY0kj5Wb2qsoIxMSlKpDqc5iv44Hu40Hu40Hu40Hu40Hu435A9M32o5puUR1AAAAAElFTkSuQmCC"
    }
  }
}

Sample request with qrType=UNIVERSAL_RP_SPECIFIC

{
    "operation":"START_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "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":"a2V5aGFuZGxlAAAAArEHCGN74lechjjgjamKXHHQKjiTujzmKNjpbWXihxTodTt32c-YSaAuLji2uw_TjV20ZXblcLlhiBWB7nZw2Xvh9KPSu4-IhjbiBSDfuH-4RFWIQ6wK5AUB2aY",
  "modeResult":{
    "qrCode":{
      "qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADAElEQVR4Xu2XUW5rIQxEvQPvf5feAfUZk/cUGqn96twPUJsQODfCAx6TWL9pFefIx3axo13saBc72sWOdrGjXexoG6uIWJGZFVUrIxfdGbZj/VfMNlXZH3mvZNiP9dLpZ685erY0mxp+AoauLTHTmYBE8RAMaLWkRBGgMcN2DBJx+3OvvQ9BTvfDCflzrFeNmmcjGDemxqrJakXTWfN/xooVwvaKs3KyZrHneA/H1I31eWSjY+Y5lfrMixkjVVrSFhhz5qkOiKSZCKxYYczKZjY95dKt8zd5LdjUDdlgYjTKFY7pA7DQohcyS1t8WmOveSOG7UneEZbnZIgzbcX0rjsAtxYpnbq/vIdgwWTGiahkTHcRuFN5O7QXk5T4C56jI5nkTxyOZMFkLWjJ5mvx/Vlebcd6VF2WPwegH0RmHjJjSuFg0/nAY0TDw9O8WGI0lDSd0LnGp7bfjnEcERlRSRuomiyyY2t784AapU9UbkzrRdMOBHm5G0jod3ktWJEyC4QrQZHG2I7G/VhrWaw51ZHWdHeEVowiq2pLIhfVTUHJFN1YbzfJQkmjh+kkFn2kjANb84NH9gLPI2OLr68xYkHeBpc7PIZrsXxxZ7MV0/WTqYUj6t6SnNRULfFiiIs3N61fi8naJ4n8GEWNdbPfmCIhlA6AH8NeyI+YklEYDg/w78aSnxGSlQHBmOJhNSZs9n57Cx0uK/spO5YsGj17y/sAcAqwGz9WWM1EwNYnedO1owWfb7Fii1TZCpM+yd2YIPwYNTekZ5I7iIzprMluN7b2MO+s/HUE/slvw4hg7eNIVqt4LLJ8f4sRo1r0INUCRbmnUERQ249R0eZQLqUwjigf3CFasaUKAsgBYJTc+RaCASsEpZ6RyN0W9Zfytr/FivHHTmM6+idvCOEBGMvX0ll8yHDUU+I8ASNHZIF4dY8R0psNWjG8T0bd+57cEz6H8LeYSMyFo6nCyytq+zE2WemCuD1XZHWS0Xbsp3axo13saBc72sWOdrGjXexov8W+AOpfqVRc/KPFAAAAAElFTkSuQmCC"
    },
    "rawData":"https://www.example.com:8443/#nnl-oobdata=%7Cr%7Ca2V5aGFuZGxlAAAAAnxBifk3A8oCWCEH_CntrzNSkYtakM_UCHuVmW3FeKoZTtL8SmqkbFiyOewc3BN0sZ-gGWGKNr6hKsDXRG79hLRsXOSU6rOmMFO-Fv-N8C37gV2_krZvu6KZd7hQLM0%7C12345%7C"
  }
}

Sample request with qrType=APP_ANY_RP

{
    "operation":"START_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"sample",
    "oobRefId":"12345",
    "policyName":"default",
    "oobMode":{
        "qr":"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":"a2V5aGFuZGxlAAAAAtddwMgKIA8ebPjirjDRm7haDH_uzmoKn4n26G_aSOHwKOqBWKEWG0310X5R0AoQ5qHaUAGFZRwlpkCzde0WgDCnE4bg37rjImoitIq1YqMCnb-Z1gBvMdKTK6Y",
  "modeResult":{
    "qrCode":{
      "qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAC+klEQVR4Xu2XUa7rIAxEvQPvf5feAW/OmEo3qNK9X8/5gKYKgZMKBo+hsf5SKs6Wr+ViR7nYUS52lIsd5WJHudhRNlYRURnBc+QqPlVunse4MoqSK7PornTzOFZRGnuulR65ahnU4y2YJA7NQwrrJrHrPZgGv7z69KmBljdgvnJFg1p+BSnB+SVC/juGtF/KaZkJzFWvuiKAr+fxo28Q22JmpaKRpVdguu2QdwLTquNjSSxOqgrDMzhnHkPQJNX0K7ZP4ununcUKRGvfSQaBTR7yTmDYA2GTu1UmOJnI7p/EEBcxSXwkaj0Rms6I0xg7GU9tHKKgrDMaT2Pci+Ak8yG0dE0OLg/LzGBkFq8+BwHHpbMhITCN4WbLap2JSo5TVJ+pZgbzBBaHJ0zdVkncM45hYla6I9HTsbBb3VFssdpU4VAUZR2ez5lOYJLWa13orJkE64958NEwxhlFIy90DQcpWdEN85jugbZsuEyBrZdpPbePEQwpHZIo68hUriYcdlwOYyy/D+sdkGzARt+A9bB7AuxtbB+A4xh30qC/+pAQE+hw/QjGH/6wxp/pYBjCcx7TYvdNTWy3PMs8P2Y4hpWPKV5tTC0Cc5MRjwgZwHTnFKDM4pCkVS/gmM/PzGEEID30gfCIutvNsxhaLk514Oxx6vDVcTmKoSgSk5SxT5/4VgfrLEYj1fYNf8t8PCAKxjEGrS5lvUBaqrY0phnHkjNAJ8HcAGAcrp/AcAt9yZZGetYs4Oykaay8+gyZwOwdjffw9zTmpScGJXQwn+pz3841oxiq7s2XmOQsaqG7dxTzPsHAOUPxQJ5B9OfSj2DeM7qaNjRz8ZRegKml8ElnGwkb7GuI/QLMEhcBQLJmEq34POZh9xZSFM4Dru5fGcW4MC+cGknUfufY2kYw1jydcfSl7ntAvwLDyhiFGKCnLf0KDC018mT7aFe7Mo9B1v6z6OOAMyFCz2M04xFmEjZykQQ/Ak9iv5WLHeViR7nYUS52lIsd5WJH+Sv2D3cf0DyjkkAHAAAAAElFTkSuQmCC"
    }
  }
}

Sample request with qrType=APP_RP_SPECIFIC

{
    "operation":"START_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"sample",
    "oobRefId":"12345",
    "oobMode":{
        "qr":"true",
        "qrType":"APP_RP_SPECIFIC"
    }
}

Sample response with 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":"a2V5aGFuZGxlAAAAAj76lWNLqqmhXLgSBji1QS7dYV1T48L0shLGeFmEYoETrrvciKJ72NptgSozDm8KgJHwhLtQ-Zl0OglQHSxih7BE7J2XqsFBvwVaTEZPg8cQZxTx4uiquPmrOdo",
  "modeResult":{
    "qrCode":{
      "qrImage":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADHUlEQVR4Xu2YPY6kMBCFCxEQcgTfpLlYSyBxMfomPgIhQatr33tmRotnpd1gA5dEBYwNn1uqqX+b/4vsVr/5o9xYJTdWyY1VcmOV3FglBTsM4h+zZNNuNmzYDi9fM/72QbDJPR+dvxNX7i9/m3X7nLFeg2AP6zPUnd0/49uwJQHssDES5hteHd3+tMGhM77xaCjsmOBqsNNi9hgXGz7SPgw20d8eo7tiBNuV7uew2E+3bBRj1ANbyf7+qKK+YUwCw1DnvZfTJW2/pH3sYJJCxu1drmbwMm2zPZgJQmD4kgaGOXd8jQMTF6+9smnDGJLtBtgZI4ZoAYZTLINBsM6XhIdercxjczb623DVtGFMSqJoLKUF0RaaPpOpKobAQCTUb5iIFRARBPf7GDCaLQSGdAV/o2FEsCC6jFVFfcMYG6jEdCVNE/sQdIOwHTNaDAylYmEFXOhnEOqnMELIRMEmvvpA04GtFIz1TM6Gtva3hjFqSgIfaSdWQOVePmJgrqbv5Z5pnYyAn5mAFfXKx+1j0hRaKeCtrHCAq/IjAbCOOYshgzm7P1vCibXwGvVNY2WO+JqHZKcyLV2M1TJ2zkPvNGwIfSYBKyv+C2JgSrtlFOKKZdDIqgyGwFC/VfdY8vBg/HPA8OJ5ITDaia6GkU7qsprg9VJ1gy1j6qJ0y3eOQmwJgaRr1DeOqY3VMMGbv7LyLLOFwKQVisbsGCtmJi4ofp6fg2AIj8wY4RWZVgujHj7oVeJqFtOVpbNqD2xGsF04KCkJSNrHsINWipuNXualD5lZAaNgzLO6tEf2Muq30t+UhdcYGGQFMaoPmRUtmWx1e9w0xvs+Xm+oCc88xZmVfchF04Yx1uqMXlaXl6aO5Ls30c+0j0lgmPdJdMzC3915CIzlw9jGlj6ESrJ+qzufg2CTMi7vBtSJn/V7paZRME5BakaKUD9pf70laB4rWkk/pitkLwxKiv8wGDTtlYBTmYzob/UA1TA2wd8QKLqthJKlkDBuJlERMLrWwbaJ4xEnil6JCxXwZ3JoE/ur3FglN1bJjVVyY5XcWCX/GfsFBmfXVddGKlMAAAAASUVORK5CYII="
    }
  }
}

INIT_OOB_REG

Initiates out-of-band registration.

The Server uses the allowed UAF authenticators specified by the FIDO registration policy passed to START_OOB_REG and device information to create a list of permitted authenticators that the user could register.

For FIDO2 authenticators, the Server compares the authenticator's characteristics to the desired FIDO2 authenticator characteristics specified by the registration 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_REG based on the policy configuration. If you have not configured the registration policy for FIDO2 authenticators, then INIT_OOB_REG fails with a 4403 when a web app tries to register a FIDO2 authenticator.

Request

Response

The following attributes are always present in the JSON payload of the response.

The following attributes are present in the response upon a successful operation (Server status code 4000).

Response status codes

The following are the descriptions of the Auth Server status codes returned by INIT_OOB_REG. 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.

Samples

Sample request URL

https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/reg

Sample request

{
    "operation":"INIT_OOB_REG",
    "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": "INIT_OOB_REG_1439247650812",
    "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_REG

Processes the registration response provided by the caller and completes the OOB registration process.

Request

Response

The following attributes are always present in the JSON payload of the response.

The following attributes are present in the response upon a successful operation (Server status code 4000).

Response status codes

The following are the descriptions of the Auth Server status codes returned by FINISH_OOB_REG. 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.

Samples

Sample request URL

https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/reg

Sample request

{
    "operation": "FINISH_OOB_REG",
    "message": "<base64url-encoded-data>"
}

Sample response

A developer updated the response filter configuration so the API Server returns the protocol, the elapsed time to process the request, additional authenticator details, FIDO policy used, post operation rule results, client app information, and payload extensions in additionalInfo.

{
  "statusCode":4000,
  "id":"rDRwiwww-m2CS3IWBbPuZw",
  "message":
"eyJzZXJ2ZXIiOnsiYXV0aGVudGljYXRvcnNSZXN1bHQiOlt7ImFhaWQiOiJBQkNEI0FCQ0QiLCJrZXlJRCI6ImZaeVNBMDNoN3h1c1gxRFpLdS11MzJ1RV9sX25RSG1tTGtSVHFDTlZ1YkEiLCJzdGF0dXMiOjQwMDB9XSwiYXBwSUQiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL1NhbXBsZUFwcCJ9LCJ1c2VyTmFtZSI6Im8yIiwidmVyc2lvbiI6IjEuMCIsIm9wZXJhdGlvbiI6IkZJTklTSF9PT0JfUkVHIiwicHJvdG9jb2wiOiJ1YWZfMS4wIn0",
  "additionalInfo":{
    "device":{
      "id":"123456789abcdef1234567890",
      "type":"android",
      "info":"NokNok Emulator",
      "model":"NokNok-AE 8.0",
      "os":"NokNokOS 8.0",
      "manufacturer":"NokNok",
      "supportsPlatformAuthenticator":true
    },
    "protocol":"uaf_1.0",
    "elapsedTime":25,
    "authenticatorsResult":[
      {
        "handle":
"WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiZlp5U0EwM2g3eHVzWDFEWkt1LXUzMnVFX2xfblFIbW1Ma1JUcUNOVnViQSJd",
        "uvi":"VPAT7rKZAfKqGzGgnX1_qLzZZ9lF9FPPpO64SfufBEg",
        "uviStatus":4,
        "status":4000,
        "aaid":"ABCD#ABCD",
        "authenticatorVersion":1,
        "attestationType":15879,
        "attestationTypeName":"basic_full",
        "attachmentHints":[
          "internal"
        ]
      }
    ],
    "oobRefId":"12345",
    "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_REG"
      },
      {
        "id":"noknok.ipaddress",
        "data":"192.168.0.102",
        "operation":"INIT_OOB_REG"
      },
      {
        "id":"noknok.wifi.ssid",
        "data":"Oviya",
        "operation":"FINISH_OOB_REG"
      },
      {
        "id":"noknok.wifi.ssid",
        "data":"Oviya",
        "operation":"INIT_OOB_REG"
      },
      {
        "id":"noknok.uaf.location",
        "data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
        "operation":"FINISH_OOB_REG"
      },
      {
        "id":"noknok.uaf.location",
        "data":"{\"accuracy\":99.2,\"countryCode\":\"US\",\"latitude\":32.52,\"longitude\":-124.482,\"status\":0}",
        "operation":"INIT_OOB_REG"
      },
      {
        "id":"noknok.uaf.jailbreak",
        "data":"{\n  \"status\" : \"0\",\n  \"isJailbroken\" : \"false\"\n}",
        "operation":"FINISH_OOB_REG"
      },
      {
        "id":"noknok.uaf.jailbreak",
        "data":"{\n  \"status\" : \"0\",\n  \"isJailbroken\" : \"false\"\n}",
        "operation":"INIT_OOB_REG"
      }
    ]
  }
}

STATUS_OOB_REG

Checks the OOB registration status on the device. This occurs on the device that starts the OOB registration operation.

The Server polls for the status of the registration operation identified by oobStatusHandle. Check if oobStatusHandle has expired since it has a lifetime.

Request

Response

The following attributes are always present in the JSON payload of the response.

The following attributes are present in the response upon a successful operation (Server status 4000).

Response status codes

The following are the descriptions of the Auth Server status codes returned by STATUS_OOB_REG. 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.

Samples

Sample request URL

https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/reg

Sample request

{
    "operation": "STATUS_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "oobStatusHandle": "AgAgUIh9AFHjsDU_mPp_DUsghnYn7kg3sl3z-keVqCtM09IDAAgAAAFPGdfXiwQAAQEBACCAcQ81Htjr69mhHEuluuT9Y9orXRfyRqZ_plbHpTNwRQ"
}

Sample response

A developer updated the response filter configuration so the API Server returns the FIDO policy used, the elapsed time for processing the request, protocol, and additional authenticator details in additionalInfo.

{
  "statusCode":4000,
  "additionalInfo":{
    "device":{
      "info":"OneSpan's device",
      "id":"dID_82b5799d-869a-4a9b-95c6-fdd36a6b61a1_1",
      "type":"android"
    },
    "policyName":"reg_policy",
    "elapsedTime":25,
    "authenticatorsResult":[
      {
        "aaid":"ABCD#ABCD",
        "uvi":"ZsGHbiYd6OgLVYW49G-qQHrwrgw83Wve5Ge5iQVYv8",
        "uviStatus":4,
        "authenticatorVersion":1,
        "attestationType":15879,
        "authenticatorExtensions":[
          {
            "id":"tag1",
            "data":"extensionData1",
            "fail_if_unknown":false
          },
          {
            "id":"tag2",
            "data":"extensionData2",
            "fail_if_unknown":false
          },
          {
            "id":"criticalTag1",
            "data":"criticalExtensionData1",
            "fail_if_unknown":true
          },
          {
            "id":"criticalTag2",
            "data":"criticalExtensionData2",
            "fail_if_unknown":true
          }
        ],
        "status":4000,
        "handle":
"WyJ1YWZfMS4wIiwiQUJDRCNBQkNEIiwiQnVKk5BQlVoVHZUeW1WY3FYMk9fRmhpRFY0aHA1OThxLTI0eWEzVlmUSJd"
      }
    ],
    "protocol":"uaf_1.0"
  },
  "push":{
    "pushHandle":
"m3-ZrKasG_GhxK4IdEIyOIUysfOFcBhMkvm5BOyRZMWCMGozvHP3Fur9edF1mFLwI1iZpc0LuwCiY1ZLGqyWJea7zOp7kGJdHFSuLzd5vCOD7wLmPp2s5ciEtXRPUEaI4z5eZYlqGXKPPtW4s7H_Q5zBOaUiqNVueRoHx_ZBVEy-8A4",
    "handleLifetimeDays":30,
    "createdTimeStamp":"2020-09-08T06:18:08.904Z",
    "status":4000
  },
  "id":"dEgViadKjxcleujKbpfi6g"
}

CANCEL_OOB_REG

Cancels the OOB operation from the second device (authenticating device) on the Server.

Request

Response

The following attributes are always present in the JSON payload of the response.

The following attributes are present in the response upon a successful operation (Server status code 4000).

Response status codes

The following are the descriptions of the Auth Server status codes returned by CANCEL_OOB_REG. 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.

Samples

Sample request URL

https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/reg

Sample request

{
    "operation":"CANCEL_OOB_REG",
    "nnlData":"giltFqT8g5CblHqnzXLrrYoxG6nmseHYWGSdWUxBW6hHVJ9RHj9WgmYxbLE8C98YSizqHqUlqzkeVZ7F_5GzigU8X67qyg"
}

Sample Response

{
    "id":"CANCEL_OOB_REG_1439247762691",
    "statusCode":4000
}

CANCEL_STATUS_OOB_REG

Checks the OOB cancel registration status on the second device.

Request

Response

The following attributes are always present in the JSON payload of the response.

Response status codes

The following are the descriptions of the Auth Server status codes returned by CANCEL_STATUS_OOB_REG. 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.

Samples

Sample Request URL

https://www.example.com:8443/nnlgateway/nnl/<tenant_id>/reg

Sample request

{
    "operation":"CANCEL_STATUS_OOB_REG",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "oobStatusHandle":"AgAgCcIuezLxWhezpTS7Le3-lGQsTmO7TqJ7IYspDote_gsDAAgAAAFPcv9jhwQAAQEBACCCp9fGEPR4GC-S57z1UCTtCXbPYBlhu5acflIHXMyUvA"
}

Sample response

{
    "id":"dEgViadKjxcleujKbpfi6g",
    "statusCode":"4000"
}