Passkey Authentication

Early Access

Introduction

This document assumes that a User has been added to an Identity Store and that the User has registered a passkey. Please follow the auto$ guide first before continuing to the authentication process.

Authenticating via Process Definition

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.
  1. Click the 'Start' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.
  2. Add a 'Create End Event' to the Process Designer and connect it to the 'Start' event using a sequence flow arrow.
  1. Click the 'End' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.

Step 2 - Start the Authentication Process

The 'Start Passkey Authentication' activity is used to begin the authentication process.

  1. In the Process Designer, add the 'Start Passkey Authentication' activity after the 'start' event and connect using a sequence flow arrow.
  1. The 'Start Passkey Authentication' provides 8 configurable parameters described below:
Input ParameterTypeDescription
Authentication PolicyStringThe authentication policy to use for the authentication process. See auto$ for information on configuring an authentication policy.
ChallengeStringThe signed challenge is represented by a public key registered to the User. This value is auto-generated.
Passkey Authentication KeyStringRequired - The unique ID associated with the passkey authentication activity.
Relying Party IDStringRequired - The ID of the relying party whose passkey registration configuration will be used.
Store NameStringRequired - The name of the Identity Store.
User External IDStringThis property can be used to identify the User that the passkey registration applies to.
User IDStringThe unique ID automatically generated when the User is created. In the context of the 'Start Passkey Registration' activity, this ID can be used to identify the User that the passkey registration applies to.
User KeyStringThe User Key that can be used to identify the User that the passkey authentication applies to.
  1. When the authentication process is started, the end-user will see a button that allows them to begin the authentication process.

Step 3 - Configure the Authentication Form

The authentication form is used to accept input from the end-user who will be completing the passkey authentication. In this example, the end-user will be requested to provide their 'User Name' and 'Display Name' to complete the authentication process.

  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'.
JSON
Copy
  1. Once the Custom Form has been created, add a 'Passkey Authentication Form' activity to the Process Designer and connect to the 'Start Passkey Authentication' activity using a sequence flow arrow.
  1. The 'Passkey Authentication Form' activity includes the following Input Parameters:
Input ParameterTypeDescription
Authentication timeout (in seconds)IntegerThe allotted time to complete the form before a timeout event occurs.
Data form nameStringThe Custom Form that will be displayed to the end-user.
Data form versionIntegerThe version of the Custom Form.
Delay (in seconds)IntegerIf 'Hide buttons' is enabled, this parameter will configure how long the page is displayed before progressing to the next step.
Form data KeyStringThe unique identifier of the 'Passkey Registration Form' activity.
Hide buttonsBooleanIf enabled, the 'continue' button will be hidden from the form. This is disabled by default, meaning buttons will be shown.
Passkey Authentication KeyStringThe unique ID associated with the passkey authentication attempt.

Start Passkey Authentication via API

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

  • /api/identity-store/stores/{storeName}/users/{userId}/passkeys/relyingParties/{rpId}/authentications/{authPolicyName}
  • /api/identity-store/{tenantId}/stores/{storeName}/users/{userExtId}/passkeys/relyingParties/{rpId}/authentications/{authPolicyName}/ext.

Permissions: TNT#{tenant}#IdentityStore:createPasskeyAuthenticationForUser, TNT#{tenant}#IdentityStore:createPasskeyAuthenticationForUserByExtId

Example Request:

HTTP
Copy

Example Response:

JSON
Copy

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

Step 3 - 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.

  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:
Download Example on Github
HTML
CSS
Javascript
Copy
  1. In the Process Definition, configure the 'Custom Page V2' activity by connecting it to the 'Start Passkey Authentication' activity.
  1. Under the activity input parameters, set the 'Session Data' to ensure the client request is sent.

In the example above, the entry is set accordingly:

  • Key: passkeyAuthClientRequest
  • Value: ${_identityStore.passkeys.authentications["passkeyAuth1"].currentPasskeyAuthenticationRecord.startPasskeyAuthenticationResponse.clientRequest}

Step 4 - 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.
  1. 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 5 - Complete Passkey Authentication

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

  1. Add the 'Complete Passkey Authentication' activity after the 'Passkey Registration Form' and connect using a sequence flow arrow.
  1. The 'Complete Passkey Authentication' has three configurable input parameters described in the table below:
Input ParameterTypeDescription
Fail Check on CancelBooleanIf enabled, checks will fail if the end-user cancels out of the process. Default behavior is disabled.
Passkey Authentication Browser ResponseString

This input parameter must be set when the passkey registration flow uses a Custom Page to collect data instead of a form.

In order to complete the passkey authentication, a response from the browser must be provided. This response is returned from the Custom Page and can be entered into the 'Passkey Authentication Browser Response' using variable substitution.

${_customUis.{{customPageKey}}.currentCapture.customPageParameters.passkeyAuthClientResponse.value}

Passkey Authentication KeyStringThe unique ID associated with the passkey authentication attempt.

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

    1. User cancelled - This event is triggered when the end-user cancels the passkey authentication flow.
    2. Failed ID Store Service Call - This event is triggered when the process fails to reach the Identity Store service.

  2. 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.

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

JSON
Copy
  1. 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 Authentication Form' activity.

Complete Passkey Authentication via API

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

  • /api/identity-store/stores/{storeName}/users/{userId}/passkeys/relyingParties/{rpId}/authentications/{authPolicyName}
  • /api/identity-store/{tenantId}/stores/{storeName}/users/{userExtId}/passkeys/relyingParties/{rpId}/authentications/{authPolicyName}/ext

Permissions: TNT#{tenant}#IdentityStore:createPasskeyAuthenticationForUser, TNT#{tenant}#IdentityStore:createPasskeyAuthenticationForUserByExtId

Example Request:

HTTP
Copy

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

Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Face Authentication
Edit on GitHub
On This Page
Passkey AuthenticationIntroductionAuthenticating via Process DefinitionStep 1 - Create a Process DefinitionStep 2 - Start the Authentication ProcessStep 3 - Configure the Authentication FormStart Passkey Authentication via APIStep 3 - Configure a Custom Page (Optional)Step 4 - Add a Simple DeciderStep 5 - Complete Passkey AuthenticationComplete Passkey Authentication via API