Passkey Configuration REST API¶

Passkey Configuration REST API

This API provides a way to manage the global passkey authentication configuration through REST, without regenerating directory.xml and without restarting the server.
It is implemented by PasskeyRestHandler and persists settings under /security/config/passkeyconfig. After a successful update, the passkey authenticator reloads its runtime configuration.

The work on this feature was implemented in #11405.

Configuration¶

Passkey Configuration REST API is a sub-module of Administration_REST_API. To use it, the global REST API must be enabled. Please see Administration_REST_API.

Add Permissions for the Passkey Configuration REST API¶

To access this API, grant ACL permissions for the endpoint family:

<node class="container" name="security">
  <node class="container" name="acl">
    <node class="container" name="webservice">
      <!-- GET /admin/config/passkey -->
      <node class="container" name="000210">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/config/passkey"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <!-- PUT /admin/config/passkey -->
      <node class="container" name="000211">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:PUT:/admin/config/passkey"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
    </node>
  </node>
</node>

For the definition of admin-rest FWD user, see Administration_REST_API.

By setting these ACL entries, you allow:

Method	Path	Description	Body Required
`GET`	`/admin/config/passkey`	Get the current passkey configuration	No
`GET`	`/admin/config/passkey?includeSecrets=true`	Get the current passkey configuration including secret values	No
`PUT`	`/admin/config/passkey`	Update one or more passkey configuration fields and reload runtime configuration	Yes

Request Object Reference¶

The request body is a JSON object used by PUT. All fields are optional; only fields present in the request are updated.

Passkey Fields¶

Field	Type	Required	Description
`enabled`	Boolean	No	Enables or disables passkey authentication. Accepts JSON booleans or textual `true`/`false` values.
`passkeyPlugin`	String	No	Fully-qualified `PasskeySsoAuthenticator` implementation class. If unset, the default implementation is used.
`challengeTtlSec`	Integer	No	Challenge lifetime, in seconds. Runtime uses at least 30 seconds.
`rpId`	String	No	WebAuthn relying-party identifier. Default is `localhost`.
`origins`	String	No	Comma-separated list of allowed WebAuthn origins. Default is `https://localhost:7443`.
`totpEncryptionKey`	String	No	Secret key used for TOTP data encryption. This value is redacted by default in `GET` responses.

SMTP Fields¶

These SMTP fields are part of the same passkey configuration resource. They are used by passkey setup and verification e-mails.

Field	Type	Required	Description
`smtpHost`	String	No	SMTP server host name or IP address.
`smtpPort`	String	No	SMTP server port. Stored as text to match the mail subsystem configuration.
`smtpConnType`	String	No	SMTP connection security mode. Accepted values are `UNENCRYPTED`, `STARTTLS_WHEN_AVAILABLE`, `STARTTLS_REQUIRED`, and `SSL`. Hyphenated forms such as `STARTTLS-REQUIRED` are also accepted.
`smtpUser`	String	No	SMTP authentication user.
`smtpPassword`	String	No	SMTP authentication password. This value is redacted by default in `GET` responses.
`mailFrom`	String	No	Sender address for passkey/TOTP setup verification e-mails.
`mailSubject`	String	No	Subject for passkey/TOTP setup verification e-mails.

Notes:

Unknown fields are rejected.
Text fields are trimmed. Blank strings are stored as null.
null removes an existing configured value.
PUT creates /security/config/passkeyconfig if the node does not exist.
Successful PUT requests call PasskeySsoAuthenticator.reloadConfigFromDirectory().
smtpConnType defaults to UNENCRYPTED at runtime if unset or invalid in the directory.
GET redacts smtpPassword and totpEncryptionKey by returning smtpPasswordConfigured and totpEncryptionKeyConfigured unless includeSecrets=true is supplied.

API Routes¶

The Passkey Configuration REST API has the following capabilities:

Authentication: login/logout are provided by the main module. See Administration_REST_API.
Read configuration: retrieve current passkey and SMTP configuration values.
Update configuration: update only the submitted fields.
Runtime reload: on successful PUT, runtime passkey configuration is reloaded.

Get Passkey Configuration¶

Retrieve the passkey configuration by performing a GET request at /admin/config/passkey.
Header must include a valid FwdSessionId token.

Show example - successful get Show example - successful get

Request:

GET /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{
  "enabled": true,
  "passkeyPlugin": "com.example.security.CustomPasskeyAuthenticator",
  "smtpHost": "smtp.example.com",
  "smtpPort": "587",
  "smtpConnType": "STARTTLS_REQUIRED",
  "smtpUser": "passkey@example.com",
  "smtpPasswordConfigured": true,
  "mailFrom": "passkey@example.com",
  "mailSubject": "Your FWD verification code",
  "rpId": "example.com",
  "origins": "https://app.example.com,https://admin.example.com",
  "totpEncryptionKeyConfigured": true,
  "challengeTtlSec": 300
}

Show example - include secret values Show example - include secret values

Request:

GET /admin/config/passkey?includeSecrets=true HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{
  "enabled": true,
  "passkeyPlugin": "com.example.security.CustomPasskeyAuthenticator",
  "smtpHost": "smtp.example.com",
  "smtpPort": "587",
  "smtpConnType": "STARTTLS_REQUIRED",
  "smtpUser": "passkey@example.com",
  "smtpPassword": "secret",
  "mailFrom": "passkey@example.com",
  "mailSubject": "Your FWD verification code",
  "rpId": "example.com",
  "origins": "https://app.example.com,https://admin.example.com",
  "totpEncryptionKey": "base64-encoded-key",
  "challengeTtlSec": 300
}

Show example - no configuration node Show example - no configuration node

Request:

GET /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{}

Update Passkey and SMTP Configuration¶

Update passkey or SMTP configuration by performing a PUT request at /admin/config/passkey.
Header must include a valid FwdSessionId token.

The request body must be a JSON object.
Only submitted fields are changed.
Secret values can be cleared by submitting null.
Runtime passkey configuration is reloaded after a successful update.

Show example - successful put Show example - successful put

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "enabled": true,
  "passkeyPlugin": "com.example.security.CustomPasskeyAuthenticator",
  "smtpHost": "smtp.example.com",
  "smtpPort": "587",
  "smtpConnType": "STARTTLS_REQUIRED",
  "smtpUser": "passkey@example.com",
  "smtpPassword": "secret",
  "mailFrom": "passkey@example.com",
  "mailSubject": "Your FWD verification code",
  "challengeTtlSec": 300,
  "rpId": "example.com",
  "origins": "https://app.example.com,https://admin.example.com",
  "totpEncryptionKey": "base64-encoded-key" 
}

Response (HTTP 200):

{
  "success": true,
  "message": "Passkey configuration updated." 
}

Show example - update SMTP fields only Show example - update SMTP fields only

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "smtpHost": "smtp.example.com",
  "smtpPort": "587",
  "smtpConnType": "STARTTLS_REQUIRED",
  "smtpUser": "passkey@example.com",
  "smtpPassword": "secret",
  "mailFrom": "passkey@example.com",
  "mailSubject": "Your FWD verification code" 
}

Response (HTTP 200):

{
  "success": true,
  "message": "Passkey configuration updated." 
}

Show example - clear optional values Show example - clear optional values

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "passkeyPlugin": null,
  "smtpUser": null,
  "smtpPassword": null,
  "totpEncryptionKey": null
}

Response (HTTP 200):

{
  "success": true,
  "message": "Passkey configuration updated." 
}

Show example - failure (unknown field)Show example - failure (unknown field)

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "enabled": true,
  "unknown": "value" 
}

Response (HTTP 400):

{
  "success": false,
  "errors": [
    "Unknown passkey configuration field: unknown" 
  ]
}

Show example - failure (invalid connection type)

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "smtpConnType": "TLS" 
}

Response (HTTP 400):

{
  "success": false,
  "errors": [
    "Invalid smtpConnType: TLS" 
  ]
}

Show example - failure (invalid boolean)

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "enabled": "yes" 
}

Response (HTTP 400):

{
  "success": false,
  "errors": [
    "Invalid boolean value for enabled." 
  ]
}

Show example - failure (request body is not an object)

Request:

PUT /admin/config/passkey HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

[
  {
    "smtpHost": "smtp.example.com" 
  }
]

Response (HTTP 400):

{
  "success": false,
  "errors": [
    "Request body must be a JSON object." 
  ]
}

Project

General

Profile

FWD

Wiki

Passkey Configuration REST API¶

Configuration¶

Add Permissions for the Passkey Configuration REST API¶

Request Object Reference¶

Passkey Fields¶

SMTP Fields¶

API Routes¶

Get Passkey Configuration¶

Update Passkey and SMTP Configuration¶