Passkey validator

Other components that this module uses or need:

• Web -> WebAuthnValidation
  To authenticate users using a Passkey you need to have a database connection. ref:tokens/
• Enrollment -> Check out the Enrollment documentation.
  To be able to authenticate you must have enrolled for a token.

Configuration

Note

Authenticator type: Passkey

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
username_parameter	Name of the property to where the username is exported	username	false
namespace	Namespace used to communicate with other modules	default	false
webroot_dir	See common authenticator configuration	web/authenticator/webauthn	false
auto_start	If true, the authentication will start automatically when the user is presented with the UI (no click required) If false, the user is presented with a button to start the authentication	true	false

Example

{
  "id": "passkey",
  "type": "Passkey",
  "config": {
    "base_path": "/saml/authn",
    "context_path": "/saml/authn/webauthn"
  }
}

Caution

Property base_path should not contain the full path when used in conjunction with the Selector, instead, the full URI will be handled by the selector. The full path will be base_path + / + id.

Logging

• WEB_100022("Passkey validated")

  • IDENTIFIER (user trace id)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_ADDRESS (ip of the remote session)

• WEB_100023("Passkey validation failed")

  • IDENTIFIER (user trace id)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_ADDRESS (ip of the remote session)

Global state

After successful authentiation, the authenticator populates the configured username property with the user identifier obtained during the Web Authentication process.

API

API follows the general conventions of the Fortified Web Authenticator API. The messages below carry the structures defined in Web Authentication: An API for accessing Public Key Credentials Level 2, W3C Recommendation, 8 April 2021.

General requirements

All requests use the HTTP PUT method with Content-Type: application/json, sent to the directory URL the view was loaded from. The session cookie must be sent with every request, and the browser must support the Web Authentication API.

Messages

Message	Purpose
init	Fetch view settings. Send it when the view loads.
options	Begin an authentication and obtain the credential request options.
verification	Return the assertion produced by the browser.
state	Fetch the current state. This authenticator keeps no intermediate state and always answers NONE.
cancel	Cancel the authentication.

Init

Send this when the view loads. The response tells the view whether to invoke the browser dialogue immediately or wait for the user to act.

Request

{
    "type": "init"
}

Response

{
    "type": "init",
    "success": true,
    "data": {
        "auto_start": true
    }
}

auto_start mirrors the configuration property of the same name.

Begin authentication

Request the credential request options. The server generates a challenge, stores it for the session, and answers with a PublicKeyCredentialRequestOptions as the whole response body.

Request

{
    "type": "options"
}

Response

{
    "challenge": "<base64url>",
    "rpId": "<relying-party-id>",
    "timeout": 60000,
    "userVerification": "preferred"
}

Caution

The stored challenge is valid for 10 minutes and is consumed by the next verification request. Request new options rather than reusing an old challenge.

Complete authentication

Pass the options to the browser to obtain an AuthenticatorAssertionResponse, then return the assertion. All binary members are base64url encoded.

Request

{
    "type": "verification",
    "data": {
        "assertion": {
            "id": "<credential-id>",
            "response": {
                "userHandle": "<base64url>",
                "authenticatorData": "<base64url>",
                "clientDataJSON": "<base64url>",
                "signature": "<base64url>"
            }
        }
    }
}

Response

{
    "status": "AUTHORIZED"
}

Errors

{
    "status": "UNAUTHORIZED"
}

Returned when the assertion cannot be verified, when no challenge is pending, or when the challenge has expired. The authenticator treats this as a failed authentication.

Getting state

This authenticator holds no intermediate state between options and verification, so the response is always the same. A view that is reloaded must start over with options.

Request

{
    "type": "state"
}

Response

{
    "status": "NONE"
}

Cancel a request

A request can be canceled at any time. This is done by sending a cancel request.

{
    "type": "cancel"
}

Response from server

Expect HTTP status code 200. Anything else is to be considered an error.

The body is a JSON object. The options response is the credential request options object itself; the other messages answer with a status property or with a complete, cancel, or failure message as described in Web Authenticator API.

Possible status messages

Status	Meaning
NONE	No authentication is in progress. Only returned by state.
AUTHORIZED	The assertion was verified and the user is authenticated.
UNAUTHORIZED	The assertion could not be verified.

Translation keys

{
  "webauthn.start_validate": "Login",
  "webauthn.verifying": "Verifying passkey",
  "webauthn.verified": "Passkey verified",
  "webauthn.redirecting": "Redirecting...",
  "webauthn.validation_error.authenticator_failure": "Passkey authentication failed",
  "webauthn.validation_error.verification_failure": "Passkey verification failed",
  "webauthn.validation_error.unknown_error": "Unknown error",
  "webauthn.reset_button": "Go back",
  "allow-cookies-body": "To save your language settings on this device you need to approve a language cookie.",
  "allow-cookies-button": "Approve language cookie",
  "authentication.help_text": "",
  "change_language": "Change language"
}

{
  "webauthn.start_validate": "Logga in",
  "webauthn.verifying": "Säkerhetsnyckel verifieras...",
  "webauthn.verified": "Säkerhetsnyckel verifierad",
  "webauthn.redirecting": "Omdirigerar...",
  "webauthn.validation_error.authenticator_failure": "Autenticering med säkerhetsnyckel misslyckades",
  "webauthn.validation_error.verification_failure": "Verifiering av säkerhetsnyckel misslyckades",
  "webauthn.validation_error.unknown_error": "Okänt fel inträffade",
  "webauthn.reset_button": "Gå tillbaka",
  "allow-cookies-body": "Vill du spara dina språkinställningar på denna enhet behövs ett godkännande av  språk-cookie.",
  "allow-cookies-button": "Godkänn språk-cookie",
  "authentication.help_text": "",
  "change_language": "Byt språk"
}