Skip to content

RP Fallback

Jump to bottom
Tim Cappalli edited this page Nov 3, 2026 · 3 revisions

Fallback from FIDO's Metadata Service

The FIDO Convenience Metadata Service (C-MDS) is now the authoritative source for credential manager names and icons for passkeys. This community GitHub list is deprecated and will no longer receive updates.

There may be a period of time where entries from this GitHub-based list do not yet appear in C-MDS. Relying parties (RPs) can use the steps below to avoid regressions in their passkey management UI during the transition.

Note

More formal and detailed developer guidance will be available on passkeys.dev by the end of the year.

Recommended lookup order

  1. Check your local copy of FIDO C-MDS. If the AAGUID is present, use friendlyNames for the name (en-US is always present). For the icon, use icon (light mode) and iconDark (dark mode) when present, since they're more specific. Otherwise, fall back to providerLogoLight / providerLogoDark.

    Note: Traditional authenticators, such as security keys, may not have providerLogoLight and providerLogoDark populated, so icon and iconDark are what you'll get for those. Some entries only include icon, so use it for both modes if iconDark is missing. Software credential managers, on the other hand, often only populate the provider logos.

  2. If not found, check your last local copy of the community GitHub list. Use the name, icon_light, and icon_dark values from that entry.

  3. If still not found, show "Other location (name unknown)" with a generic passkey icon.

If an AAGUID appears in both sources, C-MDS takes precedence.

Implementation notes

Keep local copies, don't fetch at request time

  • Download and cache the C-MDS BLOB from c-mds.fidoalliance.org, following the processing rules in the spec.
  • Periodically refresh this metadata as desired, but no more frequently than once every 24 hours.
    • On refresh, pass the serial number (no) of your cached copy, either as a query parameter (GET /?localCopySerial=<no>) or in the If-None-Match header. The server returns 304 Not Modified if no newer BLOB is available. If both are sent, only localCopySerial is used.
    • The server always returns the current serial number in the ETag header.
  • Don't fetch on every page load. The server returns 429 Too Many Requests if you request too often.
  • Take one final snapshot of this GitHub list and store it alongside your C-MDS copy. Don't depend on this repository staying available or unchanged.

Store the AAGUID, resolve at display time

  • Persist the AAGUID with each credential at registration.
  • Look up the name and icon when rendering the UI, rather than saving them with the credential. This way, entries that later move into C-MDS (or get updated names or icons) show up correctly without a data migration.

Handle missing or zeroed AAGUIDs

  • Some authenticators return an all-zeros AAGUID (00000000-0000-0000-0000-000000000000). Skip the lookup and go straight to the generic fallback.
  • Treat a missing AAGUID the same way.

Retire the fallback over time

  • Periodically check how often step 2 is hit. Once your C-MDS copy covers the AAGUIDs your users actually have, you can remove the GitHub list from your lookup path.

Don't use this data for security decisions

  • Names and icons from C-MDS and this list are for display only. For attestation, certification status, or authenticator policy, use the full FIDO Metadata Service (MDS).

Example (pseudocode)

function getPasskeyDisplayInfo(aaguid):
    if aaguid is null or aaguid == "00000000-0000-0000-0000-000000000000":
        return GENERIC
    entry = cmdsCache.get(aaguid)
    if entry:
        return {
            name:      entry.friendlyNames["en-US"],
            iconLight: entry.icon ?? entry.providerLogoLight,
            iconDark:  entry.iconDark ?? entry.icon ?? entry.providerLogoDark
        }
    entry = communityListSnapshot.get(aaguid)
    if entry:
        return {
            name:      entry.name,
            iconLight: entry.icon_light,
            iconDark:  entry.icon_dark
        }
    return GENERIC  # "Other credential manager (name unknown)" + generic icon

Additional considerations

Passkeys can move between credential managers

Users can migrate passkeys from one credential manager to another, for example when switching password managers. The AAGUID recorded at creation identifies the credential manager that created the passkey, which may not be where it's stored today. When this happens, the name and icon shown in your UI won't reflect the passkey's current location.

Plan for a current AAGUID

WebAuthn currently conveys the AAGUID only during registration. In the future, WebAuthn may offer a way to convey the current credential manager's AAGUID during authentication.

RPs may want to consider adding a currentAaguid field to their passkey metadata in the database:

  • Treat the existing AAGUID as the original, captured at creation.
  • Populate currentAaguid once WebAuthn supports conveying it, and use it for display lookups when present.

Stay tuned to passkeys.dev for more guidance on this.

Clone this wiki locally