FIDO2 in the Sandbox environment
FIDO2 is a standard for strong authentication in the web. It is comprised of the WebAuthn
Web Authentication (WebAuthn) is a web-based API that enables FIDO-based authentication for online services on supported browsers and platforms. specification and the corresponding Client-to-Authenticator Protocol (CTAP) The Client-to-Authenticator Protocol (CTAP) enables an external authenticator to work with browsers that support WebAuthn. Additionally, it serves as an authenticator to desktop applications and web services.. It allows users to authenticate to online services with their devices and/or authenticators without the need to enter a password. It can be accomplished both on their desktop and mobile environments. For more information on WebAuthn and CTAP, refer to the FIDO Alliance documentation.
In the Sandbox environment you can simulate and test the capabilities of the FIDO2 ceremonies with the help of the FIDO2 Bank Demo Web App and .
Overview of the Sandbox environment
OneSpan prepares a FIDO2 deployment specifically for your tenant in the Sandbox environment. The deployment involves the following parties:
- Client infrastructure. This includes the platform and cross-platform authenticators, as well as the web browser (with WebAuthN support). By default, OneSpan supports the FIDO2 authenticators which are part of the FIDO Alliance Metadata Service version 3.0.
- . The web server application which provides the registration and authentication features. Its back end communicates via a secure connection (TLS certificates) with the OneSpan Trusted Identity platform API.
In the Sandbox environment, you can use the FIDO2 Bank Demo Web App and to demonstrate the capabilities of the FIDO2 registration and authentication ceremonies. On the client side, the FIDO2 Bank Demo Web App and demonstrate the interaction between the web browser and the available FIDO2 authenticators. On the back-end side, the FIDO2 Bank Demo Web App and forward the data structures, which were processed by the authenticator, to the OneSpan Trusted Identity platform. These data structures are then further processed and validated by the FIDO2 Server.
Once FIDO2 has been enabled, you will be able to access:
- The FIDO2 Bank Demo Web App via https://yourtenant.sdb.tid.onespan.cloud/v1/mybank-fido
- The via https://yourtenant.sdb.tid.onespan.cloud/v1/fido-sample-relying-party
Use the FIDO2 Bank Demo Web App to demonstrate the basic FIDO2 capabilities. For more information about the FIDO2 Bank Demo Web App, see FIDO2 Bank Demo Web App.
Use the to extensively test and simulate the FIDO2 capabilities. The will assist you to integrate your relying party solution. For more information about the , see FIDO2 Sample Relying Party Web App.
- OneSpan Trusted Identity platform API. This REST API exposes the FIDO2 Server functionality via dedicated FIDO endpoints that are available in OneSpan Cloud Authentication.
For more information about FIDO concepts, refer to the specifications and technical glossary provided by the FIDO Alliance.
Configure FIDO2 in the Sandbox environment
To enable the integration of FIDO2-based functionalities with OneSpan Cloud Authentication for the Sandbox environment, the following information must be provided to properly configure FIDO2:
- Tenant name
- (If required) Metadata statements
To enable FIDO2 for the Sandbox environment, submit a service request on the Product Support page by clicking the corresponding button.
Tenant name
Ensure that you already have created a tenant. To enable FIDO2, provide the tenant name to OneSpan support—our support staff will activate FIDO2 for you.
Metadata statements
The FIDO2 Server works out-of-the-box with a list of supported FIDO2 authenticators which are part of the FIDO Alliance Metadata Service version 3.0.
If you intend to use authenticators that are not included in the FIDO Alliance Metadata Service, ensure that you provide the relevant metadata statements to OneSpan in the v3 format.
For more information about FIDO2 authenticators supported by the FIDO Alliance Metadata Service, see FIDO2-supported authenticators.
Managing FIDO2 Relying Party Resources
You can manage Relying Party Resources by using the following OneSpan Trusted Identity platform REST API endpoints.
Create a new FIDO2 Relying Party Resource
To create a new FIDO2 Relying Party Resource, call the following endpoint:
with the following mandatory request body:
- origins. Set of valid origins matching the Relying Party ID, e.g. ["https://www.yourwebapp.example-tenant.com"].
- publicKeyCredentialRpEntity:
- id. This is the Relying Party ID, e.g. "yourwebapp.example-tenant.com".
- name. This is the name of the Relying Party.
- icon. This is the Relying Party logo.
Multiple Relying Party Resources can be created. However, only the one that is set as the default (see Set a FIDO2 Relying Party Resource as default) is relevant for registration and authentication operations. The first Relying Party Resource that is created will automatically be set as the default.
The responses for this endpoint include the following:
-
201: FIDO2 Relying Party created.
The Relying Party UUID (the identifier for this newly created resource) will be returned.
- 400: Input data errors.
- 500: Internal error, sub-service failure, server crash.
Query FIDO2 Relying Party Resources
To query the FIDO2 Relying Party Resource, call the following endpoint:
The responses for this endpoint include the following:
- 200: FIDO2 Relying Parties retrieved successfully.
- 400: Input data errors.
- 500: Internal error, sub-service failure, server crash.
Retrieve a specific FIDO2 Relying Party Resource by ID
To retrieve a specific FIDO2 Relying Party Resource ID, call the following endpoint:
GET /fido2-relying-parties/{uuid}
The responses for this endpoint include the following:
- 200: FIDO2 Relying Parties retrieved successfully.
- 400: Input data errors.
- 404: FIDO2 Relying Party not found.
- 500: Internal error, sub-service failure, server crash.
Set a FIDO2 Relying Party Resource as default
You can have more than one Relying Party Resource. Only the one that is set as the default is relevant for the registration and authentication operations.
To set a FIDO2 Relying Party Resource as default, call the following endpoint:
POST /fido2-relying-parties/{uuid}/make-default
The responses for this endpoint include the following:
- 204: Make default operation successful.
- 400: Input data errors.
- 404: FIDO2 Relying Party not found.
- 500: Internal error, sub-service failure, server crash.
Only one Relying Party Resource can be the default at any given time. If you make another Relying Party the default, the Relying Party that is currently the default will automatically lose its default status.
If you change the default FIDO2 Relying Party Resource, registrations that were performed in the context of that previous default Relying Party Resource will not be working, unless you use the same Relying Party ID (publicKeyCredentialRpEntity.id) and origins.
Update a FIDO2 Relying Party Resource
To update an existing FIDO2 Relying Party Resource, call the following endpoint:
PATCH /fido2-relying-parties/{uuid}
The responses for this endpoint include the following:
- 200: FIDO2 Relying Party update successful.
- 400: Input data errors.
- 404: FIDO2 Relying Party not found.
- 500: Internal error, sub-service failure, server crash.
When updating a Relying Party Resource, only the fields that require an update need to be provided in the request body. Fields that are not provided will remain unchanged.
If you change the Relying Party ID (publicKeyCredentialRpEntity.id) or origins when updating your Relying Party Resource, note that registrations that were previously performed will not work anymore. To restore these registrations, you need to call the PATCH /fido2-relying-parties/{uuid} endpoint and enter the correct Relying Party ID (publicKeyCredentialRpEntity.id) and origins values.
We recommend as a best practice to keep records of the old Relying Party ID and origins values, as it will allow you to restore your Relying Party Resource registrations in case of problems.
Delete a FIDO2 Relying Party Resource
To delete a FIDO2 Relying Party Resource, call the following endpoint:
DELETE /fido2-relying-parties/{uuid}
The responses for this endpoint include the following:
- 204: Delete operation successful.
- 400: Input data errors.
- 404: FIDO2 Relying Party not found.
- 500: Internal error, sub-service failure, server crash.
It is not possible to delete the default Relying Party Resource.