FIDO2 Server Configuration#

This document contains a detailed reference of configuration properties. To learn how to safely update these dynamic configuration parameters, please follow the Janssen FIDO2 Configuration Guide first.

FIDO2 Server Configuration Parameters#

The following properties represent the dynamic configuration for the Janssen FIDO2 Server. They are stored in the configuration storage layer and can be updated at runtime.

Client IP in metrics#

The ipAddress recorded on a passkey metrics entry is taken from forwarded proxy headers (X-Forwarded-For and several older equivalents) before falling back to the address the request actually came from. Those headers are set by whoever sends the request, so trustedProxyEnabled controls whether they are believed:

The default is unset so that upgrading changes nothing. Deployments that want the recorded address to be trustworthy must set this explicitly.

When trusted, X-Forwarded-For is read right to left: hops that are themselves listed as trusted proxies are skipped, and the first remaining address is recorded. Reading from the right matters because a client can prepend any value before the real proxy appends to the chain — so the leftmost entry is only used when no closer untrusted hop exists, such as a single-entry header from a trusted proxy.

X-Forwarded-For is the only header consulted in this mode. The older alternatives (Proxy-Client-IP, WL-Proxy-Client-IP and the HTTP_* variants) are ignored, because a reverse proxy overwrites X-Forwarded-For but passes other request headers through as the client sent them. Legacy mode still reads all of them. If nothing usable is found, the connecting address is recorded.

Ranges accept IPv4 and IPv6 CIDR notation; a bare address is treated as a full-length mask. An IPv4-mapped IPv6 address such as ::ffff:10.1.2.3 matches an IPv4 range, since a dual-stack JVM may report the connecting address in that form.

A range may also be written in that form. Its prefix is then read on whichever scale it can only mean, so an existing IPv4-scale range keeps working:

Both sides of a comparison must be IP literals — a hostname is rejected and logged rather than resolved, because this runs on the request path.

Note on a common topology. Where a reverse proxy runs on the same host, requests reach the FIDO2 server from 127.0.0.1, and so do any sent directly to it. Trusting loopback therefore does not, on its own, distinguish the proxy from a direct caller.

The Authorization Server and Casa are callers too. Neither is a browser-facing reverse proxy, but both relay passkey ceremonies to FIDO2 and send the connecting address they observed on the browser's request (getRemoteAddr(), not a browser-supplied header) as X-Forwarded-For on that call — see Request context on raw entries. If trustedProxyEnabled is true, their addresses need to be in trustedProxyIpRanges as well, the same as any other trusted hop, or their forwarded value is ignored in favor of the connecting address.

FIDO2 Configuration Object (fido2Configuration)#

This nested block defines WebAuthn and FIDO2 attestation and assertion policy behavior.

Lock Server audit delivery#

When lockAuditEnabled is true, the server buffers passkey registration/authentication events and delivers them to the configured Lock Server's /audit/log/bulk endpoint on the lockAuditFlushInterval cadence, rather than one call per ceremony. A Lock Server that is unreachable, slow, or returns an error never affects the registration/authentication request itself — delivery is fire-and-forget, and a failed batch is dropped rather than retried inline.

No signing, hashing, or chaining of the delivered events is performed; that is planned as later work, not part of this delivery path.

Passkey registration outcomes (both successful and failed) are recorded as fido2_registration events, with decisionResult of ALLOW or DENY, principalId set to the username where known, and contextInformation carrying the relying party ID, origin, credential ID and attestation type on success. A failed registration records only the exception's class name, never its message, since some registration failure messages embed the username or challenge.

Passkey authentication outcomes (both successful and failed) are recorded as fido2_authentication events, with decisionResult of ALLOW or DENY, principalId set to the username where known, and contextInformation carrying the relying party ID, credential ID, and the origin the ceremony actually happened at — which is not necessarily the origin the credential was originally registered at, since a credential registered at one permitted origin of an RP can be used from a different permitted origin later. A failed authentication records only the exception's class name, never its message, since some authentication failure messages embed the username or challenge.

Per-relying-party policy#

An entry under rp may carry a policy object overriding the corresponding global setting for that relying party alone:

{
  "id": "high-assurance.example.com",
  "origins": ["https://high-assurance.example.com"],
  "policy": { "attestationMode": "enforced" }
}

An RP with no policy, or with the field unset, behaves exactly as it did before this existed — the global value applies. The same is true for a ceremony whose origin matches no configured RP. Nothing needs changing on upgrade.

Only attestationMode is settable per RP today. Further fields are added alongside the change that enforces them, so that anything listed here is a policy actually in effect rather than a value that is merely stored.

Native applications of a relying party#

An entry under rp may also list the Android and iOS apps that share its RP ID, next to the web origins:

{
  "id": "example.com",
  "origins": ["https://login.example.com"],
  "androidApps": [
    {
      "packageName": "com.example.app",
      "sha256CertFingerprints": ["AB:CD:EF:..."],
      "distribution": "play-store"
    }
  ],
  "iosApps": [
    { "teamId": "T9A667JL6T", "bundleId": "com.example.app" }
  ]
}

This is the single place an RP's native apps are recorded. It is what the assetlinks.json and apple-app-site-association files are meant to be generated from, and what a deployed copy of them can be checked against.

These fields are recorded but not enforced. Whether an origin is accepted is decided only by origins (see above); a package name, fingerprint, team ID or bundle ID listed here neither allows nor blocks a ceremony. When an origin is rejected, the server log says which RPs were considered and that configured native apps are not matched against it, to make that visible. An RP with neither list behaves exactly as it did before these fields existed, and nothing needs changing on upgrade.

Advertised algorithms#

The algorithms offered to the authenticator in pubKeyCredParams are not taken from enabledFidoAlgorithms directly. An algorithm is advertised only when this server can complete a registration with it end-to-end: decode the credential public key and verify a signature made with it, using the crypto provider the deployment is actually running. Anything else is dropped: a configured name that does not survive the check is logged at ERROR, and a default that does not survive it is logged at WARN.

This matters most on the FIPS build, whose provider supports strictly fewer algorithms than the standard one. Deriving the advertised set from real capability means a FIPS deployment simply offers less, rather than offering an algorithm and then failing the ceremony once the authenticator picks it.

If no configured algorithm survives the check, the server logs an error and falls back to whichever of the defaults it does support. In a deployment that supports none of them that fallback is itself empty, and pubKeyCredParams is sent empty — a state worth alerting on, since the log will already carry the reason.

Fully-specified ECDSA algorithms#

ESP256 and ESP384 name their elliptic curve in the COSE code point itself rather than leaving it to the credential: ESP256 is P-256 only and ESP384 is P-384 only. A credential that pairs one of them with any other curve is rejected during registration. ES256, ES384 and ES512 are not fully specified and take whichever curve the key carries.

Fully-specified EdDSA algorithms#

EdDSA is the original COSE code point and takes whichever Edwards curve the credential carries — both Ed25519 and Ed448 keys are accepted under it. Ed25519 and Ed448 are separate, fully-specified code points that name their curve: a credential pairing Ed25519 with an Ed448 key, or the reverse, is rejected during registration.

Existing credentials are unaffected — they were registered under EdDSA, whose behaviour is unchanged.

Post-quantum algorithms (ML-DSA)#

ML-DSA-44, ML-DSA-65 and ML-DSA-87 are supported on the standard build. They are not available on the FIPS build, because no released bc-fips provider implements them yet.

This needs no special handling from an administrator. Because the advertised set is derived from real provider capability (see Advertised algorithms), a FIPS deployment that lists an ML-DSA name simply logs it at ERROR and leaves it out of pubKeyCredParams — it never offers an algorithm it would then fail to verify. The same configuration is therefore safe to share between the two build variants.

Both the IANA spelling (ML-DSA-44) and the underscore form (ML_DSA_44) are accepted.

Cross-origin ceremonies#

As WebAuthn Level 3 requires, the server reads the crossOrigin member of CollectedClientData. An absent member is treated as false; both a non-boolean value and an explicit null fail with invalid_request.

When crossOrigin is true, the ceremony is allowed only if its topOrigin — the origin of the page that framed it — appears in allowedTopOrigins. The request fails with cross_origin_not_allowed when:

• allowedTopOrigins is empty, which is the default and denies every framed ceremony
• topOrigin is absent, null, not a string, or blank
• topOrigin is not listed

Entries are compared against the whole origin, ignoring case and surrounding whitespace. A different scheme or port is a different origin, so https://portal.example.com does not permit http://portal.example.com.

allowedTopOrigins is deliberately separate from the origins under rp. Those say which origin may serve a ceremony; this says which origin may frame one. Reusing the former would silently widen the framing policy of every existing deployment.