Adaptive registration

Digipass S3 Authentication Software provides the INIT_ADAPTIVE_REG operation under the /nnl/v2/reg endpoint to initiate Adaptive Registration. In addition to INIT_ADAPTIVE_REG, you also need to use the following REST API operations to fully implement Adaptive Registration.

To register a FIDO authenticator:

• INIT_REG

• FINISH_REG

To register a FIDO authenticator on a second device (FIDO OOB):

• START_OOB_REG

• STATUS_OOB_REG

• INIT_OOB_REG

• FINISH_OOB_REG

To register non-FIDO authenticators:

• INIT_SETUP

• SETUP

Start Adaptive Registration by calling INIT_ADAPTIVE_REG. If there is a successful Registration Decision Rule (its condition evaluates to true) and that rule has an action of either SUGGEST_REGISTRATION or ENFORCE_REGISTRATION, then the Server retrieves that rule's registration sequences. The Server filters out authentication methods that the user previously registered as well as methods not supported on the user's device. INIT_ADAPTIVE_REG returns the action and, if applicable, filtered sequence(s).

The calling app interacts with the user to select one authentication method to register from the sequence(s). The app is also responsible for interacting appropriately with the user to require ENFORCE_REGISTRATION versus SUGGEST_REGISTRATION. After the user has selected a method, the calling app must call the appropriate REST API operations to register that method.

After each successful registration, call INIT_ADAPTIVE_REG again so your app knows which authentication method to register next. If the newly-registered method is either a FIDO or FIDO OOB authenticator, then the Server checks if there is a Supplemental Check configured for that authenticator. A FIDO authenticator's characteristics are not known until the user has selected it, as a result a Supplemental Check plays a critical role in guaranteeing that the FIDO authenticator meets your organization's criteria for secure authentication.

If there is a Supplemental Check for the FIDO authenticator and its condition evaluates to true, then registration is complete because the authenticator satisfies the requirements for strong authentication.

If the Supplemental Check's condition fails OR there was no Supplemental Check, the Server does one of the following:

• IF all the authentication methods in all rule's sequences have been registered, THEN registration is done and return 4000.

• ELSEIF the newly-registered authenticator completes one sequence THEN return 4006. It is up to the calling app how it wants to handle this situation. In other words, this could be treated as either registration is complete or registration must continue. Completing a sequence means there is at least one sequence now that has no unregistered methods.

• ELSEIF there are unregistered authentication methods in any sequence that contains the newly-registered authenticator, THEN return the remaining authentication methods from all sequences that contain the newly-registered authenticator.
  
  The calling app interacts with the user to select a method, registers it, and calls INIT_ADAPTIVE_REG again.

INIT_ADAPTIVE_REG

Use INIT_ADAPTIVE_REG to start Adaptive Registration processing.

Prior to starting execution, the Server needs to determine which Adaptive Ruleset it should use. That ruleset is determined using the following algorithm:

1. IF you configured the calling client app with an Adaptive Ruleset THEN use it.

2. ELSEIF there is an Adaptive Ruleset called default THEN use it.

3. ELSE registration fails.

Each Registration Decision Rule in the ruleset is evaluated in the order until one rule succeeds (its condition evaluates to true) or all the rules fail.

If a Registration Decision Rule succeeds, then the Server returns its action and, if applicable, its registration sequences of authentication methods. The Server filters out methods that the user previously registered and are not supported on the user's device. The rule's action can be one of:

• DENY: The user cannot register.

• SUGGEST_REGISTRATION: The user can choose to register one or more authentication methods.

• ENFORCE_REGISTRATION: The user is required to register one or more authentication methods in order to be able to use the functions in the calling app. As previously mentioned, the calling app chooses how to enforce this.

• IGNORE_REGISTRATION: Based on the current situation, registration can't be done or doesn't need to be done, just move along. For example:

  • The user signed in with a FIDO authenticator (the client app provided this as context data) then no registration is needed.

  • Your company only wants to allow platform authenticators. However, the user's device has no platform authenticators. There's no point trying to register and this isn't an error.

If all the rules fail, INIT_ADAPTIVE_REG fails with a 4403.

Adaptive Registration is intended to loop through a set of unregistered policy-approved authentication methods from one successful Registration Decision Rule. The end user keeps registering an authentication method until they cancel out or there are no unregistered methods left. Because the developer must call INIT_ADAPTIVE_REG to update the set of unregistered methods at the start of the loop, INIT_ADAPTIVE_REG provides nuanced information to help the calling app tailor its behavior.

• Registration is finished because all authentication methods have been registered from all of the rule's sequences. (Server status code 4000 and rule action of either SUGGEST_REGISTRATION or ENFORCE_REGISTRATION)

• Registration is finished because the newly-registered FIDO authenticator has a Supplemental Check that succeeded. The FIDO authenticator is sufficiently strong that other authentication methods aren't needed. (Server status code 4000)

• Registration is finished because the user's device doesn't have any policy-approved authentication methods. (Server status code 4000 and rule action of IGNORE_REGISTRATION)

• Registration could be finished because the user has registered all authentication methods in at least one of the rule's sequences. (Server status code 4006 and rule action of either SUGGEST_REGISTRATION or ENFORCE_REGISTRATION)

• Registration should continue because there are still unregistered authentication methods. (Server status code 4005 and rule action of either SUGGEST_REGISTRATION or ENFORCE_REGISTRATION)

Request

"contextData":{
    "customerType" : "Privileged"
}

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 of 4000, 4005, or 4006).

Response Status Codes

The following are the descriptions of the Auth Server status codes returned by INIT_ADAPTIVE_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/<tenantID>/reg

Sample Request

{
    "operation": "INIT_ADAPTIVE_REG",
    "sessionData": {
        "sessionKey": "<session JWT>"
    },
    "ruleSetName": "androidAppRuleSet",
    "id": "sample",
    "message": "<base64url-encoded-data>", 
    "contextData": {
        "customerType": "Privileged"
    }
}

Sample Response When the Succeeding Rule's Action is SUGGEST_REGISTRATION and the End User Hasn't Registered any Methods

The following sample has 2 registration sequences configured (FIDO Auth and Email OTP) OR (FIDO Auth and SMS OTP). A developer updated the response filter so the API Server returns app information and payload extensions in additionalData.

{
    "statusCode":4005,
    "id":"t3w8UjmXK3HgJXi1vwoDdA",
    "additionalInfo":{
        "device":{
            "id":"123456789abcdef1234567890",
            "type":"android",
            "info":"OneSpan's device",
            "model":"Galaxy S20",
            "os":"Android 12",
            "manufacturer":"Samsung"
        },
        "app":{
            "id":"com.noknok.android.onramp",
            "name":"OnRamp"
        },
        "extensions":[
            {
                "id":"noknok.uaf.location",
                "data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
                "operation":"INIT_ADAPTIVE"
            }
        ]
    },
    "ruleSetResult":{
        "action":"SUGGEST_REGISTRATION",
        "ruleSetName":"androidAppRuleSet",
        "ruleName": "PrivilegedCustomerRule"
    },
    "authSequences":{
        "authSequence1":{
            "methods":[
                {
                    "type":"FIDO Auth",
                    "name":"default"
                },
                {
                    "type":"SMS OTP",
                    "name":"OTP Using SMS"
                }
            ]
        },
        "authSequence2":{
            "methods":[
                {
                    "type":"FIDO Auth",
                    "name":"default"
                },
                {
                    "type":"Email OTP",
                    "name":"OTP Using Email"
                }
            ]
        }
    }
}

Sample Response When the Succeeding Rule's Action is ENFORCE_REGISTRATION and the User Has Registered Some of the Methods

The following sample has 2 registration sequences configured (FIDO Auth and Email OTP) OR (FIDO Auth and SMS OTP) and the end user has already registered FIDO Auth. A developer updated the response filter configuration so the API Server returns app information and payload extensions.

{
    "statusCode":4005,
    "id":"t3w8UjmXK3HgJXi1vwoDdA",
    "additionalInfo":{
        "elapsedTime": 38,
        "device":{
            "id":"123456789abcdef1234567890",
            "type":"android",
            "info":"OneSpan's device",
            "model":"Galaxy S20",
            "os":"Android 12",
            "manufacturer":"Samsung"
        },
        "app":{
            "id":"com.noknok.android.onramp",
            "name":"OnRamp"
        },
        "extensions":[
            {
                "id":"noknok.uaf.location",
                "data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
                "operation":"INIT_ADAPTIVE"
            }
        ]
    },
    "ruleSetResult":{
        "action":"ENFORCE_REGISTRATION",
        "ruleSetName":"androidAppRuleSet",
        "ruleName":"PrivilegedCustomerRule"
    },
    "authSequences":{
        "authSequence1":{
            "methods":[
                {
                    "type":"SMS OTP",
                    "name":"OTP Using SMS"
                }
            ],
            "reason": "SMS_email_OTP_needed"    
        },
        "authSequence2":{
            "methods":[
                {
                    "type":"Email OTP",
                    "name":"OTP Using Email"
                }
            ]
            "reason": "Reason why the user is being prompted with Email OTP"
        }
    }
}

Sample Response When the Succeeding Rule's Action is ENFORCE_REGISTRATION and the User Has Registered the Required Methods

The following sample has 2 configured registration sequences (FIDO Auth and Email OTP) OR (FIDO Auth and SMS OTP) and the end user has registered FIDO Auth and Email OTP. A developer updated the response filter configuration so the API Server returns app information and payload extensions in additionalInfo.

{
    "statusCode":4006,
    "id":"t3w8UjmXK3HgJXi1vwoDdA",
    "additionalInfo":{
        "elapsedTime":38,
        "device":{
            "id":"123456789abcdef1234567890",
            "type":"android",
            "info":"OneSpan's device",
            "model":"Galaxy S20",
            "os":"Android 12",
            "manufacturer":"Samsung"
        },
        "app":{
            "id":"com.noknok.android.onramp",
            "name":"OnRamp"
        },
        "extensions":[
            {
                "id":"noknok.uaf.location",
                "data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
                "operation":"INIT_ADAPTIVE"
            }
        ]
    },
    "ruleSetResult":{
        "action":"ENFORCE_REGISTRATION",
        "ruleSetName":"androidAppRuleSet",
        "ruleName":"PrivilegedCustomerRule"
    },
    "authSequences":{
        "authSequence1":{
            "methods":[
                {
                    "type":"SMS OTP",
                    "name":"OTP Using SMS"
                }
            ]
        }
    }
}