Introduction
This manual provides instructions for integrating and using the WebAuthn library within your OutSystems web application. This library, an implementation of the FIDO2 .NET Library, enables user authentication via passkeys, offering a more secure alternative to traditional password-based methods.
Prerequisites
Before you begin, ensure the following prerequisites are met:
1. .NET Framework 4.8: The application server must have .NET Framework 4.8 installed.
2. Import WebAuthCredentials Entity: Import the `WebAuthCredentials` Entity from the library to store user credentials.
3. Import Client Actions: Import all client actions provided by the library into your application.
4. Import all static entities from the library.
Configuration Requirements
Configure the following parameters within your application:
- ServerDomain: The domain of your server (e.g., `example.com`).
- ServerName: The full server name, potentially including subdomains (e.g., `auth.example.com`).
- Origin: The origin URL, including protocol and port (e.g., `https://auth.example.com:443`).
These parameters are essential for the WebAuthn process and must be accurately set to match your deployment environment.
Adding a Passkey to a User's Account
Step 1: Call 'MakeCredentialsOptions' Client Action
When the user initiates the passkey addition process (e.g., by pressing a button), call the `MakeCredentialsOptions` client action.
Step 2: Configure Input Parameters
Set the input parameters for the `MakeCredentialsOptions` client action:
- ServerDomain: Your server's domain.
- ServerName: Your server's full name.
- Origin: Your server's origin URL.
- UserId: The unique identifier of the user for whom the passkey is being added.
- TypeOfAttestation : This option allows servers to indicate how important the attestation data is to this registration event. A value of "none" indicates that the server does not care about attestation. A value of "indirect" means that the server will allow for anonymized attestation data. direct means that the server wishes to receive the attestation data from the authenticator.
"none"
"indirect"
direct
- UserVerification : a FIDO2 call where the authenticator verifies that the user is authorized to use the authenticator, and signals to the RP whether user verification was successful. A value of "DISCOURAGED" indicates that the RP does not want user verification employed during the operation. "PREFERRED" value indicates that the RP prefers user verification for the operation if possible. "REQUIRED": Indicates that the RP requires user verification for the operation
Step 3: Handle the Result Object
The `MakeCredentialsOptions` client action will return a Result object. This object must be interpreted to determine the success or failure of the passkey addition.
Authenticating a User with a Passkey
Step 1: Call 'MakeAssertionOptions' Client Action
Upon the user's request to authenticate (e.g., button press), call the `MakeAssertionOptions` client action.
Set the input parameters for the `MakeAssertionOptions` client action:
- Username: The username of the user attempting to authenticate.
The `MakeAssertionOptions` client action will return a Result object. This object must be interpreted to determine the success or failure of the authentication process.
Step 4: Log in the User
If authentication is successful, use the `Login` server action from the System module to log in the user without a password.
Configuration Example
For a hypothetical website with the URL `https://auth.example.com`, the configuration would be:
- ServerDomain: `example.com`
- ServerName: `auth.example.com`
- Origin: `https://auth.example.com`
Conclusion
By following the steps outlined in this manual, you can effectively implement the WebAuthn library in your OutSystems application. This will enable a more secure and user-friendly authentication process using passkeys. If you encounter any difficulties or have questions, please refer to the detailed documentation provided with the library.
User Guide for OutSystems WebAuthn Library
Before you can use the WebAuthn library for user authentication, ensure the following prerequisites are met:
1. Import the `WebAuthCredentials` entity from the library into your OutSystems application. This entity will store the necessary user credentials.
2. .NET Framework 4.8
To configure the library for use, you must set up the following parameters:
- `ServerDomain`: The domain of your server without any subdomains (e.g., `example.com`).
- `ServerName`: The name of your server, which may include subdomains (e.g., `auth.example.com`).
- `Origin`: The origin URL of your server, including the protocol and port if not default (e.g., `https://auth.example.com:443`).
These parameters are critical for the security of the WebAuthn process and must be consistent with the actual deployment environment of your application.
Step 1: Import Register Web Block
Import the `Register` web block from the library into the desired screen of your application.
Configure the input parameters of the `Register` web block:
- `ServerDomain`: Set this to the domain of your server (e.g., `example.com`).
- `ServerName`: Set this to the name of your server (e.g., `auth.example.com`).
- `Origin`: Set this to the origin URL of your server (e.g., `https://auth.example.com`).
- `UserId`: The unique identifier of the user within your application. It cannot be null
Step 3: Set Up Event Handler
Set up the event handler for the button click event within the `Register` web block. This handler should manage the result parameter, which indicates the success or failure of adding the passkey.
Step 1: Import Authenticate Web Block
Import the `Authenticate` web block from the library into the desired screen of your application.
Configure the input parameters of the `Authenticate` web block:
- `Username`: The username of the user attempting to authenticate.
Step 3: Define Event Handler
Define the event handler for the button click event within the `Authenticate` web block. This handler should manage the result parameter, which signals the authentication outcome.
Step 4: Handle Successful Authentication
For a hypothetical website with the URL `https://auth.example.com/resturl`, the configuration would be as follows:
- `ServerDomain`: `example.com`
- `ServerName`: `auth.example.com`
- `Origin`: `https://auth.example.com`
Ensure that these values match your actual server deployment.
This guide provides a clear and concise framework for setting up and using the WebAuthn library in your OutSystems application. By following these step-by-step instructions, you can implement a secure, passwordless authentication system using passkeys.