đ Documentation âĸ đ Getting Started âĸ âī¸ Next Steps âĸ â FAQs âĸ â Feedback
We're excited to announce the release of react-native-auth0 v3.0.0! Please note that this update includes breaking changes that require your attention. To ensure a smooth transition, please review our đ Migration Guide đ for detailed instructions on updating your integration.
This SDK targets apps that are using React Native SDK version
0.60.5
and up. If you're using an older React
Native version, see the compatibility matrix below.
The following shows platform minimums for running projects with this SDK:
Platform | Minimum version |
---|---|
iOS | 13.0 |
Android | 28 |
Our SDK requires a minimum iOS deployment target of 13.0. In your project's ios/Podfile, ensure your platform target is set to 13.0.
platform :ios, '13.0'
First install the native library module:
$ npm install react-native-auth0 --save
$ 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
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.
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.
Open your app's build.gradle
file (typically at
android/app/build.gradle
) and add the following
manifest placeholders:
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:
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, 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.
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:
<activity
android:name="com.auth0.android.provider.AuthenticationActivity"
tools:node="remove"/>
<!-- Optional: Remove RedirectActivity -->
<activity
android:name="com.auth0.android.provider.RedirectActivity"
tools:node="remove"/>
Inside the ios
folder find the file
AppDelegate.[swift|m]
add the following to it:
#import <React/RCTLinkingManager.h>
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
{
return [RCTLinkingManager application:app openURL:url options:options];
}
Inside the ios
folder open the
Info.plist
and locate the value for
CFBundleIdentifier
, e.g.
<key>CFBundleIdentifier</key>
<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
and then below it register a URL type entry using the value of
CFBundleIdentifier
as the value for
CFBundleURLSchemes
:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>None</string>
<key>CFBundleURLName</key>
<string>auth0</string>
<key>CFBundleURLSchemes</key>
<array>
<string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
</array>
</dict>
</array>
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:
ios/TestApp.xcodeproj
file replacing
'TestApp' with the name of your app or run
xed ios
from a Terminal.
com.example.app
).
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.
: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. To do this, add the following snippet to app.json or
app.config.js:
{
"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
API | Description |
---|---|
domain | Mandatory: Provide the Auth0 domain that can be found at the Application Settings |
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.
|
Now you can run the application using
expo run:android
or expo run:ios
.
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.
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, 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.
{YOUR_APP_PACKAGE_NAME}.auth0://{AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
Make sure to replace {YOUR_APP_PACKAGE_NAME} and {AUTH0_DOMAIN} with the actual values for your application. The {YOUR_APP_PACKAGE_NAME} value provided should be all lower case.
{PRODUCT_BUNDLE_IDENTIFIER}.auth0://{AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
Make sure to replace {PRODUCT_BUNDLE_IDENTIFIER} and {AUTH0_DOMAIN} with the actual values for your application. The {PRODUCT_BUNDLE_IDENTIFIER} value provided should be all lower case.
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.
The SDK exports a React hook as the primary interface for performing web authentication through the browser using 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
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:
import { Auth0Provider } from 'react-native-auth0';
const App = () => {
return (
<Auth0Provider domain="YOUR_AUTH0_DOMAIN" clientId="YOUR_AUTH0_CLIENT_ID">
{/* YOUR APP */}
</Auth0Provider>
);
};
export default App;
If you're not using React Hooks, you can simply instantiate
the Auth0
class:
import Auth0 from 'react-native-auth0';
const auth0 = new Auth0({
domain: 'YOUR_AUTH0_DOMAIN',
clientId: 'YOUR_AUTH0_CLIENT_ID',
});
Then import the hook into a component where you want to get access to the properties and methods for integrating with Auth0:
import { useAuth0 } from 'react-native-auth0';
Use the authorize
method to redirect the user to the
Auth0
Universal Login
page for authentication. If scope
is not specified,
openid profile email
is used by default.
isLoading
property is set to true once the
authentication state of the user is known to the SDK.
user
property is populated with details about the
authenticated user. If user
is null
, no
user is currently authenticated.
error
property is populated if any error occurs.
const Component = () => {
const { authorize, user, isLoading, error } = useAuth0();
const login = async () => {
await authorize();
};
if (isLoading) {
return (
<View>
<Text>SDK is Loading</Text>
</View>
);
}
return (
<View>
{!user && <Button onPress={login} title="Log in" />}
{user && <Text>Logged in as {user.name}</Text>}
{error && <Text>{error.message}</Text>}
</View>
);
};
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.
Check the FAQ for more information about the alert box that pops up by default when using Web Auth on iOS.
See also this blog post for a detailed overview of Single Sign-On (SSO) on iOS.
Log the user out by using the clearSession
method from
the useAuth0
hook.
const Component = () => {
const { clearSession, user } = useAuth0();
const logout = async () => {
await clearSession();
};
return <View>{user && <Button onPress={logout} title="Log out" />}</View>;
};
auth0.webAuth.clearSession().catch((error) => console.log(error));
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.
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.
const isLoggedIn = await auth0.credentialsManager.hasValidCredentials();
if (isLoggedIn) {
// Retrieve credentials and redirect to the main flow
} else {
// Redirect to the login page
}
The credentials will be automatically renewed using the refresh token, if the access token has expired. This method is thread safe.
const credentials = await auth0.credentialsManager.getCredentials();
đĄ You do not need to call credentialsManager.saveCredentials() afterward. The Credentials Manager automatically persists the renewed credentials.
:warning: The
requireLocalAuthentication
method is no longer available as part of theCredentialsManager
class or theuseAuth0
Hook from v4 of the SDK.
âšī¸ You need to use at least version
0.59.0
of React Native, as it usesFragmentActivity
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:
import Auth0 from 'react-native-auth0';
const localAuthOptions: LocalAuthenticationOptions = {
title: 'Authenticate to retreive 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:
import { Auth0Provider } from 'react-native-auth0';
const localAuthOptions: LocalAuthenticationOptions = {
title: 'Authenticate to retreive 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 (
<Auth0Provider
domain={config.domain}
clientId={config.clientId}
localAuthenticationOptions={localAuthOptions}
>
{/* YOUR APP */}
</Auth0Provider>
);
};
export default App;
Detailed information on LocalAuthenticationOptions
is
available here
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. | Android |
:warning: You need a real device to test Local Authentication for iOS. Local Authentication is not available in simulators.
The Credentials Manager will only throw
CredentialsManagerError
exceptions. You can find more
information in the details property of the exception.
try {
const credentials = await auth0.credentialsManager.getCredentials();
} catch (error) {
console.log(error);
}
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
To provide feedback or report a bug, please raise an issue on our issue tracker.
Please do not report security vulnerabilities on the public Github issue tracker. The Responsible Disclosure Program 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.
Generated using TypeDoc