FIDO2 in the Production environment
Overview of the Production environment
A typical FIDO2 deployment for the Production environment 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.
- . This is 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. The hosts yourwebapp.example-tenant.com/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.
Configuring FIDO2 in the Production environment
To enable the integration of FIDO2-based functionalities with OneSpan Cloud Authentication for the Production environment, the following information must be provided to properly configure FIDO2:
- Tenant name
- URL of your web application
- (If required) Metadata statements
To enable FIDO2 for the Production environment, submit a support ticket on the Product Support page by clicking the SUBMIT A SERVICE REQUEST button.
OneSpan Cloud Authentication provides a default policy, which is automatically applied to all newly created Relying Party resources. According to this default policy, all FIDO2 authenticators are allowed, however, these must be certified by the FIDO Alliance. The default policy can easily be replaced with a custom created policy that fits exactly the security needs of the application.
For more information about policies, seeFIDO2 policy.
Tenant name
Ensure that you have already created a tenant. To enable FIDO2, provide the tenant name to OneSpan support—our support staff will activate FIDO2 for you.
To demonstrate the onboarding steps, the name example-tenant is used in the steps describing the procedure.
Web application URL
Provide the URL of your web application that will be used to perform the FIDO2 ceremonies (registration and authentication). Based on the provided URL OneSpan deduces the Relying Party ID
A relying party identifier is a valid domain string identifying the Relying Party on whose behalf a given registration or authentication ceremony is being performed. As the registration ceremony is generating credentials on the client side (authenticator) these are scoped to the Relying Party that was conducting the registration ceremony. and the Origins An origin indicates where a request originated from. An origin should not include any path information, and it should use the https protocol. and configures the FIDO2 Server accordingly.
Examples of valid configurations for the Relying Party ID and Origins are:
- RP ID: yourwebapp.example-tenant.com
- Origins= https://yourwebapp.example-tenant.com
Relying Party ID
To demonstrate how the Relying Party ID can be retrieved, the following URLs are used as examples:
- https://yourwebapp.example-tenant.com/register
- https://yourwebapp.example-tenant.com/login.
The Relying Party ID can be extracted from your web application URL. To obtain the domain, remove the protocol and the paths from the URL. This domain can be used as the Relying Party ID.
| Protocol | Domain | Path |
|---|---|---|
| https:// | yourwebapp.example-tenant.com | /register |
In addition to the Relying Party ID extracted above, another valid Relying Party ID can be deduced, with a more generic structure as it only includes the domain, i.e. example-tenant.com. The following table lists examples of extracted valid Relying Party IDs.
| # | Valid Relying Party ID | Invalid Relying Party ID |
|---|---|---|
| 1 | yourwebapp.example-tenant.com | https://yourwebapp.example-tenant.com |
| 2 | example-tenant.com | yourwebapp.example-tenant.com/portal |
The advantage of using the more generic Relying Party ID (example-tenant.com) is that this allows you to use the same Relying Party ID with multiple websites. These can be hosted under the subdomains of example-tenant.com:
- yourwebapp.example-tenant.com
- otherwebapp.example-tenant.com
Origins
To avoid phishing attacks, FIDO2 has important checks on the client side, where the client verifies that the Relying Party ID matches the origin. If there is a mismatch, the request will be rejected.
The Relying Party ID and the origin are part of a client structure (clientData) which is hashed and signed by the authenticator and validated again on the FIDO2 Server side. Here, the origin from the clientData is checked against the set of Origins defined during the Relying Party configuration phase. The set of Origins needs to be collected so that the Origins can be properly configured on the FIDO2 Server.
The set of Origins must include the same domain that has been defined in the Relying Party ID.
The following table contains valid Origins examples for the valid Relying Party IDs defined above:
| # | Relying Party ID | Valid Origins |
|---|---|---|
| 1 | yourwebapp.example-tenant.com | https://yourwebapp.example-tenant.com |
| 2 | example-tenant.com | https://yourwebapp.example-tenant.com, https://otherwebapp.example-tenant.com:8443 |
For the example-tenant.com Relying Party ID, two valid origins are available as part of the set of Origins. Note that port numbers are also valid and can be included as part of an origin.
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.
Next steps
With this, FIDO2 is enabled and you are ready to use the supported FIDO2 operations. For more information on these operations, see the following articles: