​
Prerequisites

The foundation for implementing passkeys in native apps involves setting up a cloud account that will manage these keys: Users must have an active cloud account, such as an enabled iCloud Keychain on Apple devices or a Google account with Google Password Manager for Android devices. This is essential for storing and managing passkeys.

​
Associating a native app with a relying party ID

The core of passkey implementation in native apps lies in establishing trust between the native device and the relying party server:
  1. Trust establishment: Before a passkey can be created, the native device (like an Android or iOS device) must verify if the relying party server trusts the app.
  2. Hosting essential files: Your relying party server needs to host the following critical files for native apps:
    • iOS: .well-known/apple-app-site-association
    • Android: .well-known/assetlinks.json
    Corbado manages both files if you use our relying party server. Your task is to configure your native devices accordingly.

​
Development considerations

Developers need to be mindful of several factors that can impact the implementation process:
  • Cached files: Particularly on iOS devices, the Apple system downloads the association file once every 24 hours and caches it. This means that frequent updates to the apple-app-site-association file may not be immediately available for your app. During development, you can bypass this by adding ?mode=development to the file request. This means you need to change the following two things (note that this feature is exclusive to Apple devices; Android does not support local server development):
    • Update your relying party ID by appending ?mode=development (e.g. acme.com?mode=development). If you use Corbado’s relying party server, you do not need to change the relying party ID in Corbado’s developer panel, as we handle this for you dynamically during the file request. If you use your own relying party server, you need to change that though.
    • Update your webcredentials in Xcode by appending ?mode=development to the associated domains (e.g. webcredentials:acme.com?mode=development)
  • Content Delivery Networks (CDNs): Be aware of how CDNs might affect the availability and updating of the necessary association files.
  • Localhost testing: Testing on localhost presents additional challenges. Even locally, the association files must be accessible to Google. Utilize this test tool to verify if the association file is correctly set up and reachable.

​
Troubleshooting common errors

When implementing passkeys in native apps, developers might encounter various issues:
  • Relying party ID mismatches: This is a common problem when switching environments (e.g. from DEV to PROD) or modifying configuration settings.
  • Device compatibility and settings: Ensure that the devices are properly configured to work with passkeys.
  • Server configuration errors: Mistakes in the server setup can lead to authentication failures.
For a detailed guide on troubleshooting these and other issues, please refer to our Flutter troubleshooting guide.