# react-native-auth0
**Repository Path**: mirrors_auth0/react-native-auth0
## Basic Information
- **Project Name**: react-native-auth0
- **Description**: React Native toolkit for Auth0 API
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2026-06-06
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
[![Build Status][circleci-image]][circleci-url]
[![NPM version][npm-image]][npm-url]
[![Coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Freact-native-auth0?ref=badge_shield)
[](https://deepwiki.com/auth0/react-native-auth0)
📚 [Documentation](#documentation) • 🚀 [Getting Started](#getting-started) • ⏭️ [Next Steps](#next-steps) • ❓ [FAQs](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md) • ❓ [Feedback](#feedback)
### ⚠️ Important Migration Notice: v4.0.0 and v5.0.0
We're excited to announce the release of react-native-auth0 `v5.0.0`!
**For v5.0.0 users:** This version requires React 19 and React Native 0.78.0 or higher. If you're using Expo, this version requires Expo 53 or higher. See the 👉 [Migration Guide](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md) 👈 for compatibility requirements and upgrade instructions.
## Documentation
- [Quickstart](https://auth0.com/docs/quickstart/native/react-native/interactive)
- [Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive)
- [Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Hooks)
- [Expo Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo)
- [React Native Web Setup](https://github.com/auth0/react-native-auth0/blob/master/REACT_NATIVE_WEB_SETUP.md)
- [FAQs](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md)
- [Examples](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md)
- [Examples for Web](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES-WEB.md)
- [Docs Site](https://auth0.github.io/react-native-auth0/)
## Getting Started
### Requirements
This SDK targets apps that are using React Native SDK version `0.78.0` and up. If you're using an older React Native version, see the compatibility matrix below.
This SDK fully supports React Native New Architecture and Expo 53+.
> ⚠️ **Warning**: If you are using Expo version less than 53, you need to use react-native-auth0 version 4.x or earlier. Version 5.x supports Expo 53 and above.
### Platform compatibility
The following shows platform minimums for running projects with this SDK:
| Platform | Minimum version |
| -------- | :-------------: |
| iOS | 14.0 |
| Android | 35 |
Our SDK requires a minimum iOS deployment target of 14.0. In your project's ios/Podfile, ensure your platform target is set to 14.0.
```
platform :ios, '14.0'
```
### Installation
First install the native library module:
### With [npm](https://www.npmjs.com)
`$ npm install react-native-auth0 --save`
### With [Yarn](https://yarnpkg.com/en/)
`$ yarn add react-native-auth0`
Then, you need to run the following command to install the ios app pods with Cocoapods. That will auto-link the iOS library:
`$ cd ios && pod install`
### Configure the SDK
You need to make your Android, iOS or Expo applications aware that an authentication result will be received from the browser. This SDK makes use of the Android's Package Name and its analogous iOS's Product Bundle Identifier to generate the redirect URL. Each platform has its own set of instructions.
#### Android
> Before version 2.9.0, this SDK required you to add an intent filter to the Activity on which you're going to receive the authentication result, and to use the `singleTask` **launchMode** in that activity. To migrate your app to version 2.9.0+, **remove both** and continue with the instructions below.
> You can also check out a sample migration diff [here](https://github.com/auth0-samples/auth0-react-native-sample/commit/69f79c83ceed40f44b239bbd16e79ecaa70ef70a).
Open your app's `build.gradle` file (typically at `android/app/build.gradle`) and add the following manifest placeholders:
```groovy
android {
defaultConfig {
// Add the next line
manifestPlaceholders = [auth0Domain: "YOUR_AUTH0_DOMAIN", auth0Scheme: "${applicationId}.auth0"]
}
...
}
```
The `auth0Domain` value must be replaced with your Auth0 domain value. So if you have `samples.us.auth0.com` as your Auth0 domain you would have a configuration like the following:
```groovy
android {
defaultConfig {
manifestPlaceholders = [auth0Domain: "samples.us.auth0.com", auth0Scheme: "${applicationId}.auth0"]
}
...
}
```
The `applicationId` value will be auto-replaced at runtime with the package name or ID of your application (e.g. `com.example.app`). You can change this value from the `build.gradle` file. You can also check it at the top of your `AndroidManifest.xml` file.
> Note that if your Android application is using [product flavors](https://developer.android.com/studio/build/build-variants#product-flavors), you might need to specify different manifest placeholders for each flavor.
If you use a value other than `applicationId` in `auth0Scheme` you will also need to pass it as the `customScheme` option parameter of the `authorize` and `clearSession` methods.
Take note of this value as you'll be requiring it to define the callback URLs below.
> For more info please read the [React Native docs](https://facebook.github.io/react-native/docs/linking.html).
##### Skipping the Web Authentication setup
If you don't plan to use Web Authentication, you will notice that the compiler will still prompt you to provide the `manifestPlaceholders` values, since the `RedirectActivity` included in this library will require them, and the Gradle tasks won't be able to run without them.
Re-declare the activity manually with `tools:node="remove"` in your app's Android Manifest in order to make the manifest merger remove it from the final manifest file. Additionally, one more unused activity can be removed from the final APK by using the same process. A complete snippet to achieve this is:
```xml
```
#### iOS
Inside the `ios` folder find the file `AppDelegate.[swift|m]` add the following to it:
For Objective-C:
```objc
#import
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
options:(NSDictionary *)options
{
return [RCTLinkingManager application:app openURL:url options:options];
}
```
For Swift:
```swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return RCTLinkingManager.application(app, open: url, options: options)
}
```
Inside the `ios` folder open the `Info.plist` and locate the value for `CFBundleIdentifier`, e.g.
```xml
CFBundleIdentifier$(PRODUCT_BUNDLE_IDENTIFIER)
```
and then below it register a URL type entry using the value of `CFBundleIdentifier` as the value for `CFBundleURLSchemes`:
```xml
CFBundleURLTypesCFBundleTypeRoleNoneCFBundleURLNameauth0CFBundleURLSchemes$(PRODUCT_BUNDLE_IDENTIFIER).auth0
```
If your application is generated using the React Native CLI, the default value of `$(PRODUCT_BUNDLE_IDENTIFIER)` matches `org.reactjs.native.example.$(PRODUCT_NAME:rfc1034identifier)`. Take note of this value as you'll be requiring it to define the callback URLs below. If desired, you can change its value using XCode in the following way:
- Open the `ios/TestApp.xcodeproj` file replacing 'TestApp' with the name of your app or run `xed ios` from a Terminal.
- Open your project's or desired target's **Build Settings** tab and on the search bar at the right type "Product Bundle Identifier".
- Replace the **Product Bundle Identifier** value with your desired application's bundle identifier name (e.g. `com.example.app`).
- If you've changed the project wide settings, make sure the same were applied to each of the targets your app has.
If you use a value other than `$(PRODUCT_BUNDLE_IDENTIFIER)` in the `CFBundleURLSchemes` field of the `Info.plist` you will also need to pass it as the `customScheme` option parameter of the `authorize` and `clearSession` methods.
> For more info please read the [React Native docs](https://facebook.github.io/react-native/docs/linking.html).
#### Expo
> :warning: This SDK is not compatible with "Expo Go" app because of custom native code. It is compatible with Custom Dev Client and EAS builds
To use the SDK with Expo, configure the app at build time by providing the `domain` and the `customScheme` values through the [Config Plugin](https://docs.expo.dev/guides/config-plugins/). To do this, add the following snippet to _app.json_ or _app.config.js_:
```json
{
"expo": {
...
"plugins": [
[
"react-native-auth0",
{
"domain": "YOUR_AUTH0_DOMAIN",
"customScheme": "YOUR_CUSTOM_SCHEME"
}
]
]
}
}
```
> :info: If you want to switch between multiple domains in your app, refer [here](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md#domain-switching)
| API | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| domain | Mandatory: Provide the Auth0 domain that can be found at the [Application Settings](https://manage.auth0.com/#/applications) |
| customScheme | Optional: Custom scheme to build the callback URL with. The value provided here should be passed to the `customScheme` option parameter of the `authorize` and `clearSession` methods. The custom scheme should be a unique, all lowercase value with no special characters. To use Android App Links, set this value to `"https"`. |
**Note:** When using `customScheme: "https"` for Android App Links, the plugin will automatically add `android:autoVerify="true"` to the intent-filter in your Android manifest to enable automatic verification of App Links.
Now you can run the application using `expo run:android` or `expo run:ios`.
### Callback URL(s)
Callback URLs are the URLs that Auth0 invokes after the authentication process. Auth0 routes your application back to this URL and appends additional parameters to it, including a token. Since callback URLs can be manipulated, you will need to add this URL to your Application's **Allowed Callback URLs** for security. This will enable Auth0 to recognize these URLs as valid. If omitted, authentication will not be successful.
> [!IMPORTANT]
> **Callback URL Formatting**: Must be **all lowercase**, have **no trailing slash**, and exactly match the URL in Auth0 Dashboard. Incorrect formatting causes the app to "hang" after authentication. See [FAQ #17](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md#17-why-does-the-app-hang-or-freeze-during-social-login-google-facebook-etc) for troubleshooting.
On the Android platform this URL is case-sensitive. Because of that, this SDK will auto convert the Bundle Identifier (iOS) and Application ID (Android) values to lowercase in order to build the Callback URL with them. If any of these values contains uppercase characters a warning message will be printed in the console. Make sure to check that the right Callback URL is whitelisted in the Auth0 dashboard or the browser will not route successfully back to your application.
Go to the [Auth0 Dashboard](https://manage.auth0.com/#/applications), select your application and make sure that **Allowed Callback URLs** contains the URLs defined below.
If in addition you plan to use the log out method, you must also add these URLs to the **Allowed Logout URLs**.
> [!NOTE]
> Whenever possible, Auth0 recommends using [Android App Links](https://developer.android.com/training/app-links) and [Apple Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) for your callback and logout URLs. Custom URL schemes can be subject to [client impersonation attacks](https://datatracker.ietf.org/doc/html/rfc8252#section-8.6).
>
> 💡 If your Android app is using [product flavors](https://developer.android.com/studio/build/build-variants#product-flavors), you might need to specify different manifest placeholders for each flavor.
#### Android
##### Custom Scheme
```text
{YOUR_APP_PACKAGE_NAME}.auth0://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
```
**Example:** If your package name is `com.example.myapp` and your Auth0 domain is `example.us.auth0.com`:
```text
com.example.myapp.auth0://example.us.auth0.com/android/com.example.myapp/callback
```
##### App Link (Recommended):
```text
https://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
```
> Replace {YOUR_APP_PACKAGE_NAME} and {YOUR_AUTH0_DOMAIN} with your actual application package name and Auth0 domain. Ensure that {YOUR_APP_PACKAGE_NAME} is all lowercase.
To enable App Links, set the `auth0Scheme` to `https` in your `build.gradle` file.
```text
android {
defaultConfig {
manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "https"]
}
}
```
This configuration ensures that your app uses https for the callback URL scheme, which is required for Android App Links.
#### Enable Android App Links Support
[Android App Links](https://developer.android.com/training/app-links) allow an application to designate itself as the default handler of a given type of link. For example, clicking a URL in an email would open the link in the designated application. This guide will show you how to enable Android App links support for your Auth0-registered application using Auth0's Dashboard.
1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.
2. Scroll to the bottom of the Settings page, and select **Show Advanced Settings**.
3. Select Device Settings, provide the [App Package Name and](https://developer.android.com/studio/build/application-id) the SHA256 fingerprints of your app’s signing certificate for your Android application, and select Save Changes.
> You can use the following command to generate the fingerprint using the Java keytool in your terminal: `keytool -list -v -keystore my-release-key.keystore`
To learn more about signing certificates, see Android's [Sign Your App](https://developer.android.com/studio/publish/app-signing.html) developer documentation.
#### iOS
##### Custom Scheme
```text
{PRODUCT_BUNDLE_IDENTIFIER}.auth0://{YOUR_AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
```
##### Universal Link (Recommended):
```text
https://{YOUR_AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
```
> Replace `{PRODUCT_BUNDLE_IDENTIFIER}` and `{YOUR_AUTH0_DOMAIN}` with your actual product bundle identifier and Auth0 domain. Ensure that {PRODUCT_BUNDLE_IDENTIFIER} is all lowercase.
#### Expo
When using Expo, the callback URL format depends on whether you provide a `customScheme` in your `app.json` plugin configuration.
##### With `customScheme`
If you set a `customScheme` (e.g., `"auth0sample"`) in your `app.json`:
```text
{YOUR_CUSTOM_SCHEME}://{YOUR_AUTH0_DOMAIN}/ios/{BUNDLE_IDENTIFIER}/callback,
{YOUR_CUSTOM_SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{PACKAGE_NAME}/callback
```
**Example:** If your custom scheme is `auth0sample`, your Auth0 domain is `example.us.auth0.com`, your iOS bundle identifier is `com.example.myapp`, and your Android package name is `com.example.myapp`:
```text
auth0sample://example.us.auth0.com/ios/com.example.myapp/callback,
auth0sample://example.us.auth0.com/android/com.example.myapp/callback
```
> **Note:** The URL scheme uses `customScheme`, but the path always contains the bundle identifier (iOS) or package name (Android), **not** the custom scheme.
##### Without `customScheme`
If you do not provide a `customScheme`, the SDK defaults to `{BUNDLE_IDENTIFIER}.auth0` / `{PACKAGE_NAME}.auth0`:
```text
{BUNDLE_IDENTIFIER}.auth0://{YOUR_AUTH0_DOMAIN}/ios/{BUNDLE_IDENTIFIER}/callback,
{PACKAGE_NAME}.auth0://{YOUR_AUTH0_DOMAIN}/android/{PACKAGE_NAME}/callback
```
> All values must be **lowercase** with **no trailing slash**.
#### Configure an associated domain for iOS
> [!IMPORTANT]
> This step requires a paid Apple Developer account. It is needed to use Universal Links as callback and logout URLs.
> Skip this step to use a custom URL scheme instead.
##### Configure the Team ID and bundle identifier
Scroll to the end of the settings page of your Auth0 application and open **Advanced Settings > Device Settings**. In the **iOS** section, set **Team ID** to your [Apple Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/), and **App ID** to your app's bundle identifier.
This will add your app to your Auth0 tenant's `apple-app-site-association` file.
##### Add the associated domain capability
In Xcode, go to the **Signing and Capabilities** [tab](https://developer.apple.com/documentation/xcode/adding-capabilities-to-your-app#Add-a-capability) of your app's target settings, and press the **+ Capability** button. Then select **Associated Domains**.
Next, add the following [entry](https://developer.apple.com/documentation/xcode/configuring-an-associated-domain#Define-a-service-and-its-associated-domain) under **Associated Domains**:
```text
webcredentials:YOUR_AUTH0_DOMAIN
```
Example
If your Auth0 Domain were `example.us.auth0.com`, then this value would be:
```text
webcredentials:example.us.auth0.com
```
If you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace `YOUR_AUTH0_DOMAIN` with your custom domain.
> [!NOTE]
> For the associated domain to work, your app must be signed with your team certificate **even when building for the iOS simulator**. Make sure you are using the Apple Team whose Team ID is configured in the settings page of your Auth0 application.
Refer to the example of [Using custom scheme for web authentication redirection](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md#using-custom-scheme-for-web-authentication-redirection)
## Next Steps
> This SDK is OIDC compliant. To ensure OIDC compliant responses from the Auth0 servers enable the **OIDC Conformant** switch in your Auth0 dashboard under `Application / Settings / Advanced OAuth`. For more information please check [this documentation](https://auth0.com/docs/api-auth/intro#how-to-use-the-new-flows).
### Web Authentication
The SDK exports a React hook as the primary interface for performing [web authentication](#web-authentication) through the browser using Auth0 [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login).
Use the methods from the `useAuth0` hook to implement login, logout, and to retrieve details about the authenticated user.
See the [API Documentation](https://auth0.github.io/react-native-auth0/functions/useAuth0.html) for full details on the `useAuth0` hook.
First, import the `Auth0Provider` component and wrap it around your application. Provide the `domain` and `clientId` values as given to you when setting up your Auth0 app in the dashboard:
```js
import { Auth0Provider } from 'react-native-auth0';
const App = () => {
return (
{/* YOUR APP */}
);
};
export default App;
```
You can also pass custom headers that will be included in all API requests:
```js
import { Auth0Provider } from 'react-native-auth0';
const App = () => {
return (
{/* YOUR APP */}
);
};
export default App;
```
Using the `Auth0` class
If you're not using React Hooks, you can simply instantiate the `Auth0` class:
```js
import Auth0 from 'react-native-auth0';
const auth0 = new Auth0({
domain: 'YOUR_AUTH0_DOMAIN',
clientId: 'YOUR_AUTH0_CLIENT_ID',
});
```
You can also pass custom headers that will be included in all API requests:
```js
import Auth0 from 'react-native-auth0';
const auth0 = new Auth0({
domain: 'YOUR_AUTH0_DOMAIN',
clientId: 'YOUR_AUTH0_CLIENT_ID',
headers: {
'X-Custom-Header': 'custom-value',
},
});
```
Then import the hook into a component where you want to get access to the properties and methods for integrating with Auth0:
```js
import { useAuth0 } from 'react-native-auth0';
```
#### Login
Use the `authorize` method to redirect the user to the Auth0 [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) page for authentication. If `scope` is not specified, `openid profile email` is used by default.
- The `isLoading` property is set to true once the authentication state of the user is known to the SDK.
- The `user` property is populated with details about the authenticated user. If `user` is `null`, no user is currently authenticated.
- The `error` property is populated if any error occurs.
```js
const Component = () => {
const { authorize, user, isLoading, error } = useAuth0();
const login = async () => {
await authorize();
};
if (isLoading) {
return (
SDK is Loading
);
}
return (
{!user && }
{user && Logged in as {user.name}}
{error && {error.message}}
);
};
```
Using the `Auth0` class
```js
auth0.webAuth
.authorize()
.then(credentials => console.log(credentials))
.catch(error => console.log(error));
```
> Web Authentication flows require a Browser application installed on the device. When no Browser is available, an error of type `a0.browser_not_available` will be raised via the provided callback.
##### SSO Alert Box (iOS)
Check the [FAQ](FAQ.md) for more information about the alert box that pops up **by default** when using Web Auth on iOS.
> See also [this blog post](https://developer.okta.com/blog/2022/01/13/mobile-sso) for a detailed overview of Single Sign-On (SSO) on iOS.
#### Logout
Log the user out by using the `clearSession` method from the `useAuth0` hook.
```js
const Component = () => {
const { clearSession, user } = useAuth0();
const logout = async () => {
await clearSession();
};
return {user && };
};
```
Using the `Auth0` class
```js
auth0.webAuth.clearSession().catch((error) => console.log(error));
```
### Credentials Manager
- [Check for stored credentials](#check-for-stored-credentials)
- [Retrieve stored credentials](#retrieve-stored-credentials)
- [Local authentication](#local-authentication)
- [Credentials Manager errors](#credentials-manager-errors)
The Credentials Manager allows you to securely store and retrieve the user's credentials. The credentials will be stored encrypted in Shared Preferences on Android, and in the Keychain on iOS.
The `Auth0` class exposes the `credentialsManager` property for you to interact with using the API below.
> 💡 If you're using Web Auth (`authorize`) through Hooks, you do not need to manually store the credentials after login and delete them after logout; the SDK does this automatically.
#### Check for stored credentials
When the users open your app, check for valid credentials. If they exist, you can retrieve them and redirect the users to the app's main flow without any additional login steps.
```js
const isLoggedIn = await auth0.credentialsManager.hasValidCredentials();
if (isLoggedIn) {
// Retrieve credentials and redirect to the main flow
} else {
// Redirect to the login page
}
```
#### Retrieve stored credentials
The credentials will be automatically renewed using the [refresh token](https://auth0.com/docs/secure/tokens/refresh-tokens), if the access token has expired. **This method is thread safe**.
```js
const credentials = await auth0.credentialsManager.getCredentials();
```
> 💡 You do not need to call credentialsManager.saveCredentials() afterward. The Credentials Manager automatically persists the renewed credentials.
#### Requiring Authentication before obtaining Credentials
> :warning: The `requireLocalAuthentication` method is no longer available as part of the `CredentialsManager` class or the `useAuth0` Hook from v4 of the SDK.
> ℹ️ You need to use at least version `0.59.0` of React Native, as it uses `FragmentActivity` as the base activity, which is required for biometric authentication to work.
You can enable an additional level of user authentication before retrieving credentials using the local authentication supported by the device, for example PIN or fingerprint on Android, and Face ID or Touch ID on iOS.
Refer to the instructions below to understand how to enable authentication before retrieving credentials based on your setup:
**Using Auth0 Class:**
The `Auth0` class constructor now accepts a new parameter, which is an instance of the `LocalAuthenticationOptions` object. This needs to be passed while creating an instance of `Auth0` to enable authentication before obtaining credentials, as shown in the code snippet below:
```tsx
import Auth0 from 'react-native-auth0';
const localAuthOptions: LocalAuthenticationOptions = {
title: 'Authenticate to retrieve your credentials',
subtitle: 'Please authenticate to continue',
description: 'We need to authenticate you to retrieve your credentials',
cancelTitle: 'Cancel',
evaluationPolicy: LocalAuthenticationStrategy.deviceOwnerWithBiometrics,
fallbackTitle: 'Use Passcode',
authenticationLevel: LocalAuthenticationLevel.strong,
deviceCredentialFallback: true,
};
const auth0 = new Auth0({
domain: config.domain,
clientId: config.clientId,
localAuthenticationOptions: localAuthOptions,
});
```
**Using Hooks (Auth0Provider):**
`Auth0Provider` now accepts a new parameter, which is an instance of the `LocalAuthenticationOptions` object. This needs to be passed to enable authentication before obtaining credentials, as shown in the code snippet below:
```tsx
import { Auth0Provider } from 'react-native-auth0';
const localAuthOptions: LocalAuthenticationOptions = {
title: 'Authenticate to retrieve your credentials',
subtitle: 'Please authenticate to continue',
description: 'We need to authenticate you to retrieve your credentials',
cancelTitle: 'Cancel',
evaluationPolicy: LocalAuthenticationStrategy.deviceOwnerWithBiometrics,
fallbackTitle: 'Use Passcode',
authenticationLevel: LocalAuthenticationLevel.strong,
deviceCredentialFallback: true,
};
const App = () => {
return (
{/* YOUR APP */}
);
};
export default App;
```
Detailed information on `LocalAuthenticationOptions` is available [here](#localauthenticationoptions)
**LocalAuthenticationOptions:**
The options for configuring the display of local authentication prompt, authentication level (Android only), and evaluation policy (iOS only).
**Properties:**
| Property | Type | Description | Applicable Platforms |
| -------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `title` | `String` | The title of the authentication prompt. | Android, iOS |
| `subtitle` | `String` (optional) | The subtitle of the authentication prompt. | Android |
| `description` | `String` (optional) | The description of the authentication prompt. | Android |
| `cancelTitle` | `String` (optional) | The cancel button title of the authentication prompt. | Android, iOS |
| `evaluationPolicy` | `LocalAuthenticationStrategy` (optional) | The evaluation policy to use when prompting the user for authentication. Defaults to `deviceOwnerWithBiometrics`. | iOS |
| `fallbackTitle` | `String` (optional) | The fallback button title of the authentication prompt. | iOS |
| `authenticationLevel` | `LocalAuthenticationLevel` (optional) | The authentication level to use when prompting the user for authentication. Defaults to `strong`. | Android |
| `deviceCredentialFallback` | `Boolean` (optional) | Should the user be given the option to authenticate with their device PIN, pattern, or password instead of a biometric. Defaults to `false` | Android |
> :warning: You need a real device to test Local Authentication for iOS. Local Authentication is not available in simulators.
### Credentials Manager errors
The Credentials Manager will only throw `CredentialsManagerError` exceptions. You can find more information in the details property of the exception.
```js
try {
const credentials = await auth0.credentialsManager.getCredentials();
} catch (error) {
console.log(error);
}
```
**Platform agnostic errors:**
You can access the platform agnostic generic error codes as below:
```js
try {
const credentials = await auth0.credentialsManager.getCredentials();
} catch (error) {
console.log(error.type);
}
```
**Using Error Code Constants (Recommended)**
For better type safety and autocompletion, you can use the exported error code constants:
```js
import {
CredentialsManagerError,
CredentialsManagerErrorCodes,
} from 'react-native-auth0';
try {
const credentials = await auth0.credentialsManager.getCredentials();
} catch (error) {
if (error instanceof CredentialsManagerError) {
switch (error.type) {
case CredentialsManagerErrorCodes.NO_CREDENTIALS:
console.log('No credentials stored. User needs to log in.');
break;
case CredentialsManagerErrorCodes.NO_REFRESH_TOKEN:
console.log(
'No refresh token available. Request offline_access scope during login.'
);
break;
case CredentialsManagerErrorCodes.RENEW_FAILED:
console.log(
'Failed to refresh credentials. Re-authentication may be required.'
);
break;
case CredentialsManagerErrorCodes.BIOMETRICS_FAILED:
console.log('Biometric authentication failed.');
break;
case CredentialsManagerErrorCodes.DPOP_KEY_MISSING:
case CredentialsManagerErrorCodes.DPOP_KEY_MISMATCH:
case CredentialsManagerErrorCodes.DPOP_NOT_CONFIGURED:
console.log(
'DPoP credential state error. Clear credentials and re-authenticate.'
);
break;
default:
console.error('Credentials error:', error.message);
}
}
}
```
| Generic Error Code | Android Native Error | iOS Native Error | Web Error Code |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----------------------------------------------------------- |
| `INVALID_CREDENTIALS` | `INVALID_CREDENTIALS` | | |
| `NO_CREDENTIALS` | `NO_CREDENTIALS` | `noCredentials` | `login_required` |
| `NO_REFRESH_TOKEN` | `NO_REFRESH_TOKEN` | `noRefreshToken` |
| `RENEW_FAILED` | `RENEW_FAILED` | `renewFailed` | `missing_refresh_token`, `invalid_grant`,`consent_required` |
| `STORE_FAILED` | `STORE_FAILED` | `storeFailed` | |
| `REVOKE_FAILED` | `REVOKE_FAILED` | `revokeFailed` | |
| `LARGE_MIN_TTL` | `LARGE_MIN_TTL` | `largeMinTTL` | |
| `INCOMPATIBLE_DEVICE` | `INCOMPATIBLE_DEVICE` | | |
| `CRYPTO_EXCEPTION` | `CRYPTO_EXCEPTION` | | |
| `BIOMETRICS_FAILED` | OneOf `BIOMETRIC_NO_ACTIVITY`,`BIOMETRIC_ERROR_STATUS_UNKNOWN`,`BIOMETRIC_ERROR_UNSUPPORTED`, `BIOMETRIC_ERROR_HW_UNAVAILABLE`,`BIOMETRIC_ERROR_NONE_ENROLLED`,`BIOMETRIC_ERROR_NO_HARDWARE`, `BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED`,`BIOMETRIC_AUTHENTICATION_CHECK_FAILED`, `BIOMETRIC_ERROR_DEVICE_CREDENTIAL_NOT_AVAILABLE` | `biometricsFailed` | |
| `NO_NETWORK` | `NO_NETWORK` | | |
| `API_ERROR` | `API_ERROR` | | |
| `DPOP_KEY_MISSING` | `DPOP_KEY_MISSING` | `dpopKeyMissing` | |
| `DPOP_NOT_CONFIGURED` | `DPOP_NOT_CONFIGURED` | `dpopNotConfigured` | |
| `DPOP_KEY_MISMATCH` | `DPOP_KEY_MISMATCH` | `dpopKeyMismatch` | |
### WebAuth errors
**Before (Platform-Specific Codes)**
```javascript
// Old way: required checking Platform.OS and different error codes
import { Platform } from 'react-native';
try {
await auth0.webAuth.authorize();
} catch (e) {
const isCancelled =
Platform.OS === 'ios'
? e.code === 'USER_CANCELLED'
: e.code === 'a0.session.user_cancelled';
if (isCancelled) {
console.log('User cancelled the login.');
} else {
console.error(e);
}
}
```
**After (Platform-Agnostic and Typed)**
```javascript
// New way: use 'instanceof' and the 'type' property
import { WebAuthError } from 'react-native-auth0';
try {
await auth0.webAuth.authorize();
} catch (e) {
if (e instanceof WebAuthError && e.type === 'USER_CANCELLED') {
console.log('User cancelled the login.');
} else {
// Handle other errors
console.error(e);
}
}
```
**Using Error Code Constants (Recommended)**
For better type safety and autocompletion, you can use the exported error code constants:
```javascript
import { WebAuthError, WebAuthErrorCodes } from 'react-native-auth0';
try {
await auth0.webAuth.authorize();
} catch (e) {
if (e instanceof WebAuthError) {
switch (e.type) {
case WebAuthErrorCodes.USER_CANCELLED:
console.log('User cancelled the login.');
break;
case WebAuthErrorCodes.NETWORK_ERROR:
console.log('Network error occurred. Please check your connection.');
break;
case WebAuthErrorCodes.BROWSER_NOT_AVAILABLE:
console.log('No browser available on this device.');
break;
default:
console.error('Authentication error:', e.message);
}
}
}
```
| Platform-Agnostic | Description | Android Native Error | iOS Native Error | Web Error Code |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------- | ------------------------------------ |
| `USER_CANCELLED` | The user actively cancelled the web authentication flow. | `a0.session.user_cancelled` | `USER_CANCELLED` | `cancelled` |
| `BROWSER_NOT_AVAILABLE` | No compatible browser application is installed on the device. | `a0.browser_not_available` | - | |
| `NO_BUNDLE_IDENTIFIER` | The native bundle identifier could not be retrieved, which is required to construct the callback URL. | - | `NO_BUNDLE_IDENTIFIER` | |
| `FAILED_TO_LOAD_URL` | The authorization URL could not be loaded in the browser. | `a0.session.failed_load` | - | |
| `BROWSER_TERMINATED` | The browser was closed unexpectedly, likely because the application was relaunched from the home screen while the login was in progress. | `a0.session.browser_terminated` | - | |
| `INVALID_STATE` | The `state` parameter returned from the server did not match the one sent, indicating a potential Cross-Site Request Forgery (CSRF) attack. | `access_denied` | `OTHER` | `state_mismatch` |
| `ACCESS_DENIED` | The user or Auth0 denied the authentication request. This can be caused by a user denying consent, a failing Action or Rule, or other authorization policies. | `access_denied` | `OTHER` | `access_denied` |
| `CONSENT_REQUIRED` | The user needs to explicitly grant consent for the application to access requested scopes or resources. | - | | `consent_required` |
| `NO_AUTHORIZATION_CODE` | The callback URL from the server is missing the required `code` parameter needed for the token exchange. | - | `NO_AUTHORIZATION_CODE` | |
| `INVALID_CONFIGURATION` | The Auth0 Application is misconfigured. Common causes include an invalid social connection configuration. | `a0.invalid_configuration` | `OTHER` | |
| `PKCE_NOT_ALLOWED` | PKCE is required but not enabled for the Auth0 Application. Ensure the "Application Type" is set to "Native" in your Auth0 dashboard. | `a0.pkce_not_available` | `PKCE_NOT_ALLOWED` | |
| `ID_TOKEN_VALIDATION_FAILED` | The ID token received is invalid and failed one or more validation checks, such as signature, issuer, audience, or nonce verification. | `a0.session.invalid_idtoken` | `ID_TOKEN_VALIDATION_FAILED` | (various validation Errors). |
| `INVALID_INVITATION_URL` | The organization invitation URL is malformed or missing the required `organization` and `invitation` parameters. | - | `INVALID_INVITATION_URL` | |
| `NETWORK_ERROR` | A network error occurred, preventing the request from completing. The device may be offline or unable to reach the Auth0 servers. | `a0.network_error` | `OTHER` (with `URLError` cause) | (Network-related fetch exception) |
| `TIMEOUT_ERROR` | The web authentication flow timed out. | - | - | `timeout` (from `PopupTimeoutError`) |
| `UNKNOWN_ERROR` | An unexpected or uncategorized error occurred. Check the `message` and `cause` properties for more specific details. | _(various)_ | `UNKNOWN` or `OTHER` | |
## Features and Platform Support
This library provides a unified API across Native (iOS/Android) and Web platforms. However, due to security models and underlying technology, not all features are available on every platform.
| Feature / Method Category | Native (iOS/Android) | Web (Browser) | Notes & Rationale |
| ------------------------------------------ | :------------------: | :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Web Authentication** | | | --- |
| `webAuth.authorize()` | ✅ | ✅ | **Primary login method.** Uses `ASWebAuthenticationSession`/`Custom Tabs` on Native and `loginWithRedirect` on Web. |
| `webAuth.clearSession()` | ✅ | ✅ | **Primary logout method.** Clears the session cookie on the server via a browser redirect. |
| `webAuth.handleRedirectCallback()` | ❌ | ✅ | **Web-only.** Manually processes the callback from Auth0. Handled automatically when using the `Auth0Provider` hook. |
| **Credential Management** | | | --- |
| `credentialsManager.getCredentials()` | ✅ | ✅ | Retrieves stored tokens. On Native, it uses the secure Keychain/Keystore. On Web, it uses the `@auth0/auth0-spa-js` cache and `getTokenSilently`. |
| `credentialsManager.hasValidCredentials()` | ✅ | ✅ | Checks for a valid local session. |
| `credentialsManager.saveCredentials()` | ✅ | ❌ | **Native-only.** Manually saving credentials is required on Native. On Web, this is handled automatically by the underlying SPA SDK and is a no-op. |
| `credentialsManager.clearCredentials()` | ✅ | ✅ | Clears locally stored tokens. On Web, this performs a "local-only" logout. |
| **Direct Authentication Grants** | | | --- |
| `auth.passwordRealm()` | ✅ | ❌ | **Not supported on Web for security reasons.** The Resource Owner Password Grant exposes credentials to the browser and is not recommended for Single Page Applications. |
| `auth.passwordless...()` | ✅ | ❌ | **Not supported on Web.** Passwordless flows on the web should be configured via Universal Login and initiated with `webAuth.authorize()`. |
| `auth.loginWith...()` (OTP/SMS etc) | ✅ | ❌ | **Not supported on Web.** These direct grant flows are not secure for public clients like browsers. |
| **Passkeys** | | | --- |
| `passkeySignupChallenge()` | ✅ | ❌ | **Native-only.** Gets a WebAuthn registration challenge from Auth0. Requires iOS 16.6+ or Android API 28+. |
| `passkeyLoginChallenge()` | ✅ | ❌ | **Native-only.** Gets a WebAuthn assertion challenge from Auth0. Requires iOS 16.6+ or Android API 28+. |
| `getTokenByPasskey()` | ✅ | ❌ | **Native-only.** Exchanges a passkey credential response for Auth0 tokens. Requires iOS 16.6+ or Android API 28+. |
| **Token & User Management** | | | --- |
| `auth.refreshToken()` | ✅ | ❌ | **Not supported on Web.** Token refresh is handled automatically by `getCredentials()` via `getTokenSilently()` on the web. |
| `auth.userInfo()` | ✅ | ✅ | Fetches the user's profile from the `/userinfo` endpoint using an access token. |
| `auth.createUser()` | ✅ | ✅ | Calls the `/dbconnections/signup` endpoint. Works on both platforms. |
| `auth.resetPassword()` | ✅ | ✅ | Calls the `/dbconnections/change_password` endpoint. Works on both platforms. |
| `users(token).patchUser()` | ✅ | ✅ | Calls the Management API. Works on any platform with a valid token, but use with caution in the browser. |
## Troubleshooting
### App Hangs During Social Login
If your app "hangs" during authentication with social connections (Google, Facebook, etc.), first upgrade to the latest SDK version, then verify your callback URL is correctly formatted: **all lowercase**, **no trailing slash**, correct platform path (`/ios/` or `/android/`), and matches the Auth0 Dashboard exactly. See [FAQ #17](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md#17-why-does-the-app-hang-or-freeze-during-social-login-google-facebook-etc) for details.
### Swift 6 Compatibility Issues on iOS
If your main application project is configured to use Swift 6, and you encounter build errors related to Swift version incompatibilities with `react-native-auth0` or its dependencies (like `Auth0.swift`, `JWTDecode`, `SimpleKeychain`), you can ensure these specific pods are compiled with Swift 5.
While `react-native-auth0` (from v5.0.0-beta.1 onwards) and its direct Swift dependencies are configured to use Swift 5, your project's build settings might try to override this. To enforce Swift 5 for these pods:
**Recommended: Podfile `post_install` Hook**
Add the following `post_install` hook to your application's `ios/Podfile`. This is generally the most robust way to manage build settings for dependencies:
```ruby
# In your application's ios/Podfile
post_install do |installer|
installer.pods_project.targets.each do |target|
# Target the react-native-auth0 pod and its Swift dependencies
if ['Auth0', 'A0Auth0', 'JWTDecode', 'SimpleKeychain'].include?(target.name)
target.build_configurations.each do |config|
config.build_settings['SWIFT_VERSION'] = '5.0'
end
end
end
end
```
## Feedback
### Contributing
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
- [This repo's development guide](CONTRIBUTING.md)
### Raise an issue
To provide feedback or report a bug, [please raise an issue on our issue tracker](https://github.com/auth0/react-native-auth0/issues).
### Vulnerability Reporting
Please do not report security vulnerabilities on the public Github issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
---
Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?
This project is licensed under the MIT license. See the LICENSE file for more info.
