auth0/auth0-ionic-react

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

| Use Case | Recommended Skill | |----------|------------------| | React SPA (no Capacitor/Ionic) | auth0-react | | React Native (bare CLI) | auth0-react-native | | Expo (React Native) | auth0-expo | | Ionic + Angular + Capacitor | auth0-ionic-angular | | Ionic + Vue + Capacitor | auth0-ionic-vue | | Next.js (server-side) | auth0-nextjs | | iOS native (Swift) | auth0-swift | | Android native (Kotlin) | auth0-android |

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

| Mistake | Fix | |---------|-----| | App type not set to Native in Auth0 Dashboard | Change application type to "Native" in Dashboard settings | | Missing or incorrect callback URL format | Use YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback — must match exactly | | Not enabling refresh tokens | Set useRefreshTokens={true} and useRefreshTokensFallback={false} on Auth0Provider | | Missing @capacitor/browser or @capacitor/app | Install both: npm install @capacitor/browser @capacitor/app && npx cap sync | | Not handling deep link callback | Add CapApp.addListener('appUrlOpen', ...) to process Auth0 redirect | | Forgetting npx cap sync after install | Always run npx cap sync after installing Capacitor plugins | | Using window.location.origin as redirect URI | Use the custom URL scheme (packageId://domain/...), not http://localhost | | Missing Allowed Origins in Dashboard | Add capacitor://localhost, http://localhost to Allowed Origins | | localStorage treated as persistent on mobile | Use refresh tokens (useRefreshTokens={true}) for reliable token persistence | | iOS SSO not working | SFSafariViewController doesn't share cookies with Safari on iOS 11+; this is expected | | Not testing on physical device | Always test auth flows on a physical device; simulators may not handle deep links correctly |

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

| API | Description | |-----|-------------| | Auth0Provider | Context provider — wraps app root with Auth0 config | | useAuth0() | Hook — returns { isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback } | | loginWithRedirect({ openUrl }) | Login via Universal Login — use Browser.open() in openUrl callback | | logout({ logoutParams, openUrl }) | Logout — use Browser.open() in openUrl callback | | handleRedirectCallback(url) | Process Auth0 callback URL from deep link | | getAccessTokenSilently() | Get access token (uses refresh tokens on mobile) | | withAuthenticationRequired(Component) | HOC to protect routes | | Browser.open({ url }) | Capacitor — opens URL in system browser (SFSafariViewController / Chrome Custom Tabs) | | CapApp.addListener('appUrlOpen', cb) | Capacitor — listens for deep link events | | Browser.close() | Capacitor — closes the in-app browser after callback |

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