Skip to main content
By Steve Hobbs
This tutorial demonstrates how to add user login with Auth0 to an Ionic React & Capacitor application.We recommend that you log in to follow this quickstart with examples configured for your account.

​
Getting started

This quickstart assumes you already have an Ionic application up and running with Capacitor. If not, check out the Using Capacitor with Ionic Framework guide to get started with a simple app, or clone our sample apps. You should also be familiar with the Capacitor development workflow.
New to Auth? Learn How Auth0 works, how it integrates with Native Applications and which protocol it uses.

​
Configure Auth0

​
Get Your Application Keys

When you signed up for Auth0, a new application was created for you, or you could have created a new one. You will need some details about that application to communicate with Auth0. You can get these details from the Application Settings section in the Auth0 dashboard.
App Dashboard
When using the Default App with a Native or Single Page Application, ensure to update the Token Endpoint Authentication Method to None and set the Application Type to either SPA or Native.
You need the following information:
  • Domain
  • Client ID
If you download the sample from the top of this page, these details are filled out for you.

​
Configure Callback URLs

A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated. The callback URL for your app must be added to the Allowed Callback URLs field in your Application Settings. If this field is not set, users will be unable to log in to the application and will get an error.
Throughout this article, YOUR_PACKAGE_ID is your application’s package ID. This can be found and configured in the appId field in your capacitor.config.ts file. See Capacitors Config schema for more info.
Go to the Application Settings section in your Auth0 dashboard and set your Callback URL in the Allowed Callback URLs box. You should set the Allowed Callback URL to: 
YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback

​
Configure Logout URLs

A logout URL is a URL in your application that Auth0 can return to after the user has been logged out of the authorization server. This is specified in the returnTo query parameter. The logout URL for your app must be added to the Allowed Logout URLs field in your Application Settings. If this field is not set, users will be unable to log out from the application and will get an error. You should set the Allowed Logout URLs to 
YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback

​
Configure Origins

To be able to make requests from your application to Auth0, set the following Allowed Origins in your Application Settings. 
capacitor://localhost, http://localhost
These origins are required for iOS and Android respectively. Lastly, be sure that the Application Type for your application is set to Native in the Application Settings.

​
Install the Auth0 React SDK

Run the following command within your project directory to install the Auth0 React SDK: 
npm install @auth0/auth0-react
The SDK exposes methods and variables that help you integrate Auth0 with your React application idiomatically using React Hooks or Higher-Order Components.

​
Install Capacitor plugins

This quickstart and sample make use of some of Capacitor’s official plugins. Install these into your app using the following command: 
npm install @capacitor/browser @capacitor/app
  • @capacitor/browser - allows you to interact with the device’s system browser and is used to open the URL to Auth0’s authorizaction endpoint
  • @capacitor/app - allows you to subscribe to high-level app events, useful for handling callbacks from Auth0
Capacitor’s Browser plugin on iOS uses SFSafariViewController, which on iOS 11+ does not share cookies with Safari on the device. This means that SSO will not work on those devices. If you need SSO, please instead use a compatible plugin that uses ASWebAuthenticationSession.

​
Configure the Auth0Provider component

Under the hood, the Auth0 React SDK uses React Context to manage the authentication state of your users. One way to integrate Auth0 with your React app is to wrap your root component with an Auth0Provider that you can import from the SDK. Open src/index.tsx and wrap the App component in the Auth0Provider component. The Auth0Provider component takes the following props:
  • domain: The “domain” value present under the “Settings” of the application you created in your Auth0 dashboard, or your custom domain if using Auth0’s Custom Domains feature
  • clientId: The “client ID” value present under the “Settings” of the application you created in your Auth0 dashboard
  • useRefreshTokens: To use auth0-react with Ionic on Android and iOS, it’s required to enable refresh tokens.
  • useRefreshTokensFallback: To use auth0-react with Ionic on Android and iOS, it’s required to disable the iframe fallback.
  • authorizationParams.redirect_uri: The URL to where you’d like to redirect your users after they authenticate with Auth0.
To persist authentication after closing and reopening the application, you may want to set cacheLocation to localstorage when configuring the SDK, but please be aware of the risks of storing tokens in localstorage. Also, localstorage should be treated as transient in Capacitor app as the data might be recovered unexpectedly in certain circumstances. Please read the guidance on storage in the Capacitor docs.Additionally, the SDK has the ability to use a custom cache implementation to store tokens, if you have a requirement to use a more secure and persistent storage mechanism.Note that we recommend against using Capacitors Storage plugin to store tokens, as this is backed by UserDefaults and SharedPreferences on iOS and Android respectively. Data stored using these APIs is not encrypted, not secure, and could also be synced to the cloud.

​
Checkpoint

Now that you have configured Auth0Provider, run your application to verify that the SDK is initializing correctly, and your application is not throwing any errors related to Auth0.

​
Add Login to Your Application

In a Capacitor application, the Capacitors Browser plugin performs a redirect to the Auth0 Universal Login Page. Set the openUrl parameter on the loginWithRedirect function to use Browser.open so that the URL is opened using the device’s system browser component (SFSafariViewController on iOS, and Chrome Custom Tabs on Android).
By default, the SDK’s loginWithRedirect method uses window.location.href to navigate to the login page in the default browser application on the user’s device rather than the system browser component appropriate for the platform. The user would leave your application to authenticate and could make for a suboptimal user experience.
Add a new file LoginButton.tsx with the following code: 
import { useAuth0 } from '@auth0/auth0-react';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/react';

const LoginButton: React.FC = () => {
  const { loginWithRedirect } = useAuth0();

  const login = async () => {
    await loginWithRedirect({
      async openUrl(url) {
         // Redirect using Capacitor's Browser plugin
        await Browser.open({
          url,
          windowName: "_self"
        });
      }
    });
  };

  return <IonButton onClick={login}>Log in</IonButton>;
};

export default LoginButton;
This component:
  • defines a template with a simple button that logs the user in when clicked
  • uses loginWithRedirect to login using Auth0’s Universal Login page
  • uses the openUrl callback to use Capacitor’s Browser plugin to open the URL and show the login page to the user
This guide focuses on using the useAuth0() custom React Hook. If you are using class components, check out these samples using the withAuth0() higher-order component.

​
Handling the callback

Once users logs in with the Universal Login Page, they redirect back to your app via a URL with a custom URL scheme. The appUrlOpen event must be handled within your app. You can call the handleRedirectCallback method from the Auth0 SDK to initialize the authentication state. You can only use this method on a redirect from Auth0. To verify success, check for the presence of the code and state parameters in the URL. The Browser.close() method should close the browser when this event is raised. Add the following useEffect hook to your main App component: 
// Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
// as well as the bits needed for Auth0 and React
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { useEffect } from 'react';
import { useAuth0 } from '@auth0/auth0-react';

// ...

const App: React.FC = () => {
  // Get the callback handler from the Auth0 React hook
  const { handleRedirectCallback } = useAuth0();

  useEffect(() => {
    // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
    CapApp.addListener('appUrlOpen', async ({ url }) => {
      if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
        await handleRedirectCallback(url);
      }
      // No-op on Android
      await Browser.close();
    });
  }, [handleRedirectCallback]);

  // ..
};
This article assumes you will be using Custom URL Schemes to handle the callback within your application. To do this, register your YOUR_PACKAGE_ID as a URL scheme for your chosen platform. To learn more, read Defining a Custom URL Scheme for iOS, or Create Deep Links to App Content for Android.

​
Checkpoint

Add the LoginButton component to your application, as well as the handler for the “appUrlOpen” event to your App component. When you click the login button, verify that your application redirects you to the Auth0 Universal Login Page and that you can now log in or sign up using a username and password or a social provider.Once that’s complete, verify that Auth0 redirects you back to your application.

​
Add Logout to Your Application

Now that users can log in, you need to configure a way to log out. Users must redirect to the Auth0 logout endpoint in the browser to clear their browser session. Again, Capacitor’s Browser plugin should perform this redirect so that the user does not leave your app and receive a suboptimal experience. To achieve this with Ionic and Capacitor in conjunction with the Auth0 SDK:
  • Construct the URL for your app Auth0 should use to redirect to after logout. This is a URL that uses your registered custom scheme and Auth0 domain. Add it to your Allowed Logout URLs configuration in the Auth0 Dashboard
  • Logout from the SDK by calling logout, and pass your redirect URL back as the logoutParams.returnTo parameter.
  • Set the openUrl parameter to a callback that uses the Capacitor browser plugin to open the URL using Browser.open.
Similar to the login step, if you do not set openUrl when calling logout, the SDK redirects the user to the logout URL using the default browser application on the device, which provides a suboptimal user experience.
Create a new file LogoutButton.tsx and add the following code to the file. Then, add the LogoutButton component to your app.

​
Checkpoint

Add the LogoutButton component to your application. When you click it, verify that your Ionic application redirects you the address you specified as one of the “Allowed Logout URLs” in the “Settings” and that you are no longer logged in to your application.

​
Show User Profile Information

The Auth0 React SDK helps you retrieve the profile information associated with logged-in users quickly in whatever component you need, such as their name or profile picture, to personalize the user interface. The profile information is available through the user property exposed by the useAuth0() hook. Take this Profile component as an example of how to use it: 
import { useAuth0 } from '@auth0/auth0-react';

const Profile: React.FC = () => {
  const { user, isLoading } = useAuth0();

  // If the SDK is not ready, or a user is not authenticated, exit.
  if (isLoading || !user) return null;

  return (
    <div>
      <Frame><img 
        src={user.picture || `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`}
        alt={user.name} 
        onError={(e) => {
          const target = e.target as HTMLImageElement;
          target.src = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`;
        }}
      /></Frame>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
};

export default Profile;
The user property contains sensitive information and artifacts related to the user’s identity. As such, its availability depends on the user’s authentication status. To prevent any render errors, use the isAuthenticated property from useAuth0() to check if Auth0 has authenticated the user before React renders any component that consumes the user property. Ensure that the SDK has completed loading before accessing the isAuthenticated property, by checking that isLoading is false.

​
Checkpoint

Add the Profile component to your application, and verify that you can display the user.name or any other user property within a component correctly after you have logged in.
What can you do next?
Configure other identity providersEnable multifactor authentication
Learn about attack protectionLearn about rules
Edit on GitHub