Auth0 Ionic Angular SDK Quickstart: Add Login to Your Ionic Angular Application

Get Started

This quickstart demonstrates how to add Auth0 authentication to an Ionic Angular application with Capacitor. You’ll build a mobile-ready app with login, logout, and user profile features using the Auth0 Angular SDK and Capacitor’s native browser plugins.

Create a new project

Create a new Ionic Angular project with Capacitor

npx ionic start auth0-ionic-angular tabs --type=angular-standalone --capacitor

Open the project

cd auth0-ionic-angular

Install the Auth0 Angular SDK and Capacitor plugins

Install the Auth0 Angular SDK along with Capacitor’s Browser and App plugins:

npm install @auth0/auth0-angular @capacitor/browser @capacitor/app

@capacitor/browser - opens the Auth0 login page in the device’s system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android)
@capacitor/app - handles deep link callbacks from Auth0 after authentication

Capacitor’s Browser plugin on iOS uses SFSafariViewController, which on iOS 11+ does not share cookies with Safari. This means SSO will not work on those devices. If you need SSO, use a compatible plugin that uses ASWebAuthenticationSession.

Setup your Auth0 App

Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

Quick Setup (recommended)
CLI
Dashboard

Create a Native Auth0 App and copy the pre-filled environment file with the right configuration values.After creating your app, update the Allowed Callback URLs and Allowed Logout URLs in the Auth0 Dashboard Settings tab. Replace YOUR_PACKAGE_ID with the appId from your capacitor.config.ts (default: io.ionic.starter):Allowed Callback URLs and Allowed Logout URLs:

YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback

Run the following command in your project’s root directory to create a Native Auth0 app and generate an environment file. Update PACKAGE_ID if your capacitor.config.ts uses a different appId:

Before you start, create an environment file in your project

src/environments/environment.ts

export const environment = {
  production: false,
  auth0: {
    domain: 'YOUR_AUTH0_APP_DOMAIN',
    clientId: 'YOUR_AUTH0_APP_CLIENT_ID'
  }
};

Head to the Auth0 Dashboard
Click on Applications > Applications > Create Application
Enter a name for your app (e.g., Ionic Angular App), select Native as the application type, and click Create
Switch to the Settings tab and note your Domain and Client ID values
Replace YOUR_AUTH0_APP_DOMAIN and YOUR_AUTH0_APP_CLIENT_ID in src/environments/environment.ts with your values

Throughout this quickstart, YOUR_PACKAGE_ID refers to the appId field in your capacitor.config.ts. The default value is io.ionic.starter. See Capacitor’s Config schema for more info.

Configure the following URLs on the Settings tab (replace YOUR_PACKAGE_ID with your actual package ID):Allowed Callback URLs:

YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback

Allowed Logout URLs:

YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback

Allowed Origins:

capacitor://localhost, http://localhost

Allowed Callback URLs are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail.Allowed Logout URLs are essential for providing a seamless user experience upon signing out. Without a matching URL, users will receive an error when logging out.Allowed Origins are required for silent authentication. The capacitor://localhost origin is for iOS and http://localhost is for Android.

Configure the Auth0 module

With your environment file in place from the previous step, configure the Auth0 module in your app:

src/main.ts

import { bootstrapApplication } from '@angular/platform-browser';
import { RouteReuseStrategy, provideRouter } from '@angular/router';
import { IonicRouteStrategy, provideIonicAngular } from '@ionic/angular/standalone';
import { provideAuth0 } from '@auth0/auth0-angular';
import { environment } from './environments/environment';
import config from '../capacitor.config';
import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';

const redirect_uri = `${config.appId}://${environment.auth0.domain}/capacitor/${config.appId}/callback`;

bootstrapApplication(AppComponent, {
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular(),
    provideRouter(routes),
    provideAuth0({
      domain: environment.auth0.domain,
      clientId: environment.auth0.clientId,
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri,
      },
    }),
  ],
});

The provideAuth0 configuration includes:

useRefreshTokens: true — required for mobile. Capacitor apps cannot use iframe-based silent authentication, so refresh tokens are used to renew sessions.
useRefreshTokensFallback: false — required for mobile. Prevents the SDK from falling back to iframe-based silent auth, which is unavailable in native apps.
authorizationParams.redirect_uri — uses your app’s custom URL scheme to redirect back after authentication.

To persist authentication after closing and reopening the application, you may want to set cacheLocation to localstorage, but please be aware of the risks of storing tokens in localstorage. Also, localstorage should be treated as transient in Capacitor apps. Please read the guidance on storage in the Capacitor docs.

Create Login, Logout and Profile components

Create the component files

touch src/app/login-button.component.ts && touch src/app/logout-button.component.ts && touch src/app/profile.component.ts

Add the following code to each component:Now update the App Component to handle Auth0 callbacks, and the home page to use your components:

App Component
Home Page

Replace the contents of src/app/app.component.ts:

src/app/app.component.ts

import { Component, OnInit, NgZone, inject } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { mergeMap } from 'rxjs/operators';
import { Browser } from '@capacitor/browser';
import { App } from '@capacitor/app';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
import { environment } from '../environments/environment';
import config from '../../capacitor.config';

const callbackUri = `${config.appId}://${environment.auth0.domain}/capacitor/${config.appId}/callback`;

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [IonApp, IonRouterOutlet],
  template: '<ion-app><ion-router-outlet></ion-router-outlet></ion-app>',
})
export class AppComponent implements OnInit {
  private auth = inject(AuthService);
  private ngZone = inject(NgZone);

  ngOnInit(): void {
    App.addListener('appUrlOpen', ({ url }) => {
      this.ngZone.run(() => {
        if (url?.startsWith(callbackUri)) {
          if (
            url.includes('state=') &&
            (url.includes('error=') || url.includes('code='))
          ) {
            this.auth
              .handleRedirectCallback(url)
              .pipe(mergeMap(() => Browser.close()))
              .subscribe();
          } else {
            Browser.close();
          }
        }
      });
    });
  }
}

Replace the contents of src/app/tab1/tab1.page.ts:

src/app/tab1/tab1.page.ts

import { Component, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { AuthService } from '@auth0/auth0-angular';
import {
  IonHeader, IonToolbar, IonTitle, IonContent,
  IonCard, IonCardHeader, IonCardTitle, IonCardContent,
} from '@ionic/angular/standalone';
import { LoginButtonComponent } from '../login-button.component';
import { LogoutButtonComponent } from '../logout-button.component';
import { ProfileComponent } from '../profile.component';

@Component({
  selector: 'app-tab1',
  standalone: true,
  imports: [
    CommonModule,
    IonHeader, IonToolbar, IonTitle, IonContent,
    IonCard, IonCardHeader, IonCardTitle, IonCardContent,
    LoginButtonComponent, LogoutButtonComponent, ProfileComponent,
  ],
  template: `
    <ion-header>
      <ion-toolbar>
        <ion-title>Home</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content class="ion-padding">
      @if (auth.isAuthenticated$ | async) {
        <ion-card>
          <ion-card-header>
            <ion-card-title>Welcome!</ion-card-title>
          </ion-card-header>
          <ion-card-content>
            <app-profile />
            <div class="ion-margin-top">
              <app-logout-button />
            </div>
          </ion-card-content>
        </ion-card>
      } @else {
        <ion-card>
          <ion-card-header>
            <ion-card-title>Get Started</ion-card-title>
          </ion-card-header>
          <ion-card-content>
            <p>Sign in to your account to get started.</p>
            <div class="ion-margin-top">
              <app-login-button />
            </div>
          </ion-card-content>
        </ion-card>
      }
    </ion-content>
  `,
})
export class Tab1Page {
  protected auth = inject(AuthService);
}

The appUrlOpen event callback in the App Component is wrapped in this.ngZone.run(). This is required because Capacitor plugin callbacks execute outside Angular’s zone, and without it Angular won’t detect the auth state changes after login. See Using Angular with Capacitor for details.

Run your app

ionic serve

If port 8100 is in use, run: ionic serve --port 8101. When testing on a device, build first with ionic build && npx cap sync && npx cap open ios (or android). Make sure your custom URL scheme is registered (see Advanced Usage below).

CheckpointYou should now have a fully functional Auth0 login page running on your localhost

Advanced Usage

Using Traditional NgModule Approach

If you created your project with --type=angular (instead of --type=angular-standalone) or prefer using NgModules, configure the SDK with AuthModule.forRoot:

src/app/app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouteReuseStrategy } from '@angular/router';
import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
import { AuthModule } from '@auth0/auth0-angular';
import { environment } from '../environments/environment';
import config from '../../capacitor.config';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

const redirect_uri = `${config.appId}://${environment.auth0.domain}/capacitor/${config.appId}/callback`;

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    IonicModule.forRoot(),
    AppRoutingModule,
    AuthModule.forRoot({
      domain: environment.auth0.domain,
      clientId: environment.auth0.clientId,
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri,
      },
    }),
  ],
  providers: [{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
  bootstrap: [AppComponent],
})
export class AppModule {}

When using NgModules, inject AuthService via the constructor (constructor(public auth: AuthService)) instead of inject(). Use *ngIf="auth.user$ | async as user" in templates instead of @if control flow syntax. Components should be declared in the module rather than marked as standalone: true.

Custom URL Scheme Setup

To test authentication on a real device, register your custom URL scheme for each platform.

iOS

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_PACKAGE_ID</string>
    </array>
  </dict>
</array>

Replace YOUR_PACKAGE_ID with your appId from capacitor.config.ts. To learn more, read Defining a Custom URL Scheme.

Android

Add an intent filter to android/app/src/main/AndroidManifest.xml inside the <activity> tag:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="YOUR_PACKAGE_ID" />
</intent-filter>

Replace YOUR_PACKAGE_ID with your appId from capacitor.config.ts. To learn more, read Create Deep Links to App Content.

Build and run on device

ionic build && npx cap sync && npx cap open ios

Or for Android:

ionic build && npx cap sync && npx cap open android

Protecting Routes with AuthGuard

Use the functional guard to protect routes that require authentication:

src/app/app.routes.ts

import { Routes } from '@angular/router';
import { authGuardFn } from '@auth0/auth0-angular';

export const routes: Routes = [
  {
    path: 'tabs',
    loadComponent: () => import('./tabs/tabs.page').then((m) => m.TabsPage),
    children: [
      {
        path: 'tab1',
        loadComponent: () => import('./tab1/tab1.page').then((m) => m.Tab1Page),
      },
      {
        path: 'tab2',
        loadComponent: () => import('./tab2/tab2.page').then((m) => m.Tab2Page),
        canActivate: [authGuardFn],
      },
      {
        path: 'tab3',
        loadComponent: () => import('./tab3/tab3.page').then((m) => m.Tab3Page),
        canActivate: [authGuardFn],
      },
      {
        path: '',
        redirectTo: '/tabs/tab1',
        pathMatch: 'full',
      },
    ],
  },
  {
    path: '',
    redirectTo: '/tabs/tab1',
    pathMatch: 'full',
  },
];

When unauthenticated users navigate to a protected route, authGuardFn automatically redirects them to the Auth0 login page.

Calling Protected APIs

Configure the HTTP interceptor to automatically attach access tokens to API calls:

src/main.ts

import { bootstrapApplication } from '@angular/platform-browser';
import { RouteReuseStrategy, provideRouter } from '@angular/router';
import { IonicRouteStrategy, provideIonicAngular } from '@ionic/angular/standalone';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideAuth0, authHttpInterceptorFn } from '@auth0/auth0-angular';
import { environment } from './environments/environment';
import config from '../capacitor.config';
import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';

const redirect_uri = `${config.appId}://${environment.auth0.domain}/capacitor/${config.appId}/callback`;

bootstrapApplication(AppComponent, {
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular(),
    provideRouter(routes),
    provideAuth0({
      domain: environment.auth0.domain,
      clientId: environment.auth0.clientId,
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri,
        audience: 'YOUR_API_IDENTIFIER',
      },
      httpInterceptor: {
        allowedList: [
          'http://localhost:3001/api/*',
        ],
      },
    }),
    provideHttpClient(
      withInterceptors([authHttpInterceptorFn])
    ),
  ],
});

Then make API calls using Angular’s HttpClient — the interceptor automatically attaches the Bearer token:

src/app/api.service.ts

import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';

@Injectable({ providedIn: 'root' })
export class ApiService {
  private http = inject(HttpClient);

  getData() {
    return this.http.get('http://localhost:3001/api/data');
  }
}

The httpInterceptor.allowedList determines which API endpoints receive access tokens. Include the audience parameter to request an access token for your API. Replace YOUR_API_IDENTIFIER with the identifier from Auth0 Dashboard > APIs.

Common Issues & Solutions

Callback URL mismatch error

Solution: Verify the callback URL in your Auth0 Dashboard matches exactly with the URL constructed in your app. Ensure YOUR_PACKAGE_ID matches the appId field in your capacitor.config.ts.Solution: Ensure the appUrlOpen event callback is wrapped in this.ngZone.run(). Without this, Angular won’t detect the state changes from handleRedirectCallback. See Using Angular with Capacitor.

”PKCE not allowed” error

Fix:

Go to Auth0 Dashboard > Applications > Your Application
Change the Application Type to Native
Set Token Endpoint Authentication Method to None
Save changes and try again

SSO not working on iOS

Capacitor’s Browser plugin uses SFSafariViewController, which does not share cookies with Safari on iOS 11+. If you need SSO, use a compatible plugin that uses ASWebAuthenticationSession.Enable cacheLocation: 'localstorage' in the provideAuth0 configuration to persist tokens across app restarts. Be aware of the security implications and Capacitor storage limitations.

Observable never executes

All AuthService methods return cold Observables. You must call .subscribe() for them to execute. If loginWithRedirect() or logout() appears to do nothing, check that .subscribe() is chained at the end.

Next Steps

Check out the following resources to learn more:

Sample Application — A complete Ionic Angular sample app with Auth0 integration
Auth0 Angular SDK Documentation — Full SDK reference and examples
Auth0 Dashboard — Configure and manage your Auth0 tenant and applications
Auth0 Marketplace — Discover integrations you can enable to extend Auth0’s functionality

Single Page App

Regular Web App

Native/Mobile App

Backend/API

Add Login to Your Ionic Angular with Capacitor Application

Get Started

Advanced Usage

iOS

Android

Build and run on device

Callback URL mismatch error

”PKCE not allowed” error

SSO not working on iOS

Observable never executes

Next Steps

Single Page App

Regular Web App

Native/Mobile App

Backend/API

Documentation Index

​Get Started

​Advanced Usage

​iOS

​Android

​Build and run on device

​Callback URL mismatch error

​Screen does not update after login

​”PKCE not allowed” error

​SSO not working on iOS

​Login works but user stays unauthenticated after app restart

​Observable never executes

​Next Steps

Get Started

Advanced Usage

iOS

Android

Build and run on device

Callback URL mismatch error

Screen does not update after login

”PKCE not allowed” error

SSO not working on iOS

Login works but user stays unauthenticated after app restart

Observable never executes

Next Steps