Skip to main content

Native app association for passkeys

When a native mobile app and a web application share the same relying party, the operating system needs to verify that the app is authorized to work with credentials from that domain. Without this verification, the platform rejects passkey creation and assertion requests from the native app.

Both Android and iOS use a file hosted at the /.well-known/ path of your relying party domain to establish this trust. If you use the default Authentication Cloud domain as your relying party ID, Authentication Cloud can serve both files automatically. If you use your own domain as the relying party ID, host both files yourself.

note

The files described on this page are required only when a native mobile app registers and asserts passkeys against the same relying party as a web application. Browser-only deployments do not require this configuration.

Android uses the Digital Asset Links protocol to verify the relationship between a website and a native app. The file must be served at:

https://<your-relying-party-domain>/.well-known/assetlinks.json

For passkey support, the file must include both a web entry declaring the site and an android_app entry declaring the native app:

[
  {
    "relation": ["delegate_permission/common.get_login_creds"],
    "target": {
      "namespace": "web",
      "site": "https://<your-relying-party-domain>"
    }
  },
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "<your.app.package.name>",
      "sha256_cert_fingerprints": [
        "<YOUR:SHA256:CERTIFICATE:FINGERPRINT>"
      ]
    }
  }
]

The web entry declares that the domain participates in credential sharing and is part of the same trusted asset group as the native app. The android_app entry authorizes the specific app to assert passkeys for that domain. The package_name and sha256_cert_fingerprints values must match the app that performs passkey operations. The certificate fingerprint differs between debug and release builds.

Verify your configuration

Use the Digital Asset Links generator to verify that your assetlinks.json file is correctly configured and publicly accessible before testing on a device.

iOS: Associated Domains​

iOS uses the Associated Domains mechanism. The file must be served at:

https://<your-relying-party-domain>/.well-known/apple-app-site-association

For passkey support, the file must include a top-level webcredentials key listing the app in <TeamID>.<BundleID> format:

{
  "webcredentials": {
    "apps": [
      "<TeamID>.<BundleID>"
    ]
  }
}

The webcredentials entitlement must also be declared in the Xcode project for the app to accept credentials from the associated domain.

Configuration​

Which approach applies depends on the relying party ID you have configured for your Authentication Cloud instance. For information on setting your relying party ID, see FIDO2 integration prerequisites.

Using the default Authentication Cloud domain​

If your relying party ID is your Authentication Cloud instance domain (for example, <your-instance>.mauth.nevis.cloud), Authentication Cloud serves both association files automatically at https://<your-instance>.mauth.nevis.cloud/.well-known/ once the native app association feature is enabled for your instance.

To add your app to the association files, provide Nevis support with the following:

  • Android: the app package name and the SHA-256 certificate fingerprint of the signing key.
  • iOS: the Apple Team ID and the app bundle identifier.

Contact Nevis support to request configuration or to update existing values.

FIDO2 example apps

The Nevis FIDO2 mobile example apps ship with pre-configured association values for the Nevis-signed builds. To run the example apps against your own Authentication Cloud instance, Nevis support can add the required entries to your instance. If you compile the apps with a different signing key, you need to provide the corresponding certificate fingerprint. See FIDO2 Mobile Example Apps for details.

Using your own domain as the relying party ID​

If you have configured your own domain as the relying party ID, host both well-known files on that domain. Nevis does not serve these files for domains outside the Authentication Cloud instance.

The files must be hosted at the root of the exact domain used as the relying party ID. For example, if the relying party ID is auth.your-company.net, the files must be served at https://auth.your-company.net/.well-known/ — not on a www subdomain or any other subdomain. A mismatch between the relying party ID and the domain serving the file causes verification to fail.

Both files must meet the following requirements:

  • Served over HTTPS with a valid SSL certificate.
  • Returned with HTTP status 200. HTTP redirects (301, 302) cause verification to fail on both Android and iOS.
  • Publicly accessible without authentication. On Android, Google Play Services retrieves assetlinks.json during app installation and verification. On iOS, Apple's CDN retrieves apple-app-site-association within 24 hours of app installation; devices then re-check approximately once per week.
iOS developer bypass

When your server is not publicly reachable during local development, you can configure the Associated Domains entitlement in your Xcode project to bypass Apple's CDN and connect directly to your server. Add ?mode=developer to the webcredentials domain entry in the entitlement:

webcredentials:<your-domain>?mode=developer

This is an app-side Xcode setting, not a backend change. Remove it before distributing the app. For details, see Supporting associated domains.

Cross-origin support​

The association files described on this page bind a single app to a single relying party domain. If your deployment spans multiple domains or brands, Authentication Cloud also supports Related Origin Requests, which allow passkeys registered on one domain to be reused on related domains. For more information, see the passkeys.dev documentation on Related Origins.