Integration of Adaptive User Login with FIDO-Based Authentication

With OneSpan Intelligent Adaptive Authentication you can implement functionality for your users to log in to your web application using the passwordless FIDO-based authentication mechanism. Intelligent Adaptive Authentication supports the following FIDO protocols:

• FIDO UAF (Universal Authentication Framework)

• FIDO2

Prerequisites for an adaptive user login with FIDO-based authentication

To ensure a user can successfully log in with FIDO-based authentication, the following prerequisites must be met:

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

  FIDO authenticator registration is handled in OneSpan Cloud Authentication. 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 the Risk Management component (see Configuration of risk analysis rules to generate the ChallengeFIDO response code).

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

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

  • If the Risk Management component accepts the login without an additional challenge, it will return a riskResponseCode of 0. In this scenario, no additional authentication steps are required. For more information, see Adaptive user login - low risk login request.

Adaptive user login secured with FIDO-based authentication

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

Adaptive user login flow secured with FIDO-based authentication - overview

Sequence of an adaptive user login operation with FIDO-based authentication

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 login 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}/login.

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

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

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

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

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

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

8. 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}/login.

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

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

11. 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 factors involved and sends the response back to the OneSpan Trusted Identity platform API.

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

13. The web server finalizes the authentication operation by sending this response to the app.

To integrate adaptive user login with FIDO-based authentication

1. Issue a login request with https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/login.

   • Method: POST

   • Payload:

     • objectType: "AdaptiveLoginInput"

     • cddc

     • sessionID

     • relationshipRef

     • fidoAuthentication

       • fidoProtocol: UAF11, FIDO2

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

       • authenticationMessage (UAF only)
         Can be null.

   • Response body:

     • riskResponseCode: 14 (ChallengeFIDO)

     • requestID

     • sessionStatus: pending

     • fidoAuthenticationRequest
       

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

   • Payload:

     • objectType: "AdaptiveLoginInput"

     • cddc

     • requestID

     • sessionID

     • relationshipRef

     • 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 user login - low risk login request

If the login 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 authentication steps are required.

Adaptive user login flow - overview

Sequence of an adaptive user login 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 login 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}/login.

2. The OneSpan Trusted Identity platform API sends a login request to the Risk Management component which accepts the login request.

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

4. The web server forwards the accepted login request to the app.

To integrate adaptive user login

• Issue a login request with https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/login.

  • Method: POST

  • Payload:

    • objectType: "AdaptiveLoginInput"

    • cddc

    • sessionID

    • relationshipRef

    • fidoAuthentication

      • fidoProtocol: UAF11, FIDO2

      • userVerification: required, preferred, discouraged (FIDO2 only)

      • authenticationMessage (UAF only)

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