Integration of the registration and deregistration of a FIDO-based authenticator

Before you can use FIDO 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.-based authentication for OneSpan Cloud Authentication, a FIDO authenticator must be registered for the UAF or FIDO2 protocol.

Prerequisites for the registration of a FIDO-based authenticator

The following prerequisites must be met before the registration process can be started:

• The user must exist in the OneSpan Trusted Identity platform.
• The user must be authenticated against OneSpan Cloud Authentication and logged in with the app.

Sequence of registering a FIDO-based authenticator

1. The app starts the registration process. This triggers the web server to initiate the registration to the OneSpan Trusted Identity platform API by calling the POST /users/{userID@domain}/generate-fido-registration-request endpoint.
2. The OneSpan Trusted Identity platform API Provides the endpoints that are required for the successful completion of the operations. initializes the registration with the FIDO Server.
3. The FIDO Server generates a registration response that is sent to the OneSpan Trusted Identity platform API.
4. The OneSpan Trusted Identity platform API receives the registration request and sends it to the web server.
5. The web server forwards the request to the app.
6. The app communicates with the FIDO authenticator to generate a registration response.
7. The app forwards the registration response to the web server, which forwards the response to the OneSpan Trusted Identity platform API by calling the POST /users/{userID@domain}/register-fido-device endpoint.
8. The OneSpan Trusted Identity platform API finalizes the registration with the FIDO Server.
9. The FIDO Server verifies the registration response that is sent to the OneSpan Trusted Identity platform API.
10. The OneSpan Trusted Identity platform API receives the success response and sends it to the web server.
11. To conclude the registration process, the web server sends this verification response to the app.

The FIDO authenticator is now registered and ready to be used for passwordless authentication.

To register a FIDO-based authenticator

1. Issue a registration request with POST /users/{userID@domain}/generate-fido-registration-request.

   • Payload:

     • fidoProtocol: UAF11, FIDO2
     • displayName (FIDO2 only)

     • authenticatorSelection (FIDO2 only)

       • (Optional) authenticatorAttachment: platform, cross-platform
       • userVerification: required, preferred, discouraged
       • requireResidentKey: true, false
     • attestation: none, indirect, direct (FIDO2 only)

   • Response body:

     • registrationRequest
     • requestID (FIDO2 only)

     • uafStatusCode

       For a full list of UAF status codes, refer to the FIDO alliance documentation.

       For FIDO2, this field will return null.

2. Issue a register fido device request with POST /users/{userID@domain}/register-fido-device.

   • Payload:

     • fidoProtocol: UAF11, FIDO2
     • registrationResponse
     • requestID (FIDO2 only)

   • Response body:

     • uafStatusCode

       For a full list of UAF status codes, refer to the FIDO alliance documentation.

       For FIDO2, this field will return null.

Authenticator management

Currently it is possible to remove an authenticator only if it has been registered using the UAF protocol.

Deregistration of a FIDO UAF authenticator

Prerequisites for removing a previously registered FIDO-based authenticator

The following prerequisites must be met before the deregistration process can be started:

• The user must be authenticated against OneSpan Cloud Authentication and logged in with the app.

Sequence of the deregistration of a FIDO UAF authenticator

1. The app sends a request to the web server. This request is forwarded to the OneSpan Trusted Identity platform API via the POST /users/{userID@domain}/deregister-fido-uaf-authenticators endpoint.
2. The OneSpan Trusted Identity platform API sends the request to the FIDO Server.
3. The FIDO Server removes the authenticator and sends a deregistration response to the OneSpan Trusted Identity platform API.
4. The OneSpan Trusted Identity platform API forwards this response to the web server.
5. The web server forwards the deregistration request to the authenticator. The authenticator then cleans up its internal storage accordingly.

If all authenticators that belong to a FIDO user have been deregistered, the FIDO user is automatically deleted.

To remove a previously registered FIDO-based authenticator

• Issue a deregister fido uaf authenticator request with the POST /users/{userID@domain}/deregister-fido-uaf-authenticators endpoint.
  • Payload:
    • aaid
  • Response body:
    • deregistrationRequest
    • uafStatusCode
      For a full list of UAF status codes, refer to the FIDO alliance documentation.
      

Deregistration of individual keys from an authenticator

Instead of completely deregistering an authenticator, individual keys can be removed from the authenticator and FIDO Server. The FIDO protocols use public-key cryptography techniques to provide stronger authentication. During registration, a new key pair is created that is unique to the user, authenticator, and to the AppId. The private key is retained within the authenticator, while the public key is stored on the FIDO Server.

It is only possible to remove individual keys from an authenticator if they have been registered using the UAF protocol.

Prerequisites for the removal of individual keys on a previously registered FIDO-based authenticator

• The user must be authenticated against OneSpan Cloud Authentication and logged in with the app.

Sequence of the removal of individual keys on a previously registered FIDO-based authenticator

1. The app sends a request to the web server. This request is forwarded to the OneSpan Trusted Identity platform API via the POST /users/{userID@domain}/deregister-fido-uaf-authenticators endpoint.
2. The OneSpan Trusted Identity platform API sends the request to the FIDO Server.
3. The FIDO Server removes the keys and sends a deregistration response to the OneSpan Trusted Identity platform API.
4. The OneSpan Trusted Identity platform API forwards this response to the web server.
5. The web server forwards the deregistration request to the authenticator. The authenticator then cleans up its internal storage accordingly.

To remove individual keys on a previously registered FIDO-based authenticator

• Issue a deregister fido uaf keys request with the POST /users/{userID@domain}/deregister-fido-uaf-keys endpoint.

  • Payload:

    • aaid
    • keyID

  • Response body:

    • deregistrationRequest