auth0-ionic-vue

Auth0 Ionic Vue (Capacitor) Integration

Add Auth0 authentication to Ionic Vue applications using Capacitor. This skill covers native mobile authentication using the @auth0/auth0-vue 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 Vue 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
Vue SPA (no Capacitor/Ionic)	auth0-vue
React SPA (no Capacitor/Ionic)	auth0-react
React Native (bare CLI)	auth0-react-native
Expo (React Native)	auth0-expo
Ionic + React + Capacitor	auth0-ionic-react
Ionic + Angular + Capacitor	auth0-ionic-angular
Next.js (server-side)	auth0-nextjs
Nuxt (server-side)	auth0-nuxt
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-vue @capacitor/browser @capacitor/app
npx cap sync

Step 3: Set Up Auth0 Plugin

Agent instruction: If Step 1 already wrote .env and updated src/main.ts, verify the configuration looks correct and skip to Step 4. Only use the template below if configuring manually.

Register the Auth0 Vue plugin in your app entry point (src/main.ts), configuring it for Capacitor. Credentials are read from .env via import.meta.env:

import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';

// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";

const app = createApp(App);

app.use(IonicVue);
app.use(router);
app.use(
  createAuth0({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    useRefreshTokens: true,
    useRefreshTokensFallback: false,
    authorizationParams: {
      redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
    }
  })
);

router.isReady().then(() => {
  app.mount('#app');
});

Step 4: Implement Login with Capacitor Browser

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';

const { loginWithRedirect } = useAuth0();

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

<template>
  <ion-button @click="login">Log in</ion-button>
</template>

Step 5: Handle Callback via Deep Link

Handle the deep link callback in your App.vue component. This must run on app initialization:

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { useAuth0 } from '@auth0/auth0-vue';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { IonApp, IonRouterOutlet } from '@ionic/vue';

const { handleRedirectCallback } = useAuth0();

let urlOpenListener: any;

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

onUnmounted(() => {
  urlOpenListener?.remove();
});
</script>

<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

Step 6: Implement Logout

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";
const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

const { logout } = useAuth0();

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: logoutUri
    },
    async openUrl(url: string) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};
</script>

<template>
  <ion-button @click="doLogout">Log out</ion-button>
</template>

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 automated setup (login, app creation, credential injection), 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 createAuth0 options, useAuth0 composable, 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 in createAuth0()
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
Not calling app.use(createAuth0(...)) before mount	Register Auth0 plugin before calling app.mount('#app')
Accessing .value incorrectly on auth refs	useAuth0() returns Vue refs — use .value in <script>, template unwraps automatically
localStorage treated as persistent on mobile	Use refresh tokens (useRefreshTokens: true) for reliable token persistence

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

Quick Reference

API	Description
createAuth0(options)	Vue plugin factory — registers Auth0 with app.use()
useAuth0()	Composable — returns { isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback, error }
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)
createAuthGuard(app)	Vue Router navigation guard factory for protected 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 Vue Quickstart
• Auth0 Vue SDK GitHub
• Auth0 Vue SDK API Reference
• Ionic Vue Capacitor Sample App
• Capacitor Browser Plugin
• Capacitor App Plugin
• Auth0 Dashboard