Skip to main content

React Native

The Authsignal React Native SDK can be used to:

  • Sign up and sign in users using passkeys
  • Enroll devices for push auth and allow users to approve or reject push auth challenges

Prerequisites​

Passkeys​

iOS

On iOS, passkeys are supported only on iOS 15 and above and synced via iCloud Keychain. Autofill requires iOS 16 and above.

To use passkeys you must first setup an associated domain with the webcredentials service type.

  1. Host an apple-app-site-association file on the domain that matches your relying party:

    GET https://<yourrelyingparty>/.well-known/apple-app-site-association

  2. The response JSON should look something like this:

    {
     "applinks": {},
     "webcredentials": {
         "apps": ["ABCDE12345.com.example.app"]
     },
     "appclips": {}
    }

    where ABCDE12345 is your team id and com.example.app is your bundle identifier.

  3. In XCode under "Signing & Capabilities" add a webcredentials entry for your domain / relying party e.g. example.com:

Android

On Android, passkeys are implemented using the Credential Manager API and synced via Google Password Manager. Passkeys are supported only on devices running Android 9 (API 28) or higher.

To use passkeys on Android you must setup a Digital Asset Links JSON file on your web domain.

  1. Host an assetlinks.json file on the domain that matches your relying party:

    GET https://<yourrelyingparty>/.well-known/assetlinks.json

  2. The response JSON should look something like this:

    [{
     "relation": ["delegate_permission/common.get_login_creds"],
     "target": {
       "namespace": "android_app",
       "package_name": "com.example",
       "sha256_cert_fingerprints": [
         "FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C"
       ]
     }
    }]

    but with the package name and SHA256 fingerprint updated to match your own app.

Installation​

Install the Authsignal React Native SDK using npm or yarn:

npm install react-native-authsignal

Then link the native iOS dependencies:

npx pod-install ios

Initialization​

Initialize the Authsignal client in your code:

import { Authsignal } from "react-native-authsignal";

const authsignal = new Authsignal({ tenantID: "YOUR_TENANT_ID", baseURL: "YOUR_REGION_BASE_URL" });

You can find your tenantId in the Authsignal Portal.

You must specify the correct baseUrl for your tenant's region.

RegionBase URL
US (Oregon)https://api.authsignal.com/v1
AU (Sydney)https://au.api.authsignal.com/v1
EU (Dublin)https://eu.api.authsignal.com/v1

Passkeys​

Registering a new passkey​

To register a new passkey, you first need to request a token via track. If the user is new, create a record for them in your own DB and pass their ID to Authsignal server-side to get a token, which can then be passed to the React Native SDK along with their username.

const { data: resultToken, error } = await authsignal.passkey.signUp({ token, userName });

if (error) {
  console.log(error);
} else if (resultToken) {
  // Pass this short-lived result token to your backend to validate that passkey registration succeeded
}

Authenticating with an existing passkey​

To handle re-authenticating when the username is captured, lookup the user by their username in your backend and then pass their ID to track to get a token, which can then be passed to the React Native SDK.

const { data: resultToken, error } = await authsignal.passkey.signIn({ token });

if (error) {
  console.log(error);
} else if (resultToken) {
  // Pass this short-lived result token to your backend to validate that passkey authentication succeeded
}

After the user authenticates with their passkey, the SDK will return a short-lived token which should be passed to your backend to validate the result of the challenge server-side.

Using passkey autofill​

You can also initiate a passkey challenge in cases where the username isn't known yet - for example when using passkey autofill. This is currently only supported on iOS.

This feature requires a text input whose textContentType attribute is set to username:

<TextInput onChangeText={setUsername} value={username} textContentType={"username"} />

You can then init passkey autofill in a useEffect hook within your component:

useEffect(() => {
  authsignal.passkey.signIn({ autofill: true }).then(({ error, data: resultToken }) => {
    if (resultToken) {
      // The user has focused your text input and authenticated with an existing passkey
      // Send the token to your server to validate the result of the challenge
    }
  });
});

For more detail on passkey autofill on iOS see Apple's documentation.

Cancelling a passkey challenge​

If a passkey challenge has been initiated and is in a pending state, for example to support autofill, it can be cancelled at any time.

authsignal.passkey.cancel();

Push​

Adding a device credential​

Adding a new credential must be authorized with a short-lived token. You can obtain this by calling the track endpoint on the Server API which will return a token in the response. This should be done at a point in your application when the user is strongly authenticated.

await authsignal.push.addCredential(token);

Removing a device credential​

await authsignal.push.removeCredential();

Getting a challenge​

const challengeId = await authsignal.push.getChallenge();

Updating a challenge​

const approved = true; // true if the user has approved the challenge

await authsignal.push.updateChallenge(challengeId, approved);