Version: 5.0

Getting Started with Auth Connect

Generate the Application

Before we explore the use of Auth Connect, we need to scaffold an application. In this section, we will generate an @ionic/react tabs based application, perform some basic configuration, and add the iOS and Android platforms.

Terminal


_10ionic start getting-started-ac tabs --type=react

Use the Ionic CLI to generate the application.

Terminal


_10ionic start getting-started-ac tabs --type=react
_10cd getting-started-ac

Change directory into the newly generated project.

Terminal

capacitor.config.ts


_12import { CapacitorConfig } from '@capacitor/cli';
_12
_12const config: CapacitorConfig = {
_12  appId: 'io.ionic.gettingstartedac',
_12  appName: 'getting-started-ac',
_12  webDir: 'dist',
_12  server: {
_12    androidScheme: 'https',
_12  },
_12};
_12
_12export default config;

Change the appId to be something unique. The appId is used as the bundle ID / application ID. Therefore it should be a string that is unique to your organization and application. We will use io.ionic.gettingstartedac for this application.

It is best to do this before adding the iOS and Android platforms to ensure they are setup properly from the start.

Terminal

capacitor.config.ts


_10ionic start getting-started-ac tabs --type=react
_10cd getting-started-ac
_10npm run build
_10ionic cap add android
_10ionic cap add ios

Build the application and install the platforms.

Terminal

capacitor.config.ts

package.json


_15{
_15  "name": "getting-started-ac",
_15  "version": "0.0.1",
_15  "author": "Ionic Framework",
_15  "homepage": "https://ionicframework.com/",
_15  "scripts": {
_15    "dev": "vite",
_15    "build": "tsc && vite build && cap sync",
_15    "preview": "vite preview",
_15    "test.e2e": "cypress run",
_15    "test.unit": "vitest",
_15    "lint": "eslint"
_15  },
_15  ...
_15}

We should do a cap sync with each build. This ensures our native projects remain up to date. Change the scripts in package.json to do this.

Terminal

capacitor.config.ts

package.json

vite.config.ts


_16import legacy from '@vitejs/plugin-legacy';
_16import react from '@vitejs/plugin-react';
_16import { defineConfig } from 'vite';
_16
_16// https://vitejs.dev/config/
_16export default defineConfig({
_16  plugins: [react(), legacy()],
_16  server: {
_16    port: 8100,
_16  },
_16  test: {
_16    globals: true,
_16    environment: 'jsdom',
_16    setupFiles: './src/setupTests.ts',
_16  },
_16});

Modify the vite.config.ts file to ensure that the development server (npm run dev) uses port 8100.

Use the Ionic CLI to generate the application.

Change directory into the newly generated project.

It is best to do this before adding the iOS and Android platforms to ensure they are setup properly from the start.

Build the application and install the platforms.

We should do a cap sync with each build. This ensures our native projects remain up to date. Change the scripts in package.json to do this.

Modify the vite.config.ts file to ensure that the development server (npm run dev) uses port 8100.

Terminal


_10ionic start getting-started-ac tabs --type=react

Install Auth Connect

In order to install Auth Connect, you will need to use ionic enterprise register to register your product key. This will create a .npmrc file containing the product key.

If you have already performed that step for your production application, you can just copy the .npmrc file from your production project. Since this application is for learning purposes only, you don't need to obtain another key.

You can now install Auth Connect and sync the platforms:

Terminal


_10npm install @ionic-enterprise/auth
_10npx cap sync

Create the "Session Store"

When using Auth Connect, the current session is defined by the current AuthResult which contains auth tokens as well as other session information. Auth Connect returns an AuthResult from the login() function. We will need a place to store that result. Let's create that now. Create a src/util directory, then create a file called src/util/session-store.ts.

Note: React allows for many different state management strategies. Your strategy may differ significantly. State management strategies are outside the scope of this tutorial. Use code that aligns with your chosen strategy.

src/utils/session-store.ts


_10import { AuthResult } from '@ionic-enterprise/auth';
_10
_10let session: AuthResult | null = null;

We know we will need to store the session, and that the session is defined by the AuthResult.

src/utils/session-store.ts


_11import { AuthResult } from '@ionic-enterprise/auth';
_11
_11let session: AuthResult | null = null;
_11let listeners: any[] = [];
_11
_11const subscribe = (listener: any) => {
_11  listeners = [...listeners, listener];
_11  return () => {
_11    listeners = listeners.filter((l) => l !== listener);
_11  };
_11};

To sync the store with React, we will eventually use useSyncExternalHook. In preparation, we need some boilerplate code starting with a subscribe() method.

src/utils/session-store.ts


_15import { AuthResult } from '@ionic-enterprise/auth';
_15
_15let session: AuthResult | null = null;
_15let listeners: any[] = [];
_15
_15const subscribe = (listener: any) => {
_15  listeners = [...listeners, listener];
_15  return () => {
_15    listeners = listeners.filter((l) => l !== listener);
_15  };
_15};
_15
_15const getSnapshot = (): AuthResult | null => {
_15  return session;
_15};

Add a getSnapshot() function that just returns the current session.

src/utils/session-store.ts


_21import { AuthResult } from '@ionic-enterprise/auth';
_21
_21let session: AuthResult | null = null;
_21let listeners: any[] = [];
_21
_21const subscribe = (listener: any) => {
_21  listeners = [...listeners, listener];
_21  return () => {
_21    listeners = listeners.filter((l) => l !== listener);
_21  };
_21};
_21
_21const getSnapshot = (): AuthResult | null => {
_21  return session;
_21};
_21
_21const emitChange = () => {
_21  for (let listener of listeners) {
_21    listener();
_21  }
_21};

When the session changes, we need to inform any subscribed listeners.

src/utils/session-store.ts


_26import { AuthResult } from '@ionic-enterprise/auth';
_26
_26let session: AuthResult | null = null;
_26let listeners: any[] = [];
_26
_26const subscribe = (listener: any) => {
_26  listeners = [...listeners, listener];
_26  return () => {
_26    listeners = listeners.filter((l) => l !== listener);
_26  };
_26};
_26
_26const getSnapshot = (): AuthResult | null => {
_26  return session;
_26};
_26
_26const emitChange = () => {
_26  for (let listener of listeners) {
_26    listener();
_26  }
_26};
_26
_26const setSession = (newSession: AuthResult | null) => {
_26  session = newSession;
_26  emitChange();
_26};

We need a function that we can use to set the session. For now, this is the only function that changes the session and emits the change.

src/utils/session-store.ts


_28import { AuthResult } from '@ionic-enterprise/auth';
_28
_28let session: AuthResult | null = null;
_28let listeners: any[] = [];
_28
_28const subscribe = (listener: any) => {
_28  listeners = [...listeners, listener];
_28  return () => {
_28    listeners = listeners.filter((l) => l !== listener);
_28  };
_28};
_28
_28const getSnapshot = (): AuthResult | null => {
_28  return session;
_28};
_28
_28const emitChange = () => {
_28  for (let listener of listeners) {
_28    listener();
_28  }
_28};
_28
_28const setSession = (newSession: AuthResult | null) => {
_28  session = newSession;
_28  emitChange();
_28};
_28
_28export { subscribe, getSnapshot, setSession };

Export the functions that will need to be used elsewhere in our application.

We know we will need to store the session, and that the session is defined by the AuthResult.

To sync the store with React, we will eventually use useSyncExternalHook. In preparation, we need some boilerplate code starting with a subscribe() method.

Add a getSnapshot() function that just returns the current session.

When the session changes, we need to inform any subscribed listeners.

We need a function that we can use to set the session. For now, this is the only function that changes the session and emits the change.

Export the functions that will need to be used elsewhere in our application.

src/utils/session-store.ts


_10import { AuthResult } from '@ionic-enterprise/auth';
_10
_10let session: AuthResult | null = null;

Create the `Authentication` Utility Functions

All interaction with Auth Connect will be abstracted into a set of functions in an authentication utility module. Create an empty src/utils/authentication.ts file.

Setup and Initialization

Before we use Auth Connect, we need to make sure that it is properly set up and initialized. We will build a utility function to perform the setup and initialization required by Auth Connect.

src/utils/authentication.ts


_10import { Capacitor } from '@capacitor/core';
_10
_10const isNative = Capacitor.isNativePlatform();

Auth Connect needs a slightly different configuration between mobile and web, so we need to know in which context we are currently running.

src/utils/authentication.ts


_10import { Capacitor } from '@capacitor/core';
_10import { Auth0Provider } from '@ionic-enterprise/auth';
_10
_10const isNative = Capacitor.isNativePlatform();
_10const provider = new Auth0Provider();

For this tutorial, we are using Auth0 as the authentication vendor. We need to create an Auth0Provider to help Auth Connect with the communication with Auth0.

src/utils/authentication.ts


_19import { Capacitor } from '@capacitor/core';
_19import { Auth0Provider, ProviderOptions } from '@ionic-enterprise/auth';
_19
_19const isNative = Capacitor.isNativePlatform();
_19const provider = new Auth0Provider();
_19
_19const authOptions: ProviderOptions = {
_19  audience: 'https://io.ionic.demo.ac',
_19  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_19  discoveryUrl:
_19    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_19  logoutUrl: isNative
_19    ? 'io.ionic.acdemo://auth-action-complete'
_19    : 'http://localhost:8100/auth-action-complete',
_19  redirectUri: isNative
_19    ? 'io.ionic.acdemo://auth-action-complete'
_19    : 'http://localhost:8100/auth-action-complete',
_19  scope: 'openid offline_access email picture profile',
_19};

Auth Connect needs to know how to communicate with our authentication vendor. You will likely need to get this information from the team that manages your cloud infrastructure.

src/utils/authentication.ts


_32import { Capacitor } from '@capacitor/core';
_32import {
_32  Auth0Provider,
_32  AuthConnect,
_32  ProviderOptions,
_32} from '@ionic-enterprise/auth';
_32
_32const isNative = Capacitor.isNativePlatform();
_32const provider = new Auth0Provider();
_32
_32const authOptions: ProviderOptions = {
_32  audience: 'https://io.ionic.demo.ac',
_32  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_32  discoveryUrl:
_32    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_32  logoutUrl: isNative
_32    ? 'io.ionic.acdemo://auth-action-complete'
_32    : 'http://localhost:8100/auth-action-complete',
_32  redirectUri: isNative
_32    ? 'io.ionic.acdemo://auth-action-complete'
_32    : 'http://localhost:8100/auth-action-complete',
_32  scope: 'openid offline_access email picture profile',
_32};
_32
_32const setupAuthConnect = async (): Promise<void> => {
_32  return AuthConnect.setup({
_32    platform: isNative ? 'capacitor' : 'web',
_32    logLevel: 'DEBUG',
_32    ios: { webView: 'private' },
_32    web: { uiMode: 'popup', authFlow: 'PKCE' },
_32  });
_32};

We need to perform a one-time setup with Auth Connect. Please refer to the documentation if you have any questions about the individual properties. We will start here with a simple set up that is good for development.

The utility module needs to return the setupAuthConnect function. It will be called elsewhere.

src/utils/authentication.ts


_34import { Capacitor } from '@capacitor/core';
_34import {
_34  Auth0Provider,
_34  AuthConnect,
_34  ProviderOptions,
_34} from '@ionic-enterprise/auth';
_34
_34const isNative = Capacitor.isNativePlatform();
_34const provider = new Auth0Provider();
_34
_34const authOptions: ProviderOptions = {
_34  audience: 'https://io.ionic.demo.ac',
_34  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_34  discoveryUrl:
_34    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_34  logoutUrl: isNative
_34    ? 'io.ionic.acdemo://auth-action-complete'
_34    : 'http://localhost:8100/auth-action-complete',
_34  redirectUri: isNative
_34    ? 'io.ionic.acdemo://auth-action-complete'
_34    : 'http://localhost:8100/auth-action-complete',
_34  scope: 'openid offline_access email picture profile',
_34};
_34
_34const setupAuthConnect = async (): Promise<void> => {
_34  return AuthConnect.setup({
_34    platform: isNative ? 'capacitor' : 'web',
_34    logLevel: 'DEBUG',
_34    ios: { webView: 'private' },
_34    web: { uiMode: 'popup', authFlow: 'PKCE' },
_34  });
_34};
_34
_34export { setupAuthConnect };

The utility module needs to return the setupAuthConnect function. It will be called elsewhere.

Auth Connect needs a slightly different configuration between mobile and web, so we need to know in which context we are currently running.

For this tutorial, we are using Auth0 as the authentication vendor. We need to create an Auth0Provider to help Auth Connect with the communication with Auth0.

Auth Connect needs to know how to communicate with our authentication vendor. You will likely need to get this information from the team that manages your cloud infrastructure.

The utility module needs to return the setupAuthConnect function. It will be called elsewhere.

src/utils/authentication.ts


_10import { Capacitor } from '@capacitor/core';
_10
_10const isNative = Capacitor.isNativePlatform();

We need to create login() and logout() functions.

src/utils/authentication.ts


_35import { Capacitor } from '@capacitor/core';
_35import {
_35  Auth0Provider,
_35  AuthConnect,
_35  ProviderOptions,
_35} from '@ionic-enterprise/auth';
_35import { getSnapshot, setSession } from './session-store';
_35
_35const isNative = Capacitor.isNativePlatform();
_35const provider = new Auth0Provider();
_35
_35const authOptions: ProviderOptions = {
_35  audience: 'https://io.ionic.demo.ac',
_35  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_35  discoveryUrl:
_35    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_35  logoutUrl: isNative
_35    ? 'io.ionic.acdemo://auth-action-complete'
_35    : 'http://localhost:8100/auth-action-complete',
_35  redirectUri: isNative
_35    ? 'io.ionic.acdemo://auth-action-complete'
_35    : 'http://localhost:8100/auth-action-complete',
_35  scope: 'openid offline_access email picture profile',
_35};
_35
_35const setupAuthConnect = async (): Promise<void> => {
_35  return AuthConnect.setup({
_35    platform: isNative ? 'capacitor' : 'web',
_35    logLevel: 'DEBUG',
_35    ios: { webView: 'private' },
_35    web: { uiMode: 'popup', authFlow: 'PKCE' },
_35  });
_35};
_35
_35export { setupAuthConnect };

Import the functions from our session store that are used to get and set the session.

src/utils/authentication.ts


_40import { Capacitor } from '@capacitor/core';
_40import {
_40  Auth0Provider,
_40  AuthConnect,
_40  ProviderOptions,
_40} from '@ionic-enterprise/auth';
_40import { getSnapshot, setSession } from './session-store';
_40
_40const isNative = Capacitor.isNativePlatform();
_40const provider = new Auth0Provider();
_40
_40const authOptions: ProviderOptions = {
_40  audience: 'https://io.ionic.demo.ac',
_40  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_40  discoveryUrl:
_40    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_40  logoutUrl: isNative
_40    ? 'io.ionic.acdemo://auth-action-complete'
_40    : 'http://localhost:8100/auth-action-complete',
_40  redirectUri: isNative
_40    ? 'io.ionic.acdemo://auth-action-complete'
_40    : 'http://localhost:8100/auth-action-complete',
_40  scope: 'openid offline_access email picture profile',
_40};
_40
_40const setupAuthConnect = async (): Promise<void> => {
_40  return AuthConnect.setup({
_40    platform: isNative ? 'capacitor' : 'web',
_40    logLevel: 'DEBUG',
_40    ios: { webView: 'private' },
_40    web: { uiMode: 'popup', authFlow: 'PKCE' },
_40  });
_40};
_40
_40const login = async (): Promise<void> => {
_40  const authResult = await AuthConnect.login(provider, authOptions);
_40  setSession(authResult);
_40};
_40
_40export { login, setupAuthConnect };

For the login(), we need to pass both the provider and the authOptions we established earlier. It returns an AuthResult that we need to store. Be sure to export the function so we can use it in the rest of our app.

src/utils/authentication.ts


_49import { Capacitor } from '@capacitor/core';
_49import {
_49  Auth0Provider,
_49  AuthConnect,
_49  ProviderOptions,
_49} from '@ionic-enterprise/auth';
_49import { getSnapshot, setSession } from './session-store';
_49
_49const isNative = Capacitor.isNativePlatform();
_49const provider = new Auth0Provider();
_49let authResult: AuthResult | null = null;
_49
_49const authOptions: ProviderOptions = {
_49  audience: 'https://io.ionic.demo.ac',
_49  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_49  discoveryUrl:
_49    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_49  logoutUrl: isNative
_49    ? 'io.ionic.acdemo://auth-action-complete'
_49    : 'http://localhost:8100/auth-action-complete',
_49  redirectUri: isNative
_49    ? 'io.ionic.acdemo://auth-action-complete'
_49    : 'http://localhost:8100/auth-action-complete',
_49  scope: 'openid offline_access email picture profile',
_49};
_49
_49const setupAuthConnect = async (): Promise<void> => {
_49  return AuthConnect.setup({
_49    platform: isNative ? 'capacitor' : 'web',
_49    logLevel: 'DEBUG',
_49    ios: { webView: 'private' },
_49    web: { uiMode: 'popup', authFlow: 'PKCE' },
_49  });
_49};
_49
_49const login = async (): Promise<void> => {
_49  const authResult = await AuthConnect.login(provider, authOptions);
_49  setSession(authResult);
_49};
_49
_49const logout = async (): Promise<void> => {
_49  const authResult = getSnapshot();
_49  if (authResult) {
_49    await AuthConnect.logout(provider, authResult);
_49    setSession(null);
_49  }
_49};
_49
_49export { login, logout, setupAuthConnect };

For the logout(), when calling Auth Connect we need to pass the provider as well as the AuthResult we established with the login(). If the logout succeeds, the session needs to be cleared.

Import the functions from our session store that are used to get and set the session.

For the logout(), when calling Auth Connect we need to pass the provider as well as the AuthResult we established with the login(). If the logout succeeds, the session needs to be cleared.

src/utils/authentication.ts


_35import { Capacitor } from '@capacitor/core';
_35import {
_35  Auth0Provider,
_35  AuthConnect,
_35  ProviderOptions,
_35} from '@ionic-enterprise/auth';
_35import { getSnapshot, setSession } from './session-store';
_35
_35const isNative = Capacitor.isNativePlatform();
_35const provider = new Auth0Provider();
_35
_35const authOptions: ProviderOptions = {
_35  audience: 'https://io.ionic.demo.ac',
_35  clientId: 'yLasZNUGkZ19DGEjTmAITBfGXzqbvd00',
_35  discoveryUrl:
_35    'https://dev-2uspt-sz.us.auth0.com/.well-known/openid-configuration',
_35  logoutUrl: isNative
_35    ? 'io.ionic.acdemo://auth-action-complete'
_35    : 'http://localhost:8100/auth-action-complete',
_35  redirectUri: isNative
_35    ? 'io.ionic.acdemo://auth-action-complete'
_35    : 'http://localhost:8100/auth-action-complete',
_35  scope: 'openid offline_access email picture profile',
_35};
_35
_35const setupAuthConnect = async (): Promise<void> => {
_35  return AuthConnect.setup({
_35    platform: isNative ? 'capacitor' : 'web',
_35    logLevel: 'DEBUG',
_35    ios: { webView: 'private' },
_35    web: { uiMode: 'popup', authFlow: 'PKCE' },
_35  });
_35};
_35
_35export { setupAuthConnect };

Handling the Authentication Flow

Now that the utility functions are complete, we will use them to implement the authentication flow of our application. To do this, we will need to:

Create the AuthActionCompletePage and route that is used in our configuration.
Expose the authentication state to our application via the creation of an AuthenticationProvider.
Add buttons to the Tab1 page that will be used to perform the login() and logout() operations.

Create the `AuthActionCompletePage`

The logoutUrl and redirectUri properties are using the /auth-action-complete route. Create a page for the route. The page does not have to do much. We will just display a spinner in case someone sees it momentarily.

src/pages/AuthActionCompletePage.tsx


_13import { IonContent, IonPage, IonSpinner } from '@ionic/react';
_13import './AuthActionCompletePage.css';
_13
_13const AuthActionCompletePage: React.FC = () => (
_13  <IonPage>
_13    <IonContent className="main-content auth-action-complete">
_13      <div className="container">
_13        <IonSpinner name="dots" />
_13      </div>
_13    </IonContent>
_13  </IonPage>
_13);
_13export default AuthActionCompletePage;

We will perform a small bit of styling to make the page look nice.

src/pages/AuthActionCompletePage.css


_10.auth-action-complete .container {
_10  text-align: center;
_10  position: absolute;
_10  left: 0;
_10  right: 0;
_10  top: 50%;
_10  transform: translateY(-50%);
_10}

Be sure to add the route in the router setup. In a production app, this likely would not be put within the IonTabs structure. Refactoring the routing, however, to avoid this is beyond the scope of this tutorial.

src/App.tsx


_80import { Redirect, Route } from 'react-router-dom';
_80import {
_80  IonApp,
_80  IonIcon,
_80  IonLabel,
_80  IonRouterOutlet,
_80  IonTabBar,
_80  IonTabButton,
_80  IonTabs,
_80  setupIonicReact,
_80} from '@ionic/react';
_80import { IonReactRouter } from '@ionic/react-router';
_80import { ellipse, square, triangle } from 'ionicons/icons';
_80import AuthActionCompletePage from './pages/AuthActionCompletePage';
_80import Tab1 from './pages/Tab1';
_80import Tab2 from './pages/Tab2';
_80import Tab3 from './pages/Tab3';
_80
_80/* Core CSS required for Ionic components to work properly */
_80import '@ionic/react/css/core.css';
_80
_80/* Basic CSS for apps built with Ionic */
_80import '@ionic/react/css/normalize.css';
_80import '@ionic/react/css/structure.css';
_80import '@ionic/react/css/typography.css';
_80
_80/* Optional CSS utils that can be commented out */
_80import '@ionic/react/css/padding.css';
_80import '@ionic/react/css/float-elements.css';
_80import '@ionic/react/css/text-alignment.css';
_80import '@ionic/react/css/text-transformation.css';
_80import '@ionic/react/css/flex-utils.css';
_80import '@ionic/react/css/display.css';
_80
_80/* Theme variables */
_80import './theme/variables.css';
_80
_80setupIonicReact();
_80
_80const App: React.FC = () => (
_80  <IonApp>
_80    <IonReactRouter>
_80      <IonTabs>
_80        <IonRouterOutlet>
_80          <Route exact path="/tab1">
_80            <Tab1 />
_80          </Route>
_80          <Route exact path="/tab2">
_80            <Tab2 />
_80          </Route>
_80          <Route path="/tab3">
_80            <Tab3 />
_80          </Route>
_80          <Route path="/auth-action-complete">
_80            <AuthActionCompletePage />
_80          </Route>
_80          <Route exact path="/">
_80            <Redirect to="/tab1" />
_80          </Route>
_80        </IonRouterOutlet>
_80        <IonTabBar slot="bottom">
_80          <IonTabButton tab="tab1" href="/tab1">
_80            <IonIcon aria-hidden="true" icon={triangle} />
_80            <IonLabel>Tab 1</IonLabel>
_80          </IonTabButton>
_80          <IonTabButton tab="tab2" href="/tab2">
_80            <IonIcon aria-hidden="true" icon={ellipse} />
_80            <IonLabel>Tab 2</IonLabel>
_80          </IonTabButton>
_80          <IonTabButton tab="tab3" href="/tab3">
_80            <IonIcon aria-hidden="true" icon={square} />
_80            <IonLabel>Tab 3</IonLabel>
_80          </IonTabButton>
_80        </IonTabBar>
_80      </IonTabs>
_80    </IonReactRouter>
_80  </IonApp>
_80);
_80
_80export default App;

Create the `AuthenticationProvider`

The Auth Connect related functionality will be exposed to our application via a context provider, which we will now build. Create a src/providers directory containing a file named src/providers/AuthenticationProvider.tsx

src/providers/AuthenticationProvider.tsx


_10import { createContext } from 'react';
_10
_10type Context = {
_10  isAuthenticated: boolean;
_10};
_10
_10export const AuthenticationContext = createContext<Context>({
_10  isAuthenticated: false,
_10});

Start with creating the context we want to provide to the application.

src/providers/AuthenticationProvider.tsx


_21import { PropsWithChildren, createContext, useState } from 'react';
_21
_21type Context = {
_21  isAuthenticated: boolean;
_21};
_21
_21export const AuthenticationContext = createContext<Context>({
_21  isAuthenticated: false,
_21});
_21
_21export const AuthenticationProvider: React.FC<PropsWithChildren> = ({
_21  children,
_21}) => {
_21  const [isAuthenticated, setIsAuthenticated] = useState(false);
_21
_21  return (
_21    <AuthenticationContext.Provider value={{ isAuthenticated }}>
_21      {children}
_21    </AuthenticationContext.Provider>
_21  );
_21};

Create a shell component for the AuthenticationProvider. It needs to render the context we created.

src/providers/AuthenticationProvider.tsx


_28import { IonSpinner } from '@ionic/react';
_28import { PropsWithChildren, createContext, useEffect, useState } from 'react';
_28import { setupAuthConnect } from '../utils/authentication';
_28
_28type Context = {
_28  isAuthenticated: boolean;
_28};
_28
_28export const AuthenticationContext = createContext<Context>({
_28  isAuthenticated: false,
_28});
_28
_28export const AuthenticationProvider: React.FC<PropsWithChildren> = ({
_28  children,
_28}) => {
_28  const [isAuthenticated, setIsAuthenticated] = useState(false);
_28  const [isSetup, setIsSetup] = useState(false);
_28
_28  useEffect(() => {
_28    setupAuthConnect().then(() => setIsSetup(true));
_28  }, []);
_28
_28  return (
_28    <AuthenticationContext.Provider value={{ isAuthenticated }}>
_28      {isSetup ? children : <IonSpinner />}
_28    </AuthenticationContext.Provider>
_28  );
_28};

Initialize AuthConnect. The child components should only be able to interact with AuthConnect after it has completed the initialization process, so display a spinner until this is complete.

src/providers/AuthenticationProvider.tsx


_40import { IonSpinner } from '@ionic/react';
_40import {
_40  PropsWithChildren,
_40  createContext,
_40  useEffect,
_40  useState,
_40  useSyncExternalStore,
_40} from 'react';
_40import { setupAuthConnect } from '../utils/authentication';
_40import { getSnapshot, subscribe } from '../utils/session-store';
_40
_40type Context = {
_40  isAuthenticated: boolean;
_40};
_40
_40export const AuthenticationContext = createContext<Context>({
_40  isAuthenticated: false,
_40});
_40
_40export const AuthenticationProvider: React.FC<PropsWithChildren> = ({
_40  children,
_40}) => {
_40  const [isAuthenticated, setIsAuthenticated] = useState(false);
_40  const [isSetup, setIsSetup] = useState(false);
_40  const session = useSyncExternalStore(subscribe, getSnapshot);
_40
_40  useEffect(() => {
_40    setupAuthConnect().then(() => setIsSetup(true));
_40  }, []);
_40
_40  useEffect(() => {
_40    setIsAuthenticated(!!session);
_40  }, [session]);
_40
_40  return (
_40    <AuthenticationContext.Provider value={{ isAuthenticated }}>
_40      {isSetup ? children : <IonSpinner />}
_40    </AuthenticationContext.Provider>
_40  );
_40};

Get the session value from our session store and update isAuthenticated when its value changes.

Start with creating the context we want to provide to the application.

Create a shell component for the AuthenticationProvider. It needs to render the context we created.

Initialize AuthConnect. The child components should only be able to interact with AuthConnect after it has completed the initialization process, so display a spinner until this is complete.

Get the session value from our session store and update isAuthenticated when its value changes.

src/providers/AuthenticationProvider.tsx


_10import { createContext } from 'react';
_10
_10type Context = {
_10  isAuthenticated: boolean;
_10};
_10
_10export const AuthenticationContext = createContext<Context>({
_10  isAuthenticated: false,
_10});

Now that the AuthenticationProvider has been created, we can add it to our application, which will allow us to perform the login and logout actions. Modify src/App.tsx to surround the bulk of our application with the provider.

src/App.tsx


_83import { Redirect, Route } from 'react-router-dom';
_83import {
_83  IonApp,
_83  IonIcon,
_83  IonLabel,
_83  IonRouterOutlet,
_83  IonTabBar,
_83  IonTabButton,
_83  IonTabs,
_83  setupIonicReact,
_83} from '@ionic/react';
_83import { IonReactRouter } from '@ionic/react-router';
_83import { ellipse, square, triangle } from 'ionicons/icons';
_83import { AuthenticationProvider } from './providers/AuthenticationProvider';
_83import AuthActionCompletePage from './pages/AuthActionCompletePage';
_83import Tab1 from './pages/Tab1';
_83import Tab2 from './pages/Tab2';
_83import Tab3 from './pages/Tab3';
_83
_83/* Core CSS required for Ionic components to work properly */
_83import '@ionic/react/css/core.css';
_83
_83/* Basic CSS for apps built with Ionic */
_83import '@ionic/react/css/normalize.css';
_83import '@ionic/react/css/structure.css';
_83import '@ionic/react/css/typography.css';
_83
_83/* Optional CSS utils that can be commented out */
_83import '@ionic/react/css/padding.css';
_83import '@ionic/react/css/float-elements.css';
_83import '@ionic/react/css/text-alignment.css';
_83import '@ionic/react/css/text-transformation.css';
_83import '@ionic/react/css/flex-utils.css';
_83import '@ionic/react/css/display.css';
_83
_83/* Theme variables */
_83import './theme/variables.css';
_83
_83setupIonicReact();
_83
_83const App: React.FC = () => (
_83  <IonApp>
_83    <AuthenticationProvider>
_83      <IonReactRouter>
_83        <IonTabs>
_83          <IonRouterOutlet>
_83            <Route exact path="/tab1">
_83              <Tab1 />
_83            </Route>
_83            <Route exact path="/tab2">
_83              <Tab2 />
_83            </Route>
_83            <Route path="/tab3">
_83              <Tab3 />
_83            </Route>
_83            <Route path="/auth-action-complete">
_83              <AuthActionCompletePage />
_83            </Route>
_83            <Route exact path="/">
_83              <Redirect to="/tab1" />
_83            </Route>
_83          </IonRouterOutlet>
_83          <IonTabBar slot="bottom">
_83            <IonTabButton tab="tab1" href="/tab1">
_83              <IonIcon aria-hidden="true" icon={triangle} />
_83              <IonLabel>Tab 1</IonLabel>
_83            </IonTabButton>
_83            <IonTabButton tab="tab2" href="/tab2">
_83              <IonIcon aria-hidden="true" icon={ellipse} />
_83              <IonLabel>Tab 2</IonLabel>
_83            </IonTabButton>
_83            <IonTabButton tab="tab3" href="/tab3">
_83              <IonIcon aria-hidden="true" icon={square} />
_83              <IonLabel>Tab 3</IonLabel>
_83            </IonTabButton>
_83          </IonTabBar>
_83        </IonTabs>
_83      </IonReactRouter>
_83    </AuthenticationProvider>
_83  </IonApp>
_83);
_83
_83export default App;

We can use the first tab of our application to test the login() and logout() functions.

src/pages/Tab1.tsx


_31import {
_31  IonContent,
_31  IonHeader,
_31  IonPage,
_31  IonTitle,
_31  IonToolbar,
_31} from '@ionic/react';
_31import ExploreContainer from '../components/ExploreContainer';
_31import './Tab1.css';
_31
_31const Tab1: React.FC = () => {
_31  return (
_31    <IonPage>
_31      <IonHeader>
_31        <IonToolbar>
_31          <IonTitle>Tab 1</IonTitle>
_31        </IonToolbar>
_31      </IonHeader>
_31      <IonContent fullscreen>
_31        <IonHeader collapse="condense">
_31          <IonToolbar>
_31            <IonTitle size="large">Tab 1</IonTitle>
_31          </IonToolbar>
_31        </IonHeader>
_31        <ExploreContainer name="Tab 1 page" />
_31      </IonContent>
_31    </IonPage>
_31  );
_31};
_31
_31export default Tab1;

Currently, the Tab1 page contains the default skeleton code.

src/pages/Tab1.tsx


_35import {
_35  IonContent,
_35  IonHeader,
_35  IonPage,
_35  IonTitle,
_35  IonToolbar,
_35} from '@ionic/react';
_35import { useContext } from 'react';
_35import { AuthenticationContext } from '../providers/AuthenticationProvider';
_35import ExploreContainer from '../components/ExploreContainer';
_35import './Tab1.css';
_35
_35const Tab1: React.FC = () => {
_35  const { isAuthenticated } = useContext(AuthenticationContext);
_35
_35  return (
_35    <IonPage>
_35      <IonHeader>
_35        <IonToolbar>
_35          <IonTitle>Tab 1</IonTitle>
_35        </IonToolbar>
_35      </IonHeader>
_35      <IonContent fullscreen>
_35        <IonHeader collapse="condense">
_35          <IonToolbar>
_35            <IonTitle size="large">Tab 1</IonTitle>
_35          </IonToolbar>
_35        </IonHeader>
_35        <ExploreContainer name="Tab 1 page" />
_35      </IonContent>
_35    </IonPage>
_35  );
_35};
_35
_35export default Tab1;

Use the AuthenticationContext to get the isAuthenticated value.

src/pages/Tab1.tsx


_39import {
_39  IonButton,
_39  IonContent,
_39  IonHeader,
_39  IonPage,
_39  IonTitle,
_39  IonToolbar,
_39} from '@ionic/react';
_39import { useContext } from 'react';
_39import { AuthenticationContext } from '../providers/AuthenticationProvider';
_39import './Tab1.css';
_39
_39const Tab1: React.FC = () => {
_39  const { isAuthenticated } = useContext(AuthenticationContext);
_39
_39  return (
_39    <IonPage>
_39      <IonHeader>
_39        <IonToolbar>
_39          <IonTitle>Tab 1</IonTitle>
_39        </IonToolbar>
_39      </IonHeader>
_39      <IonContent fullscreen>
_39        <IonHeader collapse="condense">
_39          <IonToolbar>
_39            <IonTitle size="large">Tab 1</IonTitle>
_39          </IonToolbar>
_39        </IonHeader>
_39        {isAuthenticated ? (
_39          <IonButton>Logout</IonButton>
_39        ) : (
_39          <IonButton>Login</IonButton>
_39        )}
_39      </IonContent>
_39    </IonPage>
_39  );
_39};
_39
_39export default Tab1;

Replace the ExploreContainer component with a Login or Logout button, depending on the current authentication status.

src/pages/Tab1.tsx


_40import {
_40  IonButton,
_40  IonContent,
_40  IonHeader,
_40  IonPage,
_40  IonTitle,
_40  IonToolbar,
_40} from '@ionic/react';
_40import { useContext } from 'react';
_40import { AuthenticationContext } from '../providers/AuthenticationProvider';
_40import { login, logout } from '../utils/authentication';
_40import './Tab1.css';
_40
_40const Tab1: React.FC = () => {
_40  const { isAuthenticated } = useContext(AuthenticationContext);
_40
_40  return (
_40    <IonPage>
_40      <IonHeader>
_40        <IonToolbar>
_40          <IonTitle>Tab 1</IonTitle>
_40        </IonToolbar>
_40      </IonHeader>
_40      <IonContent fullscreen>
_40        <IonHeader collapse="condense">
_40          <IonToolbar>
_40            <IonTitle size="large">Tab 1</IonTitle>
_40          </IonToolbar>
_40        </IonHeader>
_40        {isAuthenticated ? (
_40          <IonButton onClick={logout}>Logout</IonButton>
_40        ) : (
_40          <IonButton onClick={login}>Login</IonButton>
_40        )}
_40      </IonContent>
_40    </IonPage>
_40  );
_40};
_40
_40export default Tab1;

Perform a login() or logout() on click accordingly.

Currently, the Tab1 page contains the default skeleton code.

Use the AuthenticationContext to get the isAuthenticated value.

Replace the ExploreContainer component with a Login or Logout button, depending on the current authentication status.

Perform a login() or logout() on click accordingly.

src/pages/Tab1.tsx


_31import {
_31  IonContent,
_31  IonHeader,
_31  IonPage,
_31  IonTitle,
_31  IonToolbar,
_31} from '@ionic/react';
_31import ExploreContainer from '../components/ExploreContainer';
_31import './Tab1.css';
_31
_31const Tab1: React.FC = () => {
_31  return (
_31    <IonPage>
_31      <IonHeader>
_31        <IonToolbar>
_31          <IonTitle>Tab 1</IonTitle>
_31        </IonToolbar>
_31      </IonHeader>
_31      <IonContent fullscreen>
_31        <IonHeader collapse="condense">
_31          <IonToolbar>
_31            <IonTitle size="large">Tab 1</IonTitle>
_31          </IonToolbar>
_31        </IonHeader>
_31        <ExploreContainer name="Tab 1 page" />
_31      </IonContent>
_31    </IonPage>
_31  );
_31};
_31
_31export default Tab1;

Test this in the web using the following credentials:

email: test@ionic.io
password: Ion54321

At this point if we press the Login button, a tab should open where we can log in using Auth0. This tab will close after we log in. When we press the logout button a tab will briefly open to perform the logout and then automatically close. The button that is displayed changes based on our current authentication status.

Configure the Native Projects

Login and logout are working in your web browser. Build your application for mobile and try to run them there. You can use an emulator or an actual device for this test.

Terminal


_10npm run build
_10npx cap open android
_10npx cap open ios

On Android, you get an error like this one:


_10Manifest merger failed : Attribute data@scheme at AndroidManifest.xml requires a placeholder substitution but no value for <AUTH_URL_SCHEME> is provided.

On iOS, the application runs, but you get an invalid URL error after successfully logging in on Auth0.

The problem is that on mobile we are deep-linking back into our application using io.ionic.acdemo://auth-action-complete. We have not registered that scheme with the OS so it does not know to deep-link back to our application. We will set that up now.

For Android, modify the android section of the android/app/build.gradle file to include the AUTH_URL_SCHEME:

app/build.gradle


_28apply plugin: 'com.android.application'
_28
_28android {
_28    namespace "io.ionic.gettingstartedac"
_28    compileSdkVersion rootProject.ext.compileSdkVersion
_28    defaultConfig {
_28        applicationId "io.ionic.gettingstartedac"
_28        minSdkVersion rootProject.ext.minSdkVersion
_28        targetSdkVersion rootProject.ext.targetSdkVersion
_28            'AUTH_URL_SCHEME': 'io.ionic.acdemo'

For iOS, add a CFBundleURLTypes section to the ios/App/App/Info.plist file:

App/App/Info.plist


_58<?xml version="1.0" encoding="UTF-8"?>
_58<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
_58<plist version="1.0">
_58  <dict>
_58    <key>CFBundleDevelopmentRegion</key>
_58    <string>en</string>
_58    <key>CFBundleDisplayName</key>
_58    <string>getting-started-ac</string>
_58    <key>CFBundleExecutable</key>
_58          <string>io.ionic.acdemo</string>

Re-run the application from Xcode and Android Studio. You should now be able to perform the authentication properly on the mobile applications.

Persist the `AuthResult`

The user can perform login and logout operations, but if the browser is refreshed, the application loses the AuthResult. This value needs to be persisted between sessions of the application. To fix this, we will modify our session store to use the Preferences plugin to persist the AuthResult. In a production application, we should store the result more securely by using Identity Vault. However, setting up Identity Vault is beyond the scope of this tutorial.

Terminal


_10npm install @capacitor/preferences

Use the @capacitor/preferences in our session store to persist the AuthResult we received when logging in.

src/utils/session-store.ts

src/main.tsx


_28import { AuthResult } from '@ionic-enterprise/auth';
_28
_28let session: AuthResult | null = null;
_28let listeners: any[] = [];
_28
_28const subscribe = (listener: any) => {
_28  listeners = [...listeners, listener];
_28  return () => {
_28    listeners = listeners.filter((l) => l !== listener);
_28  };
_28};
_28
_28const getSnapshot = (): AuthResult | null => {
_28  return session;
_28};
_28
_28const emitChange = () => {
_28  for (let listener of listeners) {
_28    listener();
_28  }
_28};
_28
_28const setSession = (newSession: AuthResult | null) => {
_28  session = newSession;
_28  emitChange();
_28};
_28
_28export { subscribe, getSnapshot, setSession };

Currently, the session information is only stored in the session variable. We will modify our code to store the session information using the Preferences plugin.

src/utils/session-store.ts

src/main.tsx


_29import { AuthResult } from '@ionic-enterprise/auth';
_29import { Preferences } from '@capacitor/preferences';
_29
_29let session: AuthResult | null = null;
_29let listeners: any[] = [];
_29
_29const subscribe = (listener: any) => {
_29  listeners = [...listeners, listener];
_29  return () => {
_29    listeners = listeners.filter((l) => l !== listener);
_29  };
_29};
_29
_29const getSnapshot = (): AuthResult | null => {
_29  return session;
_29};
_29
_29const emitChange = () => {
_29  for (let listener of listeners) {
_29    listener();
_29  }
_29};
_29
_29const setSession = (newSession: AuthResult | null) => {
_29  session = newSession;
_29  emitChange();
_29};
_29
_29export { subscribe, getSnapshot, setSession };

Import the Preferences plugin.

src/utils/session-store.ts

src/main.tsx


_30import { AuthResult } from '@ionic-enterprise/auth';
_30import { Preferences } from '@capacitor/preferences';
_30
_30let session: AuthResult | null = null;
_30let listeners: any[] = [];
_30
_30const subscribe = (listener: any) => {
_30  listeners = [...listeners, listener];
_30  return () => {
_30    listeners = listeners.filter((l) => l !== listener);
_30  };
_30};
_30
_30const getSnapshot = (): AuthResult | null => {
_30  return session;
_30};
_30
_30const emitChange = () => {
_30  for (let listener of listeners) {
_30    listener();
_30  }
_30};
_30
_30const setSession = async (newSession: AuthResult | null) => {
_30  session = newSession;
_30  await Preferences.set({ key: 'session', value: JSON.stringify(newSession) });
_30  emitChange();
_30};
_30
_30export { subscribe, getSnapshot, setSession };

Save the session to Preferences when the session is set.

src/utils/session-store.ts

src/main.tsx


_37import { AuthResult } from '@ionic-enterprise/auth';
_37import { Preferences } from '@capacitor/preferences';
_37
_37let session: AuthResult | null = null;
_37let listeners: any[] = [];
_37
_37const subscribe = (listener: any) => {
_37  listeners = [...listeners, listener];
_37  return () => {
_37    listeners = listeners.filter((l) => l !== listener);
_37  };
_37};
_37
_37const getSnapshot = (): AuthResult | null => {
_37  return session;
_37};
_37
_37const emitChange = () => {
_37  for (let listener of listeners) {
_37    listener();
_37  }
_37};
_37
_37const setSession = async (newSession: AuthResult | null) => {
_37  session = newSession;
_37  await Preferences.set({ key: 'session', value: JSON.stringify(newSession) });
_37  emitChange();
_37};
_37
_37const initialize = async (): Promise<void> => {
_37  const { value } = await Preferences.get({ key: 'session' });
_37  if (value) {
_37    session = JSON.parse(value);
_37  }
_37};
_37
_37export { initialize, subscribe, getSnapshot, setSession };

Create an initialize() function that gets the value from the Preferences plugin.

src/utils/session-store.ts

src/main.tsx


_14import React from 'react';
_14import { createRoot } from 'react-dom/client';
_14import App from './App';
_14import { initialize } from './utils/session-store';
_14
_14const container = document.getElementById('root');
_14const root = createRoot(container!);
_14initialize().then(() =>
_14  root.render(
_14    <React.StrictMode>
_14      <App />
_14    </React.StrictMode>
_14  )
_14);

Ensure the authentication information is initialized before the application is mounted.

Currently, the session information is only stored in the session variable. We will modify our code to store the session information using the Preferences plugin.

Import the Preferences plugin.

Save the session to Preferences when the session is set.

Create an initialize() function that gets the value from the Preferences plugin.

Ensure the authentication information is initialized before the application is mounted.

src/utils/session-store.ts

src/main.tsx


_28import { AuthResult } from '@ionic-enterprise/auth';
_28
_28let session: AuthResult | null = null;
_28let listeners: any[] = [];
_28
_28const subscribe = (listener: any) => {
_28  listeners = [...listeners, listener];
_28  return () => {
_28    listeners = listeners.filter((l) => l !== listener);
_28  };
_28};
_28
_28const getSnapshot = (): AuthResult | null => {
_28  return session;
_28};
_28
_28const emitChange = () => {
_28  for (let listener of listeners) {
_28    listener();
_28  }
_28};
_28
_28const setSession = (newSession: AuthResult | null) => {
_28  session = newSession;
_28  emitChange();
_28};
_28
_28export { subscribe, getSnapshot, setSession };

If the user logs in and either refreshes the browser or restarts the application the authentication state is preserved.

Next Steps

Explore the specific topics that are of interest to you at this time. This application is used as the foundation to build upon as those topics are explored.

Happy coding!! 🤓

Generate the Application​

Install Auth Connect​

Create the "Session Store"​

Create the Authentication Utility Functions​

Setup and Initialization​

Login and Logout​

Handling the Authentication Flow​

Create the AuthActionCompletePage​

Create the AuthenticationProvider​

Hook Up the Login and Logout​

Configure the Native Projects​

Persist the AuthResult​

Next Steps​

Contents

Generate the Application

Install Auth Connect

Create the "Session Store"

Create the `Authentication` Utility Functions

Setup and Initialization

Login and Logout

Handling the Authentication Flow

Create the `AuthActionCompletePage`

Create the `AuthenticationProvider`

Hook Up the Login and Logout

Configure the Native Projects

Persist the `AuthResult`

Next Steps