feat(jans-fido2): honour forwarded end-user IP and user agent in passkey metrics

[imran-ishaq]

Prepare

• Read PR guidelines
• Read license information

---

Description

Target issue

Server half only. Populating the headers at the call sites — the person-authentication script, Casa
and passkeys.xhtml — is #14803, and cannot be in this PR: those modules build against the
published jans-fido2-client artifact, so they cannot compile against the new overloads until this
merges and republishes.
closes #14801

Implementation Details

The FIDO2 endpoints are never called by the browser. The Authorization Server, Casa and the
person-authentication script relay to them over Fido2ClientFactory, which propagates no headers, so
the only client the server can observe is the calling service. That is why ipAddress is the VM's
own address and userAgent is Apache-HttpClient/4.5.14 (Java/17.0.20) on every row.

Carrying the end user's details across the hop. ClientContextHeaders (new, in model so client
and server share one definition) names X-Jans-Client-IP and X-Jans-Client-User-Agent.
AssertionService and AttestationService gain overloads taking them as @HeaderParam. The
existing signatures are untouched deliberately: changing them would force Casa, the person
authentication script and the jans-chip demo to move in lockstep with this merge, whereas overloads
let each migrate on its own schedule. Passing null omits the header.

Deciding whether to believe them. A header is a claim, so MetricService honours these only from
a caller listed in the new fido2TrustedClientContextSources, which is empty by default — the
headers are ignored until an operator names a caller. A forwarded address is still run through
isValidIpAddress before use, and a malformed one falls back to the request's own address rather
than being stored. "*" trusts any caller, for deployments where callers have no stable address.

Stopping the device breakdown being fabricated. DeviceInfoExtractor.determineDeviceType
previously matched mobile and tablet markers and let everything else fall through to DESKTOP,
with no unknown branch — so every service-to-service call was recorded as a desktop and the chart
looked plausible rather than empty. It now tests for desktop markers explicitly and reports UNKNOWN
otherwise. The mobile test still runs first, so Android's shared Linux marker does not reclassify
phones as desktops. This is independent of the trust question above and worth having regardless.

There is also a new extractDeviceInfo(String) overload, since the user agent to parse is now often
not the one on the request.

---

Test and Document the changes

• Static code analysis has been run locally and issues have been fixed
• Relevant unit and integration tests have been added/updated
• Relevant documentation has been updated if any (i.e. user guides, installation and configuration guides, technical design docs etc)

Tests — full jans-fido2 suite green, 411 tests, 14 of them new:

• DeviceInfoExtractorTest (new, 9 tests) — the service-to-service user agent now reporting
  UNKNOWN instead of DESKTOP, real desktop user agents still DESKTOP, Android not
  reclassified, null user agent leaving fields unset.
• MetricServiceTest (5 added) — forwarded headers honoured from a trusted caller, ignored when
  unconfigured, ignored from an untrusted caller, wildcard trust, and a malformed forwarded address
  falling back to the request's own.

Static analysis — SpotBugs run locally on model, client and server. This change adds two
findings, EI_EXPOSE_REP / EI_EXPOSE_REP2 on the new List getter and setter, which is the same
finding every other collection property in AppConfiguration already carries; left consistent with
the surrounding bean rather than making one property defensively copy. The module has 121
pre-existing findings of that class and the plugin is declared only in pluginManagement, so it does
not gate the build.

Docs — updated in a separate docs: commit: passkey-telemetry.md (a "Whose device is recorded"
section explaining the relay, the new property and the UNKNOWN device type),
fido2-server-properties-config.md and the generated fido2-properties.md.

Please check the below before submitting your PR. The PR will not be merged if there are no commits that start with docs: to indicate documentation changes or if the below checklist is not selected.

• I confirm that there is no impact on the docs due to the code changes in this PR.

[mo-auto]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0d99e560-52fa-4b0b-8f06-f9ecec4ee2d7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed for 'Fido2 API'

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud