Passkey Registration

Early Access

Introduction

To construct a simple experience, registration is controlled using a Custom Form or Custom Page within TrustX. This document will describe the steps in configuring a solution using the Process Designer and TrustX API to register a new User using passkey registration.

This guide will use a Custom Form that requests a User name and User display name to register a User in an Identity Store.

Registering via Process Definition

The example Process Definition in this guide will utilize a Custom Data Form to handle the registration of a passkey.

Step 1 - Create a Process Definition

1. Create a new Process Definition by navigating to Process Definitions > New Process Definition in the Backoffice application.

2. Add a 'Create Start Event' to the Process Designer.

3. Click the 'Start' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.

4. Add a 'Create End Event' to the Process Designer and connect it to the 'Start' event using a sequence flow arrow.

5. Click the 'End' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.

Step 2 - Add a User (Optional)

This step is only required if the User has not been added to the Identity Store. See Managing Users for more information on adding a User.

1. The 'Add User' activity is used to add a new User to an Identity Store. Find the activity and connect it to the 'Start' and 'End' events using a sequence flow arrow.

2. The 'Add User' activity includes two error events. In this example, the error events have been connected to the 'End' event.

   1. Failed to add the user - This event is triggered when an error occurs adding the User to the Identity Store.

   2. ExtId Not Unique - This event occurs if the External ID provided is not unique.

3. Click the 'Add User' activity to open the right-side contextual menu. Using the available input parameters, information about the User can be defined, including the External ID and which Identity Store the user will be added to.

4. When creating a User, the following input parameters are available:

Step 3 - Start Passkey Registration

1. Add the 'Start Passkey Registration' activity to the Process Designer and connect the activity to the 'Add User' activity using a sequence flow arrow.

2. The 'Start Passkey Registration' activity contains 12 configurable input parameters. The table below describes each parameter, which is accessed by clicking the activity and opening the contextual menu on the right of the screen.

Start Passkey Registration via API

The passkey registration process can be started via the API by calling either:

• /api/identity-store/stores/{storeName}/users/{userId}/passkeys/relyingParties/{rpId}/registrations/{regPolicyName}

• /api/identity-store/stores/{storeName}/users/{userExtId}/passkeys/relyingParties/{rpId}/registrations/{regPolicyName}/ext

Permissions: TNT#{tenant}#IdentityStore:createPasskeyRegistrationForUser, TNT#{tenant}#IdentityStore:createPasskeyRegistrationForUserByExtId , TNT#{tenant}#IdentityStore:createPasskeyRegistration

Example Request:

Example Response:

As seen above, the response will return a sessionID, which is used to complete the passkey registration in Step 6.

Step 4 - Configure the Registration Form

The example in this document will use a Custom Form that collects the 'Passkey User Display Name' and 'PassKey User Name' from the end-user. This Custom Form is then populated in the 'Passkey Registration Form' activity. This is a unique type of form activity that is used for the purpose of passkey registration.

1. Create a new Custom Form from the Integration Hub > Custom Forms section of the Backoffice. For more information using the Custom Form builder, see the Custom Data Forms guide.

2. The example below demonstrates a JSON form that requests the 'User Name' and 'Display Name'.

3. Once the Custom Form has been created, add a 'Passkey Registration Form' activity to the Process Designer and connect to the 'Start Passkey Registration' activity using a sequence flow arrow.

4. The 'Passkey Registration Form' contains configurable input parameters. The table below describes each configurable parameter:

5. When the form is displayed to the end-user, they will have the ability to define their username and display name:

6. When clicking the 'Submit for Registration' button, a popup will appear to choose the registration method.

Step 4 - Configure a Custom Page (Optional)

It is also possible to request the data from a Custom Page instead of a Custom Form by using the Custom Page activity. For this flow to work, it is important that the 'Passkey Registration Browser Response' input parameter is entered in Step 6.

1. Create a new Custom Page from the Integration Hub > Custom Pages section of the Backoffice. For more information on creating Custom Pages, see the Custom Pages Guide.

2. The example HTML below requests the 'User Name' and 'Display Name' from the end-user:

3. In the Process Definition, configure the 'Custom Page V2' activity by connecting it to the 'Start Passkey Registration' activity.

4. Under the activity input parameters, set the 'Constants' to ensure the client request is sent.

In the example above, the entry is set accordingly:

• Key: passkeyRegClientRequest

• Value: ${_identityStore.passkeys.registrations["passkeyReg1"].currentPasskeyRegistrationRecord.startPasskeyRegistrationResponse.clientRequest}

Step 5 - Add a Simple Decider

A 'Simple Decider' activity can be used to determine whether the registration attempt has been successful. At this point, it can also be used to connect the various boundary events that appear in the previous steps.

1. Add the 'Simple Decider' activity to the Process Designer and connect all boundary events configured so far to the activity.

2. The 'Simple Decider' includes two input parameters which can be defined as follows:

   1. Decision on Any Failure - The result that will be returned in the event that any failure occurs during the Process Instance.

   2. Derive Decision From - Determines whether to derive a decision from a variable. In this example, the parameter is left blank.

Step 6 - Complete Passkey Registration

The 'Complete Passkey Registration' activity is used to finalize the passkey registration process.

1. Add the 'Complete Passkey Registration' activity after the 'Passkey Registration Form' and connect using a sequence flow arrow.

2. The 'Complete Passkey Registration' has three configurable input parameters described in the table below:

3. This activity includes two boundary events that are described below:

   1. User cancelled - This event is triggered when the end-user cancels the passkey registration flow.

   2. Failed ID Store Service Call - This event is triggered when the process fails to reach the Identity Store service.

4. One possible handling of the error boundary event is to request a retry from the end-user. This example demonstrates a retake form that is shown after the User cancelled boundary event is triggered.

5. Create a new Custom Form to handle the retry flow. The example form below demonstrates a simple retry flow where the registration can be attempted again.

6. In the Process Definition, add a 'Custom Data Form' activity and connect it to the 'User cancelled' boundary event using a sequence flow arrow. Connect another sequence flow arrow back to the 'Passkey Registration Form' activity.

Complete Passkey Registration via API

The passkey registration process can be completed via the API by calling either:

• /api/identity-store/stores/{storeName}/users/{userId}/passkeys/relyingParties/{rpId}/registrations/{regPolicyName}

• /api/identity-store/stores/{storeName}/users/{userExtId}/passkeys/relyingParties/{rpId}/registrations/{regPolicyName}/ext endpoints.

Permissions: TNT#{tenant}#IdentityStore:createPasskeyRegistrationForUser, TNT#{tenant}#IdentityStore:createPasskeyRegistrationForUserByExtId , TNT#{tenant}#IdentityStore:createPasskeyRegistration

Example Request:

The {sessionId} is supplied by the response of the Start Passkey Registration API response seen above.