Integration of Adaptive Event Signing with FIDO-Based Event Validation

Intelligent Adaptive Authentication supports the FIDO UAF and FIDO2 protocols for adaptive event signing with FIDO-based event validation.

Prerequisites for securing adaptive event signing with FIDO-based event validation

The following prerequisites have to be met before starting the event validation process:

• The user has been assigned to a registered tenant.

• The user exists in OneSpan Cloud Authentication.

• FIDO has been configured in the tenant configuration service.

• The user has a registered FIDO authenticator for their account.

  FIDO authenticator registration is described in the OneSpan Cloud Authentication documentation. For more information about authenticator registration, see Register a FIDO-based authenticator.

• A relying party instance with defined policies has been created during the onboarding process.

• The rules that generate the ChallengeFIDO response code have been configured in OneSpan Risk Analytics (see Configuration of risk analysis rules  to generate the ChallengeFIDO response code).

  The event validation flow will vary depending on the result of the risk evaluation performed by Risk Analytics. Risk Analytics performs a real-time analysis of vast amounts of user, device and historical data to calculate the risk involved. The result is then returned as a risk response code (riskResponseCode).

  • If the event validation request is regarded as risky, the Risk Management component will challenge the user with an additional event validation step. In case of event signing with FIDO-based event validation, the Risk Management component will return a riskResponseCode of 14 (ChallengeFIDO). For more information regarding this scenario, see Adaptive event signing secured with FIDO-based event validation.

  • If the Risk Management component accepts the event validation request without an additional challenge, it will return a riskResponseCode of 0. No additional validation steps are required. For more information, see Adaptive event validation - low risk validation request.

Adaptive event signing secured with FIDO-based event validation

If the event validation request is regarded as risky, the Risk Management component will challenge the user with an additional event validation step. In case of adaptive event signing with FIDO-based event validation, the Risk Management component will return a riskResponseCode of 14 (ChallengeFIDO). After the event has been validated using a FIDO-based authenticator, the Risk Management component will re-evaluate the request and accept or decline the event.

Sequence of an adaptive event signing operation secured with FIDO-based event validation

Before starting the operation, ensure the correct state of the user account by validating the output of the GET /users/{userID@domain} endpoint.

1. The user starts the event validation operation. The app collects CDDC data and sends the validation request with the CDDC data and the FIDO event data to the web server. The web server forwards the request to the OneSpan Trusted Identity platform API by calling https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/events/validate.

1. The OneSpan Trusted Identity platform API forwards the request to the Risk Management component, which returns a riskResponseCode of 14 (ChallengeFIDO).

2. The OneSpan Trusted Identity platform API initializes the FIDO authentication by sending a request to the FIDO Server.

1. The FIDO Server generates an authentication request that is sent to the OneSpan Trusted Identity platform API.

2. The OneSpan Trusted Identity platform API forwards the authentication request to the web server.

3. The web server forwards the authentication request to the app.

4. The app communicates with the FIDO authenticator to generate an authentication response.

5. The app collects CDDC data and sends it with the FIDO authentication response to the web server, which forwards the request to the OneSpan Trusted Identity platform API by calling https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/events/validate.

6. The OneSpan Trusted Identity platform API finalizes the authentication with the FIDO Server.

7. The FIDO Server verifies the authentication response and returns a success response.

8. The OneSpan Trusted Identity platform API sends all the gathered data with the result of the FIDO authentication to the Risk Management component. This component assesses all the factors involved and sends the response back to the OneSpan Trusted Identity platform API.

9. The OneSpan Trusted Identity platform API receives the success response and sends it to the web server.

10. The web server finalizes the event validation operation by sending this response to the app.

To integrate adaptive event signing secured with FIDO-based event validation

1. Issue an event validation request with https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/events/validate.

   • Method: POST

   • Payload:

     • eventType

     • cddc

     • relationshipRef

     • sessionID

     • fidoAuthentication

       • fidoProtocol: UAF11, FIDO2

       • userVerification: required, preferred, discouraged (FIDO2 only)
         Can be null which will default to preferred.

       • authenticationMessage (UAF only)
         Can be null.

   • Response body:

     • riskResponseCode: 14 (ChallengeFido)

     • requestID

     • sessionStatus: pending

     • fidoAuthenticationRequest

2. After confirming the event data with the FIDO-based authenticator, issue a second event validation request with https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/events/validate.

   • Method: POST

   • Payload:

     • eventType

     • cddc

     • relationshipRef

     • requestID

     • sessionID

     • credentials

       • fidoAuthenticator

         • authenticationResponse

   • Response body:

     • riskResponseCode: 0

     • sessionStatus: accepted

     • uafStatusCode
       For a full list of UAF status codes, refer to the FIDO alliance documentation.
       For FIDO2, this field will return null.

Adaptive event validation - low risk validation request

If the event validation request is regarded as low risk, the Risk Management component will accept the request and return a riskResponseCode of 0 (accepted). In this case, no additional validation steps are required.

Sequence of an adaptive event validation operation

Before starting the operation, ensure the correct state of the user account by validating the output of the GET /users/{userID@domain} endpoint.

1. The user starts the event validation operation. The app collects CDDC data and sends the login request with the CDDC data and the FIDO authentication data to the web server. The web server forwards the request to the OneSpan Trusted Identity platform API by calling https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/events/validate.

2. The OneSpan Trusted Identity platform API sends an event validation request to the Risk Management component. This component accepts the event validation request.

3. The OneSpan Trusted Identity platform API receives the accepted event validation request and sends it to the web server.

4. The web server forwards the accepted event validation request to the app.

To integrate adaptive event validation

• Issue an event validation request with https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/events/validate.

  • Method: POST

  • Payload:

    • eventType

    • cddc

    • relationshipRef

    • sessionID

    • fidoAuthentication

      • fidoProtocol: UAF11, FIDO2

      • userVerification: required, preferred, discouraged (FIDO2 only)
        
        Can be null which will default to preferred.

      • authenticationMessage (UAF only)
        Can be null.

  • Response body:

    • riskResponseCode: 0

    • sessionStatus: accepted

    • uafStatusCode
      For a full list of UAF status codes, refer to the FIDO alliance documentation.
      For FIDO2, this field will return null.