Non-FIDO authentication

URL: /nnlgateway/nnl/<tenantID>/auth Method: POST

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 non-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.

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:

• statusHandle

• lifetimeMillis

• data.identifier present for

  • Email OTP

  • SMS OTP

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.

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:

• The requested ruleset is not available on Server.

• The requested ruleset denied authentication.

• None of the rules in the ruleset matched.

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.

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.

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:

• statusHandle

• data: Contains an identifier field with the following masked value:

  • Email OTP: The user's email address that receives the OTP

  • SMS OTP: The user's phone number that receives the OTP

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.

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,

5. The client app must have sent this information in the INIT_ADAPTIVE request message attribute.

6. Update the response filter configuration so the API Server returns the information you want. By default, the API Server automatically returns device information. Refer to Response Filter Configuration.

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:

• The authentication method in the response completed verification.

• None of the method combinations in the authentication sequence can be performed. This is based on the userName identified from the authentication method in the response.

• The authentication method in the response has not reached a final state. Applies to FIDO OOB, SMS OTP, email OTP, Photo ID, and external authentication.

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.

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:

• 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. Based on id.

• The user can't complete an authentication method (for example, the FIDO challenge expired or the OTP expired) before that method's expiry time. The expiry time is in the method's lifetimeMillis field. Based on statusHandle.

4402

Security Exception

• sessionData.userName for the current method does not match the one used for previously authenticated methods.

• There is an invalid method name or statusHandle in the request.

{
  "operation": "SETUP",
   "methods": [
    {
    "type": "email",
    "name": "recoveryEmailOtp",
    "statusHandle":"wrong statusHandle"
  }
  ]
}

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

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.

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:

• statusHandle

• state

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.

4000

OK. Operation completed

The authentication method was successfully cancelled.

4401

Operation expired

An operation expires when:

• 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. Based on id.

• The user can't complete an authentication method (for example, the FIDO challenge expired or the OTP expired) before that method's expiry time. The expiry time is in the method's lifetimeMillis field. Based on statusHandle.

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:

• method

  • type

  • name

  • statushandle