Passkey Support

​

Overview

To enable passkey functionality in your web application, you need to properly configure well-known files for both iOS and Android platforms. These files establish the association between your website and your mobile applications, allowing for seamless passkey operations. This guide walks you through the setup process for both platforms.

​

Hosting Requirements

• The files must be publicly accessible at: https://[your-domain]/.well-known/apple-app-site-association and https://[your-domain]/.well-known/assetlinks.json
• HTTPS is mandatory
• The file must be served with the application/json content type
• No redirects are allowed

​

1. iOS Configuration

​

1.1 Setting up apple-app-site-association

The apple-app-site-association (AASA) file is required to establish a secure connection between your website and iOS application for passkey support.

1. Create a file named apple-app-site-association (without any file extension)
2. Place it in the .well-known directory at your domain root
3. Serve it with the application/json content type

Here’s the required structure for the AASA file:

{
    "webcredentials": {
        "apps": [
            "TEAM_ID.BUNDLE_ID"
        ]
    }
}

Replace the following values:

• TEAM_ID: Your Apple Developer Team ID (found in the Apple Developer Portal)
• BUNDLE_ID: Your iOS application’s bundle identifier

Example:

{
    "webcredentials": {
        "apps": [
            "A1B2C3D4E5.com.example.myapp"
        ]
    }
}

​

1.2 Configuring Associated Domains Entitlement

Before your iOS app can use webcredentials, you need to configure the Associated Domains entitlement. This entitlement establishes a secure connection between your website and iOS app. Here’s how to set it up:

​

Using Xcode

1. Open your Xcode project
2. Select your target in the project navigator
3. Click on the “Signing & Capabilities” tab
4. Click the ”+” button in the top-left corner of the capabilities editor
5. Search for and select “Associated Domains”

Once added, you’ll see a section where you can specify your domains. For webcredentials support:

1. Click the ”+” button under “Domains”
2. Add an entry in the following format:

   webcredentials:your-domain.com
   

For example, if your website is https://example.com, you would add:

webcredentials:example.com

You can add multiple domains if needed, each on a new line.

​

Using Entitlements File

If you prefer to configure entitlements manually:

1. Create or open your .entitlements file
2. Add the following configuration:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <key>com.apple.developer.associated-domains</key>
       <array>
           <string>webcredentials:example.com</string>
       </array>
   </dict>
   </plist>
   

Important Considerations

1. The domain must exactly match the domain where your apple-app-site-association file is hosted
2. Don’t include the protocol (http:// or https://) in the domain specification
3. For development and testing:
   • Enable the “Associated Domains Development” option in Xcode’s signing capabilities
   • Use your development team’s provisioning profile
   • Make sure your Apple Developer account has Associated Domains enabled

Verifying the Configuration

To verify your entitlements are correctly configured:

1. Open your app’s .entitlements file
2. Ensure the com.apple.developer.associated-domains entry exists with your domain
3. Build your app and check the generated embedded.mobileprovision file contains the entitlement
4. You can examine the provisioning profile using:

   security cms -D -i /path/to/embedded.mobileprovision
   

​

2. Android Configuration

​

2.1 Setting up assetlinks.json

For Android, you need to create an assetlinks.json file to establish the digital asset links between your website and Android application.

1. Create a file named assetlinks.json
2. Place it in the .well-known directory at your domain root
3. Serve it with the application/json content type

Here’s the required structure:

[{
    "relation": ["delegate_permission/common.get_login_creds"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example.myapp",
        "sha256_cert_fingerprints": [
            "SHA256_FINGERPRINT"
        ]
    }
}]

Replace the following values:

• package_name: Your Android application’s package name
• SHA256_FINGERPRINT: Your app’s SHA256 fingerprint

To obtain your SHA256 fingerprint, use the following command with your keystore:

keytool -list -v -keystore path/to/your/keystore.jks

Example:

[{
    "relation": ["delegate_permission/common.get_login_creds"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example.myapp",
        "sha256_cert_fingerprints": [
            "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
        ]
    }
}]

​

3. OwnID Console Configuration

1. Log in to your OwnID Console
2. Navigate to your Application
3. Select “Integration” > “Native Apps” from the menu

Android Configuration

In the Android section of the Mobile Apps configuration:

1. Enter your Android Package Name (e.g., com.company.appname)
2. Provide the SHA-256 certificate fingerprint from your app’s signing certificate
   • This should match the fingerprint you’ll use in your assetlinks.json file

iOS Configuration

In the iOS section of the Mobile Apps configuration:

1. Enter your iOS Bundle ID (e.g., com.company.appname)
   • This should match the bundle identifier in your Xcode project
   • Make sure it’s the same identifier you’ll use in your apple-app-site-association file

Save your changes.

​

Verification

1. Use Apple’s verification tool at https://app-site-association.cdn-apple.com/a/v1/[your-domain]
2. Use Google’s Asset Links Tool: https://developers.google.com/digital-asset-links/tools/generator
   • In Relation Type choose “Credential Sharing”

​

Common Issues and Troubleshooting

iOS

• Ensure your AASA file is served without any file extension
• Verify the content-type header is correctly set to application/json
• Check that your Team ID and Bundle ID exactly match your iOS app configuration
• Make sure HTTPS is properly configured with a valid SSL certificate

Android

• Verify the SHA256 fingerprint matches your app signing certificate
• Ensure the package name exactly matches your Android app’s package name
• Check that the assetlinks.json file is accessible without any redirects
• Confirm HTTPS is properly configured with a valid SSL certificate

​

Additional Resources

• Apple’s Associated Domains Documentation
• Android’s Digital Asset Links Documentation