Passkey Authentication

Recommended: JavaScript SDK for React Native

While this SDK is still supported, we recommend using newer JavaScript SDK, which is optimized for React Native, but also comes with a host of other benefits.

Passkeys in React Native provide secure authentication for both primary authentication (1FA) and multi-factor authentication (2FA), allowing users to use passkeys as their primary login method or as a second factor to enhance account security.

To use passkeys in your React Native app, your website domain must grant credential access to the mobile app so passkeys can be created associated with the website domain. This allows users to seamlessly use the same passkeys across both your app and website.

Prerequisites

Before setting up passkeys, ensure you have:

• A React Native project with Dynamic SDK already integrated
• A domain/website that you control (for hosting the required .well-known endpoints)
• Access to your app’s bundle identifier and signing certificates
• For iOS: Apple Developer account and Xcode
• For Android: Android Studio and signing key information

Installation

Install the required package using your preferred package manager:

expo

Shell

npx expo install react-native-passkey@3.1.0

npm

Shell

npm install react-native-passkey@3.1.0

yarn

Shell

  yarn add react-native-passkey@3.1.0

Post-Installation Steps

After installing the react-native-passkey package, you need to link the native packages to your project:

For iOS

Shell

cd ios && pod install

For Expo Projects

If you are using Expo, you may need to run a prebuild or create a new build:

Shell

expo prebuild

Or use the EAS service to create a new build for your app:

Shell

eas build

After running expo prebuild, you’ll need to rebuild your app for the native modules to be properly linked.

Configuration

Dynamic SDK Configuration

To create passkeys associated with the correct website, you must configure the appOrigin in the ReactNativeExtension:

const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
}).extend(
  ReactNativeExtension({
    appOrigin: 'https://yourdomain.com' // Replace with your actual domain
  })
);

The appOrigin must match your website domain exactly (e.g., https://example.com). This domain will be used to create and associate passkeys, so ensure it’s the same domain where you’ll host the required .well-known endpoints.

OS Configuration

iOS

There are iOS-specific steps to configure Passkey support. If you have already set up an associated domain for your application, you can skip this step.

Set Up an Associated Domain for Your Application

Follow the Apple documentation to associate a domain with your application. On your webserver, set up this route:

GET https://\{\{yourdomain\}\}/.well-known/apple-app-site-association

This route should serve a static JSON object containing your team ID and bundle identifier. Example (replace XXXXXXXXXX with your team identifier and “YYY.YYYYY.YYYYYYYYYYYYYY” with your bundle ID, e.g., H123456789.com.example.mobileApp):

{
  "applinks": {
    "details": []
  },
  "webcredentials": {
    "apps": ["XXXXXXXXXX.YYY.YYYYY.YYYYYYYYYYYYYY"]
  }
}

In Xcode, under Signing & Capabilities, add a new Capability of type Associated Domains. Now add this and replace XXXXXX with your domain (e.g., apple.com):

webcredentials:XXXXXX

If you are using Expo, add the webcredentials:{{yourdomain}} to your app.json file. See the Expo documentation for more details.

You can validate your Apple App Site Association (AASA) configuration using the Branch AASA Validator. This tool tests your domain against Apple’s requirements and helps ensure your Universal Links and passkey setup is properly configured.

{
  "expo": {
    "ios": {
      "associatedDomains": ["webcredentials:\{\{yourdomain\}\}"]
    }
  }
}

Android

The Android-specific configuration is similar to iOS. If you have already set up Digital Asset Links for your application, you can skip this step.

Associate Your App with a Domain

Follow the Android documentation to associate a domain with your application. On your webserver, set up this route:

GET https://\{\{yourdomain\}\}/.well-known/assetlinks.json

This route should serve a static JSON object containing the following information (replace with your data, and replace SHA_HEX_VALUE with the SHA256 fingerprints of your Android signing certificate):

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

Managing passkeys

Now that your application has correctly associated your domain with your application, you can register and authenticate using passkeys for both primary authentication (1FA) and multi-factor authentication (2FA).

Register a passkey

The passkey module provides a method to trigger passkey registration. Here’s an example:

import { dynamicClient } from '<path to the dynamic client>';

const App = () => {
  const handleRegisterPasskey = async () => {
    try {
      await dynamicClient.passkeys.register();
      console.log('Passkey registered successfully');
    } catch (error) {
      console.error('Failed to register passkey:', error);
    }
  };

  return (
    <Button
      title="Register passkey"
      onPress={handleRegisterPasskey}
    />
  );
};

When the user taps the button, the passkey registration flow will be triggered and the OS will prompt the user to register a passkey.

Authenticate with passkeys (1FA)

You can use passkeys as the primary authentication method. Here’s how to implement passkey-based sign-in:

import { dynamicClient } from '<path to the dynamic client>';

const App = () => {
  return (
    <Button
      title="Login with Passkey"
      onPress={() => dynamicClient.auth.passkey.signIn()}
    />
  );
};

Use passkeys for MFA (2FA)

For multi-factor authentication, you can use the following methods to list and authenticate with passkeys:

• dynamicClient.passkeys.get() - Retrieves all registered passkeys for the user
• dynamicClient.passkeys.authenticateMFA() - Uses a registered passkey for multi-factor authentication

Here’s a complete example for 2FA:

import { dynamicClient } from '<path to the dynamic client>';
import { useState, useEffect } from 'react';

const App = () => {
  const [passkeys, setPasskeys] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const loadPasskeys = async () => {
      try {
        setLoading(true);
        const userPasskeys = await dynamicClient.passkeys.get();
        setPasskeys(userPasskeys);
      } catch (error) {
        console.error('Failed to load passkeys:', error);
      } finally {
        setLoading(false);
      }
    };

    loadPasskeys();
  }, []);


  const handleAuthenticate = async () => {
    try {
      const verifyResponse = await dynamicClient.passkeys.authenticateMFA();
      console.log('Authentication successful:', verifyResponse);
    } catch (error) {
      console.error('Authentication failed:', error);
    }
  };

  if (loading) {
    return <Text>Loading passkeys...</Text>;
  }

  return (
    <View>
      <Text>Registered Passkeys: {passkeys.length}</Text>
      {passkeys.length > 0 ? (
        <Button
          title="Authenticate with passkey"
          onPress={handleAuthenticate}
        />
      ) : (
        <Text>No passkeys registered. Register a passkey first.</Text>
      )}
    </View>
  );
};

Conclusion

By following these steps, you can successfully integrate passkey functionality with the Dynamic SDK into your React Native app. This enables secure authentication for both primary login (1FA) and multi-factor authentication (2FA), providing users with a seamless and secure authentication experience across your mobile app.