Auth0 Ionic React (Capacitor) Integration

Add Auth0 authentication to Ionic React applications using Capacitor. This skill covers native mobile authentication using the @auth0/auth0-react SDK combined with @capacitor/browser and @capacitor/app plugins for deep link handling on iOS and Android.

Prerequisites

• Node.js 18+
• Ionic CLI (npm install -g @ionic/cli)
• An existing Ionic React application with Capacitor configured
• Auth0 account and tenant
• For iOS: Xcode 14+ and CocoaPods
• For Android: Android Studio with API level 21+
• Auth0 CLI — brew install auth0/auth0-cli/auth0

When NOT to Use

Quick Start Workflow

Step 1: Configure Auth0

For automated setup with Auth0 CLI, see Setup Guide for complete scripts.

For manual setup, configure a Native application in the Auth0 Dashboard and note your Domain and Client ID.

Step 2: Install Dependencies

npm install @auth0/auth0-react @capacitor/browser @capacitor/app
npx cap sync

Step 3: Set Up Auth0Provider

Wrap the app root with Auth0Provider, configuring it for Capacitor. In src/main.tsx:

import React from 'react';
import { createRoot } from 'react-dom/client';
import { Auth0Provider } from '@auth0/auth0-react';
import App from './App';

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;
const packageId = import.meta.env.VITE_AUTH0_PACKAGE_ID; // e.g., com.example.myapp

const redirectUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      useRefreshTokens={true}
      useRefreshTokensFallback={false}
      authorizationParams={{
        redirect_uri: redirectUri
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

Step 4: Implement Login with Capacitor Browser

import { useAuth0 } from '@auth0/auth0-react';
import { Browser } from '@capacitor/browser';

const { loginWithRedirect } = useAuth0();

const login = async () => {
  await loginWithRedirect({
    async openUrl(url) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};

Step 5: Handle Callback via Deep Link

import { useEffect } from 'react';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { useAuth0 } from '@auth0/auth0-react';

const { handleRedirectCallback } = useAuth0();

useEffect(() => {
  const listener = CapApp.addListener('appUrlOpen', async ({ url }) => {
    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
      await handleRedirectCallback(url);
    }
    await Browser.close();
  });

  return () => {
    listener.then(l => l.remove());
  };
}, [handleRedirectCallback]);

Step 6: Implement Logout

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: `${packageId}://${domain}/capacitor/${packageId}/callback`
    },
    async openUrl(url) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};

Step 7: Build and Test

Agent instruction: After integration, verify the build:

ionic build
npx cap sync

For iOS: npx cap open ios then build in Xcode. For Android: npx cap open android then build in Android Studio. If the build fails, iterate up to 5-6 times to fix issues. If still failing, use AskUserQuestion to request help.

Detailed Documentation

• Setup Guide — Auth0 CLI configuration, Capacitor URL scheme registration, secret management
• Integration Patterns — Login/logout with Capacitor Browser, deep link callback handling, user profile, protected routes, token access, error handling
• Testing & Reference — Full API reference for Auth0Provider props, useAuth0 hook, Capacitor plugin configuration, testing checklist, common issues

Common Mistakes

WebAuth Method

This SDK uses Auth0's Universal Login (WebAuth) via the Capacitor Browser plugin. The loginWithRedirect() method opens the Auth0 authorization endpoint in a system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android). After authentication, Auth0 redirects back to the app using a native callback URL with a custom scheme: {packageId}://{domain}/capacitor/{packageId}/callback. The @capacitor/app plugin captures this deep link, and handleRedirectCallback(url) processes the authorization code exchange.

Unlike standard native SDKs that use https://{domain}/android/{packageId}/callback or https://{domain}/ios/{bundleId}/callback, Ionic Capacitor apps use the Capacitor-specific callback path with the package ID as the URL scheme.

Related Skills

• auth0-react — React SPA (browser-only, no Capacitor)
• auth0-ionic-angular — Ionic with Angular and Capacitor
• auth0-ionic-vue — Ionic with Vue and Capacitor
• auth0-react-native — React Native (bare CLI, no Ionic/Capacitor)
• auth0-expo — Expo (React Native) with Auth0

Quick Reference

References

• Auth0 Ionic React Quickstart
• Auth0 React SDK GitHub
• Auth0 React SDK API Reference
• Ionic React Capacitor Sample App
• Capacitor Browser Plugin
• Capacitor App Plugin
• Auth0 Dashboard