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 FIDOClosed The FIDO (Fast IDentity Online) Alliance is an organization whose main goal is to reduce the user’s reliance on passwords. It proposes several frameworks that enable passwordless authentication. protocols:

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:

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