Passkey Authentication

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:

npx expo install [email protected]

npx expo install [email protected]

npm install [email protected]

  yarn add [email protected]

​

Post-Installation Steps

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

​

For iOS

cd ios && pod install

​

For Expo Projects

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

expo prebuild

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

eas build

​

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
  })
);

​

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.

{
  "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()}
    />
  );
};

​

List and authenticate with passkeys (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.