Ionic SDK
Guide on how to use Authgear in an Ionic project
Last updated
Was this helpful?
Guide on how to use Authgear in an Ionic project
Last updated
Was this helpful?
In this post, you'll learn how to use Authgear with your Ionic project using the Authgear Ionic SDK.
The following are the minimum versions of Android and iOS your native app can target based on the requirement of Capacitor v7:
iOS 14
Android 6 (API level 23)
At the end of this tutorial, we'll build an Ionic app that can do the following:
Allow users to log in to their account on your Authgear project
Allow new users to sign up
Allow signed-in users to view their user info and logout.
The final UI for the app we'll build should look like this:
To follow this guide seamlessly, make sure to have the following:
Node.js installed on your local machine
Android Studio (for building the Android client of your application)
Xcode (for building the iOS client of your application)
Any code editor (VS Code, Sublime, etc)
Follow this guide to add Authgear to your Ionic app in 🕐 10 minutes.
In this part, you'll learn how to configure an Authgear client application that you will use in your Ionic project. You'll do this by performing the following steps in the Authgear Portal.
In your project, navigate to the Applications section then click on Add Application to create a new Authgear application. Enter a name for your application and select Native App as the Application Type. Next, click Save to continue to the configuration page for your new application. Skip the screen that shows you a list of tutorials for different frameworks.
In this step, you'll set up authorized redirect URIs for your application. An authorized redirect URI should be a URI pointing to a page on your Ionic app where you want to redirect users at the end of the authorization flow.
To add a URI, scroll to the URIs section of your application configuration page and enter the URI in the text field. You can click the Add URI button to add additional URIs.
For our example app, add the following URIs:
com.authgear.example.capacitor://host/path
capacitor://localhost
http://localhost:8100/oauth-redirect
https://localhost
Once you're done, click on the Save button.
Now that you have your Authgear application configured, we can proceed with creating the Ionic application that will have all the features stated in our objective earlier.
For this tutorial, we'll be implementing an Ionic app using React.
Before you can create an Ionic project, install the Ionic CLI on your computer by running the following command in Terminal or Command Prompt:
Now create a new Ionic project by running the following command:
After running the above command, follow the wizard to create a new blank project.
Next, open your new project in a code editor and update for appId
in capacitor.config.ts to the following value:
This new value for appId
is the same value we used in the authorized redirect URI earlier.
Run the following command from the root directory of your new Ionic project to preview your blank project on a browser:
Finally, create the Android and iOS projects for your app by running the following commands from your Ionic project's root folder:
First, install the Android and iOS platforms:
Then, create the projects:
In this step, you'll install the Authgear SDK for Ionic (Capacitor) and the Javascript SDK for the web. The web SDK will help you test your application on a web browser.
To install the SDKs, run the following commands in your Terminal or Command Prompt:
Authgear Ionic SDK
Authgear Web SDK
In this step, you'll learn how to configure your Ionic project using the details from your Authgear application configuration.
To get started, open src/pages/Home.tsx in your code editor then import the Authgear SDK by adding the following code to the top of the file:
The above code imports all the components of the Authgear SDK we need for our example app.
Because Ionic apps can run on the web and native mobile platforms, we had to import both Authgear web and Authgear Capacitor SDKs.
Next, add the following constants to Home.tsx just below the last import statements:
Update the values for the constants (CLIENT_ID
, ENDPOINT
) to the correct values from your client application's configuration page in the Authgear Portal.
Now, just below the constants, add this small utility function that will help to check whether your Ionic app is running natively or on a web browser:
Import Capacitor by adding the following to the import section at the top of Home.tsx:
You will use the above function to determine which instance of the Authgear SDK to call based on the current platform a user is on.
Now implement a new AuthenticationScreen
component in Home.tsx by pasting the following code:
Import useState
, useMemo
, useEffect
and useCallback
at the top of Home.tsx:
The above code also implements a sessionState
constant and a delegate to let your app know when a user's session state changes.
Next, add the following configure()
method to the AuthenticationScreen()
component just before the return statement:
The above code configures a new instance of the Authgear SDK using the Client ID and Endpoint for the Authgear client application we created in the first part of this guide.
Next, implement the postConfigure()
method that was called in the configure() method:
The postConfigure()
method checks if the user is already authenticated and calls the fetchUserInfo() method of the Authgear SDK. Calling the fetchUserInfo() method will refresh the user's access token if it is expired.
Now, call the configure() method in useEffect
by adding the following code after the postConfigure()
method:
The above useEffect
will initialize Authgear on page load.
In this step, we'll add the Login button and the UI components we want to show authenticated users.
Add the following code to the <div>
inside the return statement of the AuthenticationScreen
component:
Import IonButton
by adding it to the import for other Ionic components in our app:
Finally, add the <AuthenticationScreen/>
component to the Home component:
Here, we'll implement an authenticate()
method inside the AuthenticationScreen
component we created in the previous step.
To do this, first, add the following code just before the return statement of the AuthenticationScreen()
component:
Calling this authenticate()
method will initialize an authentication flow. The page
parameter can be used to specify whether to start the authentication flow on the login
page or signup
page.
Finally, implement a onClickAuthenticate()
method that will call authenticate
when the Login button is pressed:
Import MouseEvent
:
At this point, the complete code for Home.tsx should look like this:
You should be able to see the Authentication UI after you click on the Login button. However, you can't complete the authentication flow because we're yet to handle the redirect.
At the end of an authentication flow, your users will be redirected to the URL you specified in redirectURI
. In this step, we'll set up the routes and code to process redirects to the URIs.
To handle redirect on web, create a new file OAuthRedirect.tsx in src/pages/ and add the following code to it:
Change the values for CLIENT_ID
and ENDPOINT
in the above code to the correct value from your Authgear application configuration page.
Now open src/App.tsx and create a new route for OAuthRedirect
using the following code:
Remember to import OAuthRedirect
in App.tsx:
To handle redirect in the Android project, add the following code to android/app/src/main/AndroidManifest.xml:
At this point, if you build your project and run it, you should be able to login successfully.
To implement Logout, we'll add a Logout button, an onClick handler, and a method that will call the logout() method of the Authgear SDK.
Add a Logout button to AuthenticationScreen
component just below <p>Welcome user</p>
:
Next, add a logout()
method to AuthenticationScreen
component:
Finally, implement the onClick method in AuthenticationScreen
:
The Authgear SDK offers a fetchUserInfo()
method that can return details such as User ID, email, phone number, and so on about the current user. In this step, we'll demonstrate how to call fetchUserInfo
in our app.
First, add a Fetch User Info button to your AuthenticationScreen
component just below the Logout button:
Next, add a fetchUserInfo()
method to the AuthenticationScreen
component:
Finally, add the method that will handle click on the Fetch User Info button:
Authgear provides a default User Settings page where your users can view details about their profile and change details or security settings like their password.
To allow users to open the settings page from your app, first add a User Settings button to you r AuthenticationScreen
component just below the Fetch User Info button:
Now add an openUserSettings()
method in AuthenticationScreen
component:
Finally, implement the onClick method for the User Settings button:
To deploy your app to a mobile device (for example Android) run the following commands:
First build your project by running:
Then sync the changes to the mobile project using this command:
You can run the project by opening the android
project folder in Android Studio or ios
folder in Xcode.
You can quickly open the project in Android Studio using the following command:
Or run the following command to open your project in Xcode for iOS:
Once your project builds successfully, you can try the Login, Signup, Fetch User Info, and Logout buttons.
An Authgear account. You can sign up for one for free .
First, log in to Authgear Portal at and select an existing project or create a new one.
Save your work and run the command to serve your project on the web or .
Authgear Capacitor SDK makes it easier to use Authgear in your Ionic application. It provides many helpful methods and interfaces for interacting with the Authgear service from your Ionic application. To learn more about the SDK check . Also, check out the complete repo for the Authgear Ionic SDK example app .