Passkey Mobile Integration Guide

This document provides step-by-step instructions for integrating passkey registration and authentication in your native mobile app using IDaaS.

Association Files

Passkeys require association files to establish trust between your app and the domain. These files are essential for verifying the authenticity of the passkeys and ensuring secure communication between the app and your domain.

Association files must be hosted on your domain to enable passkey functionality. They are used to verify the association between your app and the domain, allowing users to register and authenticate using passkeys seamlessly.

Association files are typically located at the following paths:

• For Android: https://yourdomain.com/.well-known/assetlinks.json
• For iOS: https://yourdomain.com/.well-known/apple-app-site-association

For native mobile applications, proper relying party configuration requires additional setup to establish trust between your app and your domain:

Android Configuration

Source: https://developer.android.com/identity/sign-in/credential-manager

1. Create and host assetlinks.json

Create an assetlinks.json file and host it at https://yourdomain.com/.well-known/assetlinks.json:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls", "delegate_permission/common.get_login_creds"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourcompany.yourapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

Key Fields:

• package_name: Your Android app's package identifier
• sha256_cert_fingerprints: SHA256 fingerprint of your app's signing certificate

2. Obtain Certificate Fingerprint

keytool -list -v -keystore your-release-key.keystore -alias your-key-alias

3. App Manifest Configuration

Add intent filters to your Android manifest:

<activity android:name=".MainActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https"
              android:host="yourdomain.com" />
    </intent-filter>
</activity>

iOS Configuration

Source: https://developer.apple.com/documentation/authenticationservices/connecting-to-a-service-with-passkeys

1. Create and host apple-app-site-association

Create an apple-app-site-association file and host it at https://yourdomain.com/.well-known/apple-app-site-association:

{
  "webcredentials": {
    "apps": ["TEAMID.com.yourcompany.yourapp"]
  }
}

Key Fields:

• TEAMID: Your Apple Developer Team ID
• com.yourcompany.yourapp: Your iOS app's bundle identifier
• webcredentials: Essential for passkey functionality

For more information - https://developer.apple.com/documentation/xcode/supporting-associated-domains

2. App Configuration

Add associated domains to your iOS app entitlements:

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:yourdomain.com</string>
    <string>webcredentials:yourdomain.com</string>
</array>

Prerequisites

• IDaaS Account: Ensure you have an IDaaS account with access to the Administration API
• Native App: Your mobile app must be registered in IDaaS with the correct package name/bundle identifier (see instructions below)
• Web Domain: Your web domain must be configured to host the association files
• SSL Certificate: Ensure your domain has a valid SSL certificate to serve the association files over HTTPS

1. Create Administration API Application

1. Log in to your IDaaS account
2. Navigate to Applications and create a new Administration API application
3. Provide the required details:
   • Application name
   • Description
   • Required permissions for FIDO token management
4. Save the application ID and shared secret for your backend integration

2. Configure Relying Party Settings

1. Navigate to the Passkey/FIDO2 settings page of your IDaaS account

2. Enable the Enable Passkey/FIDO2 Allowlist option and click the Add button

3. Enter the Relying Party ID (RP ID) of your domain name (e.g., yourdomain.com)

4. Click the Sync with Association Files button to automatically fetch the origin settings from your hosted association files

   info

   If you have not hosted the association files yet, you can manually enter your origin settings.

5. Click OK to close the dialog then click Save to apply the changes.

3. Create Authentication API Application

1. Navigate to Applications and create a new Authentication API application
2. Provide the required details:
   • Application name
   • Description
3. Save the application ID for your frontend integration

4. Configure Resource Rules

1. Navigate to the Resource Rules page
2. Create a new resource rule for your Authentication API application
3. Select Passkey/FIDO2 as one of the authentication methods
4. Ensure Passkey is enabled in the Login Flow settings

Integration Steps

Backend Setup

See the Getting Started page for help with initializing the IDaaS SDK in your backend application.

Your backend will handle communication with the IDaaS APIs, while your frontend manages the WebAuthn native mobile WebAuthn API interactions.

Communication between your mobile app and your backend application is out of scope for this document. The typical flow involves the mobile app making API calls to your backend, which in turn interacts with IDaaS for passkey registration and authentication.

Passkey Registration

1. Start Passkey Registration

Initiate the passkey registration process by creating a FIDO token for the user. This involves generating a challenge and providing the necessary authenticator settings.

GET /api/web/v1/fidotokens/challenge/:id

Send the registration parameters to your mobile app.

tip

If you don't have the UUID of the user you want to register a passkey for, you can get it by fetching the user details via the POST /api/web/v3/users/userid API.

When your mobile app receives the challenge, pass the parameters into the mobile WebAuthn API and it should prompt the user to register their passkey. The user will interact with the device's biometric or security features to complete the registration.

important

The timeout parameter, specified in seconds, must be converted to milliseconds to comply with WebAuthn specifications for passkey registration on mobile devices.

• Sample code for Android - https://developer.android.com/identity/sign-in/credential-manager#registration-flows
• Sample code for iOS - https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service

2. Complete Passkey Registration

After the user successfully registers their passkey, your mobile app will receive an attestation response. This response contains the attestation object and client data JSON, which must be sent to your backend server to complete the registration process with IDaaS.

POST /api/web/v1/fidotokens/complete/:id

warning

The request body includes a 'name' parameter representing the passkey name, which must be unique for each passkey associated with the user.

Once registered successfully, the user can view the Passkey/FIDO2 credential listed as one of the authenticators in their profile.

Passkey Authentication

1. Start Passkey Authentication

To authenticate users with passkeys, your mobile app must initiate the authentication flow by sending a request to your backend server which will request an authentication challenge from IDaaS.

POST /api/web/v2/authentication/users/authenticate/PASSKEY

Request Body:

{
  "applicationId": "Authentication API application ID",
  "userId": "Optional. User ID of the authenticating user",
  "origin": "The Relying Party ID of the registered passkey"
}

Your backend should then return the challenge to your mobile app and into the mobile WebAuthn API. The user will interact with the device's biometric or security features to complete the authentication.

The userId is optional. If not provided, the user will be prompted to select their passkey from a list of available passkeys on the device. If provided, the user will be authenticated using the specified passkey.

Note that the challenge request API will return a token that must be used in the subsequent authentication completion request.

2. Complete Passkey Authentication Response

After the user successfully authenticates, your mobile app will receive an assertion response. This response contains the authenticator data, client data JSON, credential ID, and signature, which must be sent to your backend server to complete the authentication process with IDaaS.

POST /api/web/v1/authentication/users/authenticate/PASSKEY/complete

Make sure you include the Authorization header with the token received from the challenge request.

---

Error Handling

Error Code	Description	Resolution	HTTP Status
max_fido_tokens	Maximum FIDO tokens reached	Check the number of passkeys for the user	400
fido_register_no_challenge	No challenge found on server for registration	Retry registration process	400
fido_token_invalid_name	Invalid passkey token name	Ensure passkey name is in correct format and within length limits	400
fido_token_invalid_name_html	Invalid passkey token name (contains HTML)	Remove HTML content from passkey name	400
fido_token_duplicate_name	Duplicate passkey name	Provide a unique passkey name	400
fido_invalid_registration_response	Invalid registration data	Verify the registration input data	400
fido_none_active	No passkey token registered/active	User must have an active passkey before initiating authentication	403
fido_no_challenge	No challenge found for passkey authentication	Initiate authentication with challenge first	400
fido_invalid_authentication_response	No fidoResponse parameter found in the request	Ensure fidoResponse parameter is not null	400
fido_rpid_not_allowed	RPID in the request is not allowed	RPID should match the one the passkey is associated with	401