Native App Readiness#

Passkeys in an Android or iOS app only work when the relying party's domain vouches for the app. The domain does that by serving two files under /.well-known/:

• assetlinks.json for Android
• apple-app-site-association for iOS

When one of them is missing, unreachable or out of date, the app fails with a generic error and nothing says why. The readiness check compares the files an RP has actually deployed with the androidApps and iosApps recorded for it under rp (see Native applications of a relying party) and reports what is wrong.

The check is read-only. It never changes configuration and never changes how a ceremony is decided.

Enabling the check#

nativeReadinessEnabled must be true to run the check at all. nativeReadinessAllowExternalFetch is needed only for checking the files an RP has deployed; leave it false to get the configuration-only report. Both are false by default, so an upgrade changes nothing until an administrator turns them on.

The size, time and cache properties (nativeReadinessMaxResponseBytes, nativeReadinessTimeoutMs, nativeReadinessCacheTtlSeconds) are described in Native app readiness.

Running a check#

POST /jans-fido2/restv1/rp/{rpConfigId}/readiness

POST /fido2/rp/{rpConfigId}/readiness

rpConfigId is the RP id exactly as configured, URL-encoded. The body is empty, or:

{ "recheck": true }

Any other field is ignored. In particular, no URL, host, port or path can be supplied.

Result#

{
  "enabled": true,
  "externalFetch": true,
  "platforms": {
    "android": [
      { "check": "reachability.status", "status": "pass", "reason": "HTTP 200" },
      { "check": "content.android.fingerprint", "status": "fail",
        "reason": "fingerprint AB:CD:... for package com.example.app not listed" }
    ],
    "ios": [
      { "check": "content.ios.app", "status": "pass", "reason": "app T9A667JL6T.com.example.app listed in webcredentials.apps" },
      { "check": "content.ios.cdn", "status": "warn", "reason": "iOS reads this file through app-site-association.cdn-apple.com, which caches aggressively; a correct file may not take effect immediately" }
    ]
  },
  "checkedAt": "2026-10-21T09:30:00Z",
  "fromCache": false,
  "nextRecheckAllowedAt": "2026-10-21T09:31:00Z"
}

Each check has a status and a short reason:

The reason names only configured values (a package name, a fingerprint, TeamID.BundleID), HTTP status codes and counts. The result never contains the content of a fetched file, a redirect target, a resolved address or a parser error message.

A platform with no configured apps is not fetched. Its list holds one pass saying so.

Checks#

Reachability#

Run once per file, for every platform that has apps configured.

Content#

Run only when the file answered HTTP 200 and was not cut off at the size limit.

content.drift and content.ios.cdn are advice, not verdicts, and never fail a check on their own.

When nothing is fetched, the check reports config.android and config.ios instead (a pass when apps are configured, a warn when none are), fetch.skipped when external fetching is off, and config.rp-id as a fail when the configured RP ID is not a public host name that can be checked.

Apple CDN caching#

iOS does not read apple-app-site-association from your server when the app is installed. It reads a copy held by Apple's CDN, app-site-association.cdn-apple.com, which caches aggressively. The check cannot see that copy and does not contact the CDN, so a correct file can still take a while to take effect after you deploy it. This is why content.ios.cdn is always a warn.

CMS-signed apple-app-site-association#

An apple-app-site-association file can be served CMS-signed, which is not JSON. The check reads the file as JSON only, so a signed file is reported as content.parse fail and its contents are not checked. This is a limitation of the check, not necessarily a fault of the file: if you serve a signed file, treat that fail as expected and verify the file another way.

What the server will and will not contact#

Fetching is the risky part of this feature, so it is deliberately narrow:

• Only the configured RP ID is contacted. The caller selects a configured entry; it cannot supply a host, URL, port or path. An id that is not configured gets 404 and no outbound request.
• The RP ID must be a public host name. An IP address, localhost, a name with a port and similar values are refused before any lookup.
• HTTPS on port 443 only, at the two fixed paths /.well-known/assetlinks.json and /.well-known/apple-app-site-association.
• Redirects are never followed. A 3xx answer is reported and nothing more.
• Blocked address ranges. After the name is resolved, the connection is made only to an address the server has checked. Loopback, private, link-local (which includes the 169.254.169.254 cloud metadata address), unique-local IPv6, carrier-grade NAT, multicast, documentation, benchmarking, unspecified and reserved ranges are refused, and so are IPv6 forms that wrap one of those IPv4 addresses.
• Bounded. The response size is capped at 256 KiB and the HTTP fetch at 10 seconds, whatever the properties say. The name lookup happens before that deadline starts and is bounded only by the server's DNS resolver, so a slow lookup can make a whole check take longer.
• Nothing sent. No cookies, credentials, proxy or server tokens. Only Accept and User-Agent are set.

Caching and rate limits#

A result is kept in memory, per server node, for nativeReadinessCacheTtlSeconds and never for less than 60 seconds. A request served from the cache has "fromCache": true and makes no outbound request.

The cache is keyed by the RP id only, so changing an RP's androidApps or iosApps does not invalidate it. After changing them, send {"recheck": true} to see a result for the new configuration.

Sending {"recheck": true} (the "Recheck now" action) skips the cache, but not the rate limits. The limits are per server node, so in a cluster the installation-wide ceiling is the number of nodes times these values:

A request that would exceed one of them gets 429 with a Retry-After header and causes no fetch. nextRecheckAllowedAt in the result says when the same relying party can be fetched again.

Audit#

Each executed check writes one line to the FIDO2 server log, starting with native-readiness-audit:

requestedBy is informational. The FIDO2 server does not authenticate callers, so a request that reaches it directly can set any value.