Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Manage users and their access
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Follow this quickstart tutorial to add authentication to your React application
Authgear helps you add user logins to your React apps. It provides a pre-built login page and user settings page that can accelerate your development process.
After that, we will need to create an Application in the Project Portal.
To create a client application, go to Applications on the left menu bar in the Authgear Portal.
Next, click ⊕Add Application in the top toolbar.
Enter the name of your application, e.g. "MyAwesomeApp", then select Single Page Application as the Application Type. Click the Save button to create the application.
The Authorized Redirect URI is a URL in you application where the user will be redirected to after login with Authgear. In this path, make a finish authentication call to complete the login process.
Go to the URI section of the Authgear client application you just created and add a new Authorized Redirect URI. For this tutorial, add http://localhost:4000/auth-redirect
to Authorize Redirect URIs.
Click Save to keep all client app configuration changes before proceeding to the next steps.
In this section, we'll create a simple React application and connect it to Authgear such that, users of the app will log in, view their user settings, and log out of their account.
Here are some recommended steps to scaffold a React project. You can skip this part if you are adding Authgear to an existing project. See Step 2: Install Authgear SDK to the project in the next section.
Run the following command from your preferred folder to create a new React project with Vite:
Next, run the following commands to open the new project directory and install the dependencies:
In the package.json
file, update the value of dev
field in the script.dev
section to:
This will enable the npm run dev
command run the app in development mode on port 4000.
The file structure in your project should look like this now:
Run npm run dev
now to run the project and you will see the default "Vite + React" page when you open http://localhost:4000
on a web browser.
Run the following command within your React project directory to install the Authgear Web SDK
In src/main.tsx
, import authgear
and call the configure
function to initialize an Authgear instance on application loads.
The Authgear container instance takes endpoint
and clientID
as parameters. They can be obtained from the configuration page for the application created in Setup Application in Authgear. Create a .env
file in the root directory of your project and add your Authgear client application configuration using the following fields:
It is recommended to render the app after configure()
resolves. So by the time the app is rendered, Authgear is ready to use.
Since we want to reference the logged-in state everywhere in the app, let's put the state in a context provider with UserProvider.tsx
in the /src/context
folder.
The UserProvider.tsx
file will have an isLoggedIn
boolean and a setIsLoggedIn
function. The isLoggedIn
boolean state can be auto-updated using the onSessionStateChange
callback. This callback can be stored in delegate
which is in the local SDK container.
Next, we will add an "AuthRedirect" page for handling the authentication result after the user has been authenticated by Authgear.
First, install react-router-dom
using the following command:
Create the AuthRedirect.tsx
component file in the src/
folder.
Call the Authgear finishAuthentication()
function in the Auth Redirect component to send a token back to Authgear server in exchange for an access token and a refresh token. Don't worry about the technical jargons, finishAuthentication()
will do all the hard work for you and save the authentication data.
When the authentication is finished, the isLoggedIn
state from the UserContextProvider will be automatically set to true
. Finally, navigate back to root (/
) which is our Home page.
The final AuthRedirect.tsx
will look like this
Now, we will add a "Home" page. Create a Home.tsx
component file the src/
folder.
Then import Home and AuthRedirect as routes. And Import UserContextProvider and wrap the routes with it.
Your final App.tsx
should look like this:
The file structure should now look like
First, we will import the Authgear dependency and the React Hook that we will use to Home.tsx
. Then add the login button which will call startAuthentication(ConfigureOptions)
through the startLogin
on click callback. This will redirect the user to the login page.
You can now run npm run dev
and you will be redirected to the Authgear Login page when you click the Login button.
The Authgear SDK helps you get the information of the logged-in users easily.
In the last step, the user is successfully logged in, so let's try to print the user ID (sub) of the user on the Home page.
In Home.tsx
, we will add a simple loading splash and a greeting message printing the Sub ID. We will add two conditional elements such that they are only shown when user is logged in. We can also change the login button to show only if the user is not logged in.
Make use of isLoggedIn
from the UserContext
to control the components on the page. Fetch the user info by fetchInfo()
and access its sub
property.
Run the app again, the User ID (sub) of the user should be printed on the Home page.
Now, let's add a Logout button that is displayed when the user is logged in.
In Home.tsx
, we will use conditional elements to show a Logout button only for a user that is currently logged in.
Find the following line in Home.tsx:
Add the following code on a new line just after the above line:
Then, add the logout
callback:
Run the app again, we can now log out by clicking the Logout button.
Authgear provides a built-in UI for the users to set their attributes and change security settings.
Use the openURL
function to open the settings page at <your_app_endpoint>/settings
In Home.tsx
Add a conditional link to the existing elements.
And add the userSetting
callback:
This is the resulting Home.tsx
:
To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers. The Web SDK provides a fetch
function which automatically handles this, or you can get the token with authgear.accessToken
.
You can get the access token through authgear.accessToken
. Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call to refresh the access token only if it is expired. Include the access token into the Authorization header of the application requests.
Follow this 15-minute tutorial to create a simple app using React with the Authgear SDK.
Check out and clone .
To use Authgear's features, you'll need an account and a Project. Sign up for a free account at and create a new Project to get started.
Since in React 18, useEffect will be fired twice in development mode, we need to implement a to stop it from firing twice. We will use an useRef
Hook to stop the user token from being sent twice to the Authgear Endpoint.
Authgear SDK provides the fetch
function for you to call your application server. This fetch
function will include the Authorization header in your application request, and handle the process of refreshing an access token automatically. The authgear.fetch
implements .
A quick guide on getting started with Authgear
Authgear makes it easy to add user authentication and authorization to any application. In this guide, we'll show you how to get started with Authgear in 5 minutes.
After you sign up, you'll see the onboarding screen that will guide you through the process of creating your first Authgear project.
An Authgear project is similar to a container that holds all your users, settings, and client applications. You need an Authgear project before you can start signing users up.
You can create multiple projects under one account based on your needs. When you create multiple projects, each project is isolated from the others. For example, you can create Project 1 for your e-commerce business and Project 2 for a fitness club you organize. Project 1 and Project 2 will not share the same users or settings.
To create an additional project, log in to your Authgear account then click on the "Create Project" button.
Before any integration, you can try out the signup flow for your project from the "Getting Started" page.
You should be greeted with the AuthUI Login/Sign-up page. Use the form to create a new user account under your project.
After logging in from the previous step, you can check out the Pre-Built User Settings Page. This page is the default page where users of your project can edit their profile and manage security settings.
Click on the Edit Profile to edit and view profile attributes such as first name, last name, photo, etc.
Users can manage the identities (email address, phone number, or social media account) linked to their account under the My Account section of the User Settings page.
The Security section of the User Settings page has the following options:
Password: users can change their password from here.
2-step verification: users can click on this option to view and manage 2-step authenticators for their account. The option is only available when you enable 2FA for your project in Authgear Portal > Authentication > 2FA.
Signed-in device: from this page, the user can view browsers and devices that their account is currently signed in on.
To get more from Authgear and use Authgear to add user authentication to your web or mobile application, you should integrate Authgear to your application or website.
Authgear offers multiple options for viewing and managing all users who sign up for your project. These options include:
Authgear Portal
The quickest way to manage your users is from the Authgear Portal. To open the user management page in the Authgear Portal, click on the User Management link in the navigation bar on the left side.
Click on Users to view a list of all the users in your project. Click on a user from the list to view their complete profile and perform administrative operations like modify profile details, suspend/unsuspend user, delete account, etc.
You can also add new users to your project from the User Management page. To do that, click on the Create User button on the right.
Continue to navigate around the Authgear Portal to see all the features and settings available for your project.
You can also check out any of the following guides to learn more about Authgear:
Choose the integration approach based on application type
There are 3 different high-level approaches to integrating Authgear with your applications:
Mobile apps or single-page web applications: The frontend clients integrate with Authgear’s SDKs, which handle full login flow and session management. It’s important to validate the session in your backend server.
Regular Web Applications: Traditional server-side rendered web apps that run on the server can use OIDC protocol to authenticate with Authgear. The application server has full control over the session storage.
Software built by others: Integrate with other OIDC/SAML compatible applications like WordPress, Salesforce for Single Sign-On.
Check out the following guides for your specific framework:
Guides for Frontend JS SDK
Guides for Mobile SDKs
The Authgear Admin API enables comprehensive user management via a GraphQL endpoint for your backend server. The server can perform operations including searching for users, updating user details, deleting user accounts, and disabling user access.
If your application is a traditional web app running on a server, you can leverage the OpenID Connect (OIDC) protocol to authenticate users via Authgear. A wide range of plug-and-play libraries can be found that simplify the integration process. These libraries handle crucial tasks such as authentication requests, session management, and redirecting users back to your application seamlessly.
See the following tutorials for your specific application framework:
The Authgear Admin API enables comprehensive user management via a GraphQL endpoint for your server. The server can perform operations including searching for users, updating user details, deleting user accounts, and disabling user access.
When implementing identity management for your enterprise software, Authgear provides robust single sign-on (SSO) capabilities that seamlessly connect your workforce. Enterprise applications typically support standard authentication protocols like OpenID Connect (OIDC) and Security Assertion Markup Language (SAML)
You need to protect a JavaScript SPA application that runs entirely in a browser
Authgear is a highly adaptable identity-as-a-service (IDaaS) platform for web and mobile applications
Authgear is an authentication & user management solution which makes it very easy for developers to integrate and customize their consumer applications, it includes these features out of the box:
Easy-to-use interfaces for user registration and login, including email, phone, username as login ID, and password, OTP, magic links, etc for authentication.
Support biometric login on mobile, Passkeys, and Multi-Factor Authentication (MFA) such as SMS/email-based verification and authenticator apps with TOTP.
A user management portal, like password resets, account locking, scheduled deletion or anonymization, and user profile management.
Single Sign-On (SSO) provides a single unified experience for your customers to log into multiple web/mobile apps, including Web2Web, Web2App, and App2App SSO.
Session management with Authgear Portals, and a pre-built setting page for users to control concurrent sessions.
Customizable UI with a user-friendly low-code dashboard.
Various security features such as audit logs, brute force protection, smart account lockout, password policy, etc.
Authgear contains the following high-level components:
Auth UI - is the default batteries included UI for login, signup and setting page. You can customize the style via the Portal, including the CSS and HTML of each page.
Features for managing your users via Authgear Portal
If you are developing mobile or desktop applications, choose from one of these SDKs for your platform to get started.
The Authgear Android SDK comes with kotlin support out of the box. In fact, the SDK is written in kotlin!
If you are using kotlin, you can benefit from the suspend function APIs authgear provides. For example, the above authorize example can be written as follows:
Follow this quickstart tutorial to add authentication to your Vue application
Authgear helps you add user logins to your Vue apps. It provides a prebuilt login page and user settings page that accelerate the development.
After that, we will need to create an Application in the Project Portal.
In this step, we'll create an Authgear client application in the Authgear Portal. We'll use the configuration for this application in later steps to connect our Vue application to Authgear.
To create a client application navigate to Applications on the left menu bar in Authgear Portal.
Next, click ⊕Add Application in the top toolbar to open the New Application page.
Input the name of your application, e.g. "MyAwesomeApp" then select Single Page Application as the Application Type.
Click Save to create the application.
On the next screen, you'll see links to tutorials for different frameworks. Click Next to skip to the application configuration page
The Redirect URI is a URL in your application where the user will be redirected to after login with Authgear. In this path, make a finish authentication call to complete the login process.
Scroll to the URI section of the configuration page for the client application you created in the last step. For this tutorial, add http://localhost:4000/auth-redirect
to Authorize Redirect URIs.
Click the Save button to save your changes before you proceed.
In this section, we'll add Authgear to a Vue application and use the Authgear JavaScript SDK to implement the following features:
User Login/Sign-up
Read logged-in user's info
Open User Settings page
End user session using a Logout button
Run the following commands to create a new project:
Create project and move into the project directory:
Install dependencies:
Install Vue router:
As we are using port 4000 for this tutorial, we need to add the port information to the config. In the vite.config.ts
file, modify the file with the following lines:
After doing so, when you run npm run dev
, the server will be running on port 4000.
Home.vue
fileCreate a new file called Home.vue
in the src/components
folder with simply showing Hello World
on the screen. Add the follow code to Home.vue
:
App.vue
fileThe App.vue
file is generated by Vite
already but some sections of it might not be needed for this tutorial. Edit the content of App.vue
to the following:
Some of the files might not be used and thus can be deleted. You can perform the following script to delete these files:
The file structure in your project is now:
Run npm run dev
now to run the project and you will see the default page with the title Vite + Vue
and a "Hello World" message on http://localhost:4000
.
Create a AuthRedirect.vue
file in the src/components
folder with the same content as src/components/Home.vue
at this moment.
Create a file called router.ts
in the src/
folder. We will import Home
and AuthRedirect
component as the route and we will implement these components later. The content of this file will look like this:
Run the following command within your Vue project directory to install the Authgear Web SDK
In src/main.ts
, import authgear
and call the configure
function to initialize an Authgear instance on application loads. We will also import router
and use it to build routes for us. Your main.ts
file should look like this:
Create a .env
file in the root directory of your project and add your Authgear client application configuration using the following fields:
It is recommended to render the app after configure()
resolves. So by the time the app is rendered, Authgear is ready to use.
Since we want to reference the logged-in state everywhere in the app, let's put the state in a context provider with UserProvider.vue
in the /src/contexts
folder.
In UserProvider.vue
, will have a isLoggedIn
boolean value. The isLoggedIn
boolean state can be auto-updated using the onSessionStateChange
callback. This callback can be stored in delegate
which is in the local SDK container.
Next, we will add an "AuthRedirect" page for handling the authentication result after the user has been authenticated by Authgear.
Create the AuthRedirect.vue
component file in the src/components/
folder.
Call the Authgear finishAuthentication()
function in the Auth Redirect component to send a token back to Authgear server in exchange for access token and refresh token. Don't worry about the technical jargons, finishAuthentication()
will do all the hard work for you and and save the authentication data.
When the authentication is finished, the isLoggedIn
state from the UserContextProvider will automatically be set to true
. Finally, navigate back to root (/
) which is our Home page.
The final AuthRedirect.vue
will look like this
As we have already configured the routes in the previous section, we can simply add <router-view />
tag to the App.vue
. We can then Import UserProvider and wrap the router-view
with it.
Your final App.vue
should look like this:
The file structure should now look like
First, we will import the Authgear dependency. Then add the login button which will call startAuthentication(ConfigureOptions)
through startLogin
callback on click. This will redirect the user to the login page.
You can now run npm run dev
and you will be redirected to the Authgear Login page when you click the Login button.
The Authgear SDK helps you get the information of the logged-in users easily.
In the last step, the user is successfully logged in so let's try to print the user ID (sub) of the user in the Home page.
In Home.vue
, we will add a simple Loading splash and a greeting message printing the Sub ID. We will add two conditional elements such that they are only shown when user is logged in. We can also change the login button to show only if the user is not logged in.
Make use of isLoggedIn
from the UserProvider
to control the components on the page. Fetch the user info by fetchInfo()
and access its sub
property.
The Login button can be also rendered conditionally which only visible if the user is not logged in.
Run the app again, the User ID (sub) of the user should be printed on the Home page.
Finally, let's add a Logout button when a user is logged in.
In Home.vue
, we will add the following conditional elements in the template:
And add the logout
callback:
Run the app again, we can now log out by clicking the Logout button.
Authgear provides a built-in UI for the users to set their attributes and change security settings.
Use the open
function to open the settings page at <your_app_endpoint>/settings
In Home.vue
append a conditional link to the logout button section like this:
And add the userSetting
callback:
This is the resulting Home.vue
:
To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers. The Web SDK provides a fetch
function which automatically handles this, or you can get the token with authgear.accessToken
.
You can get the access token through authgear.accessToken
. Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token into the Authorization header of the application request.
Integrate your iOS application with Authgear iOS SDK
This guide provides instructions on integrating Authgear with an iOS app. Supported platforms include:
iOS 11.0 or higher
Follow this guide to add Authgear to your iOS app in 🕐 10 minutes.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an Authgear client application in the project.
Go to Applications on the left menu bar.
Click ⊕Add Application in the top toolbar.
Input the name of your application and select Native App as the application type. Click "Save".
You will see a list of guides that can help you for setting up, then click "Next".
Head back to Authgear Portal, and add com.example.authgeardemo://host/path
as Redirect URI.
Click "Save" button and note the Client ID. and Endpoint for your new client application as you'll use them later in your iOS application. You can also obtain the Client ID again from the Applications list later.
In this step, we'll add user authentication to a simple iOS app using the Authgear iOS SDK and the client application we created in the previous steps.
To follow the steps in this guide seamlessly, you should have the following:
Some knowledge of SwiftUI
For the purpose of this guide, we'll create a new project in Xcode. Skip this step if you're adding Authgear to your existing app.
To create a new project, open Xcode and navigate to File > New > Project. Create your new project with the following details:
Project Name: my_demo_app
choose SwiftUI
as Interface Leave other fields unchanged and proceed to create the project.
The Authgear iOS SDK makes it easy to interact with Authgear services from your iOS project.
To add Authgear SDK to your project, in Xcode navigate to File > Add Package Dependencies and enter https://github.com/authgear/authgear-sdk-ios.git
in the Package URL text field.
Click Add Package to proceed.
On the next screen, select your application under Add to Target then click on Add Package.
Alternatively, if your project uses cocoapods, install the SDK using:
In this step, we'll initialize an instance of the Authgear SDK when the user interface of our app loads.
For our demo app, add the following code to ContentView.swift
First import Authgear iOS SDK:
In struct ContentView: View {}
, initialize an instance of Authgear()
and call the .configure()
method in an .onAppear()
modifier attached to VStack
like this:
Now let's add the Login button and other UI elements for the demo app.
Add the following views to VStack
:
In addition to the Login button, we've included a ProgressView and a block with views we want only logged-in users to see. Create the isLoading
, userId
and loginState
variables that the if-statement and Text view depend on at the top of the class just after private var authgear: Authgear = Authgear(...)
:
Implement a startAuthentication()
method in your ContentView
class that will call the authenticate()
method of the Authgear SDK:
In order to get your app to build at this point, add empty declarations for logout and openUserSettings methods:
The full code for ContentView.swift
at this point should look like this:
Run your app now. When you click on the Login button, you should be redirected to the user authentication page.
Open your project's Info.plist
or project settings UI in Xcode and add the following:
Navigate to Targets > {Your project} > Info and expand the URL Types section.
Add a new URL scheme with the following details:
Identifier: CFBundleURLTypes
URL Schemes: com.example.authgeardemo://host/path
Role: Editor
Now run your app again and try logging in. Because we've set up a redirect URL, Authgear should redirect back to our app correctly.
Implement the logout method that will be executed when the Logout button is clicked by updating the empty logout function we added in the previous step:
Now clicking on the Logout button will call Authgear SDK's logout method and end the current user session.
The Authgear SDK can return the current user's details via the UserInfo object. The authenticate method returns this userInfo object as demonstrated earlier in our app's startAuthentication()
method. You can also call the SDK's .fetchUserInfo()
method to get the UserInfo object.
Add a new getCurrentUser()
method to your ContentView
class:
Now call the new getCurrentUser()
method in the .onAppear()
modifier of the VStack
like this:
Authgear offers a pre-built User Settings page that user's can use to view, and modify their profile attributes and security settings.
Implement the empty openUserSettings()
method we added in the previous step to call the .open()
method of the Authgear SDK:
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users a Login button if they haven't logged in).
The value of sessionState
can be .unknown
, .noSession
or .authenticated
. Initially, the sessionState
is .unknown
. After a call to authgear.configure
, the session state would become .authenticated
if a previous session was found, or .noSession
if such session was not found.
Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token in the Authorization header of your application request.
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
How to use authgear android SDK
This guide provides instructions on integrating Authgear with an Android app. Supported platforms include:
Android 5.0 (API 21) or higher
Follow this guide to add Authgear to your Android app in 🕐 10 minutes.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project.
Go to Applications on the left menu bar.
Click ⊕Add Application in the top toolbar.
Input the name of your application and select Native App as the application type. Click "Save".
You will see a list of guides that can help you for setting up, then click "Next".
Head back to Authgear Portal, and add the URL scheme you have defined as a Redirect URI. For our demo app, add the following URI:
Click "Save" in the top toolbar and note the Client ID as you'll use it later in your Android app. You can also obtain it again from the Applications list later.
In this step, we'll add user authentication to an Android application using the Authgear client application we set up in the previous steps.
To follow along, you need to have the following:
Android Studio installed on your computer
Basic knowledge of Kotlin or Java
For the purpose of this guide, we'll be creating a new simple Android app project. Feel free to skip this step if you are adding Authgear to your existing app.
Open Android Studio and create a new project with the following details:
Select Empty View Activity on the Activity selection screen.
Name: My Dem App
Build configuration language: Groovy DSL
The Authgear Android SDK makes it easier to interact with Authgear endpoints and services from your Android app.
To add the SDK to your app, first, add the jitpack.io
repository to your project by adding the following to your project's settings.gradle
file:
Next, add authgear
in the dependencies
section of your app-level (/app/build.gradle
) build.gradle
. Use $branch-SNAPSHOT
(e.g. main-SNAPSHOT
) for the latest version in a branch or a release tag/git commit hash of the desired version.
To enable Java 8+ API desugaring support for your project, make the following changes to the app-level build.gradle
file.
Add coreLibraryDesugaringEnabled true
to the android
> compileOptions
section:
Then add the coreLibraryDesugaring to the dependencies section:
Sync Gradle to continue.
In this step, we'll initialize Authgear in the onCreate method of our app's MainActivity.kt
class using a member variable. Alternatively, you can initialize Authgear in any class that's the entry point for your app:
First, declare a member variable authgear
like this:
Next, we'll initialize a new instance of the Authgear SDK and call the configure()
method in the onCreate function.
Replace <CLIENT_ID>
and <ENDPOINT>
with the values from the configuration page of your Authgear client application.
The complete code for MainActivity.kt
at this point should look like this:
In this step, we'll add a login button that when the user taps on will open the login/sign-up page.
Open res/layout/activity_main.xml
and delete the default "Hello World!" TextView.
Switch to the code view of activity_main.xml
and add the login button and a TextView inside the root view (ConstraintsLayout).
Also, add the following views to activity_main.xml
to include a Progress Bar, a User Settings button, and a Logout button that will be visible to a logged-in user.
Enable View Binding
Create a binding
member variable in MainActivity.kt
and modify the onCreate()
method as shown below to use view binding in setContentView
:
Create a startLogin()
method in the MainActivity.kt
inside class MainActivity : AppCompatActivity(){}
. This method will call the Authgear SDK's authenticate()
method to start a new authentication flow.
Next, implement the updateUi()
method that was called in startLogin()
. This function will update the Views on the screen when the user's logged-in state changes.
Finally, call the startLogin()
method on click of the Login button by adding an onClickListener in the onCreate() method.
At this point, if you try to run your application on a mobile device or emulator, you should be able to see the authentication UI (login/sign-up page) when you click on the Login button. However, you will be unable to complete authentication at this point because you have not implemented the activity that handles the Redirect URI.
Add the following activity entry to the AndroidManifest.xml
of your app. The intent system would dispatch the redirect URI to OAuthRedirectActivity
and the SDK would handle the rest.
If your Android app is targeting API level 30 or above (Android 11 or above), you need to add a queries
section to AndroidManifest.xml
.
Add a logout()
method to your MainActivity.kt class that will call the Authgear SDK's logout() method and end the current user session.
Finally, add an onClickListener for the Logout button that calls the above logout()
method in the onCreate() method.
Authgear offers a pre-built User Settings page that user's can use to view, modify their profile attributes and security settings.
Add the following openUserSettings()
method to your MainActivity.kt class:
Then add an onClickListener for the User Settings button in the onCreate() method that calls the above openUserSettings() method.
The value of SessionState
can be UNKNOWN
, NO_SESSION
or AUTHENTICATED
. Initially, the sessionState
is UNKNOWN
. After a call to authgear.configure
, the session state would become AUTHENTICATED
if a previous session was found, or NO_SESSION
if such session was not found.
To start using Authgear in your application, create a free Authgear account on .
Now that you have created a project in Authgear, you're ready to integrate Authgear into your applications for your customers/users to sign up and log in. See our documentation for adding Authgear to your application or website for your favourite framework and programming language.
Advanced Settings: contains additional settings. For example, when you enable for your project, users can click on this link to access the Delete Account button.
You can learn more about the User Settings page .
Authgear has official SDKs for integrating Authgear with React, React Native, ionic, Native Android, iOS, and Flutter applications. See the section of Authgear documentation for detailed instructions for each SDK and using other frameworks without the official SDK.
login and sign-up page to match your branding needs using the Design tool
guides on how to .
how to .
Client-side SDKs are designed for developers to quickly implement authentication with Auth UI on your web and mobile applications. After login, it returns the user data for your apps. It can open a hosted for the user to manage their own account. The SDKs manage session token storage automatically and have built-in token ownership protection () against stolen refresh tokens.
After the frontend integration is complete, every request sent from your application to the backend server should include the Authgear session in its header. JWKS should be used to validate the requests and decode user information from the JWT access token. See for details and code examples.
You can to match your branding. can be used to stay notified and add functionality during the authentication process.
For detailed implementation instructions and API capabilities, refer to the guide.
If you wish to use a custom UI instead of the pre-built UI for signup and login, you need to deploy another server and complete the signup/login process using Authentication Flow API. See for in-depth instructions.
You can to match your branding. can be used to stay notified and add functionality during the authentication process.
For detailed implementation instructions and API capabilities, refer to the guide.
If you wish to use a custom UI instead of the pre-built UI for signup and login, you need to deploy another server and complete the signup/login process using Authentication Flow API. See for in-depth instructions.
Zero trust authentication architecture with (OIDC) standard.
Support a wide range of identity providers, such as , , and (AD).
Enable for your users to log into multiple web applications easily.
APIs for further integration and customizations. For example, build your own custom login and sign-up pages from the ground up powered by .
Most importantly, you can with Authgear for free.
Client App SDKs - for developers to quickly implement authentication with Auth UI on your web and mobile applications. Check out for tutorials and API References.
- for developers to implement their own login, signup and reauthenticate UI (e.g. a mobile native view); or to define a customized login, signup and reauth flow.
- for developers to use Authgear with other software that already support OIDC login, you can use Authgear as an OpenID Connect Provider.
- explain the common approach of using Access Token or Cookies (JWT or random string) to authenticate an API or HTTP Requests.
- allow your backend to interact directly with Authgear for user management purpose.
- call external web endpoint or use the hosted type-script to customize the behaviour of Authgear. E.g. blocking certain type of sign up, or call external endpoint for each login.
- Import multiple users from another service to your project.
- Export user data from Authgear into a CSV or file.
- Link an OAuth provider to a user's account without AuthUI.
Authgear Portal - You can configure your projects, manage users, check out , or customize the AuthUI. See the for Authgear Portal.
Analytics Page - View reports of all users and active users over a specific time interval on the .
- Set account Lockout Policy to safeguard a user account from brute-force login attempts.
- Bot protection tools to block automated attackers.
- Learn how to set password strength and how the password strength is calculated.
- Add biometric login to your application.
- Enable 2FA in your Authgear project.
- Allow users to log in without a password using a magic link.
- Set up passkey for your project.
- Allow users to log in to your application using their existing account with a social media site or enterprise login provider.
- Customize the look and feel of AuthUI to match your branding.
- Change the language for display texts.
- Create a new account for a user from Authgear Portal.
- Delete a user account from your project.
- Detailed guide on how to use Roles and Groups.
- Guides on how to view and manage user profile information.
Follow this 15-minute tutorial to create a simple app using Vue with Authgear SDK.
Check out and clone .
You need an Authgear account and a project to use Authgear. Sign up for a free account at and create a Project.
Here are some recommended steps to scaffold a Vue project. You can skip this part if you are adding Authgear to an existing project. See in the next section.
Create the project folder and install the dependencies. We will use as the build tool and the vue-router
package. Also, we will use TypeScript in this tutorial.
The Authgear container instance takes endpoint
and clientID
as parameters. They can be obtained from the application page created in .
Authgear SDK provides the fetch
function for you to call your application server. This fetch
function will include the Authorization header in your application request, and handle the refresh access token automatically. The authgear.fetch
implements .
You can find the full code for the demo app for this tutorial in
Sign up for an Authgear Portal account at . Or you can use your self-deployed Authgear.
Here you'll need to define a custom URI scheme that Authgear will use to redirect users back to your app after authentication. For our example app, this URL Scheme will be com.example.authgeardemo://host/path
. For further instructions on setting up a custom URI scheme in iOS, see the official documentation .
(Latest Version)
Replace "<CLIENT_ID>" and "<AUTHGEAR_ENDPOINT>" with the client ID and endpoint from the configuration page of the client project you .
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the fetchUserInfo
function to obtain the user info, see .
This will make your app refresh the access token and greet users who are already logged in with their sub
(a unique user ID) when the launch the app. You can read other user attributes like email address, phone number, full name, etc. from .
The sessionState
reflects the user logged-in state in the SDK local state. That means even if the sessionState
is .authenticated
, the session may be invalid if it is revoked remotely. Hence, after initializing the Authgear SDK, call fetchUserInfo
to update the sessionState
as soon as it is proper to do so. We demonstrated how to use sessionState
, and fetchUserInfo
, to get a user's true logged-in state and retrieve their UserInfo in .
For detailed documentation on the iOS SDK, visit .
You can find the full code for the demo app for this tutorial in
Sign up for an Authgear Portal account at . Or you can use your self-deployed Authgear.
Define a custom URI scheme that Authgear will use to redirect users back to your app after they have authenticated. The scheme should be based on the package name for your Android app. For the demo app, we'll be creating in this guide the scheme is: com.example.authgeardemo://host/path
. To learn more about setting up a custom URI scheme in Android, see the official documentation .
Replace SNAPSHOT
with the latest version of the Authgear SDK from: . For example, replacing SNAPSHOT with 2024-12-11.0
to use the latest version at the time of writing this.
Learn more about Java 8+ API desugaring support .
The complete content of activity_main.xml
can be found .
Next, set up so that you can easily reference Views in your MainActivity.kt
file. Add the following to your app-level (/app/build.gradle
) build.gradle
file under the android
block to enable view binding:
The updateUi()
method also calls the fetchUserInfo()
method of the Authgear SDK. This will return the of the current user such as their email address, name, etc.
You can use the user's logged-in state to determine whether a user is logged in and display content like their user info and a logout button as we have done in the updateUi()
method in . The SessionState
reflects the user logged-in state in the SDK local state. That means even if the SessionState
is AUTHENTICATED
, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call fetchUserInfo
to update the SessionState
as soon as it is proper to do so.
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI as we did in ). Use the fetchUserInfo
function to obtain the user info, see .
Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token in the Authorization header of your application request. If you are using OKHttp in your project, you can also use the interceptor extension provided by the SDK, see .
To protect your application server from unauthorized access. You will need to .
For detailed documentation on the Flutter SDK, visit
[^1]: For further instruction on setting up custom URI scheme in Android, see [^2]: For more explanation on JWT, see
Get Started
Jump in with Authgear's getting started guides.
How-To Guides
Find a step-by-step guide to take your project to the next level.
Concepts
Learn the basics.
The Authgear Android SDK provides an optional Okhttp
interceptor which handles everything from refreshing the access token to putting the access token in the header.
The extension is included in the SDK. Please refer to the above section for getting the SDK.
Configure OkHttpClient
to use AuthgearInterceptor
as follows:
The client would then include the access token in every request and refresh the access token when necessary before the requests.
Integrate Authgear on the client side in mobile apps without SDK
Authgear is built based on OIDC 2.0 standard, you can integrate it into any application framework without SDK.
Authorization Code Flow with Proof Key for Code Exchange (PKCE)
For public clients like mobile apps and SPAs, PKCE flow should be used. It uses code_challenge_method
& code_challenge
parameters in the authentication requests and the code_verifier parameter in the code exchange step. It ensures that the application that starts the code flow is the same one that finishes it.
This endpoint serves as a JSON document containing the OpenID Connect configuration of your Authgear project. That includes the authorization endpoint, the token endpoint, and the JWKs endpoint. The URL looks like:
To singup or login, redirect the user to the /authorize
endpoint. The URL should look like this:
Code Example
“S256” is supported in code_challenge_method.
The code_verifier
is a string of length between 43 and 128 generated on the client side. It should be unique for each authorization request. The code_challenge
is a SHA-256 hash of the verifier.
The state parameter is optional. Authgear will include the value of the state parameter when redirecting the user back to the client application. Learn more at Use the OAuth 2.0 State Parameter
After login, the user will be redirected to [redirect_uri]?code=[AUTH_CODE]
, the AUTH_CODE
is needed in the next step
See the supported scopes at Supported Scopes
After receiving the AUTH_CODE
in your application, make a POST request to the /token
endpoint.
Include the code_verifier
used for generating the code_challenge
to prove both requests come from the same client.
The response may contain the ID token, the access token and the refresh token depending on the scope
supplied by the previous step.
When the user logs out, revoke the refresh token by making a POST request to the revocation_endpoint
with the refresh token in the body in application/x-www-form-urlencoded
as content-type. The endpoint looks like https://AUTHGEAR_ENDPOINT/oauth2/revoke
, it can be found in OpenID Connect configuration document.
Then clear the access token and refresh token stored locally in your app.
Include the access token in the Authorization headers of the frontend requests to verify your user’s identity. Follow this guide to learn about validating the JWT in your application server Validate JWT in your application server
How to integrate with a Flutter app
This guide provides instructions on integrating Authgear with a Flutter app. Supported platforms include:
Flutter 2.5.0 or higher
Android minimum SDK 30 (Android 11 or later)
Follow this guide to add Authgear to your Flutter app in 🕐 10 minutes.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project.
Go to Applications on the left menu bar.
You will see the "New Application" page or Click ⊕Add Application in the top tool bar.
Input the name of your application and select Native App as the application type. Click "Save".
You will see a list of guides that can help you for setting up, then click "Next".
Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous step.
Click "Save" and note the Client ID. and Endpoint. You can also obtain them from the Applications list later.
In this part of the guide, we'll add user Authentication to a simple demo app using the Authgear Flutter SDK.
The demo app will have a login button that users can click to initiate the authentication flow. It will also include a group of widgets for greeting logged-in users, opening the user settings page, and logout.
Run the following command to create a new Flutter project:
Run the following command from the root directory of your Flutter project to install the Authgear SDK:
First, import Authgear at the top of lib/main.dart
:
Next, create a field variable _authgear
of type Authgear
and an _init()
method in your page's State class:
Replace "<AUTHGEAR_ENDPOINT>" and "<ClIENT_ID>" with the client ID and endpoint for the client application you created earlier.
Finally, override the initState()
method for your State class to call your new _init()
method. This will initiate a new instance of the Authgear SDK that you'll use to perform operations like starting an authentication flow.
In this step, we'll add a login button and other UI widgets to our demo application.
To do that, first, add a _userInfo
field variable to the State class:
Our demo app will use the value of the _userInfo
variable to determine when to show a login button or the group of widgets for logged-in users.
Next, replace the widget in body
attribute of Scaffold
with the following:
Now implement the loggedInUserScreen()
custom widget like this within the State class:
In the next step, we'll implement the _onPressedAuthenticate()
method.
Here we will implement the _onPressedAuthenticate()
method that will be called when a user clicks on the Login button.
Add the following method in the State class:
The above code calls the authenticate()
method of the Authgear SDK. This will start a new authentication flow. Replace the value for the redirectURI argument with the redirect URI you registered in your client application.
Create empty _onPressedSettings()
and _onPressedLogout()
methods in your State class for now so that you can build application:
At this point, the full code for main.dart should look like this:
Checkpoint
At this point, you can save your work and run the following command to test your app on a mobile device or emulator:
When your app runs, you should see the Login button, clicking on it should start a new Authentication. However, you may not be able to complete authentication because we're yet to configure our app to handle redirect from Authgear.
To finish the integration, setup the app to handle the redirectURI specified in the application. This part requires platform specific integration.
Here you declare the URL schemes supported by your app, so the device can redirect the user to the app after authentication using the redirect URI.
Add the following <activity>
entry to the /android/app/src/main/AndroidManifest.xml
of your app. The intent system would dispatch the redirect URI to OAuthRedirectActivity
and the SDK would handle the rest.
You also need to add a queries
section to AndroidManifest.xml
.
Remove the following line from AndroidManifest.xml
because this setting conflicts with the SDK:
Next, open /android/app/build.gradle
and set minSdk
to 30
:
In the Info.plist
in your project's ios
folder, add the matching redirect URI by adding the key CFBundleURLTypes
and the values inside <dict>
as shown as the following example.
Now if you run your app again, you should be able to login, be redirected back to your app and view the group of widgets that's for logged-in users.
To log out the user from the current app session, you need to invoke thelogout
method of the SDK.
Update the empty _onPressedLogout
you added earlier so that it calls the logout
method.
Authgear provides a pre-built user settings page from which your users can view and edit their profile details, and change security settings like password, and 2FA.
The SDK includes a method that you can use to easily open this user settings page.
Update the empty _onPressedSettings
method you added earlier so it initiates the process of opening the user settings page.
At this point, our application already shows the current user's info (their unique ID, sub
). However, the Authgear SDK includes a getUserInfo()
method that you can call explicitly to get an object that contains the current user's information like their email, phone number, name, etc.
Calling this getUserInfo() method can also refresh the current user's access token to make sure that their session state is really authenticated
, that is, an logged-in user is not using an expired access token.
Update your _init()
method to check the user's logged-in state and fetch their user info when the state is SessionState.authenticated
.
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users the login page if they haven't logged in). The sessionState
reflects the user logged in state in the SDK local state. That means even the sessionState
is SessionState.authenticated
, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call fetchUserInfo
to update the sessionState
as soon as it is proper to do so.
The value of sessionState
can be SessionState.unknown
, SessionState.noSession
or SessionState.authenticated
. Initially, the sessionState
is SessionState.unknown
. After a call to authgear.configure
, the session state would become SessionState.authenticated
if a previous session was found, or SessionState.noSession
if such session was not found.
To include the access token to the HTTP requests to your application server, use wrapHttpClient
.
The wrapped client will include the Authorization header in every HTTP request, and refresh access token automatically.
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
How to integrate with a Xamarin app
This guide provides instructions on integrating Authgear with a Xamarin app. Supported packages include:
Xamarin.Essentials 1.7.2 or higher
Xamarin.Forms 5.0.0.2401 or higher
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project.
Open Visual Studio
Create a new project
Choose the Xamarin.Forms template
Authgear.Xamarin targets MonoAndroid 12.0 on Android, and Xamarin.iOS10 on iOS. Update the target framework of the Android and iOS projects to match Authgear.Xamarin's target frameworks.
Update Android and iOS project's Xamarin.Essentials to 1.7.2.
To finish the integration, setup the app to handle the redirectURI specified in the application. This part requires platform specific integration.
If your Android app is targeting API level 30 or above (Android 11 or above), you need to add a queries
section to AndroidManifest.xml
.
In your MainActivity.cs
In your AppDelegate.cs
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users the login page if they haven't logged in). The SessionState
reflects the user logged in state in the SDK locally on the device. That means even the SessionState
is Authenticated
, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call FetchUserInfoAsync
to update the SessionState
as soon as it is proper to do so.
The value of SessionState
can be Unknown
, NoSession
or Authenticated
. Initially, the SessionState
is Unknown
. After a call to authgear.configure
, the session state would become Authenticated
if a previous session was found, or NoSession
if such session was not found.
To log out the user from the current app session, you need to invoke thelogout
function.
To include the access token to the HTTP requests to your application server, you set the bearer token manually by using authgear.AccessToken
.
You can get the access token through authgear.AccessToken
. Call RefreshAccessTokenIfNeededAsync
every time before using the access token, the function will check and make the network call only if the access token has expired. Then, include the access token into the Authorization header of the http request.
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
Authentication for Next.js app with Authgear
You will learn the following throughout the article:
How to add user login, sign-up, and logout to Next.js Applications.
How to create a middleware to protect Next.js application pages.
Before you begin, you'll need the following:
After you created the Authgear app, you choose how users need to authenticate on the login page. From the Authentication tab, navigate to Login Methods, you can choose a login method from various options including, by email, mobile, or social, just using a username or the custom method you specify. For this demo, we choose the Email+Passwordless approach where our users are asked to register an account and log in by using their emails. They will receive a One-time password (OTP) to their emails and verify the code to use the app.
Since you've cloned a working repo, you don't need to follow the next section. If you'd like to understand more about what was done in the demo application, feel free to read them.
If you want to create your own application instead of using our demo project, you can create a new Next.js application by running the command below.
The create-next-app
wizard will ask you a few questions on how to set up your application. Answer them accordingly.
Now, you need to create a file named exactly like [...nextauth].js
in src/pages/api/auth
. First, make the directory and then create a file named [...nextauth].js
in that directory.
In the following code, we made a few config:
We have made id
and name
in the Next Auth session (under callbacks
). You can also add other attributes such as email
, phone_number
, and preferred_username
to the session as well.
To allow components to check whether the current user is logged in, change src/pages/_app.js
to have your application rendered inside a <SessionProvider>
context, as shown below.
Then, you change your home component located at src/pages/index.js
to include the <LoginButton />
component inside <main>
.
In the root directory of your project, add the file .env.local
with the following environment variables:
replace with Authgear app settings values from Part1 such as Issuer
, ClientId
, ClientSecret
.
Start the HTTP server by running the following command.
Click the "Log in" button to be taken to a page with a "Sign in with Authgear" button.
After clicking it, you should be redirected to your Authgear login screen.
After you have authenticated with a one-time password sent to your email, you'll arrive back at your Next.js application home screen, with your email address displayed and a "Log out" button.
This tutorial showed how to quickly implement an end-to-end OpenID Connect flow in Next.js with Authgear. Only simple code is needed, after which protected views are secured with built-in UI login pages.
Traditional web app that runs on the server
Follow this quickstart tutorial to add authentication to your Angular application
Authgear helps you add user logins to your Angular apps. It provides prebuilt login page and user settings page that accelerate the development.
Table of Content
After that, we will need to create an Application in the Project Portal.
Go to Applications on the left menu bar.
Click ⊕Add Application in the top tool bar.
Input the name of your application, e.g. "MyAwesomeApp".
Select Single Page Application as the application type
Click "Save" to create the application
The Redirect URI is a URL in you application where the user will be redirected to after login with Authgear. In this path, make a finish authentication call to complete the login process.
For this tutorial, add http://localhost:4000/auth-redirect
to Authorize Redirect URIs.
The Post Logout Redirect URI is the URL users will be redirected after they have logged out. The URL must be whitelisted.
For this tutorial, add http://localhost:4000/
to Post Logout Redirect URIs.
Save the configuration before next steps.
To install the Angular CLI, open a terminal window and run the following command:
Run the following cli command to create a new workspace and initial app called my-app
with a routing module generated.
In the package.json
file, edit the start
script in the script
section
The start
script run the app in development mode on port 4000 instead of the default one.
app.component.html
fileBy default, the Angular CLI generated an initial application for us, but for simplicity, we recommend to modify some of these files to scratch.
In the src/app/app.component.html
file, remove all the lines and add the following line:
Run npm start
now to run the project and you will see "Hello world" on http://localhost:4000
.
Run the following command within your Angular project directory to install the Authgear Web SDK
In src/app/app.component.ts
, import authgear
and call the configure
function to initialize an Authgear instance on application loads.
It is recommend to render the app after configure()
resolves. So by the time the app is rendered, Authgear is ready to use.
Since we want to reference the logged in state in anywhere of the app, let's put the state in a service with user.service.ts
in the /src/app/services/
folder.
In user.service.ts
, it will have a isLoggedIn
boolean variable. The isLoggedIn
boolean variable can be auto updated using the onSessionStateChange
callback. This callback can be stored in delegate
which is in the local SDK container.
Next, we will add an "auth-redirect" page for handling the authentication result after the user have been authenticated by Authgear.
Create the auth-redirect
component using the following command:
We will inject the router and the UserService to get the use of navigation and the isLoggedIn
state.
Call the Authgear finishAuthentication()
function in the Auth Redirect component to send a token back to Authgear server in exchange for access token and refresh token. Don't worry about the technical jargons, finishAuthentication()
will do all the hard work for you and and save the authentication data.
When the authentication is finished, the isLoggedIn
state from the UserService will automatic set to true
. Finally, navigate back to root (/
) which is our Home page.
The final auth-redirect.component.ts
will look like this
Next, we will add a "Home" page . Create a home
component using the following command:
Then import HomeComponent and AuthRedirectComponent as routes. We can add those routes in the app-routing.module.ts
file:
You can apply those routes in src/app/app.component.html
by replace the lines with the following:
The file structure should now look like
First we will import the Authgear dependency and inject the UserService in home.component.ts
. Then add the startLogin
method which will call startAuthentication(ConfigureOptions)
. This will redirect the user to the login page.
Then you can add a button which will trigger the startLogin
method in home.component.html
:
You can now run npm start
and you will be redirected to the Authgear Login page when you click the Login button.
The Authgear SDK helps you get the information of the logged in users easily.
In the last step, the user is successfully logged in so let's try to print the user ID (sub) of the user in the Home page.
In home
component, we will add a simple Loading splash and a greeting message printing the Sub ID. We will add two conditional elements such that they are only shown when user is logged in. We can also change the login button to show only if the user is not logged in.
Make use of isLoggedIn
from the UserService
to control the components on the page. Fetch the user info by fetchInfo()
and access its sub
property.
In the home.component.html
:
Run the app again, the User ID (sub) of the user should be printed on the Home page.
Finally, let's add an Logout button when user is logged in.
In home.component.html
, we will add a conditional element in the markup:
And add the logout
method:
Run the app again, we can now logout by clicking the logout button.
Authgear provide a built-in UI for the users to set their attributes and change security settings.
Use the open
function to open the setting page at <your_app_endpoint>/settings
In home.component.html
append a conditional link to the logout button section.
And add the userSetting
method:
This the resulting home.component.ts
:
This is the resulting home.component.html:
To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers. The Web SDK provides a fetch
function which automatically handle this, or you can get the token with authgear.accessToken
.
You can get the access token through authgear.accessToken
. Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token into the Authorization header of the application request.
Authentication for Express.JS apps with Authgear and OAuth2
Authgear makes it easy to add user authentication to a regular web app that is not powered by any framework. You can do this by integrating Authgear into your application as an OIDC identity provider.
In this post, you'll learn how to add user authentication to an Express.js application using Authgear.
How to create an Authgear Application.
How to add User Login to an Express app using Authgear.
How to request user info from Authgear.
You'll need the following to follow along with this tutorial:
Node.js Installed
Follow this guide to add user authentication to an Express application using Authgear in 🕐 15-minute.
In this step, we'll create the Authgear client application that we'll use later to connect Authgear to the Express application.
After you log in to Authgear Portal, select a project then navigate to Applications on the left menu bar.
Next, click on the ⊕Add Application button on the top toolbar to open the New Application page.
Enter an application name (for example: "My App") and select OIDC/SAML Client Application
as the Application Type. Click Save to create the app.
On the next screen, you'll see links to tutorials for different frameworks. Click Next to skip to the application configuration page.
The Authorized Redirect URI should be a page on your Express application where you make an HTTP(S) request to the Authgear token endpoint and exchange an Authorization Code for an Access Token.
For our demo Express application for this guide, this URL will be http://localhost:3000/auth-redirect
. So, scroll to the URI section of your application configuration page in the Authgear Portal and add http://localhost:3000/auth-redirect
as an authorized redirect URI.
Click Save to keep your changes.
In this section, we'll be building a simple Express app that has the following features:
A landing page with a login link that takes users to the login route.
A /start-login
route that initiates the authentication flow.
Logic that exchanges the authorization code from Authgear for an access token.
A page that uses that access token to fetch user info from Authgear.
A logout button to end the current user session.
Refresh access token.
It is now time to create the Express app that will be connecting to our Authgear client application. Run the following commands to create a new folder for the project and set it as your current working directory:
Next, install the Express npm package and other dependency packages like axios
, nodemon
, session
, and dotenv
.
We'll be using the axios
library to make HTTP requests in the example app. We'll also use nodemon
to add hot reload to our development environment. Run the following commands from the root of your Express project directory to install Express and other dependencies:
app.js
fileOnce Express and the other dependencies are installed, create a new app.js
file in the root of your project folder and add the following code to the file:
Add the following code to the scripts
section of the package.json
file in the root directory of your Express project:
Now run the npm run dev
command and you should get a page like this on a web browser when you visit localhost:3000
:
Here we'll be implementing the login route in our Express app. This route will initiate the authentication flow by redirecting the user's browser to the login page (AuthUI). This process involves redirecting the user to your Authgear project/client application's authorization URL (https://<AUTHGEAR_ENDPOINT>/oauth2/authorize
).
Update the code for the app.get("/login", ...)
route to the following:
Create a .env
file on the root directory of your project and add your Authgear client application configuration (Client ID, secret, endpoint) using the following fields:
Now if you save your code and restart your app, clicking on the Login link should redirect to the Authgear authorization page.
On successful login, an authorization code will be sent back to your Express application.
In this step, we will be exchanging the authorization code for an access code that users can later use to access protected resources.
Update the code for the app.get("/auth-redirect", ...)
route to the following:
The above code sends an HTTP POST request to the token endpoint (https://<AUTHGEAR_ENDPOINT>/oauth2/token
). The authorization code we got from the previous step is sent along with other client credentials in the HTTP request body. The header should contain "Content-Type": "application/x-www-form-urlencoded"
A valid access token is returned in the response to the HTTP(S) request in response.data.access_token
. In the above code sample, we've saved this access token temporally using express-session so we can access it from "/"
route after redirecting the user.
We can now use this access token to make authenticated requests to protected resources in our app or from the Authgear User Info endpoint. In the next step, we'll attempt to get the current user's info from Authgear using the access token.
Authgear provides an endpoint where your application can request user info (https://<AUTHGEAR_ENDPOINT>/oauth2/userinfo
). This endpoint will return the user's details on Authgear like their email address, gender, full name, and more.
To get user info in our example app, update the app.get("/", ...)
app.js
, to use the following conditional statement to render a different block of code when a valid access token is set for the current session:
Here our app sends another HTTP(S) request, but this time to the user info endpoint and the request type is GET. The access token is sent as a Bearer authorization header.
At this point, save all changes and restart the application. Try logging in all over again, at the end you should be greeted with "Welcome [your email address]" and a dump of the response from the UserInfo endpoint if the access token in your authorization header is valid.
To allow your users log out, add a new /logout
route to your Express application. Within the route, you'll implement code that will call express-session destroy()
method to delete the access token from the session. Then you'll redirect the user to Authgear's logout endpoint to log the user's session on Authgear.
To redirect the user back to your Express app after they logout, add http://localhost:3000
as a Post Logout Redirect URI for your client application in Authgear Portal.
Your implementation of the logout route should look like this:
Finally, place a link to the logout route below the </prev>
tag using the following code:
We recommend that you check that an access token is still valid before using it in your authorization header to access protected resources like the User Info endpoint.
To add the capability of refreshing an expired access token to our Express app, add the following function to app.js:
Next, find the following line within the app.get("/auth-redirect", ...)
route:
Add the following code just after the above line:
Finally, find the following line in the app.get("/", ...)
route:
Replace the above line with the following code:
Now our Express app gets an access token by first calling the new refreshAccessTokenIfExpired()
method. If the current access token is expired, the method will make a request to Authgear's token endpoint for a new access token. This request needs to have a grant_type
of refresh_token
, and the refresh_token
should be included in the POST request body.
To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers.
For example:
And there you have it, you've successfully added user authentication to your Express app using Authgear as the OAuth provider.
You can add so much more to your app with the new Authgear authentication, like protecting your own app endpoint with the access code. You can also store the access token securely to persist the user session using express-session and cookies.
Authentication for a Python web application
You will learn the following:
How to create an app on Authgear.
How to enable Email-based login.
Add sign-up and login features to the Flask app.
Before you begin, you'll need the following:
Every application in Authgear is assigned an alphanumeric, unique client ID that your application code will use to call Authgear APIs through the Authlib client library in the Flask app. Record the generated Authgear Issuer Domain
(for example, example-auth.authgear-apps.com
), CLIENT ID
, CLIENT SECRET
from the output. You will use these values in Part 2 for the Flask app config.
After you create the Authgear app, you choose how users need to authenticate on the login page. From the Authentication tab, navigate to Login Methods, you can choose a login method from various options including, by email, mobile, or social, just using a username or the custom method you specify. For this demo, we choose the Email+Passwordless approach where our users are asked to register an account and log in by using their emails. They will receive a One-time password (OTP) to their emails and verify the code to use the app.
Next, create a Flask application with a single page and routes for home, callback, login, and logout flows.
Start with creating a requirements.txt
file in your project directory:
Run pip install -r requirements.txt
from your command-line interface to make these dependencies available to the Python project.
Create a server.py
file in the project directory that contains application logic. Add the necessary libraries the application uses.
Load the configuration .env
file to use values such as AUTHGEAR_CLIENT_ID AUTHGEAR_CLIENT_SECRET
, AUTHGEAR_DOMAIN
and APP_SECRET_KEY
in the app.
Configure Authlib to handle the application's authentication with Authgear based on OIDC:
When visitors to the app visit the /login
route, they'll be redirected to Authgear to begin the authentication flow.
Once users complete the login process using Authgear, they will be redirected back to the application's /callback
route. This route ensures that the user's session is saved, so they won't need to log in again during subsequent visits.
Refresh Token
Calling the authorize_access_token()
method of the Flask Authlib package will include a refresh token in the token response, provided your Flask application has offline_access
as one of the OAuth 2.0 scopes.
Authlib will also use the refresh token to obtain a new access token automatically when the current access token has expired.
Logout
The route /logout
manages the user's logout process from the application. It clears the user's session within the app and momentarily redirects to Authgear's logout endpoint to guarantee a thorough session clearance. After this, users are navigated back to your home route (which we'll discuss shortly).
The home route will either display the details of a logged-in user or provide an option for visitors to sign in.
Create a new sub-directory in the project folder named templates
, and create a file home.html
.
Run the application from the project root directory:
python server.py
You can find the full code for the demo app for this tutorial in the Github repo .
Signup for an Authgear Portal account in . Or you can use your self-deployed Authgear.
In your IDE, define a custom URI scheme that Authgear will use to redirect users back to your app after they have authenticated , For your demo application for this guide, the URI scheme will be: com.example.authgeardemo.flutter://host/path
. To learn more about setting up URI Scheme in flutter, visit .
If you're new to Flutter, follow the official to see how you can install Flutter on your computer.
To learn more about why minSdk is set to 30, see
For detailed documentation on the Flutter SDK, visit
Signup for an Authgear Portal account in . Or you can use your self-deployed Authgear.
Step 1: Create an application in the Portal
Go to Applications on the left menu bar.
Click ⊕Add Application in the top tool bar.
Input the name of your application and select Native App as the application type. Click "Save".
You will see a list of guides that can help you for setting up, then click "Next".
Step 2: Configure the application
In your IDE (e.g. Visual Studio), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. com.myapp.example://host/path
.[^1]
Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
Click "Save" in the top tool bar and keep the Client ID. You can also obtain it again from the Applications list later.
Search for "Authgear.Xamarin" on nuget.org and add it to your base project.
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the FetchUserInfoAsync
function to obtain the user info, see .
For detailed documentation on the Xamarin SDK, visit
[^1]: For further instruction on setting up custom URI scheme in Xamarin, see [^2]: For more explanation on JWT, see
In this guide, you'll learn how to implement authentication for the application, a popular React-based framework for JavaScript, and as the OIDC provider. The source code can be found on .
In the , the Next.js app is integrated with Authgear, and the client library is used for sending authentication requests as an OpenID Connect middleware from the app to Authgear.
A free Authgear account. if you don't have one already.
.
Experience with framework and application development.
To use Authgear services, you’ll need to have an application set up in the Authgear . This setup allows users in Authgear to sign in to the Next.js application automatically once they are authenticated by Authgear.
To set up the application, navigate to the and select Applications on the left-hand navigation bar. Use the interactive selector to create a new Authgear OIDC Client application or select an existing application that represents the project you want to integrate with.
Every application in Authgear is assigned an alphanumeric, unique client ID that your application code will use to call Authgear APIs through the NextAuth.js Client in the Next.js app. Record the generated Authgear ISSUER
(for example, ), CLIENT ID
, CLIENT SECRET
from the output. You will use these values in the next step for the client app config.
An Authorized Redirect URI of your application is the URL that Authgear will redirect to after the user has authenticated for the OpenID Connect middleware to complete the authentication process. In our case, it will be a home page for our Next.js and it will run at .
Set the following to the Authorized Redirect URIs field. If not set, users will not be returned to your application after they log in.
You have two options here. You can either clone a or build the app from scratch.
If you want to run an already working application, you can clone the demo project from this using the following command.
Either way, continue configuring the to proceed with this tutorial.
Now that you have the application running, let's implement the authentication process by using . We recommend you look also at the for the most up-to-date instructions. First, install NextAuth.js:
Next, you'll configure a for Authgear. Doing so ensures every request to the /api/auth/*
path is handled by NextAuth.js.
We've added as the scope to make Authgear return all user profiles
This will make the React Hook accessible to your entire application. Now, create a component that will either render a "Log in" or "Log out" button, depending on the session state, in a src/components/login-button.jsx
file.
Browse to . If the installation went successful, you should see the Login page.
Your users can sign-up and login to your application through a page hosted by Authgear, which provides them with a secure, standards-based login experience that you can customize with your own branding and various authentication methods, such as , , , with SMS/WhatsApp, and multi-factor authentication (MFA).
If your application is a traditional web app running on a server, for example, Java EE, Express, PHP, GO, Laravel, or Core MVC, you can leverage the OpenID Connect (OIDC) protocol to authenticate users via Authgear. A wide range of plug-and-play libraries can be found that simplify the integration process. These libraries handle crucial tasks such as authentication requests, session management, and redirecting users back to your application seamlessly.
Follow this 15 minutes tutorial to create a simple app using Angular with Authgear SDK.
Check out and clone .
Signup for an account in and create a Project.
Here are some recommended steps to scaffold an Angular project. You can skip this part if you are adding Authgear to an existing project. See in the next section.
For Windows clients, please find your reference in for more information on installing the Angular CLI.
The Authgear container instance takes endpoint
and clientID
as parameters. They can be obtained from the application page created in .
Authgear SDK provides the fetch
function for you to call your application server. This fetch
function will include the Authorization header in your application request, and handle refresh access token automatically. The authgear.fetch
implements .
A free Authgear account. Sign up for one .
Check out and clone .
Login to your Authgear account (you can sign up for one ) to perform the steps in this section.
You can get the value for Client ID and Client Secret from the configuration page for the client application you created in the earlier step, . The Authgear Endpoint looks like https://project_id.authgear.cloud
if you are using Authgear Cloud version.
After the user logs in and grants authorization to your app on the Login page, they are redirected back to the . In addition to this redirect, an authorization code is sent via a code
URL query parameter.
An access token is usually only valid for a short period. However, you can use the refresh token, also included in the response from the token endpoint in to request a new access token.
The above code will store the values of refresh_token
and expires_in
that were returned in in express-session. To convert expire_in to a time in the future, we multiply it by 1000 and add that to the current time.
See more about refreshing access tokens .
Here's a link to the complete code for .
This guide demonstrates how to add authentication with Authgear to a Python web application built with the framework using the OAuth library. The full source code for this sample project can be found on the .
A free Authgear account. if you don't have one already.
Make sure that 3.10 or above is installed on your machine.
Download and Install to manage project packages.
To use Authgear services, you’ll need to have an application set up in the Authgear . This setup allows users in Authgear to sign in to the Flask application automatically once they are authenticated by Authgear.
To set up the application, navigate to the and select Applications on the left-hand navigation bar. Use the interactive selector to create a new Authgear OIDC Client application or select an existing application that represents the project you want to integrate with.
An Authorized Redirect URI of your application is the URL that Authgear will redirect to after the user has authenticated in the Authgear to complete the authentication process. In our case, it will be a home page for our Flask and it will run at .
Set the following to the Authorized Redirect URIs field. If not set, users will not be returned to your application after they log in.
The application should now be accessible to open from a browser at .
There is so much more you can do with Authgear. Explore other means of login methods such as using in an email, , or . For the current application, you can also from the Authgear portal.
Implement Authgear to control access to your applications
Authgear simplifies the use of open industry standards like OAuth 2.0, and OIDC. Users can log into your applications with a variety of user login options. This set of how-to guides provides you with detailed instructions, code snippets, and configuration examples for each type of login method.
Authentication for Laravel websites with Authgear and OAuth2
In this guide, you'll learn how to add user authentication to a Laravel app using Authgear as an OIDC provider.
Authgear supports multiple ways to allow users to log in to apps such as passwordless sign-in, phone OTP, and 2FA. In this post, we'll show you how to enable all these options in your Laravel app without worrying about the underlying logic.
How to create an Authgear Application.
How to request OAuth 2.0 authorization code from Authgear.
How to get user info from Authgear using OAuth 2.0 access code.
Link user info from Authgear with Laravel's default Breeze authentication.
To follow along with the example, you should have the following in place:
A Laravel project.
The example app we'll build in this post uses the default Laravel Breeze authentication kit. This kit provides the starter code for email and password user authentication systems.
We will be using Authgear to handle and process authentication data instead of the default Breeze database. By doing so, we get all the benefits of Authgear including more security and flexibility.
In this section, we'll walk through the complete steps for building the example app.
Before we can use Authgear as an OAuth identity provider, we need to set up an application on the Authgear portal.
To do that, log in to Authgear then select a project. Next, navigate to the Applications section for your project. Create a new application or configure an existing one with OIDC Client Application as Application Type as shown below:
Once you're done, click on Save to go to the application configuration page. This page reveals the application credentials and OAuth 2.0 endpoints.
Note down details like the Client ID, Client Secret, and the endpoints as you'll use them later in your Laravel project.
While you're still on the application configuration page, scroll down to the URL section then click on Add URI. Enter localhost:8000/oauth/callback
in the text field if you will be running your Laravel app on your local machine. Once you're done, click Save.
The redirect URI we provided above should be a valid page on our Laravel app as Authgear will redirect users to the page after authorization.
Now create a new Laravel project on your computer by running the following command:
Once your project is created, open the project folder in your preferred code editor and replace the content of resources/views/welcome.blade.php
with the following code:
Alternatively, you can create a new index.blade.php
file in the resources folder and add the above code inside it. Then, update the web.php
route file to render the new file instead of welcome.blade.php
.
Next, run the php artisan serve
command in the terminal to test your application. At this point, your application should look like the following screenshot when you access localhost:8000 on a browser:
Breeze is the official user authentication starter kit for Laravel. What that means is that Breeze helps you set up the database, routes, controller, and user interface for a user registration and user login system.
To install Breeze on your Laravel project, run the following command:
After that, run the following command to enable Breeze to set up all the resources for the user authentication system in your project:
During the setup, select blade
as the stack and leave the other options as default.
Once the setup is complete, navigate around your project file structure and you should notice some new folders and files related to authentication were added. Some of these new folders/files include an Auth sub-folder in the controllers folder, another auth sub-folder inside the views folder, and some database migration files.
Before we continue, let's add an extra oauth_uid
field to the users
table migration file. This field will store a user's unique ID from Authgear after successful login.
Open the create_users_table...
file that is inside the database/migrations/
folder (this file will have a date value at the end of its name) and add the following code to a new line inside the Schema::create()
method:
Add the MySQL database DB_DATABASE
, DB_USERNAME
, and DB_PASSWORD
for the database you wish to use with your Laravel project in your Laravel project's .env
file.
Finally, create the users and other tables by running the following command:
In this step, we'll create a new route that will handle the task of redirecting users from our app to Authgear's OAuth authorization page where they can grant our app authorization to their data on Authgear. If you've used other OAuth 2.0 providers before, for example, signing in to a website using Google OAuth, you may already be familiar with an authorization page.
First, create a new controller that will handle all OAuth operations in our Laravel app by running the following command:
Before we start implementing the logic for our new controller, we need to install a PHP OAuth 2.0 client package. This package will simplify the process of interacting with Authgear's OAuth endpoints. Run the following commands to install the package:
Now, back to implementing the controller; open the new OAuthController file (from the app/Http/Controllers
folder) and add the following code to it:
Next, add your Authgear Application's Client ID, Client Secret, and the redirect URI you specified earlier to your Laravel project's .env file using the following keys:
Note: Your Authgear project URL is the hostname of any of your endpoint URLs. For example, the project URL for a project with an authorization endpoint: https://laravel-app.authgear.cloud/oauth2/authorize
will be https://laravel-app.authgear.cloud
.
Now let's create a route in our Laravel project that will call the startAuthorization()
method.
Open the routes/web.php
file and add new routes using the following code:
We've included a second route for the redirect URI (callback), we'll implement this route in the next step.
Before we continue, let's clean up some of the additional routes added by the Breeze package that we won't be needing for this example. Open the routes/auth.php
file and delete the following lines:
At this point accessing the /login
route should redirect to the Authgear authorization page.
Update the empty handleRedirect()
method in OAuthController to the following:
The above code gets the authorization code sent in the redirect URL from Authgear after user authorization and exchanges it for an access token. With this access token, our application can access protected resources like the user info endpoint.
In this step, we'll use the access token we got from the last step to get the current user's info from Authgear.
First, add the following code at the end of the handleRedirect()
method:
The getResourceOwner()
method will call Authgear's UserInfo endpoint.
If you dump the userInfo variable (dd($userInfo)
), you should get an output similar to this:
The above array contains the user's info from Authgear. We'll proceed to use this information to link the Authgear user to a default (Breeze) Laravel authentication account. As a result, our app can start a regular Laravel authenticated user session and allow access to protected routes.
To implement the above feature, find the following line in OAuthController.php:
Add the following code after the above line:
OAuth 2.0 access tokens expire after some time. The refresh token on the other hand live longer. As a result, you can use the refresh token to request a new access token. In this step, we'll do exactly that in our Laravel application.
First, app/Http/Controllers/ProfileController.php and update the content of the edit() method to the following:
The above code checks if the current access token is expired using the hasExpired()
method. If the condition is true, we call the getAccessToken()
method with the refresh token to get a new access token.
The value of the current access token is updated to the new access token.
Next, this edit() method also displays the current user's profile details from your Authgear project on the UI. To implement this, add the following code to resources/views/profile/edit.blade.php, just below the line with "<div class="max-w-7xl mx-auto sm:px-6 lg:px-8 space-y-6">
":
At this point, if we run our app and click on the login link on the landing page, we should be redirected to the Authgear authorization page. After granting authorization, we are directed to the callback route of our Laravel app. If authentication is successful we should be redirected to the default Breeze-protected dashboard page that looks like this:
To log a user out, we'll delete all existing PHP session data and then call the Authgear token revoke endpoint.
First, add a new logout function to the OAuthController.php file using the following code:
Then, open routes/web.php and update the logout route to the following:
You should try enabling the different login methods on Authgear from the Portal to enjoy features like 2FA, passwordless login, and more without updating anything on the code for your app.
An API or service protected by Authgear
If your API or backend service needs authentication, you can validate the session in your application server code. Each request from the client to your application server should contain an access token or a cookie. Your backend server should validate them for each HTTP request.
There are different approaches to verify the requests based on whether you validate JWT (JSON Web Tokens) in your server, or forward authentication to Authgear Resolver Endpoint.
Reliability
Medium JWT only updates when expire. That means before the token expiry, your application may see the user is valid even they has been disabled
High Update near real-time, based on your reserve proxy cache setting
Integration difficulties
Easy You only need to add code in your application to validate and decode JWT
Medium Need to setup extra reverse proxy to resolve authentication information
Transportation of session
Access Token in Authorization
header
Session ID in Cookies or
Access Token in Authorization
header
Authgear returns the access token
and refresh token
to the client app after authentication. Your client app should call the backend with the access token in the Authorization header. The tokens should be parsed and validated in the backend server to ensure they are not compromised and the signature is authentic.
Request example:
Forward Authentication is a process where an intermediate reverse proxy or API Gateway is responsible for authenticating a request before it reaches the intended application or service. This can add an extra layer of security and centralize the authentication logic. An intermediate service forwards each incoming HTTP request to the Authgear Resolver Endpoint to verify the access token or cookie in the HTTP header.
In this approach, instead of validating the token in authorization header, Authgear returns Set-Cookie
headers and sets cookies to the browser. The cookies are HTTP only and share under the same root domains. So you will need to setup the custom domain for Authgear, such as identity.yourdomain.com
.
Request example:
Authentication for Spring Boot App with Authgear and OAuth2
You will learn the following:
How to create an app on Authgear.
How to enable Email based login.
Add sign-up and login features to Spring Boot App.
Before you get started, you will need the following:
Java 17 or higher.
Use the interactive selector to create a new Authgear OIDC Client application or select an existing application that represents the project you want to integrate with.
A Redirect URI is a URL in your application that you would like Authgear to redirect users to after they have authenticated. In our case, it will be a home page for our Spring Boot App. If not set, users will not be returned to your application after they log in.
To follow the example in this post, add the following URL as a redirect URI:
After you create the Authgear app, you choose how users need to authenticate on the login page. From the “Authentication” tab, navigate to “Login Methods”, you can choose a login method from various options including by email, mobile, or social, just using a username or the custom method you specify. For this demo, we choose the Email+Passwordless approach where our users are asked to register an account and log in by using their emails. They will receive a One-time password (OTP) to their emails and verify the code to use the app.
Spring Security makes it easy to configure your application for authentication with OIDC providers such as Authgear. We need to add the client credentials to the application.properties file with your Auhgear provider configuration. You can use the sample below and replace properties with the values from your Authgear app:
To enable user login with Authgear, create a class that will provide an instance of SecurityFilterChain, add the @EnableMethodSecurity
annotation, and override the necessary method:
We create a simple home.html page using Thymeleaf templates. When a user opens the page running on http://localhost:8080/, we show the page with buttons for login or logout:
Next, we create a controller class to handle the incoming request. This controller renders the home.html page. When the user authenticates, the application retrieves the user's profile information attributes to render the page.
To run the application, you can execute the mvn spring-boot:run
goal. Or run from your editor the main ExampleApplication.java file. The sample application will be available at http://localhost:8080/.
Click on the Login button to be redirected to the Authgear login page.
You can also customize the login page UI view from the Authgear Portal. After you sign up, you will receive an OTP code in your email to verify your identity.
And log into your new account, you will be redirected back to the home page:
Add authentication for ASP.NET app with Authgear
You will learn the following throughout the article:
Before you get started, you will need the following:
Use the interactive selector to create a new Authgear OIDC Client application or select an existing application that represents the project you want to integrate with.
Also, enable Issue JWT as an access token option under the Access Token section of the app configuration:
After you create the Authgear app, you choose how users need to authenticate on the login page. From the Authentication tab, navigate to Login Methods, you can choose a login method from various options including, by email, mobile, or social, just using a username or the custom method you specify. For this demo, we choose the Email+Passwordless approach where our users are asked to register an account and log in by using their emails. They will receive a One-time password (OTP) to their emails and verify the code to use the app.
Assume that there is a protected resource like a Razor page Protected.cshtml
that is used to represent views:
And ProtectedModel.cs
class to which Authorize
the attribute is applied requires authorization.
To see protected data, users need to go through the authentication process via Authgear.
If a user has not authenticated yet, Unauthenticated.chtml
the page is rendered, an OpenID Connect redirect flow is triggered and the user needs to authenticate through the Authgear login page. See Run the Application section
After successful authentication, you should see the protected page with the following details:
As part of the OAuth 2.0 standard, we can use the refresh token returned by the token endpoint to get a new access token. Doing so enables our application to replace an expired access token without requiring the user to repeat the entire login process.
The following code in ProtectedModel.cs
is responsible for doing that:
Note: You must include offline_access
in your OAuth 2.0 scope for the Authgear authorization server to return a refresh token.
The Logout button on the Protected.cshtml
page calls the OnPostLogout()
method in ProtectedModel.cs. The method will delete the current user session and redirect to Authgear's end session endpoint for the user to complete the logout process.
The code sample below shows the implementation of the OnPostLogout()
method:
Start by cloning the project into your local machine:
Make the project directory your current working directory:
Update the following configuration variables in the appsettings.json
file with your Authgear app settings values from Part1 such as Issuer
, ClientId
, ClientSecret
, and Authgear endpoint:
After you have authenticated, a protected view is rendered. The application receives an Access token that it uses to present user data on the screen, and tokens that could be used in upstream requests to some backend API, to access data on behalf of the user.
This guide showed how to quickly implement an end-to-end OpenID Connect flow in .NET with Authgear. Only simple code is needed, after which protected views are secured with built-in UI login pages.
Generative AI powered by large language models (LLMs) has revolutionized software development, giving rise to a new paradigm called “Vibe Coding.” This approach empowers individuals with ideas—regardless of their coding expertise—to create software quickly and intuitively. For developers, generative AI automates repetitive tasks, boosts productivity, and even enhances code quality in some cases.
While vibe coding is undeniably exciting, there’s one area where caution is essential: security. AI-generated code can sometimes be buggy or incomplete, and when deployed in real-world applications, critical aspects like user authentication and data protection cannot be left to chance.
To bridge this gap, Authgear offers a plug-and-play authentication solution that ensures your AI-generated applications are enterprise-grade secure. With the right prompts, developers can integrate robust security features into their projects in seconds. These features include:
Email/Phone Verification with OTP: Ensure user identities are verified during sign-up or login.
By incorporating Authgear into your vibe coding workflow, you can focus on building innovative applications while ensuring top-notch security for your users.
Passkeys give users a simple and secure way to sign in to your apps and websites across platforms without passwords.
Passkeys replace passwords and other passwordless login methods. It is built on the WebAuthn standard (also known as FIDO Sign-in), which uses public key cryptography to authenticate the user. With 1 click, Authgear upgrades your app to support this cutting-edge auth technology.
Users can log in to their accounts using their biometrics easily. On Apple devices, Touch ID and Face ID authorize the use of the passkey which then authenticates the user on the app or website.
Authgear adds a passkey feature to your apps and websites instantly. To enable it:
In your project portal, go to Authentication > Login Methods.
In the Select Login Methods section, turn on the Enable passkey support for compatible devices. toggle.
Press "Save" and your app now supports passkey login!
See the list of Passkey support via Authgear on different platforms.
macOS 12: Passkey is supported on major browsers. However, the credentials are deleted when clearing browser data.
iOS 15.5: Passkey is supported on Safari and stored locally a the device. Credential will be deleted by "Settings > Safari > Clear History and Website Data"
iOS 16 Beta 3: Passkey is synced with iCloud Keychain. The individual credentials can be viewed and managed in "Settings > Passwords"
Android 9 (API level 28) or higher: Supported.
AI-assisted IDEs like Cursor and Windsurf are increasingly popular among developers for enhancing productivity. These tools offer LLM-based agents for code suggestions, debugging, and understanding codebases.
Now, you’ve created an innovative software project consisting of a frontend application and a backend server. By leveraging generative AI with the right prompts, you can integrate robust security features into your project within seconds.
In the project creation wizard, choose how your users will perform signup and login. For example:
By email with a password
By receiving OTP via SMS or WhatsApp
Next, navigate to the “Applications” page and create an application of the type Single Page Application.
There are two values you will need for the subsequent steps:
Client ID: An ID to identify your application application with Authgear
Endpoint: The URL to identify your Authgear project and allow your application to connect to it.
Under “Authorized Redirect URIs,” add the URL of your local environment with /auth-redirect
appended. For example, if your frontend application runs on port 4000, use: http://localhost:4000/auth-redirect
there.
Save your changes.
To integrate login functionality into your frontend code, follow the corresponding documentation based on your framework:
In the chat, select the documentation as context and put in the following prompt.
Run the SPA with this prompt to verify the result.
In the backend, add the following documentation as context:
Run the backend server with this prompt to verify the result.
Similarly you can prompt the chat to protect any API endpoints in the backend.
Now you have the a protected API in the backend, add a button in the frontend to test it out.
Include the corresponding frontend SPA docs to the "context" added in the previous step. Then use the following prompt to add a button the test the API call:
Run both the frontend and backend servers simultaneously. Your frontend should now feature a button that calls the protected API. Logged-in users will see their user ID retrieved successfully, while logged-out users will encounter an error message.
Authenticate the incoming HTTP requests by forwarding Authentication to Authgear Resolver Endpoint
In this section, we will explain how to set up a reverse proxy in NGINX to protect your app server from unauthorized access with the Authgear resolver. You can forward the requests without the request body to the resolver endpoint. Authgear will look at the Authorization
and Cookie
in the HTTP header, verify the token, and respond to HTTP 200 with X-Authgear-
headers for session validity, the user id...etc.
You can also use the forward authentication features of the other popular reverse proxy. e.g.
Authgear provides an endpoint for forward authentication. Subrequests should be made to the following endpoint for authentication.
https://<your_app_endpoint>/_resolver/resolve
After the user is logged in, send an application request to your server from the client app with access token/cookies.
Set up a reverse proxy in your infrastructure to authenticate HTTP requests. The reverse proxy will forward the incoming HTTP requests without the request body to the Authgear Resolver Endpoint.
Authgear resolver parses the access token and returns HTTP headers including the user login state. The headers are starting with x-authgear-
.
You have to instruct your reverse proxy to include those extra headers, before forwarding the request to your backend server.
Your backend server looks at the headers and responds to the client app accordingly. e.g. Returns the user's content or HTTP 401 if the user is not logged in.
There are so many reverse proxies available in the wild. So here we are going to illustrate the idea of using Nginx as the reverse proxy.
We will use the module auth_request
in NGINX. The module is not built by default, it should be enabled with the --with-http_auth_request_module
configuration parameter.
Run this command and verify that the output includes --with-http_auth_request_module
:
The trick here is to declare an internal location
and use auth_request
to initiate a subrequest to the resolved endpoint.
If the reverse proxy, Authgear, and your backend server are in different regions, authenticating every request could result in a huge downgrade in the performance.
You may consider enabling caching.
Authenticate the incoming HTTP requests by validating JWT in your application server
In this section, we will go through how to decode the JWT token to obtain the currently logged-in user.
Before we start, make sure the option Issue JWT as access token is enabled in your Application settings in the Portal.
With the Issue JWT as access token option turned on in your application, Authgear will issue JWT as access tokens. The incoming HTTP requests should include the access token in their Authorization
headers. Without setting the reverse proxy, your backend server can use your Authgear JWKS to verify the request and decode user information from the JWT access token.
This Discovery endpoint serves as a JSON document containing the OpenID Connect configuration of your app. It includes the authorization endpoint, the token endpoint, and the JWKS endpoint.
https://<YOUR_AUTHGEAR_ENDPOINT>/.well-known/openid-configuration
The JSON Web Key Sets (JWKS) endpoint can be found in jwks_uri
in the configuration.
OpenID Connect Configuration JSON Example
Follow this step-by-step example to verify and decode the JWT token.
Define a function to find the JWKS endpoint from the OpenID Connect configuration. Use your Authgear endpoint as the base_address
Define a function to extract the access token from the Authorization header in the incoming request. It should look like Authorization: Bearer <access_token>
.
Here we show an example of using the Flask web framework to guard a path. You may need to adjust some of the codes to suit your technologies.
Use the following method to get the JWKS URI (you'll need to URI to extract the public signing key from a JWT).
Use the following code to extract only the token part from a Bearer [token]
authorization header in your Express app:
Next, decode the access token so that you can extract the JWT kid
from the result. You'll need this `kid to get the public signing key. Use the following code to decode the JWT:
Use the following code to extract the JWT public keys then verify the JWT using the keys:
Here's what your Express app should look like after putting the code in all the steps together:
Use your Authgear endpoint as base_address
The following example uses Spring Boot.
Add the following dependencies to your build.gradle file:
Then add the following imports to the top of your controller file:
Implement the following method to fetch the JWKS URI:
Get the signing key from the JWK using the following method:
To demonstrate how to validate a JWT, we'll implement a validateJWT
endpoint in a Spring Boot application. The endpoint will read access tokens from the bearer authorization header.
It will call the fetchJwksUri()
and getSigningKeyFromJwks()
from steps 1 and 2 to get the JWK URI and signing key required to parse the JWT.
First, install the dependencies required by running these com
Create a function that finds the JWKS endpoint from your Authgear application endpoint using the following code:
Add the following code to your application to get the JWT signing key:
To extract the access token from the HTTP request use the following code:
Finally, decode the JWT signing key.
Validating JWT in your application server is currently only available for Token-based authentication.
A free Authgear account. if you don't have an account yet.
Find the complete code for the OAuthController .
Find the complete code for the example app in our .
Authgear uses for secure data transmission, authentication, and authorization.
Read more on guide.
Read more on guide.
Instead of validating the access token in the backend, a reverse proxy forwards the request to an . This endpoint resolves and verifies the access token in the Authorization Header of the request.
If you have multiple applications under yourdomain.com
, all applications would share the same session cookie automatically. After that, you can verify the cookies using the .
In this guide, you will learn how to add authentication to your Java Spring Boot application using with Authgear as the Identity Provider (IdP).
A free Authgear account. if you don't have one already.
To use Authgear services, you’ll need to have an application set up in the Authgear . The Authgear application is where you will configure how you want authentication to work for the project you are developing.
Every application in Authgear is assigned an alphanumeric, unique client ID that your application code will use to call Authgear APIs through the Spring Boot . Note down the Authgear issuer (for example, https://example-auth.authgear.cloud/), CLIENT ID, CLIENT SECRET, and OpenID endpoints from the output. You will use these values in the next step for the client app config.
To create a new Spring Boot application you use the . Then you add dependencies to pom.xml file such as starter provides all the Spring Security dependencies needed to add authentication to your web application and Thymeleaf is used just to build a single page UI.
You have successfully configured a Spring Boot application to use Authgear for authentication. Now users can sign up for a new account, log in, and log out. The full source code of the examples can be found .
There is so much more you can do with Authgear. Explore other means of login methods such as using in an email, , or . For the current application, you can also from the Authgear portal.
In this guide, you will learn how to add authentication features with by implementing an flow, then retrieving OAuth tokens, to call APIs. View on GitHub.
How to add user login, sign-up, and logout to Core Applications.
How to use the Core Authorization Middleware to protect Core application routes.
A free Authgear account. if you don't have one already.
downloaded and installed on your machine. You can also use and to automatically detect the .NET version.
To use Authgear services, you’ll need to have an application set up in the Authgear . The Authgear application is where you will configure how you want to authenticate and manage your users.
Every application in Authgear is assigned an alphanumeric, unique client ID that your application code will use to call Authgear APIs through the OpenID Connect Client in the .NET app. Note down the Authgear ISSUER
(for example, ), CLIENT ID
, CLIENT SECRET
, and OpenID Token Endpoint
() from the output. You will use these values in the next step for the client app config.
A Redirect URI of your application is the URL that Authgear will redirect to after the user has authenticated in order for the OpenID Connect middleware to complete the authentication process. In our case, it will be a home page for our and it will run at.
Set the following redirect URI: If not set, users will not be returned to your application after they log in.
This guide will be used to provide a way for your users to log in to your Core application. The can be found on GitHub. If you are familiar with the steps, you can skip this part and clone the code repository and run the code sample by following the file there.
To integrate Authgear with Core you will use both the Cookie and OpenID Connect (OIDC) authentication handlers. If you are not using a sample project and are integrating Authgear into your own existing project, then please make sure that you add Microsoft.AspNetCore.Authentication.OpenIdConnect
packages to your application. Run the following command in your terminal or use your editor to include the NuGet package there:
To enable authentication in your Core application, use the OpenID Connect (OIDC) middleware. Open Startup
the class and in the ConfigureServices
method, add the authentication services and call the AddAuthentication
method. To enable cookie authentication, call the AddCookie
method. Next, configure the OIDC authentication handler by adding method AddOpenIdConnect
implementation. Configure other parameters, such as Issuer
, ClientId
, ClientSecret
, and Scope
. Here, is what looks like Startup.cs
after you apply these changes:
Execute the following command to run the Core web application:
You can now visit to access the application. When you click on the "View Protected Data" button, Core takes you to the Authgear’s Login page.
Your users can log in to your application through a page hosted by Authgear, which provides them with a secure, standards-based login experience that you can customize with your own branding and various authentication methods, such as , , , with SMS/WhatsApp, and multi-factor authentication (MFA).
: Add an extra layer of security to user accounts.
: Safeguard against unauthorized access attempts.
: Keep malicious bots at bay.
The passkey standard is supported on the latest versions of Chrome, Safari, and Firefox browsers. On iOS 16 and macOS 13 (Ventura), to the iCloud Keychain service. Passkeys are also (API level 28) or higher. A passkey is synchronized and relayed with an iCloud account and can be used across a user's devices.
Besides the built-in support of all major desktop and mobile platforms, passkeys can also be stored in hardware security keys such as , which provide the highest security against attacks.
First, create an account and a project in the .
React:
Vue:
Angular:
To show the login status in the home page, use the following prompt to change the appearance of the logged in status and add a button to the .
Validate JWT in your application server:
Note: The prompt is designed for Express JS (Node JS) backend. For other backend technologies, copy and paste the corresponding code blocks from for the best result.
If you use a popular reverse proxy on your deployment, such as , , or API Gateways such as , you can configure it with a few simple lines of forward auth config. Your backend should read the returned headers to determine the identity of the user of the HTTP request.
See docs for auth_request
in NGINX for more details.
See the list of x-authgear-
headers in the specs:
Here is .
The auth_time
claim in an OIDC ID token represents the time when the user authentication occurred. Extract the auth_time
claim from the token, which should represent the time of the original authentication in seconds. If the difference between the current time and auth_time
exceeds your threshold (for example, 5 minutes), initiate the process.
See an example of how to verify the signature of the ID token, and then validate the claims auth_time
inside .
For Cookie-based authentication, JWT in cookies is not supported yet. .
Passwordless login with email links
Email Login Links, also known as "magic link", is a passwordless authentication method that allows users to log into a website or application without using a traditional password. Instead, it relies on a unique link sent to the user's email address.
Here's how it works:
User initiates the login process by entering their email address on the login page.
Authgear generates a unique, time-limited login link associated with the user's email address.
The link is sent to the user's email inbox, with a button prompting them to click on it to log in.
The user clicks on the link, and approve the login
The user is securely logged in to the app or website.
Magic link login offers several advantages. It eliminates the need for users to remember and manage passwords, reducing the risk of weak or reused passwords. It also simplifies the login process and reduces friction, as users only need to access their email to authenticate.
To enable Email Login Links:
In the Authgear Portal, go to "Authentication" > "Login Methods"
Select "Email" or "Mobile/Email" as login methods
Go to the "Verification and OTP" tab
Under "Email", in the "Verify email by" field, select "Login Link"
Allow guest users to use your apps and website and promote to regular users later.
You can use the Anonymous Users feature to create an anonymous user account for the guests in your apps so that they can carry out interactions just like a normal user. For example, guests can post comments and save preferences in your social platform before setting their email and password. The user session will persist even if the app has been closed.
This improves the app experience because the user does not need to set up authenticators until further down the user journey, while still enjoying most of the app features. For app developers, the ability to create and assign Anonymous Users also makes it easier to link the activities of an individual before and after sign-up.
In the portal, go to Authentication > Anonymous Users.
Turn on Enable anonymous users.
Save the settings.
This will create an Anonymous User for the session. Subsequent requests from the end-user in the session can be identified by the same sub
UserInfo
The promoteAnonymousUser
function can be called to promote an anonymous user to a regular user. You'll call the function with a login ID (e.g., email, phone number) and authenticators (e.g., password). The end-user will be prompted with a sign-up page to complete the promotion. The sub
of the end-user will remain the same after the promotion.
Step 1: Start the promotion flow
When the user clicks promote on your website, make a start promotion call to redirect them to the promotion page.
Step 2: Handle the promotion result
After the user promotes on the promotion page, the user will be redirected to the redirectURL
with a code
parameter in the URL query. In the redirectURI
of your application, make a finish promotion call to handle the promotion result.
On Mobile SDKs, creating an anonymous user will create a key-pair. The key-pair is stored in the native encrypted store on the mobile device. The end-user can always re-login to the same anonymous user with the key-pair. Such anonymous user will become inaccessible when the encrypted store is removed.
On the Web SDK, there will be no key-pair created. Therefore, the end-user will not be able to login to the same Anonymous User after their session becomes invalid. For cookie-based authentication, it is controlled by the "idle timeout" and "session lifetime" of the Cookie. For token-based authentication, it is controlled by the "idle timeout" and "token lifetime" of the Refresh Token.
In other words, the anonymous user account lifetime is the same as the logged-in session lifetime.
To adjust the lifetime settings, change the timeouts and lifetimes in Portal > Applications accordingly.
You should create anonymous users only when necessary in the user journey to prevent creating excessive orphan accounts in your tenant.
Learn how to add authentication to any web page without using Authgear's SDKs with IIFE(Immediately-invoked Function Expression) bundle
Start with making a new folder on your computer to keep the app’s source code (In the example, we call it authgear-spa-js-login
). Then, initialize a new NPM project by running the following command:
Next, we install two required packages:
Next, open the package.json
file and edit scripts entry to have start
and dev
commands like the below:
Now you can run the app in two modes: prod and dev.
For example, npm run dev
will run the application using nodemon
, monitoring for changes as we modify files.
Create a new file server.js
in the root of the project and populate it with the following code:
Create a index.html
file in the root of the project and add the following content to the created file:
Create a new folder called public
folder in the project root folder and create another folder called css
inside the public
folder. Add a new file in there called main.css
. This will be used to determine how the log-in and log-out button elements will be hidden on the main page depending on whether a user is authenticated or not.
Open the newly-created public/css/main.css
file and add the following CSS:
After creating an HTML file and applying CSS styles, see now how our page looks like by running npm run dev
and accessing it at http://localhost:3000.
To add some action to the page, we create a new directory in the public
folder called js
, and add a new file there called app.js
. Copy and paste the following JS code that reads authgear_config.json
file Authgear app-specific values (endpoint
and clientId
) from the endpoint using fetchAuthConfig
function. Also, it configures a new Authgear client, and defines login and logout logic:
Let’s breakdown down app.js
code in the previous section and understand how authentication is achieved with Authgear:
Configure the Authgear client
fetchAuthConfig
: Firstly, this function makes a request to the /authgear_config.json
the endpoint we exposed in server.js
to fetch Authgear app setting values from authgear_config.json
file.
configureClient
: Once we retrieve the configuration information for the Authgear client from the authgear_config.json
file and we set up the Authgear client with these settings. It also logs a message to the console, informing whether the configuration was successful or not.
Login flow
login
: The function is called by the Login button previously defined on the HTML page. It performs the login action by calling authgearClient.startAuthentication
Authgear’s function. It redirects the user to the Auhthgear login page. After the user logs in successfully, they will be redirected back to the same page we set in redirectURI
. Run the project and click the Login button. You should be taken to the Authgear Login Page configured for your application.
After authenticating successfully, you will be redirected to the page you were before.
Logout flow
Update the UI
window.onload
: This is a function that runs when the page loads. It configures the Authgear client and updates the UI. If the page's URL contains a "code=" it means the user is authenticated (code
the query will be received from the Authgear server), it updates the UI again and removes the "code=" from the URL.
Evaluate the authentication state
updateUI
: This function updates the status of the login and logout buttons based on whether the user is authenticated or not. In Authgear, you can check if the user has logged in or not with sessionState
the attribute. If the user is authenticated, we disable the login button and enable the logout button, and vice versa if the user is not authenticated.
Allow users to log into your app via OTP with WhatsApp, as a secure alternative to SMS
Authgear let your users login passwordlessly with WhatsApp OTP.
To enable this feature from the Portal:
Go to Authentication > Login Methods, we are going make few changes on this page.
In the top section of Select Login Methods, select Mobile.
In Authentication of Select Login Methods, select Passwordless.
In the tabs section below, switch to the tab Verification and OTP.
In the dropdown Verify phone number by, select either WhatsApp or SMS or WhatsApp only.
Press Save on the top left corner.
When the user login with their phone number, a WhatsApp message with an OTP and the app name will be received. They can copy the code by tapping on the "Copy code" button and log in by the code.
If "Verify phone number by WhatsApp or SMS" is enabled, the user can switch to receive the OTP via SMS instead in the login page.
Use the Phone Number Validation Settings to configure your app to check the phone number your users enter without depending on SMS or WhatsApp for validation and verification.
To access Phone Number Validation settings in your Authgear project, navigate to Authentication > Login Methods in the Authgear Portal.
Next, select a login method that uses mobile phone number as login ID (e.g., Mobile, Mobile/Email, or Custom with phone number enabled as login ID). Then, scroll down to the Phone Number Validation section. Select validate phone number with libphonenumber or validate only the country code and phone number length.
Settings for requiring users to reset their password if they haven't logged in after specific number of days
You can set up your Authgear project such that a user's password expires after a specific number of days. When a user logs in after the password expiry date, they'll see a prompt to change their password before they're redirected back to your app.
In this post, you'll learn how to set the Password Expiry feature in the Authgear Portal.
To enable password expiry, first, log into the Authgear portal, select your project then navigate to Authentication > Login Methods. Next, select a Login method that supports password, then switch to the Passwords tab and scroll to the Password Expiry section. Toggle the "Force password change on next login if it has expired" button to enable password expiry.
You can use the text field labeled Force change since last update (days) to specify the number after which a user's password should expire. The value should be the number of days in the future from the last date the user set or updated their password. For example, setting the value to 90 means the user's password will expire 90 days later from the last date they set or updated their password.
Once you're done, click on the Save button at the top of the page to keep your changes.
Learn how to configure different options for password reset/account recovery.
The Forgot/Reset Password settings tab allows you to configure the behavior of the account recovery process for your Authgear project to meet your specific needs. For example, you can use this feature to determine whether to deliver recovery code to users via SMS, WhatsApp, or email.
In this post, you'll learn the various configurations available via the Password Settings tab and how to navigate to the page.
To access the Password Settings page, log in to your Authgear account, select your project, and then navigate to Authentication > Login Methods.
Next, select your current Login Method (Email, Mobile, Mobile/Email, or Custom). The login method you select affects the options available for you to customize.
Scroll down to just below the Select Login Methods section and click on the Password tab to reveal the Password settings screen.
Note: Make sure the login method you select has password enabled (you can not view the password settings screen if you only enable Passwordless login).
When you enable password reset by phone number for your project, users will receive an OTP code that they can enter in the AuthUI to finish the account recovery flow.
To able this feature, first in the Password Settings tab, select a Login Method that supports Mobile (E.g Mobile or Mobile/Email methods) and has the password option enabled.
Next, click on the "Reset password with phone by" dropdown then select how you want to send the OTP from the available options. The available options include SMS, WhatsApp, and WhatsApp or SMS.
Once you're done save your changes to enable the new configuration.
The next time your users try to reset their password using their phone number as the login ID, they should see a screen like this to enter the OTP sent to their phone:
If you prefer your users receive an OTP that they can enter in the AuthUI instead of a recovery link that they would normally click, you can use this password recovery settings to enable that.
To enable this setting, click on the "Reset password with email by" dropdown in the Password Settings tab. Then, select the One-time Password (OTP) option. Save your changes to enable the feature.
Authgear provides an easy method to reauthenticate the end-users. You can use this as a security measure to protect sensitive operations.
Your sensitive operation server endpoint MUST require the ID token. When you receive the ID token, you MUST verify the signature of it. If the signature is valid, you can trust the claims inside the ID token.
The auth_time
claim in the ID token tells when was the end-user last authenticated. You should check the auth_time
claim to see if the end-user was authenticated recently enough.
The https://authgear.com/claims/user/can_reauthenticate
claim in the ID token tells whether the end-user can be reauthenticated. If the value of this claim is false
, then depending on your business needs, you can either allow the end-user to proceed, or forbid the end-user to perform sensitive operations. The flows are illustrated by the following diagrams.
The following code snippets illustrate the interaction between the SDK and Authgear.
If the end-users in your application often perform a series of sensitive operation, it is annoying that they have to reauthenticate themselves repeatedly before every operation. To allow the end-users to skip reauthentication if they have just reauthenticated themselves recently, the SDK allows you to inspect the last authentication time of the end-user.
Finally in your backend, you have to verify the signature of the ID token, and then validate the claims inside.
After "signing up" as an anonymous user, you can and see the sub
of the end-user.
In this guide, you'll make a simple website server to host the SPA app using . We'll also use it to serve our HTML page and any assets it needs, like JavaScript, CSS, and so on. You can also view a on the GitHub repo.
Before we start, ensure you have Node.js installed in your system. If not, download and install it from the .
An Authgear account: You need an Authgear account to follow this guide. If you don't have one, you can on the Authgear website.
A Registered App: You need a registered application type (Single Page Application) in Authgear. Follow the guide and skip part. You will retrieve the Authgear Web SDK from Authgear's CDN using IIFE(Immediately-invoked Function Expression) bundle and reference a script in our HTML directly.
Also, install so that our server can be restarted automatically on any code changes in dev mode:
We do not use a package manager such as , we will retrieve the Authgear Web SDK from Authgear's CDN using IIFE(Immediately-invoked Function Expression) bundle. We can reference a script in our HTML directly:
You can install the Authgear Web SDK as a dependency of your application, it is useful if you are building React or React Native apps. See how to .
Go ahead and create a new user or log in using an email (we specified the Passwordless Email login method in the first part). When you try to log in with your email, you should receive a to your email box to confirm login operation.
logout
: This function logs the user out and redirects them back to the original page (at). It uses Authgear’s logout
function and logs a message to the console indicating the result of the operation.
Under the hood, the Phone Number Validation Settings uses the library. The library can parse, format, and validate phone numbers for all countries/regions in the world.
By default, password expiry is turned off for your Authgear project. shows that forcing users to change their password after some time can do more harm than good.
Reauthentication in Authgear is built on top of the . The ID token is a JWT.
Authgear supports enabling biometric login in the native mobile application. You will need to
Enable biometric login in your application via the portal.
In the mobile app, use the mobile SDK to enable biometric login for your users.
A pair of cryptographic keys will be generated upon registering biometric login. The private key will be stored securely in the device (using Keystore in Android and Keychain in iOS), while the public key is stored in the Authgear server. To authenticate the user, fingerprint or face is presented to unlock the private key, and a digital signed message is sent to the server to proof the authenticity of the user.
Fig 1.0. The following figure shows the sequence for enabling Biometric Login on a supported device:
The Client App that is already logged in to a user's account will check if biometrics is supported by the user's device. If the device supports biometric login, it is then enabled. The public key is sent to Authgear server and associated with the logged-in user's account.
The flow is then completed and biometric login is enabled for the user on the Client App.
Fig 2.0. The following figure shows the sequence for a user logging in with Biometric:
With biometric login already enabled for the user, the next time they need to log in they can initiate a biometric authentication flow which will follow the sequence shown in Fig 2.0 above. Once the biometric login is successful, Authgear server will return an access token and a refresh token. The client application can then use the access token to make authenticated requests.
Sounds overwhelming? Authgear's magic handles all these for you. Follow this guide to enable biometric login with a few lines of code in your app.
In the portal, go to Authentication > Biometric.
Turn on Enable biometric authentication.
Save the settings.
Biometric login is usually used when you want the user to re-login after a relatively short period of time. For sensitive applications such as financial apps, it's recommended to use a short refresh token lifetime and a short idle timeout.
In the Authgear Portal, go to Applications
Select the client application that represent the integration with the mobile app
Set a short Refresh Token Lifetime to say 3,600 seconds (1 hour)
Enable Expire after idling
Set a short Idle Timeout, to say 1,800 seconds (30 minutes)
By doing so, the end-user's session will be expired 1 hour after their login, or after 30 minutes of inactivity. The end-user will need to authenticate themself again with biometric, even if the app process has not yet been killed.
Apart from the short token lifetimes, it's also common for sensitive apps to ask the user to re-login by biometric after the app process is killed and relaunched.
The SDK should be configured to use TransientTokenStorage so the tokens are stored in memory, and will be cleared when the app is closed. So the end-users must authenticate with biometrics again.
In the following section, we will show you how to use biometric login in the SDK. In the SDK code snippet, authgear
is referring to the configured Authgear container.
In the SDKs, a set of biometric options is required to check the support or enable biometric on the device.
There are two options on iOS:
localizedReason
is the message string the user will see when FaceID or TouchID is presented
constraint
is an enum that constraint the access of key stored under different conditions:
biometryAny
: The key is still accessible by Touch ID if fingers are added or removed, or by Face ID if the user is re-enrolled
BiometricCurrentSet
: The key is invalidated if fingers are added or removed for Touch ID, or if the user re-enrolls for Face ID
policy
can be used to allow users to log in with only biometrics, or using biometrics and the device PIN/password as fallback when biometric verification fails. The following are the available options:
BiometricLAPolicy.deviceOwnerAuthenticationWithBiometrics
: When this policy is set, users can ONLY use a biometric method to complete the login. Users cannot log in with their device PIN/password after a failed biometric login attempt.
BiometricLAPolicy.deviceOwnerAuthentication
: enable this policy to allow users to log in with non-biometric local authentication methods like device PIN/password when biometric verification fails or is not enrolled on their device.
There are 6 options on Android:
title
is the Title of the biometric dialog presented to the users
subtitle
is the subtitle of the biometric dialog presented to the users
description
is the description of the biometric dialog presented to the users
negativeButtonText
is what the dismiss button says in the biometric dialog
Always check if the current device supports biometric login before calling any biometric API, including before enabling biometric login and before using biometrics to login.
Enable biometric login for logged in user
Before asking the user to log in with biometric, Check if biometric login has been enabled on the current device. I.e. Is the key pair exist on the device (Keystore in Android and Keychain in iOS).
This method will still return true even if all the fingerprint and facial data has been removed from the device. Before this method, you should use the "checkBiometricSupported" to check if biometry is supported in the device level.
If biometric is supported and enabled, you can use the Authenticate Biometric method to log the user in. If the key pair is invalidated due to changes in the biometry settings, e.g added fingerprint or re-enrolled face data, the biometricPrivateKeyNotFound
will be thrown. You should handle the error by the Disable Biometric method, and ask the user to register biometric login again.
In all methods related to biometric, the SDK may throw the following errors that describe the status of the biometry enrollment or the key pair stored on the device.
In some use cases, you may want to provide an alternative means for users to log in when biometric verification fails on their devices. For example, in a case where a user's finger is dirty (touch-based) or when the user's face is covered (Face ID).
In the biometric options, the parameters policy: BiometricLAPolicy.deviceOwnerAuthentication
(iOS) and constraint BiometricAccessConstraintAndroid.DeviceCredential
(Android) can be used to allow users to enter their device PIN/Password when biometric verification fails.
The biometric pop-up will look like this after a failed biometric log-in attempt with BiometricLAPolicy.deviceOwnerAuthentication
policy on iOS:
With the BiometricLAPolicy.deviceOwnerAuthenticationWithBiometrics
policy, the biometric login pop-up will not include the Enter Passcode button. An example is shown below:
Setting up the local development environment for websites that use cookie-based authentication.
This guide is only for cookie-based authentication in local development setups. A typical scenario is developing websites. If you are developing mobile applications which use token-based authentication, you can just skip this guide and continue with it as usual.
Authgear sets a cookie in the browser inside the project domain. When running your application on localhost
, the browser will not see the cookies because the website is not in the subdomain of the domain in which the cookies are set. Therefore, the browser will not be able to authenticate itself.
For local development, it is highly recommended to create a new application on Authgear before continuing to the rest of the guide.
Go to the Application tab in your dashboard
Add your local application domain {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud
under the Allowed Origins list
Add an application, name it whatever you want. DO NOT check the Issue JWT as access token box because we are using cookie-based authorization.
Put your redirect URI for login and logout under the Redirect URIs list and Post Logout Redirect URIs list respectively.
hosts
To make the cookies visible to the browser, the local website domain has to be inside the domain where the cookies are set.
By adding the following line to the /etc/hosts
file on the local machine, we can point the application domain name to localhost.
The browser will be able to see the auth cookies if visiting the website via this domain.
Although you can see the cookies now, the cookies have the Secure attribute set. To include them in an HTTP request, the request has to be transmitted over a secure channel (HTTPS in most browsers). Therefore, we also need to establish HTTPS connections for our browser with the server.
A key file and a cert file will be generated. They will be used in the next part of the guide.
We will need an nginx server to serve the certificate and enable SSL.
Add the following config file to your nginx/conf.d
directory, or mount it to a volume together with the cert and key if you are using nginx in docker.
The examples below show the nginx config files for nginx in host and nginx in docker.
Now visit the website through https://<yourapp>.authgear.cloud
, and the browser will be able to send requests with the authorization cookies.
Provide a seamless user experience across multiple applications with the single sign-on feature.
Single sign-on (SSO) is defined as login once, logged in all apps. If you have multiple mobile apps or websites that wants to streamline the user experiences. You can configure your apps to turn on the SSO feature, so the end-users only have to enter their authentication credentials once.
There are multiple ways to achieve Single Sign-on, with various pros-and-cons:
Learn how to take users directly to an external OAuth provider's authorization page without opening AuthUI login page.
You can use Authgear's x_oauth_provider_alias
parameter to add social/enterprise login to your application without showing any AuthUI pages. To do this, you must enable the Social/Enterprise only login method for your project in Authgear Portal.
In this post, you'll learn how to use the x_oauth_provider_alias
parameter to skip AuthUI and take users directly to a social/enterprise login provider's authorization page.
In this post, we'll walk through the steps for adding only the social/enterprise login method to an Authgear application.
We'll use the Authgear SDK for React Native to set the x_oauth_provider_alias
parameter and show how to use x_oauth_provider_alias
without the SDK in an example Express app.
The sequence diagram above demonstrates the flow for using x_oauth_provider_alias
to skip AuthUI.
First, when the user clicks on the sign-in button, your application will call your Authgear project's authorize
endpoint with the x_oauth_provider_alias parameter appended.
Next, when Authgear server receives the call, it redirects to the third-party OAuth (Social/EnterpriseLogin) provider's authorization server. The user is then shown the OAuth provider's login/authorization page for them to grant authorization. Once that is done, the OAuth provider returns an authorization code to Authgear.
In the next step, Authgear exchanges the authorization code for an access token, refresh token, and ID token and then starts creating a new user or logging the existing user in.
The rest of the flow from there involves the usual sending of the authorization code to the client application and the client application exchanging the authorization code for an access token, refresh token, and ID token.
The first step is to add the Social/Enterprise login provider you wish to use to your Authgear project. For our example, we'll be adding Facebook.
To add a new provider, log in to Authgear Portal, select your project, then navigate to Authentication > Social/Enterprise Login.
Next, click on the Edit button, then enter the Client ID and Client Secret for the Social/Entreprise login provider then click Save. Also, note the value for Alias as you'll use it in a later step.
An important step for making Authgear to skip AuthUI is to enable the Social/Enterprise only login method. By doing this, Authgear will understand that the only login method your app will use is from a third-party OAuth provider. As a result, it's ok to skip showing AuthUI for login, registration, or login method selection and go to the OAuth provider's authorization page directly.
To enable Social/Enterprise only, navigate to Authentication > Login Methods. Next, select the Social/Enterprise only Login Method and click Save.
Now that you've set up everything to allow your application to use only Social/Enterprise Login, you can open Authgear's authorize
endpoint with the x_oauth_provider_alias
parameter to start an authorization request that will skip AuthUI.
We will show 2 ways to do this. The first is using the SDK and the second is by passing x_oauth_provider_alias
as a URL query parameter.
The following example shows how to add x_oauth_provider_alias
using the Authgear React Native SDK:
Note that the value for oauthProviderAlias
must be the Alias for the social/enterprise provider you configured in step 1.
You can manually add x_oauth_provider_alias
parameter to the Authgear authorization endpoint when you're not using the Authgear SDK.
The following example shows how to add x_oauth_provider_alias
to the Authgear authorization endpoint:
The above code will append &x_oauth_provider_alias=facebook
to the authorization URL.
Perform faster authentication flow via another app installed on the same device.
This may be familiar for users from UK, which many neobanks are using the app2app mechanism to authorize the money transfer from 1 bank app to another.
The App2App mechanism allows one app to authenticate the user using another apps connected to the auth server installed on the same device. This is achieved by universal links and the apps do not need to share the session via the system browser or the refresh tokens via the token storage.
The session cannot be shared via the browser cookies
The session cannot be shared via a common token storage
An app can start the authentication flow by opening a link to another app, instead of using the authorization endpoint. The app which handles the link should validate the authentication request, then could return a valid authorization code. The valid code is then transferred to the original app using universal link. The initiating app can use that authorization code to perform code exchange for tokens with Authgear.
Go to the Application detail page of the authorizing app, i.e. the app which handles the app2app authentication requests.
Scroll to the bottom and you will see the App2App config panel.
Migration mode offers a less secure mechanism which helps older user sessions to participate in App2App. DO NOT enable it unless there is migration problem.
Go to the Application detail page of the initiating app, i.e. the app which initiates the app2app authentication requests.
In the redirect URIs, a universal link that's capable of opening this app should be set.
Define and set up the universal links for both apps, for example:
https://a.example.com/authorize
should open the authorizing app (App A)
https://b.example.com/redirect
should open the initiating app (App B)
In App B, call startApp2AppAuthentication(options: App2AppAuthenticateOptions)
to initiate the app2app login
App2AppAuthenticateOptions.authorizationEndpoint
should be an url of an universal link pointing to App A, i.e. https://a.example.com/authorize
App2AppAuthenticateOptions.redirectUri
should be an URI for the authorizing app to return the authentication result. It must be an universal link which opens the current app. i.e. https://b.example.com/redirect
In App A, upon receiving the app2app login request
Call parseApp2AppAuthenticationRequest(url: URL): App2AppAuthenticateRequest?
The result will be null
if the url is not a valid app2app request.
You can approve or reject the app2app request in App A
Approve: approveApp2AppAuthenticationRequest(request: App2AppAuthenticateRequest)
Approves an app2app request returning the result through the redirect URI.
request
should be the return value of parseApp2AppAuthenticationRequest
.
This method must be called when then SDK session state is AUTHENTICATED
, and the current session supported app2app authentication by providing a device_key
, or else an error will be thrown.
Reject: rejectApp2AppAuthenticationRequest(request: App2AppAuthenticateRequest, error: Error)
Rejects an app2app request, returning an error through the redirect URI.
request
should be the return value of parseApp2AppAuthenticationRequest
.
error
is the reason to reject the request.
When it's back to App B, call handleApp2AppAuthenticationResult(url: URL)
This method should be called by the app which initiate the app2app authentication flow, and when received the result through the universal link, url
should be the URL of the universal link received.
Reference on what the OAuth 2.0 parameter is and how to use it in Authgear SDK.
The authorization server (Authgear) will include the value of the state parameter when redirecting the user-agent back to the client application. As a result, the client application can retrieve the value of state
returned to verify that it is the origin of the authorization request.
In this post, we'll cover some possible usage of the state
parameter and how to include the state
parameter in an authorization request to the Authgear server.
The following are some use cases of the OAuth 2.0 state parameter.
Because the value for the state parameter passed at the beginning of an authorization request is returned unchanged after authorization, you can use this behavior to customize the post-login or sign-up user experience.
For example, you can show users some custom messages after they sign up or log in, using a special link that was sent to them via email or SMS. The "special" thing in the link would be the value of a query parameter that can be passed in the state
parameter.
Then, a client application can read the value of the state
parameter and based on that, determine when and how to display the custom message or user experience.
Another possible use of the state
parameter is analytics and tracking user behavior. You can use the state token to include a unique key that tracks your campaigns. This way, you can know the number of users who sign up or log in to your application from a particular campaign.
Cross-site Request Forgery or short CSRF is a type of web security vulnerability where the attacker uses malicious means to trick a user into performing undesired actions on sites they use and trust. This type of attack usually targets users who are signed in and attempts to compromise access to their protected resources.
In OAuth, an attacker can perform a Cross-site Request Forgery using the client application's redirect URI. The attacker can trick a user into using a redirect URI that contains their authorization code or access token. Hence the user will end up using the access token and protected resources of the attacker. When they save new data using this access token, the attacker can also view them (as they are the original owner of the protected resources).
The official Authgear SDKs have mechanisms for protecting your applications from CSRF built into them.
However, if you are not using the official SDK, you can secure your application by generating a random hard-to-guess value on the client application and passing it in the state
parameter. Your application should store this value securely on the user's client-side using session cookies or some other form of local storage. Then, verify the state
parameter in the redirect URI against the value stored locally to confirm that a user-agent is the origin of an authorization request before exchanging the authorization code for an access token.
The following URL shows an example of an authorization request URL:
As you can see from the above URL, state
is a query parameter in addition to other parameters like the client_id
and redirect_uri
.
If you're constructing the authorization URL manually, you can include the state parameter by simply appending "&state=random_state_value
" to the authorization URL.
Alternatively, if you're using any of the Authgear SDKs, you can use the built-in state
field to set a value.
The following code samples show the use of the state parameter with Authgear.
First, install the Authgear web SDK by running the following command:
Next, configure Authgear in your React Project's index.tsx file like this:
Set the state
field in your call to the startAuthentication()
method of the Authgear SDK to a random hard-to-guess value based on your use case.
Implement the component that handles your OAuth 2.0 redirect like this:
The above code will read the value of the state parameter returned in the redirect and compare it to the initial value.
For this example, when the initial value of the state
parameter before authorization is not the same as the value returned in the redirectURL, we halt the authentication process.
Next, configure your PHP to use Authgear like this:
The League OAuth 2.0 client we are using in this example helps us generate random strings for the state
parameter. In the above code, we store the value for the state generated in session on the line with $_SESSION['oauth2state'] = $provider->getState()
;.
Add an else block for the if (!isset($_GET['code']))
condition with the following code:
The above code will prevent your PHP application from exchanging an authorization code for an access token when the value of state
stored in the PHP session is not identical to the state returned in the redirect URI. The usage demonstrated above can prevent CSRF attacks.
Force Authgear to always show login page even if the user have already logged in.
When user login / signup to Authgear, it usually starts with your application making a request to the authorization endpoint, which leads to a login or signup screen.
If the user is already signed in on the browser, the Single Sign On feature will show a "Continue Screen" instead as follows.
If your application do not want to utilize the Single Sign On feature, and always show the login / sign up screen instead, you can force Authgear to show login page by using prompt="login"
at the authorize
endpoint.
The following code shows how to set prompt: "login"
in Authgear SDKs:
If you are building token-based websites or mobile apps, you can enable the SSO feature via the SDK.
When SSO-enabled is ON, the end-user will need to enter their authentication credentials when they login to the first app. Later on, when they login to the second app, they will see a continue screen so that they can log in with just a click, without authenticating themselves again.
When the end-user logout the SSO-enabled app, all the apps will be logged out at the same time.
You can turn on this feature when you configure the SDK by setting the is sso enabled option to true
.
These type of SSO requires sharing the cookies between mobile apps and the system browsers on mobile, hence underlying it use ASWebAuthenticationSession
on iOS and Custom Tab
on Android, which will show a popup box like this:
Use the pre-authenticated URLs feature to open a website from a native app in an authenticated state.
Pre-authenticated URLs is a feature that enables single sign-on (SSO) from a mobile application to a website. It allows users who are authenticated on a mobile application to open a website in an authenticated state.
An example use case for a pre-authenticated URL is opening a web application in a WebView.
To use pre-authenticated URLs, you must have the following:
A native app using Authgear as authentication
A web application using the same Authgear project as authentication
First, ensure your mobile application uses an Authgear application with the Native App. Enable "preAuthenticatedURL" to allow pre-authenticated URLs to work.
Next, add an allowed origin to the web application client in Authgear. Navigate to Applications in the Authgear Portal, select the web application client, and scroll to the Allowed Origins section. Then, add the origin you wish to use for Pre-authentication URLs. Note that the origin should be of the format "protocol (scheme) + domain + port". For example, if the mobile application wants to open https://www.mywebapp.com/home?key=value
, the origin must be https://www.mywebapp.com
.
The Pre-Authenticated URL is a link that the Authgear SDK can generate for a mobile client that has the Pre-Authenticated URLs feature enabled. Your mobile application can open the Pre-Authenticated URL in a web view for users to start browsing the origin in an authenticated state.
To generate the Pre-Authenticated URL, call the makePreAuthenticatedURL()
method of the Authgear SDK as shown below:
The makePreAuthenticatedURL()
method accepts an object as a parameter. Inside the object, you should provide your web application's client ID and web app URI.
After the makePreAuthenticatedURL()
return the URL, your mobile application should open the URL in a WebView. From there, users should be able to continue their current authenticated session (from the mobile app) on the web application.
The following code sample shows how to open the pre-authenticated URL using the Browser.open()
method in Ionic.
The following code sample shows how to open the pre-authenticated URL using the Linking.openURL()
method of React Native.
The pre-authenticated URL is opened in the browser via the native app. In the web application, trigger authentication with the injected SSO session and get the authenticated state.
In the web application, enable SSO to allow pre-authenticated URLs to work. You can initialize the SDK as following
And in the web application URI, trigger authentication as following. Note here prompt: PromptOption.None
is used to skip the SSO continue screen.
In a normal login flow, for example the user browses the web page in the browser rather than from a link in the native app, the prompt should not be used because it will hinder the user from opening the login page. Only use this prompt when an SSO session is surely set in the browser, for instance in conjunction with this Pre-authentication URL feature.
SAML Attribute Mapping allows you to configure your Authgear client application to include additional fields in the SAML assertion. This is a great way to pass additional data from Authgear to your SAML application that depends on Authgear as an Identity Provider.
Authgear supports using SAML attribute mapping to include additional fields in the SAML assertion using any field in the user profile attributes (UserInfo).
There's also support for a template that can be used to customize the values of the fields before including them in the SAML assertion. For example, the template {{.preferred_username}}@example.com
will return the preferred_username
field from the UserInfo prepended to '@example.com'.
The above example creates three SAML attributes (family_name
, given_name
, placeholder_email
) that will be added to the SAML assertion.
The value for pointer
refers to a user profile attribute in the UserInfo object.
From an attribute that uses a template, the value in between the {{}}
also refers to a user profile attribute in the UserInfo object.
Add third-party identity providers to enable frictionless sign in for your users
Authgear supports the following social and enterprise identity providers. Please click the link below for setup instructions.
Guide on how to use Authgear as a SAML IdP for Dropbox
Security Assertion Markup Language (SAML) is a standard that allows an Identity Provider (IdP) and a Service Provider (SP) to perform user authentication and authorization without exchanging a user's password.
In this post, you'll learn how to set up Authgear as an Identity Provider and Dropbox as a Service Provider.
An Authgear account. Sign up for free.
A Dropbox Business Advanced account.
You need an Authgear client application of type OIDC/SAML Client Application
to use Authgear as a SAML identity provider.
To create a new client application, log in to Authgear Portal, select your project then click on the Applications link from the navigation menu.
Next, click on Add Application to create a new client application. Alternatively, select an existing application of type OIDC/SAML Client Application
and skip to step 2.
On the New Application page, enter Name and select OIDC/SAML Client Application
as the Application Type.
Click Save to proceed.
By default, SAML 2.0 is not enabled for the client application.
To enable SAML for your client application, click on the SAML 2.0 tab then toggle the SAML 2.0 Support switch on.
Next, change NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
.
Add the following URL (Dropbox post-back URL) in Allowed Assertion Consumer Service URLs (ACS URLs) field:
Click on Save to keep your changes.
Scroll down to the Configuration Parameters section of your Authgear client application's SAML 2.0 tab. Note the value for the login URL.
Also, download the Identity Provider Certificate for the client application to your computer.
You'll use the Login URL and certificate later in the Dropbox Admin console.
Log in to your Dropbox Business Advanced account then click on Admin console in the navigation menu.
In the Dropbox Admin console navigate to Settings > Single sign-on.
Now in the Dropbox Single sign-on settings page, set Single sign-on to Required. Then, configure the following:
Paste the value for your Authgear client application's Login URL
in the Identity provider sign-in URL
field.
Under X.509 certificate, click on the Certificate upload button, then upload the Identity Provider Certificate you downloaded from your Authgear client application in the previous step.
To test your SAML implementation, you need to add a new user to your Dropbox with an email address that is associated with a user account in your Authgear project.
To add a new user to your Dropbox, navigate to Admin console > People > Members > Invite member.
Accept the invite for the new user, and try to log in to Dropbox using the registered email address for the new user. You should be redirected to the Authgear SAML login page. On successful login to the Authgear account, you should be redirected and signed in to Dropbox.
Using Authgear as an OpenID Connect Provider for any OIDC compatible applications.
If your application supports logging in using an OpenID Connect provider, you can use Authgear as the provider.
Go to Applications on the left menu bar.
Click ⊕Add Application in the top tool bar.
Input the name and select the application type OIDC Client Application. Click "Save".
You will see a link to this guide that can help you for setting up, then click "Next".
In the URIs section, fill in the Authorized Redirect URIs with your application's redirect uri.
Obtain the OpenID Connect configuration:
You can obtain the Client ID and Client Secret from the Basic Info section.
You can obtain the OIDC Endpoints from the Endpoints section.
Provide the OpenID Connect configuration to your application.
🎉 Done! You should be able to use Authgear to log in to your application.
In this section, we are going to demonstrate how to use Authgear as the OIDC provider for WordPress login.
Go to Setting > OpenID Connect Client.
Fill in the form
Client ID: Obtain the Client ID from the Basic Info section.
Client Secret Key: Obtain the Client Secret from the Basic Info section.
OpenID Scope: Space separated list of scopes the plugin could access.
Example: openid offline_access https://authgear.com/scopes/full-userinfo
.
https://authgear.com/scopes/full-userinfo
is needed to obtain user's profile (e.g. email). Otherwise the plugin will be able to get the user id only.
Login Endpoint URL: Obtain Authorization Endpoint from the Endpoints section.
Example: https://{AUTHGEAR_APP_DOMAIN}/oauth2/authorize
.
Userinfo Endpoint URL: Obtain Userinfo Endpoint from the Endpoints section.
Example: https://{AUTHGEAR_APP_DOMAIN}/oauth2/userinfo
.
Token Validation Endpoint URL: Obtain Token Endpoint from the Endpoints section.
Example: https://{AUTHGEAR_APP_DOMAIN}/oauth2/token
.
End Session Endpoint URL: Keep it empty.
Identity Key: Where in the user claim to find the user's identification data.
Suggest to use sub
which is the user id in Authgear.
Setup the user claim keys based on your project login method setting.
If your project is using email to login
Nickname Key: Set it to email
.
Email Formatting: Set it to {email}
.
If your project is using phone to login
Nickname Key: Set it to phone_number
.
Email Formatting: Clear it.
If your project is using username to login
Nickname Key: Set it to preferred_username
.
Email Formatting: Clear it.
At the bottom of the plugin settings page, you will be able to obtain the Redirect URI. Go to Authgear portal, add the uri to the Authorized Redirect URIs.
Guides on how to use Authgear as a SAML Identity Provider
SAML allows the Identity Provider and Service Provider to authenticate and authorize without exchanging a user's password.
The Service Provider (SP): In SAML, this is the service that trust the Identity Provider to handle the process of user authentication.
The Identity Provider (IdP): handles user authentication and notifies the Service Provider once the user is authenticated.
Authgear supports the SAML protocol. Hence, you can set up third-party services like Salesforce, Dropbox, Figma, etc. to trust Authgear with the user authentication process.
See the following guides for some popular service providers:
To set up SAML in Authgear, you need to create an Authgear client application with the Application Type: OIDC/SAML Client
. Then use the configuration for the Authgear client application to configure a SAML IdP on the Service Provider's platform.
The following steps show more details on how to set up an OIDC/SAML Client Application in Authgear Portal.
Log in to Authgear Portal, then click on Applications from the navigation menu.
Click on Add Application to create a new client application. Or select an existing client application with the OIDC/SAML Client
type.
Enter a Name for the application and select OIDC/SAML Client Application as the Application Type.
Click Save to proceed.
By default, the SAML 2.0 Configuration is disabled for the client application.
Click on the SAML 2.0 tab then toggle SAML 2.0 Support switch to enable SAML 2.0.
You'll be required to enter at least one Allowed Assertion Consumer Service URLs (ACS URLs) before you can save your changes. Hence, get an ACS URL from the Service Provider you plan to use.
Visit the portal for the Service Provider you plan to use and add Authgear as an Identity Provider using the SAML configuration from your Authgear client application.
Refer to the following instructions for a generic SP:
Configuration on SP:
Enter the Identity Provider Metadata URL provided by Authgear if it's supported by the SP. e.g. https://[AUTHGEAR_ENDPOINT]/saml2/metadata/[CLIENT_ID]
If the SP does not support uploading an IDP metadata file, you can manually enter the parameters into the SP. These values can be copied from the application settings page:
Issuer: urn:[AUTHGEAT_ENDPOINT]
Login URL: https://[AUTHGEAR_ENDPOINT]/saml2/login/[CLIENT_ID]
Logout URL: https://[AUTHGEAR_ENDPOINT]/saml2/logout/[CLIENT_ID]
Identity Provider Certificates in PEM format: Download from the application settings page
Configuration on Authgear
Upload the Metadata XML file provided by your client application into the Authgear Portal
You may also manually enter the parameters into the application settings page in the Portal:
NameID Format
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
, or
When the format is unspecified
, you can choose to use the User ID, Email, Phone, or Username as the attribute value
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Allowed Assertion Consumer Service URLs (ACS URLs)
Response Destination (Optional)
Subject Recipient (Optional)
Assertion Audience (Optional)
Assertion Valid Duration (seconds), Default: 1200
Enable/Disable Single Logout (SLO)
SLO Callback URL
Callback Binding
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
, or
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
Enable/Disable message signature verification
Upload the SP's certificate in PEM format
You may find more detailed guides for adding IdP on the Service Provider's documentation.
Guides on how to add social login providers like Facebook, Google, LinkedIn Apple
See reference in Apple Developers Doc on and .
constraint
is an array that defines the requirement of security level, which can be BIOMETRIC_STRONG
, BIOMETRIC_WEAK
, DEVICE_CREDENTIAL
. See reference in Android developers documentation on
invalidatedByBiometricEnrollment
is a boolean that controls if the key pair will be invalidated if a new biometric is enrolled, or when all existing biometrics are deleted. See reference in Android developers documentation on .
You can set the policy for iOS and constraint for Android in the of the Authgear SDK. The following is an example of a biometric options that allows users to use device's PIN/Password in iOS and Android:
is not trivial. This guide provides a simple way to bootstrap your local application that communicates with the production Authgear server.
Log in and create a new project on
One quick simple way to do this is to use , you may follow the installation steps . After installing mkcert, generate a certificate with the following command:
In the above examples, nginx will also authenticate requests by creating sub-requests to the Authgear internal endpoint. You can learn more .
For implementing login and logout logic in your website, please refer to .
SSO between Websites with the same apex domain
Requires all of the websites with the same "root domain" (e.g. app1.example.com and app2.example.com)
SSO between Mobile Apps and Browsers
Requires the use of ASWebAuthentication
and Custom Tab
on iOS/Android respectively
SSO between two independent mobile apps
Based on OIDC App2App
SSO from a Mobile App to Website
Open a URL from Mobile App and pass the user session along, based on OIDC Token Exchange
SSO between Mobile Apps from the same publisher
Keychain Sharing / Android Account Manager ( if you need it)
Requires both apps published by the same publisher from App Store.
An Authgear account. Create one for free .
See our guide for instructions on how to get a Client ID and Client Secret for Facebook Login.
The key thing about using the above option is the presence of oauthProviderAlias: 'facebook'
in the authenticate()
method of the Authgear SDK. This parameter tells Authgear to redirect directly to an OAuth provider, given that the Social/Enterprise provider is configured properly as shown in . Also, the Social/Enterprise only Login method is enabled.
This is an Enterprise feature, please contact us for using the App2App flow in your project at
Please note that this is not the Single Sign-on feature, if your are offering multiple apps under the same brand and wish the users to use a shared login session among their apps in the device, you may want to use instead. App2app should be used when:
A detailed explanation on the technology can be found in .
This is an Enterprise feature, please contact us for enabling the App2App flow in your project at
Select Enable App2App login for this Application"
The includes an optional state
parameter. The value of the state
parameter can be any random string or number defined by a client application (e.g. a web or mobile that uses Authgear for user authentication) before making an authorization request. In fact, the state
parameter is added to the authorization URL as a URL query.
You can also use the value you specify in the state
parameter in an analytic tool (for example, as id
in the identify(id)
function) to track user's behavior pre-login and post-login.
To learn more about using the state parameter for tracking user behavior, see our detailed guide .
Create a new React project or use an existing project and configure the project to use Authgear. The following example is based on our .
This example uses the PHP package. Install the package using the following command:
The prompt="login"
parameter which is defined in the can force AuthUI to show the login page. Authgear SDKs have a prompt
parameter that can be used to set prompt="login". Once the prompt
parameter is set to login
Authgear will always show the login screen when your application calls the SDK's authenticate method.
If you want to avoid the said popup box, you will need to use WKWebView
on iOS and WebKitWebView
on Android for UIImplementation
instead; And use for sharing login session between mobile apps, and between mobile and web instead.
By default, only the sub
field of the is included in the SAML assertion. To include other fields like users' email address, phone number, etc., you can set up SAML Attribute Mapping for the fields.
To enable SAML Attribute Mapping for your Authgear project, .
Follow the previous section () to setup an OIDC Client Application.
We are going to use plugin . Or you can use any other OIDC compatible plugin. Download and activate it in your WordPress site.
Security Assertion Markup Language or short is a standard for exchanging security information between businesses. In SAML, one party acts as the Identity Provider (IdP), and the other party is the Service Provider (SP).
A guide on how to use Authgear as a SAML Identity Provider IdP in Salesforce
The Service Provider (SP) trust the Identity Provider to handle the process of user authentication. The Identity Provider handles user authentication and notifies the Service Provider once the user is authenticated.
In this guide, you'll learn how to set up SAML with Authgear as an Identity Provider (IdP) and Salesforce as the Service Provider (SP) in SAML.
A Salesforce account.
An Authgear Client application is required to set up Authgear as a SAML Identity Provider. To create an Authgear application, login to the Authgear Portal and navigate to the Applications in your project.
Click on Add Application to create a new application. Or, select an existing application that is of type OIDC/SAML Client Application
and skip to step 2.
Now on the New Application page, enter a name for your application (e.g. My App) and set the Application Type to "OIDC/SAML Client Application".
Click Save to continue.
If prompted to view a tutorial, click Next to proceed to the application configuration page.
On the configuration page of your Authgear client application, switch to the SAML 2.0 tab. Toggle the SAML 2.0 Support switch on to enable SAML for the application.
Next, change NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
.
Enter your Salesforce domain in the Allowed Assertion Consumer Service URLs (ACS URLs) field under SSO Settings. You can get value for your Salesforce domain from the My Domain page on the Salesforce Setup page.
Click on Save to keep your changes.
Still, on the SAML 2.0 tab, scroll to the Configuration Parameters section and click on the Download Metadata button to download the Identity Provider Metadata XML file for your Authgear application to your computer.
Next, scroll to the Identity Provider Certificates section and click Download Certificate to download the certificate to your computer.
You will use the downloaded metadata file and certificate in later steps.
To enable SAML in Salesforce, login to your Salesforce account, click on the Settings icon on the top right corner then select Setup. This will open the Salesforce Setup page.
On the Setup page, type "single sign-on" in the Quick find search box on the left. Select Single Sign-On from the result to open the Single Sign-On Settings page.
Next, click on the Edit button under Select Single Sign-On Settings then check the SAML Enabled box under Federated Single Sign-On Using SAML. Click Save to keep your changes.
To add Authgear as a SAML Identity Provider, return to the main page of Single Sign-On Settings.
On the next screen, you should see configurations for your new SAML IdP, including the details from the metadata file. Edit the Name field to Authgear SAML. The value for the Name field will be visible on your Salesforce login page.
Once you're done with the above configurations, click Save to finish.
In order to log in with a specific SAML IdP, you must first enable the provider in Salesforce.
To enable your new SAML IdP (Authgear SAML) search for "my domain" in Quick find. Click on My Domain from the result. On the My Domain page, scroll to Authentication Configuration then click on the Edit button.
You should find your Authgear SAMP IdP under Authentication Service. Check the box next to Authgear SAML to enable it. Click Save to keep changes.
Once you have enabled your SAML Identity provider in this step, it will be visible on your Salesforce login page the next time you attempt login.
Force you can log in to your Salesforce project using Authgear SAML, you need to create a user using an email address that is linked to a user account in your Authgear project.
To create a user in Salesforce, use type "users" in the Quick find search box, then select Users > Users from the result. This will take you to the All Users page.
From the All Users page, click on New User. Create a new user with an email address that's linked to an account on your Authgear project.
Now, to test your SAML implementation, log out of Salesforce and attempt logging in again. This time, you should see a Login with Authgear SAML button.
When you click on Login with Authgear SAML, you should be redirected to Authgear Login page. Login to the account on your Authgear project that has the same email address as the new user you created earlier in this step. You should be successfully logged in to your Salesforce project.
In "Authorization callback URL", use https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/github
.
After the creation, click "Generate a new client secret". Remember the client secret.
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with GitHub.
Fill in Client ID.
Fill in Client Secret.
Save the changes.
🎉 Done! You have just added GitHub integration to your apps!
Add Facebook Sign in to your apps in less than 5 minutes.
This guide shows how to connect your Authgear application to Facebook so users can log in using the Login with Facebook feature.
If you are using Authgear in your existing Facebook Apps, you may skip to the next step to set up the OAuth client.
On the next screen, select Other as your app use case then, click Next.
In the app type selection screen, pick the option that best meets your requirements. For our example, we'll select the Consumer app type.
Enter your app name on the next screen and finish the app creation process.
In the app panel, click Add Product next to Products in the sidebar.
Click the Set Up button in Facebook Login.
Go to Settings of Facebook Login.
Make sure Client OAuth Login and Web OAuth Login are enabled.
Add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/facebook
to Valid OAuth Redirect URIs and save the changes.
After setting up the Facebook Login product, go to App settings > Basic in the sidebar.
You will need the App ID and App Secret to configure Facebook Login so, note them down.
In the portal, go to Authentication > Social / Enterprise Login.
Enable Login with Facebook.
Fill in the Client ID with the App ID obtained from the Facebook Developers portal in the previous step.
Save the settings.
🎉 Done! You have just added Facebook Login to your apps!
Guides on how to integrate identity providers to Authgear
Security Assertion Markup Language or short is a standard for exchanging security information between businesses. In SAML, one party acts as the Identity Provider (IdP) and the other party is the Service Provider (SP).
An Authgear account. for free.
Next, click on the New from Metadata File button. Then, click Choose file, and select the Metadata XML file you downloaded in . Click on Create to continue.
Next, click on the Choose file button next to Identity Provider Certificate then select the SAML IdP Certificate file you downloaded in from your computer.
Follow the to create a OAuth App.
You will need a Facebook developer Account. Register as one by clicking Get Started in the website.
To create a new app, go to the Facebook Developers panel then click the Click Create App button.
See for instructions on how to get the value for YOUR_AUTHGEAR_ENDPOINT
.
Your end-users can now sign in with Facebook on Authgear's pre-built Log In and Sign Up page. Existing end-users can connect their account to Facebook in the page.
Setup your own AD FS server
Create an application in your AD FS Server, obtain "Client ID", "Client Secret" and "Discovery Document Endpoint". Discovery Document Endpoint typically ends with /.well-known/openid-configuration
. Configure your application with redirect uri https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/adfs
.
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with Microsoft AD FS.
Fill in Client ID, Client Secret and Discovery Document Endpoint.
Save the settings.
🎉 Done! You have just added Microsoft AD FS Login to your apps!
Choose "Supported account type", the following options are supported:
Accounts in this organizational directory only (Contoso AD (dev) only - Single tenant)
Accounts in this organizational directory (Any Azure AD directory - Multitenant)
Accounts in this organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
"Personal Microsoft accounts only" is not supported yet. Remember the account type chosen as this affects the configuration on Authgear portal
Configure "Redirect URI" with https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/azureadv2
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with Microsoft
Fill in Client ID with Application (client) ID of your just created Azure AD application.
Fill in Client Secret" with the secret you get after creating a client secret for your Azure AD application.
For Tenant field:
If single tenant (first option) is chosen, fill in the Directory (tenant) ID of your Azure AD application.
If multi tenant (second option) is chosen, fill in the string literal organizations
.
If multi tenant and personal account (third option) is chosen, fill in the string literal common
.
Save the settings.
🎉 Done! You have just added Azure Active Directory (Azure AD) Login to your apps!
Microsoft AD FS supports the prompt=login
parameter. You can include this parameter in your request when you want users to re-authenticate. See our in Authgear SDKs to learn more.
Create an Azure Active Directory (Azure AD) account
Setup a tenant by completing
Register an application by completing
Follow section to add a client secret. Remember to record the secret value when you add the client secret, as it will not be displayed again. This will be needed for configure OAuth client in Authgear.
Azure Active Directory automatically logs in to the same account without requiring a username and password. To prevent this behaviour, you can use the prompt=login
parameter to force Azure Active Directory to show the login page. See our in Authgear SDKs to learn more.
Integrate Authgear with your product
Cut down on implementation time by utilizing integrations that have been developed by Authgear. The Authgear platform is designed to be flexible, allowing you to meet your specific needs by customizing identity processes with your own code and easily integrating with other external applications and tools.
This set of how-to guides provides you with detailed instructions, code snippets, and configuration examples for each type of integration.
Configure "Redirect URI" with https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/azureadb2c
.
After creating the user flow, configure it
Open "Application Claims".
Make sure "Email Addresses" is checked.
If you have finished the above prerequisite, you should have the following information:
The Tenant Name, obtained in Step 2
The Application (Client) ID, obtained in Step 5
The Policy (User flow) Name, obtained in Step 7
Then in Authgear portal, do the following:
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with Microsoft Azure AD B2C.
Fill in Client ID with the Application (Client) ID above.
Fill in Client secret with the client secret you get when you create the app registration.
Fill in Tenant with the Azure AD B2C Tenant Name.
Fill in Policy with the Policy (User Flow) Name. Normally it starts with b2c_
.
Save the changes
🎉 Done! You have just added Azure AD B2C Login to your apps!
Use OIDC prompt parameter to force OAuth providers to show login screen.
In this post, you'll learn how to use prompt: "login"
in Authgear SDKs to force OIDC providers to always show your users their login screen. You can also use prompt: "login"
to allow users to switch accounts with a Social/Enterprise Login provider on the same device (or browser).
Authgear SDKs have a prompt
parameter that you can set in your application. The value of the prompt parameter will be passed to the Social/Enterprise Login provider. Hence, if you set prompt: "login"
in the SDK, your Social/Enterprise Login provider will receive a prompt="login"
parameter. The following code examples show how to use the prompt parameter in Authgear SDKs.
Sign in .
Create a B2C tenant by following .
Enable self-service sign-up for the tenant by following
Go back the main page of and search for "Azure AD B2C"
Create a app registration for Authgear by following .
Follow to create a sign-up and sign-in user flow.
Azure AD B2C automatically logs in to the same account without requiring a username and password. To prevent this behaviour, you can use the prompt=login
parameter to force Azure AD B2C to show the login page. See our in Authgear SDKs to learn more.
The prompt="login"
parameter which is defined in the can prompt Social/Enterprise Login Providers to always show their login screen. As a result, you can use the prompt="login"
parameter to allow users to switch accounts when their previous authentication session on the provider is still stored.
Guide on how to add LinkedIn as a social login provider
LinkedIn App
Go to the Auth tab of your LinkedIn app and take note of the "Client ID" and "Client Secret".
Also, add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/linkedin
to "Authorized redirect URLs" under "OAuth 2.0 settings" section.
Next, open the Products tab of your LinkedIn app, and request access to "Sign In with LinkedIn using OpenID Connect."
In the Authgear Portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with LinkedIn.
Then fill in the Client ID. and Client Secret from your LinkedIn app.
Save the settings.
🎉 Done! You have just added LinkedIn Login to your apps!
Learn how to add custom attributes to a JWT Access Token using Authgear
JWTs (JSON Web Tokens) are a common method for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. With Authgear, it is straightforward to add custom fields to your JWT access tokens.
Make sure the option Issue JWT as access token is enabled in your Application settings in the Portal.
Navigate to the Applications tab and choose the existing App.
On the App Configuration dashboard, locate the "Access token" section.
Make the toggle Issue JWT as access token switch on.
Navigate to your Authgear Dashboard's Advanced->Hooks section.
Add a new Blocking Event.
Choose the Block Hook Type as the TypeScript and set the Event option to JWT access token pre-create. You will write a new Typescript function from scratch.
Click on Edit Script under the Config option.
Copy and paste the following into the editor:
Click on Finish Editing.
Back to the Hooks page from the navigation bar and click on the Save button at the top of the page.
There are two ways to test it:
If you created the application type OIDC Client Application, you need to follow the steps below. Expand it to see instructions.
A LinkedIn Developer profile. You can create one on the .
Log in to the and create a new app or update the configuration for an existing one.
This how-to guide will walk you through the process of adding custom fields such as attributes to a JWT access token payload using Authgear and Javascript .
Here's an example of the and an explanation of their values.
You can also to on the Authegear Portal.
An Authgear account: You need an Authgear account to follow this guide. If you don't have one, you can on the Authgear website.
A Registered App: You need a (client) in Authgear.
Log into your .
With the use of Hooks, Authgear provides flexibility for adding custom logic to your authentication pipeline. You can create a Hook which is triggered any of these about to occur. For example, oidc.jwt.pre_create
the event happens just before issuing the JWT access token and it can be used to put extra information into the token.
In the above code, we are importing the necessary modules such as HookResponse
and EventOIDCJWTPreCreate
which are types from the Authgear hook . We modify the JWT payload by adding (e.payload.user.standard_attributes
) and (e.payload.user.custom_attributes
) of the user.
You can do this by on your application server side using a JWT decoder and inspecting the payload.
Finally, we can debug the access token using the to see if the custom field and value we added previously are there inside the JWT payload.
Monitor your Authgear implementation
You can monitor the Authgear app, and see and retrieve log event data.
Guides for changing the default SMS provider to your own custom provider
Authgear allows you to change the provider that sends text messages in your project.
You can access the settings for changing SMS provider from Advanced > Custom SMS Gateway in Authgear Portal.
When Custom SMS Gateway is enabled, you can select either of the following providers. Click on a provider for a detailed guide on how to configure it
Set up a custom domain to let your users access the Authgear pages with your unique, brand-centric domain name. You can use a custom domain (e.g. auth.yourdomain.com
) instead of the Authgear generated domain (e.g. <YOUR_APP>.authgear.cloud
).
Go to Branding > Custom Domains in your project portal.
Enter the custom domain name that you would like to connect to Authgear, and click Add.
Your custom domain will appear on the list, click Verify to start the verification process.
Go to your domain provider's site, and add DNS records based on the values shown on the portal page.
Click Verify after adding the DNS records, you may need to wait for the propagation of your updated DNS records.
You will return to the custom domain list after verifying your custom domain. Click Activate to use your custom domain.
Now you can access Authgear pages with your custom domain, your default Authgear generated domain (e.g. <YOUR_APP>.authgear.cloud
) cannot be used anymore. Update your SDK endpoint to use the new custom domain.
The certificate of your custom domain is managed by Authgear, you may need to wait for a while for certificate provisioning.
Users can access the login and logout pages directly in your Authgear project when you're using a custom domain. As a result, the post-login and post-logout links are available to help you determine where users are redirected when they access the above pages without an OAuth flow.
To configure these values, in Authgear Portal navigate to Branding > Custom Domains. Then scroll down to the Default Redirect URLs section.
Use this field to set the page where users will be redirected after login if they visit the login page directly instead of going through an OAuth flow.
The URL you enter as a post-logout link is where users will be redirected after logout when they visit the logout page directly.
Add Google Sign in to your apps in less than 5 minutes.
To configure Google OAuth client for Authgear, you will need to create an OAuth client on Google Cloud Platform first.
Click Create Credentials -> OAuth client ID
Choose Web application in Application type and assign a name as reference. You should always choose Web application here regardless of the platform of the app you are creating. It is because this OAuth Client ID is used by your Authgear services, which is a web application in Google’s classification.
In Authorized JavaScript origins, add your Authgear endpoint, e.g. https://myproject.authgear.cloud
In Authorized redirect URIs, add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/google
. For example, https://myproject.authgear.cloud/sso/oauth2/callback/google
After creating a client ID, you will see the client ID under the OAuth 2.0 Client IDs section of the Credentials page.
After creating an OAuth client, click the name of OAuth client to view the details.
You will need the values of Client ID, Client secret to configure Google Sign In.
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with Google.
Fill in the Client ID and Client Secret with the values obtained from the previous step.
Save the settings.
🎉Done! You have just added Google Sign In to your apps!
To create a website application in WeChat, you can choose to setup a website application and wait for approval or a sandbox account for testing.
Create Website Application (网站应用), fill in information and wait for approval (It may take few days).
View the application detail page, obtain the "AppID" and "AppSecret" on the top of the application page.
Go to Account Center > Basic information, to obtain the "原始ID".
Obtain the "appID", "appSecret" and "原始ID". The "原始ID" is the "微信号" in the top right corner.
Fill in 接口配置信息. The URL must be pointing at a publicly reachable server. The token is a string of your choice.
Implement the 接口配置信息 server. Here is an example written in Golang.
Fill in JS接口安全域名. The value is your Authgear domain name plus port, e.g. 192.168.2.88:3000
or myapp.authgear.cloud
Fill in 网页授权获取用户基本信息. The value is your Authgear domain name plus port, e.g. 192.168.2.88:3000
or myapp.authgear.cloud
Look for an QR code in the sandbox settings page. You must scan it with your Wechat app and follow the sandbox account.
In the portal, do the following:
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with WeChat (Web/网站应用).
Fill in Client ID with the AppID.
Fill in Client Secret with the AppSecret.
Fill in 原始 ID with the 原始 ID.
Check the checkbox Is Sandbox account if you are using sandbox account.
Save the settings.
Wechat integration is a bit more complicated then other social login, here are the overview of what needs to be done:
Register an account and create mobile application in WeChat Open Platform. Approval is needed in this process.
Enable and configure WeChat Login in Authgear portal.
Include Authgear SDK on your app.
Implement a delegate function to be triggered when user clicks the "Login with WeChat" button during authorization. You need to integrate WeChat SDK to open WeChat app to perform authentication in the delegate function (we have sample code below). After obtaining the authorization code from WeChat, call the Authgear callback with the auth code and complete the "Login With WeChat" process.
Here are the detailed steps for iOS, Android, React Native, and Flutter.
Create Mobile Application (移动应用), fill in information and wait for approval (It may take few days).
View the application detail page, obtain the AppID
and AppSecret
on the top of the page.
Go to Account Center > Basic information, to obtain the "原始ID".
Save those values, we will need them in the section below.
Setup Authgear iOS SDK.
After setting up the WechatOpenSDK
, universal link should be enabled in your application. We will need two links for the setup. One is for the WeChat SDK used, another is for the Authgear SDK to trigger delegate function when user click "Login with WeChat" button. Here are the suggestion of the links.
WECHAT_UNIVERICAL_LINK: https://{YOUR_DOMAIN}/wechat
WECHAT_REDIRECT_URI_FOR_AUTHGEAR: https://{YOUR_DOMAIN}/open_wechat_app
Login WeChat Open platform, open the application detail page, update the development information iOS section.
Fill in "Bundle ID" field with your app bundle id.
Fill in "Universal Links" with "WECHAT_UNIVERICAL_LINK" above.
Go to Authgear portal, do the following:
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with WeChat (Mobile/移动应用).
Fill in Client ID with the AppID.
Fill in Client Secret with the AppSecret.
Fill in 原始 ID with the 原始 ID.
Add WECHAT_REDIRECT_URI_FOR_AUTHGEAR above in WeChat redirect URIs.
Save the settings.
Update the code
Setup WeChat SDK when app launch
Setup Authgear delegate and call WeChat SDK when sendWechatAuthRequest
is triggered
Handle universal link
Provide wechatRedirectURI
when calling authenticate
and promoteAnonymousUser
in authgear sdk
Setup Authgear iOS SDK.
Login WeChat Open platform, open the application detail page, update the development information Android section.
Fill in application signature, you can obtain it with command keytool -list -v -keystore YOUR_KEYSTORE_FILE_PATH
. WeChat needs the certificate fingerprint in MD5, remove :
in the fingerprint. It should be string in length 32.
Fill in your package name
We will need to define a custom url for Authgear SDK to trigger delegate function when user click "Login with WeChat" button. Here is the example, you should update it with your own scheme.
"WECHAT_REDIRECT_URI_FOR_AUTHGEAR": com.myapp://host/open_wechat_app
Go to Authgear portal, do the following:
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with WeChat (Mobile/移动应用).
Fill in Client ID with the AppID.
Fill in Client Secret with the AppSecret.
Fill in 原始 ID with the 原始 ID.
Add WECHAT_REDIRECT_URI_FOR_AUTHGEAR above in WeChat redirect URIs.
Save the settings.
Update the code
Update application AndroidManifest.xml
Configure WeChat SDK
Setup Authgear delegate
Create wxapi directory in the directory named after your package name and create WXEntryActivity
activity. In WXEntryActivity
, pass the received intent and the object that implements IWXAPIEventHandler API to the handleIntent
method of the IWXAPI
API, as shown below:
You will be able to receive the authentication code and state in onResp
method, call Authgear wechatAuthCallback
with code
and state
.
Provide wechatRedirectURI
when calling authorize
and promoteAnonymousUser
in Authgear SDK.
Setup Authgear SDK
In iOS, after setting up the WechatOpenSDK, universal link should be enabled in your application. We will need two links for the setup. One is for the WeChat SDK used, another is for the Authgear SDK to trigger delegate function when user click "Login with WeChat" button. Here are the suggestion of the links.
IOS_WECHAT_UNIVERSAL_LINK: https://{YOUR_DOMAIN}/wechat
IOS_WECHAT_REDIRECT_URI_FOR_AUTHGEAR: https://{YOUR_DOMAIN}/open_wechat_app
In android, you need to sign your app to use WeChat SDK. Obtain your application signature by running command keytool -list -v -keystore YOUR_KEYSTORE_FILE_PATH
with your keystore file. WeChat needs the certificate fingerprint in MD5, remove :
in the fingerprint. It should be string in length 32.
Login WeChat Open platform, open the application detail page, update the development information iOS and Android sections.
In iOS
Fill in "Bundle ID" field with your app bundle id.
Fill in "Universal Links" with "IOS_WECHAT_UNIVERSAL_LINK" above.
In Android
Fill in application signature.
Fill in your package name
For android, we will need to define a custom url for Authgear SDK to trigger delegate function when user click "Login with WeChat" button. Here is the example, you should update it with your own scheme.
ANDROID_WECHAT_REDIRECT_URI_FOR_AUTHGEAR: com.myapp://host/open_wechat_app
Login Authgear portal, go to "Single-Sign On" page, then do the following:
Enable "Sign in with WeChat (Mobile/移动应用)"
Fill in "Client ID" with the WeChat "AppID".
Fill in "Client Secret" with the WeChat "AppSecret".
Fill in "原始 ID" with the WeChat "原始 ID".
Add "IOS_WECHAT_REDIRECT_URI_FOR_AUTHGEAR" and "ANDROID_WECHAT_REDIRECT_URI_FOR_AUTHGEAR" above into "WeChat redirect URIs"
Click save.
Update the code
In Android, Update application AndroidManifest.xml
.
In iOS, update your App Delegate
Provide wechatRedirectURI
when calling Authgear SDK authorize
and promoteAnonymousUser
in js
Setup Authgear delegate and open WeChat SDK when sendWechatAuthRequest is triggered
Setup Authgear SDK
In iOS, after setting up the WechatOpenSDK, universal link should be enabled in your application. We will need two links for the setup. One is for the WeChat SDK used, another is for the Authgear SDK to trigger delegate function when user click "Login with WeChat" button. Here are the suggestion of the links.
IOS_WECHAT_UNIVERSAL_LINK: https://{YOUR_DOMAIN}/wechat
IOS_WECHAT_REDIRECT_URI_FOR_AUTHGEAR: https://{YOUR_DOMAIN}/open_wechat_app
In android, you need to sign your app to use WeChat SDK. Obtain your application signature by running command keytool -list -v -keystore YOUR_KEYSTORE_FILE_PATH
with your keystore file. WeChat needs the certificate fingerprint in MD5, remove :
in the fingerprint. It should be string in length 32.
Login WeChat Open platform, open the application detail page, update the development information iOS and Android sections.
In iOS
Fill in "Bundle ID" field with your app bundle id.
Fill in "Universal Links" with "IOS_WECHAT_UNIVERSAL_LINK" above.
In Android
Fill in application signature.
Fill in your package name
For android, we will need to define a custom url for Authgear SDK to trigger delegate function when user click "Login with WeChat" button. Here is the example, you should update it with your own scheme.
ANDROID_WECHAT_REDIRECT_URI_FOR_AUTHGEAR: com.myapp://host/open_wechat_app
Login Authgear portal, go to "Single-Sign On" page, then do the following:
Enable "Sign in with WeChat (Mobile/移动应用)"
Fill in "Client ID" with the WeChat "AppID".
Fill in "Client Secret" with the WeChat "AppSecret".
Fill in "原始 ID" with the WeChat "原始 ID".
Add "IOS_WECHAT_REDIRECT_URI_FOR_AUTHGEAR" and "ANDROID_WECHAT_REDIRECT_URI_FOR_AUTHGEAR" above into "WeChat redirect URIs"
Click save.
Update the code
In Android, Update application AndroidManifest.xml
.
Provide wechatRedirectURI
.
Provide sendWechatAuthRequest
Authentication for PHP websites with Authgear and OAuth2
Using OAuth, you can use Authgear to add user authentication in a vanilla PHP application.
In this guide, we'll cover how to implement OAuth 2.0 login in a regular PHP web application with Authgear as the Identity Provider.
At the end of this post, you'll learn the following:
How to create an Authgear Application
How to enable email and password sign-in
How to sign in with Authgear from a PHP app
How to request user info from Authgear
How to use a refresh token
And finally how to log users out and revoke access tokens.
To follow along, you'll need the following:
PHP runtime (E.g XAMPP for testing offline on Windows devices)
Your preferred code editor (e.g VS Code).
In this guide, we'll build a basic PHP application that lets a user sign in with their registered email and password.
The application will welcome the user with their email address after they sign in successfully. If the user is not signed in, the application will display links to Register or Login.
The following screenshot shows what the User Interface for the app will look like:
Now let's dive into the actual steps of how to add Authgear to a PHP application.
Under this section, we will cover the steps for configuring the Authgear application our PHP website will be connecting to. We'll do all these configurations in the Authgear Portal.
To do that, log in to the Authgear Portal, and select your project (or create a new one if you don't have any yet). From your project dashboard navigate to the Applications section and enter the details for your new application as shown below:
Once you're done, click on the Save button to continue. Then, click on Next to see the configuration page for your application.
The application configuration page contains basic information like Client ID
and Client Secret
that we'll use later in this tutorial. Hence, try to note the values down.
In addition to basic information, you can find other configuration information including endpoints and Authorized Redirect URIs.
The Authorized Redirect URIs section contains a link to the page you want Authgear to redirect users to after login.
Update the value for Authorized Redirect URIs to a page on your application. For our example PHP application the value will be http://localhost
because we plan to test run it offline using XAMPP. Also, try to note this value down as we'll be using it in later steps.
Here we will cover the steps for implementing a PHP website that interacts with Authgear using the Open ID Connect (OIDC) standard.
Create a new PHP project on your computer and add an index.php
file to the root of the project folder.
Add the following code to index.php to create the User Interface of the example app.
Note: The Login and Logout links in the above code currently point to login.php and logout.php respectively, we'll create both files later.
In this step, we'll add our Authgear application configuration to the PHP project.
Install the package manually from Github or via Composer by running the following command from your PHP project's root directory:
Next, after the package is installed, create a new config.php
file in the PHP project folder. Add the following code to the file:
Note: Replace the values for clientId
, clientSecret
, redirectUri
with corresponding values from the Authgear application you created in Step 1.
Including the offline_access
scope is required to get a refresh token from Authgear.
The flow for Login on our app is as follows:
The user clicks on the Login button
User is redirected to the Authgear authorization page where they can sign in using email and password or any other sign-in methods you have enabled for your Authgear project.
The user is redirected back to your website with an authorization code.
In order to implement the above, you need to create a login.php
file in your project's root directory. Add the following code to the login.php file:
At this point, if you try running the example app in a browser and click the Login link in index.php, your app should redirect to the Authgear login page. If you sign in successfully, you should be redirected back to the redirect URL you specified earlier in your project configuration.
Authgear will redirect to your Authorized Redirect URI with extra parameters like code
or an error message in the URL. The value for the code parameter is your authorization code. In the next step, we'll use the authorization code to generate an access token.
Usually, after successful sign-in, you'll want to start using the current user's info to offer custom experience in your app.
In this step, we'll use the PHP OAuth 2.0 Client once more to interact with our Authgear app.
First, open index.php
and search for the line with the following code:
Replace the above line with this code:
The above code exchanges the authorization code returned in the redirect for an access token. It then stores the access token in the PHP session so that we can use this token in future requests to protected resources.
Now that we have the access token, let's try to get the current user's details. To do that, update the HTML part in index.php like this:
Now test the app on your browser again and you should get the following page after login:
We've successfully added user authentication to our PHP app using Authgear as the identity provider. The above page displays a welcome message with the email address the user registered with on your Authgear project. You can display other info about the user from the value of $userInfo
variable.
In OAuth 2.0, a refresh token is a key that's usually included in the response from the token endpoint when a client application exchanges the authorization code for an access token.
Access tokens expire after some time. Hence, we can use this refresh token to request a new access token without requiring our application users to log in again. In this step, we'll show you how to use the refresh token.
In the last step, we stored the value for the refresh token in the $_SESSION['refreshToken']
variable. So, to get the refresh token, simply read the value from that variable.
Now, add the following code to index.php to read and use the refresh token to get a new access token:
First, find the line with the following code:
Replace that line with the following blocks of code:
Note: It is required to include offline_access in your OAuth 2.0 scopes to get a refresh token from Authgear.
Authgear provides a token revoke endpoint that you can use to revoke a refresh token and all the access associated with it.
To use the token revoke endpoint to log users out of your application, create a new logout.php
file in your project directory then add the following code to the file:
The above code will revoke your refresh token and delete all the session variables.
In this post, we covered how to get started with adding Authgear to a regular web app built with PHP and no framework.
We also tried out an example of using the Authgear authorization code to retrieve an access token, then we used the token to access the user info endpoint.
Integrate Authgear to your website with the Web SDK
Your application can send the access token in subsequent HTTP requests to access protected resources.
Follow this guide to add Authgear SDK to any web application in under 🕐 10 minutes.
This guide uses the Authgear Web SDK for integrating Authgear with a SPA Web app. Supported browsers include:
Last 2 Firefox major versions
Last 2 Chrome major versions
Last 2 Edge major versions
Last 3 Safari major versions
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project.
Go to Applications on the left menu bar.
Click ⊕Add Application in the top toolbar.
Input the name of your application and select the application type Single Page Application. Click the Save button to proceed.
On the next screen you will see a list of tutorials for different frameworks, click on Next to skip to your client application configuration page.
First, decide the paths in your website that users will be redirected to after they have authenticated with Authgear.
To run the demo app in this tutorial offline, scroll to the URIs section of your client application page add the following URI:
Under Authorized Redirect URIs add http://localhost:3000/
Click on the Save button to keep your changes.
In this section, we'll create a simple web page and use the Authgear Web JavaScript SDK to add user authentication to the page.
For this guide, we'll create a basic web application with only one page. Follow these steps to set up the application. First, create a new directory on your computer for the project. You can do this in a terminal using the following commands:
We'll create an Express.js server in the web project directory so that we can access the HTML page in a web browser using http://localhost:3000
. Run the following commands from the root of your web project directory to install Express.
First, generate a package.json file in your project directory:
Install the Express npm package:
Install Nodemon (used for adding hot road to JavaScript development):
Now create a server.js
file in the root folder of your project. Add the following code to server.js:
Next, open the package.json
in your project directory and add the following lines in the script section:
Create a new file called index.html
in the root of your project directory. Add the following code to the file:
The content index.html
is a simple web page that contains some text, a Log in button, and a Log out button. In later steps, we will implement the onclick
events for both steps such that each calls the correct function from the Authgear Web JavaScript SDK.
The Web JS SDK is available on a CDN that you can include in any webpage using the following script tag:
We recommend that you use the npm package to add Authgear to your web application when you're using build tools like Vite and Webpack, and when building with frameworks like React, Vue, Angular, etc.
The easiest way to add a JavaScript library such as the Authgear SDK to a generic Single Page Application (a basic .html
file page), is to use a CDN. Hence, we'll use the CDN method to add the Authgear Web JavaScript SDK to our demo application for this tutorial.
To install the Authgear SDK, add the Authgear SDK CDN <script> tag to index.html
on a new line just before the </body>
. Your index.html should look like this at this point:
With that, we have added the Authgear SDK to a basic HTML page and we are ready to start making calls to its functions.
At this point, the structure of your project folder should look like this:
To test your progress so far save your files then run the npm run dev
command. Next open localhost:3000
on your preferred web browser and you should see a page that looks like this:
Create a new public/js
directory in the root of your project directory.
Create a new file called app.js
in the public/js
directory. Add the following content to app.js
:
In app.js, the configureClient()
function gets an instance of the Authgear Web SDK (authgearClient
) and then calls the configure()
function of the SDK to initialize Authgear.
You can find value for clientID
and endpoint
from your Authgear client application configuration page.
Finally, link app.js
in index.html
using <script src="js/app.js"></script>
just above the line with the Authgear CDN <script>
tag as shown below:
When the user clicks login/signup on your website, make a start authorization call to redirect them to the login/signup page (AuthUI).
In this step, we'll implement the login()
function that is called when the Log in button is pressed.
Update app.js
by adding the following code after the declaration of the configureClient()
function:
After the user authenticates on the login page, the user will be redirected to the redirectURI
with a code
parameter in the URL query. In the redirectURI
of your application, make a finish authorization call to handle the authentication result. This will attempt to exchange the code
for the access token and user info.
Once authorization succeeds, the application should be able to display user info and access protected resources.
To handle the redirect after authentication, we'll call the Authgear SDK's finishAuthentication()
function when there's a code parameter in the URL of the current page. To do that, update the window.onload
callback in app.js to the following:
The updateUI()
function will update the state of the webpage when the user's logged-in state changes. Add the following code to the end of app.js to implement updateUI
:
The complete content of app.js at the end of this step should look like this:
At this point, your file structure should look like this:
Save all changes in your code, and rerun your app on a web browser. This time, clicking on the Log in button should redirect you to your Authgear project's user login page (AuthUI).
To add a User Settings button to your app, add the following tag to your index.html
just below the Logout button:
Next, add the following code to app.js
: just below the logout()
function:
Finally, add the following line to the end of your updateUI()
function so that the User Settings button is displayed when the user is authenticated:
Save your work and run your app again. When you click on the User Settings button, your web app should open the pre-built User Settings page.
When you start launching the application. You may want to know if the user has logged in. (e.g. Redirect users to log in if they haven't logged in). The sessionState
reflects the user logged-in state in the SDK local state. That means even thesessionState
is AUTHENTICATED
, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call fetchUserInfo
to update the sessionState
as soon as it is proper to do so.
The value of sessionState
can be UNKNOWN
, NO_SESSION
or AUTHENTICATED
. Initially the sessionState
is UNKNOWN
. After a call to authgearClient.configure
, the session state would become AUTHENTICATED
if a previous session was found, or NO_SESSION
if such session was not found.
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the fetchUserInfo
function to obtain the user info.
Use the logout
function to log out the user. The user will be redirected to your Authgear endpoint to log out their session. You should provide the redirectURI
for the user to return to your app.
Once you have logged-in user, you can start making authenticated requests to backend APIs as described below.
There are two ways to include the access token in the HTTP requests to your application server.
You can get the access token through authgearClient.accessToken
. Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call to refresh the access token only if it is expired. Include the access token in the Authorization header of the application request.
How to integrate with a React Native app
This guide provides instructions on integrating Authgear with a React Native app. Supported platforms include:
React Native 0.60.0 or higher
Follow this guide to add Authgear to your React Native app in 🕐 10 minutes.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project.
Go to Applications on the left menu bar.
You'll see the "New Application" page, or Click ⊕Add Application in the top tool bar.
Input the name of your application and select Native App as the application type. Click "Save".
On the next screen, you will see a list of guides that can help you with setting up, click "Next" to continue.
In your IDE, define a custom URI scheme that will be used to redirect users back to your app after they have authenticated with Authgear. For example, in our example app, we will define the following URI scheme:
Now head back to Authgear Portal, and add the URI that you have defined (com.authgear.example.rn://host/path
for this example) as an Authorized Redirect URI.
Click "Save" and note the Client ID and Endpoint for your Authgear client application. You can also obtain it again from the Applications list later.
In this section, we'll walk through the steps to create a new React Native app and use the Authgear SDK to add user authentication to the app.
Run the following command to create a new React Native project:
Run the following commands from the root directory of your React Native project to install the Authgear SDK:
In this step, we'll implement the code to initialize an instance of the Authgear SDK which we will be using to interact with the Authgear client application we created earlier.
First, open the App.tsx
file in your project then add the following import statements at the top:
Add the following code at the top inside the App()
function in App.tsx
to configure a new Authgear instance and set up a delegate
that will help our app to know the current state of a user's session (whether they're logged in or not):
Replace <CLIENT_ID>
and <AUTHGEAR_ENDPOINT>
with the Client ID and Endpoint for your Authgear client application.
The above code includes a postConfigure()
method that helps to get the true session state for a user that was previously logged in.
Replace the content for the return
statement in the App()
function inside the App.tsx
file with the following:
Import the necessary components at the top App.tsx
:
In this step, you will implement an authenticate()
method that calls the authenticate()
method of the Authgear SDK. The Login button we added in the previous step calls this authenticate()
method to start an authentication flow.
Add the following code to the App()
function just after the useEffect()
for the configure()
method in step 3:
At this point the complete code in your App.tsx
should look like this:
Now save your work and try running your app on Android or iOS using any of the following commands:
Android
iOS
When your app opens, if you click on the Login button, you should be redirected to the Authentication UI. However, you can't complete authentication because we are yet to handle the redirect URI.
To finish the integration, set up the app to handle the redirect URI specified in your Authgear client application. This part requires platform-specific integration.
Add the following activity
entry to the android/app/src/main/AndroidManifest.xml
of your React Native project. The intent system would dispatch the redirect URI to OAuthRedirectActivity
and the sdk would handle the rest.
You also need to add a queries
section to AndroidManifest.xml
.
In ios/<your_project>/Info.plist
, add the matching redirect URI.
Now let's add a Logout feature to our example app so users can logout and end their session.
We'll add a Logout button and implement a logout()
method that calls the corresponding logout()
method of the Authgear SDK:
Add a logout()
method to your App()
function after the authenticate() method you added earlier:
Next, add the Logout button and call the logout() method from onPress. Add the button to the return statement for App()
just below <Text style={{paddingTop: 50, paddingBottom: 16}}> Welcome User</Text>
:
Save your code and run the app. Click the Logout button and the user should be logged out.
The Authgear SDK includes a fetchUserInfo()
method that returns details such as user ID, email, phone number, etc about the current user.
In this step, we'll add a Show User Info button to our app. This button will call the fetchUserInfo() to demonstrate how the method works.
Add a showUserInfo()
method to your App()
function just below the logout()
method:
The showUserInfo()
method calls the fetchUserInfo()
method of the Authgear SDK and displays the data returned in an Alert
.
Next, add the Show User Info button to the return statement of App()
just below the Logout button from the previous step:
Authgear offers a pre-built User Settings page for users of your application to view and modify their profile and security details.
In this step, we'll use the open()
method in the Authgear SDK to open this User Settings page when a logged-in user clicks on a button.
Add an openSettings()
method to your App()
function just below the showUserInfo() from the previous step:
Next, add a User Settings button to the return statement of App()
just below the Show User Info button:
Now run your app and you should be able to access the User Settings page when you click on the User Settings button.
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users the login page if they haven't logged in).
The sessionState
reflects the user logged-in state in the SDK local state. That means even if the sessionState
is AUTHENTICATED
, the session may be invalid if it is revoked remotely. Hence, after initializing the Authgear SDK, call fetchUserInfo
to update the sessionState
as soon as it is proper to do so. We demonstrated this in our example app using the postConfigure()
method.
The value of sessionState
can be UNKNOWN
, NO_SESSION
or AUTHENTICATED
. Initially, the sessionState
is UNKNOWN
. After a call to authgear.configure()
, the session state would become AUTHENTICATED
if a previous session was found, or NO_SESSION
if such session was not found.
To include the access token in the HTTP requests to your application server, there are two ways to achieve this.
You can access the access token through authgear.accessToken
. Call refreshAccessTokenIfNeeded()
every time before using the access token. The refreshAccessTokenIfNeeded()
function will check and make the network call to refresh the access token only if it has expired.
Include the access token in the Authorization header of your application request.
Guide on how to use Authgear in an Ionic project
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.
Connect with any SMS providers with webhook or custom scripts for communication with the users.
In this guide, you'll learn how to switch from the default SMS provider to just about any third-party SMS provider.
An SMS provider with an API endpoint that accepts external HTTPS requests.
An Authgear project with the Custom SMS Gateway feature enabled.
To enable Custom SMS Gateway, log in to Authgear Portal, and navigate to Advanced > Custom SMS Gateway.
Toggle the Enable Custom SMS Gateway switch on to enable Custom SMS Provider.
Select Webhook under SMS Gateway Provider to set up a custom SMS provider using Webhook.
Alternatively, select Custom JS/TS to set up a custom SMS provider using custom JavaScript/TypeScript code in your Authgear project.
A key thing to consider before implementing your webhook or custom script is the structure of the payload your Authgear application will send to your endpoint.
The following is the structure of the JSON payload for custom SMS webhook and custom JS/TS (CustomSMSGatewayPayload
).
to
is the phone number of the receiver.
The body
field contains the actual message.
app_id
: is the identifier for the Authgear project sending the SMS.
language_tag
: a tag specifying the language of the message.
template_variables
: this is an object with all the variables that are used to add dynamic content such as OTP code
, the app_name
of your app, etc, to the SMS template.
For Webhook, follow these steps to configure the options:
Webhook Endpoint: enter the full URL for the page in your application that will receive the payload from Authgear's webhook request and use it to send the SMS.
JSON Payload Sample: this section shows the structure of the JSON payload. The key payload includes a to
and a body
field.
Timeout: enter a value between 1 to 60. Use a number close to the maximum if your webhook requires more time to respond.
Implement the logic for sending an HTTPS request to your custom SMS provider in the Custom script editor.
The default sample code can be used as a good base for starting out:
Replace https://some.sms.gateway
with the actual endpoint for your SMS provider.
The following example shows how to send SMS via Custom JS/TS:
In the above example, we read the values of to and body from Authgear's CustomSMSGatewayPayload
(e) and used it to build the format of JSON data our custom SMS gateway expects.
See the official documentation for your SMS gateway to learn more about how to structure your HTTPS request.
Both the Webhook and JavaScript/TypeScript share the same response. The following shows the schema of the response your webhook or custom script should send to Authgear for better user experience and error handling:
code
: this field is required, and the value can be one of the following strings:
ok
: return this code if the sms is delivered successfully.
invalid_phone_number
: return this code if the receiver's phone number is invalid.
rate_limited
: return this code if some rate limit is reached, and the user should retry the request.
authentication_failed
: return this code if some form of authentication has failed, and the developer should check the current configurations.
delivery_rejected
: return this code if the sms delivery service rejected the request for any reason the user cannot fix by retrying.
provider_error_code
: this is an optional field to include an error code that could appear on Authgear Portal and assist debugging. A good way to use this field is to put the error code returned by your custom SMS provider (e.g., Twilio). The value should be a string.
Finally, click on the Save button to save your new custom provider settings.
To test your work, click on the Test button next to the Save button, enter your phone number, and then click Send to test your new SMS provider.
Authgear provides the event logs for you to analyze security issues and monitor the business.
The portal provides an interface for you to look up the log by event and date range.
The Users Activities tab on the Audit Log page filters the log to only show activities performed by a normal user or by an admin on a user's profile.
When using the Admin API, you can filter the Audit Log by an attribute like activityTypes to omit records you're not interested in.
The following is an example that includes filters.
The above query will only return events with activity types USER_AUTHENTICATED
and USER_DELETED
.
Here is the list of activity types that are logged:
Each audit log event contains the following attributes in their data
See information about the total number users and active users on your Authgear project
The Analytics section on the Authgear portal provides reports on your project activities. For example, the report shows the total number of users that sign up and active users over a specific time interval.
In this guide, you'll get detailed information about the information provided on the Authgear Analytics page and how to interpret it.
The Analytics page shows two activity bar charts that show a weekly or monthly summary of user activities on your Authgear project.
The first chart shows the total active users per week or month. Active users are users who sign up, log in, or access their accounts within a specific time.
The second bar chat in the Activities section shows the total number of users your Authgear project has over a specific time interval. That is the total number of accounts created minus deleted users.
The signup conversion piechart shows how many users visited your signup page (unique pageviews) and how many went ahead to complete the signup process. This report also shows a percentage of the signup conversion (unique pageviews vs. total signups).
This section shows how many users you have per signup method in a pie chart.
Note: The data on the Analytics page may take 24 hours to be updated.
The Admin API & Portal tab in the Audit Log page allows you to analyze and monitor changes and activities that occur on Admin API and the Authgear Portal of your project.
The data under this tab can be handy for securing your Authgear project. For example, whenever an admin on your project downloads the Admin API key, the event is registered under the Admin API & Portal tab.
Activity logs for Admin API and Portal are part of the data the auditLogs query returns.
For example, the following query will return any recent events from Admin API and Portal that have been logged:
Note: The above request will also include events triggered by users.
The following is a list of the activity types that are logged:
Use the user import API to bulk import users from external systems to your Authgear project
Some ways to add users to your Authgear project include; using the Add User UI in Authgear Portal, using the createUser() mutation in Admin API, and last but not least, having the user accounts created using sign-up page on AuthUI.
A common downside of all the above-listed methods is that they do not support batch import of users. Meaning, that you have to add users one by one. This isn't ideal for importing multiple users from existing legacy systems to Authgear. For adding bulk users, there is the User Import API.
In this post, you'll learn what the User Import API is and see examples of how to import bulk users to an Authgear project.
The following are the endpoints for the User Import API.
Use this endpoint to start a new user import task.
Use this endpoint to verify the status of an existing user import task.
In this section, you can find code for a simple example of using the User Import API to add multiple users to an Authgear project.
To follow this example and be able to run the code on your local machine, you must have the following:
Install Express.js by running the following command from your project directory: npm install express
.
As mentioned earlier in this post, the User Import API requires the Admin API JWT to access. In this step, we'll generate an Admin API JWT using Node.js.
First, install JsonWebToken (a Node package for generating JWT) by running the following command:
The following code shows how to get the token:
To import users to your Authgear project using the User Import API, make a POST HTTP(S) request to the Initiate Import endpoint (/_api/admin/users/import
).
In the following steps, we'll use the node-fetch package to make HTTP requests to the User Import API. Hence, install node-fetch by running the following command:
The following code sample demonstrates how to import 2 users from a JSON document that's stored in a simple constant (const data
):
If the user import was initiated successfully, you'll get a response that looks like this:
In the next step, we'll use the value of the id
field from the above response to query the status of the import task.
In this step, we'll make a GET HTTP(S) request to the Check Status endpoint (/_api/admin/users/import/{ID}
) to get the status of the user import task we initiated in the last step. You'll need to replace {ID}
in the URL with the value of id
in the previous response.
To do this, add a new route to the Express app that accepts the task id
as a parameter and uses that id
to query the status of the task. Here's the code for the route:
The response to the request to query the status of the import task will look like this:
From the response, you can see the status
of the entire task (import was completed
), including a summary ( { "total": 2, "inserted": 2, "updated": 0, "skipped": 0, "failed": 0 }
).
The details
field contains an array of details such as the outcome
for each user in the original JSON document.
How to pass the Apple Store review process if your app uses passwordless login.
However passwordless login via email/phone OTP cannot be used in the review because the reviewer do not have access to the email inbox or phone number of that demo account.
You can enable "test mode" on a specific phone number or an email address so the demo account can authenticate with a fixed OTP 000000
.
Create a project on Google Cloud Platform through . If you are adding Authgear to your existing Google Cloud Platform projects, you may skip to the next step to create the OAuth client.
After creating a new project, you will need to configure the OAuth consent screen. Press the button on the top-left and go to APIs & Services -> OAuth consent screen and follow the instruction to create the consent screen.
Go to -> APIs & services -> Credentials
You can find more details in
Your end-users can now sign in with Google on Authgear pre-built Log In and Sign Up page. Existing end-users can connect their account to Google in the page.
Register an account in .
Use your WeChat app to login in .
Register an account in .
Follow to setup WeChat SDK. For the coding part, we will further explain in the below steps.
WechatOpenSDK
is Objective-C library. If you are using swift. You will need to create bridging header. To setup bridge header, please check . Here is the example WechatOpenSDK-Bridging-Header.h
.
Here is the completed .
Follow to setup Wechat SDK. For the coding part, we will further explain in the below steps.
Here is the completed .
Follow and to setup WeChat SDK. For the coding part, we will further explain in the below steps.
Implement the NativeModules to use WeChat SDK to open WeChat app for authorization. Here is the completed .
Follow and to setup WeChat SDK. For the coding part, we will further explain in the below steps.
Implement the platform specific code to use WeChat SDK to open WeChat app for authorization. Here is the completed .
An Authgear account. for free if you don't have an account yet.
(PHP package manager) installation
The first step you need to take is to create a new application or configure an existing application on the Authgear .
We'll use the PHP package for the configuration.
Here's a link complete source code for .
There's so much more you can do with Authgear and you can continue learning by checking out more topics on the .
In this guide, you'll learn how to integrate Authgear into your website using the . In the token approach, the Authgear server returns an access token and a refresh token to your SPA application after successful user authentication.
See and clone the full code for the demo app for this tutorial in .
Signup for an Authgear Portal account in . Or you can use your self-deployed Authgear.
The Web JS SDK is also available as . That can be installed using any of the following commands:
See more user info .
Authgear SDK provides the fetch
function for you to call your application server. This fetch
function will include the Authorization header in your application request, and handle refresh access token automatically. The authgearClient.fetch
implements .
To protect your application server from unauthorized access. You will need to .
For detailed documentation on the JavaScript Web SDK, visit
You can find the full code for the demo app for this tutorial in the Github repo .
React Native have opt-in support for the since 0.68. Given that the New Architecture is still considered as unstable, we do not support it at the moment.
Signup for an Authgear Portal account in . Or you can use your self-deployed Authgear.
For further instruction on setting up custom URI scheme in React Native, see
For a more detailed guide on how to create a project and set up a development environment for React Native, follow the .
Authgear SDK provides the fetch
function for you to call your application server. The fetch
function will include the Authorization header in your application request, and handle refresh access token automatically. authgear.fetch
implement .
To protect your application server from unauthorized access. You will need to .
For detailed documentation on the JavaScript React Native SDK, visit
You can find the full code for the demo app for this tutorial in
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 .
Webhook and Custom JavaScript/TypeScript are some of the ways you can configure your Authgear project to .
Note: Your project must be on an enterprise plan to use the Custom SMS Provider feature. for more details.
template_name
: the value shows the specific sms template type that is used for composing the message body
. For example, verification_sms.txt when a verification SMS is sent using the verification template set in in Authgear portal.
Webhook Signature Secret Key: this field displays your project's Webhook Signature Secret Key. Each webhook event request includes a signature to confirm it comes from Authgear. We recommend that you verify this signature to confirm that the request is actually from your Authgear project before proceeding. See .
e contains the payload (CustomSMSGatewayPayload
) with details such as the body
and to
(the receiver's phone number). See the example of a .
You can view the audit log in the Portal, or retrieve logs using the .
The API schema can be found in the . For example:
The User Import API is an API that supports the bulk import of users from another system to an Authgear project. This API is not part of the Admin API GraphQL. However, a valid is required to access the endpoints of the User Import API.
To learn more detailed information about the User Import API (such as endpoints, inputs, and responses), see the .
An Authgear account. Sign up for free .
installation on your local computer.
See our post on for a more detailed guide (and examples for other programming languages/frameworks) on how to get your key ID, and private key and generate Admin API JWT.
The user data you wish to import must be provided as a JSON input in the HTTP(S) request body as specified in the .
When you try to publish a mobile app on the Apple AppStore, there will be an . You need provide a demo user account for the reviewers to access the features of the app.
Please contact us at if you need to enable test mode for a phone number or email address in your project.
AUTHENTICATION_IDENTITY_ANONYMOUS_FAILED
Anonymous user authentication failed
AUTHENTICATION_IDENTITY_BIOMETRIC_FAILED
Authentication with biometric failed
AUTHENTICATION_IDENTITY_LOGIN_ID_FAILED
A user's login attempt failed because the email or user ID provided is not found
AUTHENTICATION_PRIMARY_OOB_OTP_EMAIL_FAILED
Authentication using the OTP sent via email failed
AUTHENTICATION_PRIMARY_OOB_OTP_SMS_FAILED
Authentication using the OTP sent via SMS failed
AUTHENTICATION_PRIMARY_PASSWORD_FAILED
A user entered an invalid password during a login attempt
AUTHENTICATION_SECONDARY_OOB_OTP_EMAIL_FAILED
2FA via email failed
AUTHENTICATION_SECONDARY_OOB_OTP_SMS_FAILED
2FA via SMS failed
AUTHENTICATION_SECONDARY_PASSWORD_FAILED
Secondary authentication using password failed
AUTHENTICATION_SECONDARY_RECOVERY_CODE_FAILED
Recovery code verification failed
AUTHENTICATION_SECONDARY_TOTP_FAILED
A 2FA attempt failed
IDENTITY_BIOMETRIC_DISABLED
Biometric login is disabled by a user or an admin
IDENTITY_BIOMETRIC_ENABLED
User enabled biometric login
IDENTITY_EMAIL_ADDED
A user or admin added a new email to an existing user
IDENTITY_EMAIL_REMOVED
An email address was removed from an existing user's profile
IDENTITY_EMAIL_UPDATED
A user updated their email address
IDENTITY_OAUTH_CONNECTED
A profile is linked to OAuth
IDENTITY_OAUTH_DISCONNECTED
A profile is unlinked from OAuth
IDENTITY_PHONE_ADDED
A user or admin added a new phone number to an existing user
IDENTITY_PHONE_REMOVED
A phone number was removed from an existing user's profile
IDENTITY_PHONE_UPDATED
A user updated their phone number
IDENTITY_USERNAME_ADDED
A user or admin added a new username to an existing user
IDENTITY_USERNAME_REMOVED
A user or admin removed the username for a user
IDENTITY_USERNAME_UPDATED
The username for a user was updated
USER_ANONYMOUS_PROMOTED
This event is triggered when an anonymous user is promoted to a normal user
USER_AUTHENTICATED
Successful user sign-in
USER_CREATED
A new user successfully registered
USER_DELETED
A user account is deleted
USER_DELETION_SCHEDULED
A user account deletion is scheduled
USER_DELETION_UNSCHEDULED
A previously scheduled user deletion is unscheduled
USER_DISABLED
User account disabled. An admin disabling a users account can trigger this event
USER_PROFILE_UPDATED
A user updated details like their profile name, gender and more
USER_REENABLED
A user account that was previously disabled is enabled
USER_SESSION_TERMINATED
An active user session is terminated
USER_SIGNED_OUT
A user that was signed in logged out
WHATSAPP_OTP_VERIFIED
User completed a verification process using WhatsApp to receive OTP
SMS_SENT
An SMS notification like OTP was sent to a user
EMAIL_SENT
An email notice like verification code was sent to a user
id
Unique identifier of the event
seq
Sequence number of the event
type
Activity type
context
The who, when and where of the event triggered. e.g. IP address, user agent, user ID, timestamp
payload
Relevant data according to the event type:
Messaging (SMS, Email OTP): the phone number/email address of the receiver
Authentication/Identity/User actions: a snapshot of the related session and user attributes
PROJECT_APP_SECRET_VIEWED
An admin downloaded the Admin API key
PROJECT_APP_UPDATED
Project configurations updated
PROJECT_BILLING_CHECKOUT_CREATED
An admin attempted to subscribe to one of the billing plans
PROJECT_BILLING_SUBSCRIPTION_CANCELLED
Billing subscription was canceled
PROJECT_BILLING_SUBSCRIPTION_STATUS_UPDATED
Account billing status is updated
PROJECT_BILLING_SUBSCRIPTION_UPDATED
Billing details updated
PROJECT_COLLABORATOR_DELETED
An admin is removed
PROJECT_COLLABORATOR_INVITATION_ACCEPTED
A user accepted an invitation to become an admin
PROJECT_COLLABORATOR_INVITATION_CREATED
Invitation to add new admin sent
PROJECT_COLLABORATOR_INVITATION_DELETED
A previously sent admin invitation was canceled
PROJECT_DOMAIN_CREATED
A new custom domain name added
PROJECT_DOMAIN_DELETED
A custom domain name was removed
PROJECT_DOMAIN_VERIFIED
A domain name was successfully verified
ADMIN_API_MUTATION_SET_DISABLED_STATUS_EXECUTED
Admin disabled/enabled a user account
ADMIN_API_MUTATION_CREATE_SESSION_EXECUTED
A new session is created
ADMIN_API_MUTATION_ANONYMIZE_USER_EXECUTED
An admin initiated the process to annonymize a normal user. This command will delete all user data like email, full name and phone number
ADMIN_API_MUTATION_CREATE_IDENTITY_EXECUTED
New Identity was created by an admin
ADMIN_API_MUTATION_CREATE_USER_EXECUTED
An admin created a new user
ADMIN_API_MUTATION_DELETE_AUTHENTICATOR_EXECUTED
An authenticator was removed
ADMIN_API_MUTATION_DELETE_AUTHORIZATION_EXECUTED
An authorization was removed
ADMIN_API_MUTATION_DELETE_IDENTITY_EXECUTED
Identity deleted
ADMIN_API_MUTATION_DELETE_USER_EXECUTED
An admin deleted a user
ADMIN_API_MUTATION_GENERATE_OOB_OTP_CODE_EXECUTED
New OTP code generated
ADMIN_API_MUTATION_RESET_PASSWORD_EXECUTED
Password was reset by an admin
ADMIN_API_MUTATION_REVOKE_ALL_SESSIONS_EXECUTED
All sessions revoked
ADMIN_API_MUTATION_REVOKE_SESSION_EXECUTED
A users session is revoked
ADMIN_API_MUTATION_SCHEDULE_ACCOUNT_ANONYMIZATION_EXECUTED
An admin scheduled the anonymization of a user account
ADMIN_API_MUTATION_SCHEDULE_ACCOUNT_DELETION_EXECUTED
An admin scheduled the deletion of a user
ADMIN_API_MUTATION_SEND_RESET_PASSWORD_MESSAGE_EXECUTED
Password reset message was sent
ADMIN_API_MUTATION_SET_VERIFIED_STATUS_EXECUTED
Verified status for a user is updated
ADMIN_API_MUTATION_UNSCHEDULE_ACCOUNT_ANONYMIZATION_EXECUTED
A previously scheduled user anonymization request was canceled
ADMIN_API_MUTATION_UNSCHEDULE_ACCOUNT_DELETION_EXECUTED
A previously scheduled user deletion request was canceled
ADMIN_API_MUTATION_UPDATE_IDENTITY_EXECUTED
Identity updated by admin
ADMIN_API_MUTATION_UPDATE_USER_EXECUTED
An admin updated details like a user's name, gender and more
Learn how to integrate popular analytics and tracking tools into your Authgear project using Google Tag Manager
Authgear allows you to add third-party user analytics tools to your project using Google Tag Manager.
Google Tag Manager (GTM) is a tag management tool from Google that makes it easy to add marketing tags to your website without modifying the site's source code.
Tags can help you track traffic and user behavior on your website or application.
In this guide, we will show you how to add Google Tag Manager to your Authgear project and send data to Google Analytics. You can also configure Google Tag Manager to send data from your Authgear project to other marketing tags from providers like Facebook.
In order to setup Google Tag Manager and Google Analytics with Authgear, you need to have the following:
Authgear account
Google Tag Manager Account
Google Analytics Account
The process for connecting your GTM account to Authgear is simple and can be done in these two steps.
Google Tag Manager lets you create containers that hold marketing tags. Each container has a unique ID and you'll need this container ID to connect your GTM container to Authgear.
If you don't have a container for your Authgear project yet, click on Create Account to create a new container. Enter your domain name for your Authgear project as the container name and select a target platform. For this example, we'll select Web as the target platform.
First, log in to the Authgear Portal, then select your project and navigate to Integrations.
Click on the Connect button next to the Google Tag Manager addon to open the configuration page.
Paste the GTM container ID you got from the previous step then click the Save button. And with that, you've successfully connected your GTM container to Authgear. In the next steps, we'll show you how to create tracking tags and send data to Google Analytics.
Google Analytics is one of the marketing tags we can manage from GTM. In this part of the guide, we'll set up some tags to track page views and user events like clicking on a link or button. The tags will send these data to Google Analytics.
In order to create tags that send data to Google Analytics, you need to have an active data stream on Google Analytics. GTM requires the details for this stream while creating new tags for Google Analytics.
To create a stream, log in to Google Analytics then navigate to the Admin settings page.
Create a new Google Analytics property for your Authgear project or select an existing one. Click on the Data Streams item under the property to view all streams and add a new web stream for your Authgear project.
Note down the Measurement ID for your stream as we'll be using it later to create new tags.
Before we start sending data to Google Analytics, let's create a new variable in Google Tag Manager.
Go back to GTM and select the correct container for your project.
Next, click on the Variables item on the left side navigation bar and create a new user variable with the following details:
Variable type: Data Layer Variable
Data Layer Variable Name: gtm.element.dataset.authgearEvent
Once you're done save the variable as "gtm.element.dataset.authgearEvent" and continue to the next step.
Navigate to Triggers from the sidebar and create a new trigger with the following details:
Trigger type: Click > All Elements
This trigger fires on: Some Clicks
Authgear's implementation of GTM is declarative. The primary button on each page has data-authgear-event
attribute. We'll be setting a condition for the "Some Clicks" using that attribute. Configure Some "Click" as shown below:
Next, save the trigger as "Authgear-btn-click" and continue.
Navigate to Tags from the sidebar and create a new tag with the following configurations:
Tag type: Google Analytics > Google Tag
Tag ID: <Your Tag ID is the unique Measurement ID for your stream in Google Analytics (See part 2 step 1 for more details)>
Next, expand the Advanced Settings section and set Tag firing options to Once per page.
Now, scroll down to the Trigger section of the new tag and select All Pages (page view) as the trigger.
Save this new tag as "Auth-gear-pageview" and continue.
In this step, create another tag with the following configuration:
Tag type: Google Analytics > Google Analytics: GA4 Event
Measurement ID: <Your Google Analytics stream measurement ID>
Event Name: gtm.element.dataset.authgearEvent
Next, set the trigger for this tag to the "Authgear-btn-click" trigger we created earlier.
Save the tag as "Authgear-event-tag" and continue to preview the entire setup or publish to go live.
After you publish your changes in Google Tag Manager when users generate hits or click buttons with the data-authgear-event
attribute on your project you should see data on Google Analytics.
The following is a list of values for the data-authgear-event
attribute:
authgear.button.change_password
authgear.button.change_additional_password
authgear.button.create_password
authgear.button.change_login_id
authgear.button.remove_login_id
authgear.button.resend_oob_otp
authgear.button.enter_oob_otp
authgear.button.enter_password
authgear.button.enter_recovery_code
authgear.button.enter_totp
authgear.button.send_reset_password_code
authgear.button.sign_in
authgear.button.sign_up
authgear.button.sign_out
authgear.button.oauth
authgear.button.reset_password
authgear.button.continue_with_current_account
authgear.button.use_another_account
authgear.button.remove_biometric
authgear.button.schedule_account_deletion
authgear.button.connect_oauth
authgear.button.disconnect_oauth
authgear.button.resend_verification_code
authgear.button.update_profile
authgear.button.regenerate_recovery_code
authgear.button.download_recovery_code
authgear.button.remove_totp
authgear.button.remove_oob_otp
authgear.button.setup_oob_otp
authgear.button.setup_totp
authgear.button.enter_verification_code
authgear.button.revoke_session
authgear.button.revoke_session_group
authgear.button.revoke_all_sessions
Use custom Twilio account as SMS provider for communication with the users.
In this guide, you'll learn how to set up your Authgear project to use Twilio as a custom SMS provider.
By configuring your Authgear project to use Twilio as a custom SMS provider, you switch from the default SMS provider to your own Twilio account. As a result, you can control and manage billing and other settings for your SMS from the Twilio console independent of Authgear.
A Twilio account
An Authgear project with the Custom SMS Gateway feature enabled.
To get started, log in to Authgear Portal, then navigate to Advanced > Custom SMS Gateway.
Next, toggle the Enable Custom SMS Gateway switch on to enable the SMS Gateway Provider settings.
To get your Account SID and Auth Token from Twilio, log in to your Twilio console and scroll to the Account Info section to find your Account SID, Auth Token, and Twilio phone number.
Once you have your Twilio credentials, click on Twilio from the SMS Gateway Provider list. This will open the provider's settings.
API Key
To use API Key as credential, search for "API Key" in the search bar on the top right corner of the Twilio console. Select Home > API Keys from the search result to open the API Keys page.
Click on the Create API Key button to create a new API Key.
Enter the name for your new API Key in the Friendly name text field then click Create.
Copy the SID and Secret for your new API Key and store them in a safe location. Note that you can only view your API Secret once.
Now set the following options in Authgear Portal using the details from your Twilio account:
Enter your Twilio Account SID.
Enter an SMS Sender, this can be either a Message Service ID, or your Twilio phone number, shortcode or alphanumeric sender ID that is registered on Twilio.
Select the type of credential you wish to use to connect to your Twilio account. This can be either an Auth Token or API Key from your Twilio console. We recommend using the API Key as the credential.
API Key (Recommended): Use the API Key SID and API Key Secret obtained in the Twilio's API Keys & Token page
Auth Token: The token is under "Account Info" in the Twilio dashboard home page
Finally, click on the Save button to save your new Twilio provider settings.
To test your work, click on the Test button next to the Save button, enter your phone number then click Send to test your new SMS provider.
How to guides related to user profiles
Export users from your project into a CSV or JSON file
In this guide, you'll learn how to use the User Export API.
The User Export API allows developers to bulk export users into a file.
The export process is asynchronous. That is, the process runs in the background. Hence, you will need to initiate an export task in one endpoint call and then, make an additional call to another endpoint to get the status of the export task.
The following are the two endpoints for the User Export API:
POST
/_api/admin/users/export
Use this endpoint to create a new user export task.
Headers
Content-Type
application/json
Authorization
Bearer <Admin API JWT Token>
Host
<Your Authgear Project domain>
Body
The Initiate Export endpoint accepts JSON input via an HTTP(S) request body. The following is an example of the input:
The format
field is where you specify the format of the export file. The value can be csv
or ndjson
.
csv
: use this field when format
is set to csv
. The value is an object with a fields
property.
csv.fields
: you can use this field to list all the user attributes you want to include as fields in the CSV file. The value should be an array and each item in the array is an object with a pointer
and an optional field_name
property that describe a user attribute.
GET
/_api/admin/users/export/{Task ID}
Use this endpoint to query the status of an existing export task. Replace {Task ID}
with the task id
returned in the response body of the initiate export endpoint.
Headers
Authorization
Bearer <Admin API JWT Token>
Host
<Your Authgear Project domain>
The following example shows how to use the User Export API in a Node.js application.
First, you need to get the Admin API JWT that will be used to authenticate requests to the endpoints.
To do that, install JsonWebToken (a Node package for generating JWT) by running the following command:
Now, create a generateJWT()
function in your Express app to generate the JWT:
Make an HTTP(S) POST request to the initiate export endpoint to initiate a new user export task.
To do that, first, install the node-fetch package in your app using this command:
Then add the following code to your application:
The response to the HTTP(S) request in this step should look like this:
Response
id
: the value of id is the task ID that can be used in the check status endpoint to query the task and get the download URL for the export file.
In this step, we'll check the status of the export task we initiated by making an HTTP(S) request to the Check Status endpoint (/_api/admin/users/export/{Task ID}
). Replace {Task ID}
in the URL with the task ID for the export task in the previous task.
Add the following route to your app to check the status of an export task using the task ID:
When the status task is completed, the HTTP(S) response body will look like this:
Response
download_url
: open the URL in the value of download_url
to download the exported users file.
Note: The result from a completed export task will expire after 24 hours. Hence, after 24 hours, you can no longer use the task ID associated with the task to generate a new download link.
The complete information in the user profiles is a combination of standard attributes and custom attributes. Attributes are a way of grouping the fields of the user profile information. With standard attributes containing common fields, you'll find in a user profile, hence the names of these fields are set by Authgear. You set custom fields on the other hand based on the unique needs of your project.
Name
Hidden
String
Given Name
Editable
String
Family Name
Editable
String
Middle Name
Hidden
String
Nickname
Hidden
String
Profile
Hidden
URL String
Picture
Editable
URL String
Website
Hidden
URL String
Gender
Editable
male
, female
or Custom String
Birthdate
Editable
Date in YYYY-MM-DD
Timezone
Editable
Language
Editable
BCP47 language tag enabled by the project
Address
Hidden
JSON Object
The standard attributes coupled with identities are listed below:
email
email_verified
phone_number
phone_number_verified
preferred_username
The above attributes are coupled with identities when a user specifies them during sign-up, when users verify their email address or phone number, or from User Management > Users > select a user > Identities in Authgear portal or via the Admin API.
The Login Methods enabled for an Authgear project affect the identities available.
You can define a set of custom attributes in the user profile. They are returned as a JSON object in under the custom_attributes
key in userInfo
.
Go to Portal > User Profile > Custom Attributes and click Add New Attribute
Authgear supports the following attribute types:
String
Number
Integer
Dropdown
Phone Number
Email Address
URL
Country Code
You can change a custom attribute name and validation settings such as min and max value. The attribute type cannot be changed once it's set. To migrate the attribute into a new type, create a new attribute, migrate the values from the old to the new one, and then change the name and access right of the old attribute to make it obsolete.
Deleting custom attributes is not supported. You can change the name and access rights to make an attribute obsolete.
The access rights for different parties on individual attributes can be configured through the Authgear Portal. Under the hood, all the attributes are available, however, they can be configured to be hidden
or read-only
according to the needs of your projects to avoid confusion.
These are the parties that have access to the user profile:
The admin user can view or edit the standard attributes via the Authgear Portal.
Define and manage roles and groups that you can apply to your users
The following case is an example of how you can use roles to deliver unique features and interfaces to different categories of users of your application. Let's say you have an application XYZ that powers a transportation business. The app has roles for admin
, driver
and passenger
. You can use the value Authgear returns in UserInfo or JWT access token to enable features for managing drivers to a user with admin
role only. Similarly, you can allow only users with driver
role view features to manage their vehicle, passengers, and trip. Finally, you can restrict users with the passenger
role to only view their ticket and trip details.
In this post, you'll learn how to create roles and groups for your Authgear project and how to manage them.
You can create a group in your Authgear project and add one or more roles to the group. Both groups and roles can be applied to a user. For instance, if your Authgear project, has the following roles:
management
department_lead
team_member
And a managers
group, you can add the management
and department_lead
roles to the group. Then, adding a user to the managers
group will grant them both management
and department_lead
roles.
The following figure shows the core relationship with Groups, Roles, and Users in Authgear.
Each role or group has three properties that describe it. These include a required key
, and optional name
and description
.
The key
property serves as the identifier for the role or group. The value for key
is what AUthgear will include in the UserInfo and JWT access token of a user. A valid key must meet the following conditions:
The value of key
can not be empty.
A key must be between 1 and 40 characters long.
The valid characters are [a-zA-Z0-9:_]
.
The prefix authgear:
is reserved for Authgear internal use.
The following are some examples of valid keys:
reader
app:editor
store_manager
Name is an optional label for a role or group. The value for the name property is what will be displayed in Authgear portal. It has less strict constrict for allowed characters. For example, you can use white spaces here.
The description property is also optional. You can use it to give more details about a role or group.
In the next section of this post, we'll show you how to create roles and groups for your project.
The. following JSON document shows how roles are returned when your application requests for UserInfo:
The value of the https://authgear.com/claims/user/roles
attribute is an array that contains the roles of the current user.
Follow these steps to create new roles in your Authgear project via the Portal.
First, log in to Authgear Portal, select your project then navigate to User Management > Roles to open the Roles page.
Click the Create Role button in the middle of the Roles page (or the top right corner if you have existing roles) to start creating a new role.
Enter the Name, Role Key, and Description of your new role in their respective fields. Click on the Create button at the bottom of the form to finish creating your new role.
Repeat the above steps to add more roles.
As mentioned earlier in this post, you can also create new roles using the Admin API. In this section, we'll walk you through the steps for doing that.
Run the following mutation to create a new role:
Just like roles, you are responsible for creating groups for your Authgear project. You can also create new groups either via Authgear Portal or using the Admin API.
The steps for creating a new group from the Portal are similar to that of roles. The steps are as follows:
First, log in to Authgear Portal, select your project then navigate to User Management > Groups to open the Groups page.
Click the Create Group button in the middle of the screen (or in the top right corner if you already have some groups) to access the Create Group form.
Enter the Name, Group Key and Description in the group creation form then click the Create button to finish.
It's possible to create a new group using the Admin API GraphQL. The following guide shows the steps for doing that.
Execute the following GraphQL mutation to create a new group:
You can manage the roles you've created via the Portal or using the Admin API. In this section, we'll cover how to manage roles.
To add a role to a user, first, in the Authgear Portal, navigate to User Management > Users. From this page, you can view a list of all the users who have signed up on your Authgear project. You can also search users by their current roles there.
Next, click on the user you wish to add a new role to. This will open their User Details page. From that page, navigate to the Roles tab
To remove an existing role from a user, click on the Remove button next to the role in the user's Roles tab.
Adding a group to a role is a way of connecting a role and a group from the role management side.
To do this in Authgear Portal, first navigate to User Management > Roles, then click on the role you wish add a group to.
Next, in the details page for the selected role, go to the Groups tab, then click the Add to Group button. Select the group you wish to add from the drop-down then click Add. If there's no groups in the dropdown, try creating some new groups first.
To update the properties of an existing role such as the name, description or key, navigate to User User Management > Roles in Authgear Portal. Click on the role you wish to modify to open the Settings tab, then change the value for the property you wish to update in the form. Once you're done, click on the Save button.
To delete a role, click on the Delete button once you open the role's Settings tab.
To add a group to a user's profile in the Portal, first navigate to User Management > Users and select a user.
In the User Details page, switch to the Groups tab then click on Add to Group.
Select the group you wish to add the user to from the drop-down then click on Add.
To add a role to a group, navigate to User Management > Groups then click on the group you wish to add roles to.
In the group details page, switch to the Roles tab, then click on the Add Role button.
Select the roles you wish to add to the group from the drop-down then click on the Add button.
To update an existing group, go to User Management > Groups and click on the group you wish to update. Modify the property you wish to update using the form in the group's Setting tab. Once you're done, click on Save to keep your changes.
To delete an existing group, click on the Delete Group button once you're in the Settings tab for that group.
Learn how to access User Profiles
Access Right defines what information can be viewed or modified when a user's profile is accessed via the Authgear Portal, User Info endpoint, or User Settings page.
An Access Right can be set for each profile attribute under a specific medium of accessing user profiles. For example, in the following screenshot, the Primary Email attribute has the Editable Access Right for Portal, Read-only
for User Info endpoint (also known as access Token Bearer), and Editable
for User Settings page. In simpler terms, the example means an admin can modify Primary Email in Authgear Portal, while a client application can use a user's access token to view their Primary Email. Finally, users can edit their own Primary Email from the User Settings page.
The following are the available Access Right options that can be applied to each attribute for a specific medium.
Editable: Grants a medium access to view and modify the value of an attribute.
Read-only: A medium with this access for an attribute can only view the value of the attribute.
Hidden: If the access for an attribute is set to Hidden
for a medium, that medium can not view or modify the attribute.
By default, Authgear sets different access rights for the standard attributes on each way of accessing user profiles. You can view and configure this default access right from User Profile > Standard Attributes in the Authgear Portal.
For Custom Attributes, you can define the access right for each way of accessing a user profile from User Profile > Custom Attributes in the portal.
Each way of accessing user profiles belongs to one of the following Access Right Categories:
Portal Admin Access Right: Use this category to set the access right of an attribute in the Authgear Portal for an admin user.
Token Bearer Access Right: This sets the access right of an attribute for the User Info endpoint when a token bearer accesses it. It can be "Hidden" or "Read-Only".
End-user Access Right: Use this to set the access right of the attribute for the default User Settings UI when accessed by an end-user.
It is the fastest and easiest way to view user profiles and manage them.
The UserInfo endpoint returns the Claims about the authenticated end-user, including the standard profile and custom attributes.
The userInfo
object is returned from calling fetch user info function which contains a unique identifier of the user.
The following are some attributes that are usually in the userInfo object. Other attributes like email, phoneNumber and custom attributes will be in the userInfo object if those attributes were set for the current user.
isAnonymous
boolean
isVerified
boolean
Indicate if the user completed the verification requirement
sub
string
Unique identifier of the user in your Authgear project
To access a user's profile using the UserInfo endpoint of OpenID Connect, you need to follow these steps:
Authgear WebHooks makes it possible to embed the standard attributes and custom attributes for a user's profile into the OIDC JSON Web Token (JWT). Hence, you access both profile attributes in the JWT returned to your OIDC client without making another call to the UserInfo endpoint.
Guide on how to add Two-Factor Authentication to your application.
Authgear supports Two-Factor Authentication (2FA) or Multi-Factor Authentication (MFA) for additional layers of security in your application.
When you enable MFA on your application, Authgear will require your users to present two or more factors in order to log in. These factors could be their password and a One-time Password (OTP) that is sent to their registered email address or phone number. As a result, an attacker can not gain access to a user's account with only a compromised password.
In this post, you'll learn how to enable MFA or 2FA for your Authgear project and how to configure 2FA grace period.
An Authgear Project.
You can enable 2FA and configure other settings from the 2-Factor Authentication page in Authgear Portal.
To open the 2-Factor Authentication page, log in to Authgear Portal, select your project, then navigate to Authentication > 2FA.
Next, use the 2FA Requirements dropdown on the 2-Factor Authentication page to set when to require users to use 2-Factor Authentication to sign in.
The available options are:
Disabled: When this is selected, 2FA will not be required to log in for any user, including users who already have 2FA set up for their account.
Optional: This policy will only require 2FA to log in for users who already have 2FA set up for their account. Users who have not set up 2FA can continue to log in without it.
Toggle the Show "Do not ask again on this device" for 2FA switch on if you wish to require 2FA only the first time a user logs in from a specific device.
The Available 2-Factor sub-section on the 2-Factor Authentication page shows a list of supported second-factor authentication methods. The supported methods include:
Google Authenticator/Authy
Additional Password
OTP Code/Login Link via Email
OTP Code via Phone
Check the box for each 2FA method you wish to enable for your project.
Use the up and down allows on the right of each method to order the priority of the 2FA methods.
Once you're done, click on the Save button at the top-left of the 2-Factor Authentication page to keep your new settings.
The 2FA Grace Period feature grants your users some time to set up 2FA for their accounts. This is very helpful for the Mandatory enforcement of 2FA.
The following are the two types of 2FA grace periods you can set for your Authgear project:
Global Grace Period: When this type of grace period is enabled, all users who do not have 2FA set up for their account will be asked to set up 2FA the next time they log in. When the Global Grace Period is disabled, users who have not set up 2FA for their account cannot log in. Instead, they'll get an error message requesting them to contact an admin.
Individual Grace Period: This is a type of grace period that is set per user. It grants a user 10 days to set up 2FA for their account. This is ideal for allowing individual users to set up 2FA when the Global Grace Period is disabled.
The following steps show how to roll out Mandatory 2FA using grace periods:
Change 2FA requirement policy to Mandatory
Enable Global Grace Period so that all users who haven't set up 2FA are required to do so the next time they login.
Use your own channel to notify user's about the duration of the global grace period you've decided.
Disable the Global Grace Period once the date you notified users of has passed. After you do this, users that still haven't set up 2FA will be unable to log in.
To enable the Global Grace Period, navigate to Authentication > 2FA in the Authgear Portal. Then, set 2FA Requirements to Mandatory so that you can view the Enable global grace period switch.
Toggle the Enable global grace period switch on so that your users without 2FA will be required to set up 2FA the next time they log in. Or set Enable global grace period off, if you do not want users without 2FA to log in, or set up 2FA without contacting an admin.
When you set the 2FA requirement for your project to Mandatory and Global Grace Period is turned off, you can still use the individual grace period to grant a specific user a grace period to set up 2FA for their account.
To set individual grace period, navigate to User Management > User in Authgear Portal. Then, select the user you wish to set individual grace period for by clicking on the row with their ID in your project's users' list.
From the selected user's details page, click on the Account Security tab, then the Grant grace period to set up 2FA button. You will see a prompt to confim your action, click Confirm to continue.
The duration of the individual grace period is 10 days. However, you can extend or cancel it from the user's details page.
Learn how to add custom attributes to user profiles and manage existing custom attributes
In Authgear, a user's profile includes two types of attributes.
The first is the standard attributes which are basically common profile fields such as Primary Email, Primary Phone, Username, Name, Birthday, etc that are present by default.
The second type is the custom attributes an Authgear user can set for their project. This allows you to add custom fields to the profiles of your users. For example, you can add a Post Code custom attribute to your Authgear so users can provide this data for their profile.
In this post, you'll learn how to add new custom attributes to your Authgear project. You'll also learn how to manage existing custom attributes.
You can add new custom attributes to your project from the Authgear Portal. To do this, first, navigate to User Profile > Custom Attributes. Then, click on the Add New Attribute button to open the Add Custom Attribute page.
Enter the Attribute Name, a valid attribute name should consist of lowercase letters (a-z), digits (0-9), and underscore () only, must start with lowercase letters (a-z), and NOT end with an underscore (_).
Select the appropriate Attribute Type based on the type of data you expect users to enter in the custom attribute. The option you select will affect the type of input field (text field, dropdown, etc) users will see in their profile settings UI.
Once you're done, click the Save button to add the new custom attribute.
Usually, the next key action to take after adding a new custom attribute will be to set the access right. An attribute's Access Right is a configuration that determines who can see (Read-only) or add or modify (Editable) the value of an attribute's field.
You can set the Access Right for an attribute under the following groups:
Portal Admin: Access control for the user profile attributes in Admin Portal > User Management.
Token Bearer: Access control for the user profile attributes in the UserInfo endpoint.
End-user: Access control for the user profile attributes in the End-user settings page.
To set the access right for an attribute, navigate to User Profile > Custom Attributes in the Authgear Portal. On the Custom Attributes list, click the Access Right dropdown for the group and custom attribute you wish to update. Click Save when you're done to keep the changes.
Note: Selecting the Hidden access right, for any group will hide the field for the attribute from that group. For example, selecting Hidden for the post_code
attribute for the Token Bearer group means the post_code
field will be hidden (not included) in the UserInfo endpoint response.
From the Custom Attributes list, click on the pencil icon to open the Edit Custom Attribute page.
Note: You can't modify the Attribute Type for an existing attribute. The alternative will be to create a new custom attribute with the new Type and migrate data from the old attribute to it. Also, rename and change the access right for the old attribute to make it obsolete.
You can set the order of how custom attributes appear in the UI.
To do that, in the Custom Attributes list, click and drag the stacked icon next to an attribute up or down to move the position.
Delete is not supported. Instead, you should change the name and access right to make the attribute obsolete.
Allow end-users to initiate account deletion within the apps.
Enable this button by:
Go to Advanced -> Account Deletion page in the Portal
Enable the button and press Save
Note that if you enable this feature, you have to prepare for encountering invalid session every time your users close User Settings in your mobile apps. If your users unfortunately decided to delete their account in User Settings, all their sessions will become invalid immediately.
You must verify the validity of the session every time the User Settings is closed. The open
method in the SDK is blocking. You can verify if the user session is still valid when the method resolves. Here is an example with the React Native SDK:
You can now open the account deletion directly from Authgear SDKs. The account deletion page will be opened in a WebView.
You must enable the button in Portal -> Advanced -> Account Deletion before calling the function.
The following code examples show how to open the account deletion page from Authgear SDKs:
When the end-user has initiated the account deletion, their account will be deactivated and scheduled for deletion after the grace period.
Deactivated users are always disabled. They will not be able to complete the authentication process. The is_deactivated
status signal that the is_disabled
status was turned true
by the end-user themselves rather than the admin.
You can set the grace period for how long the user account will be deactivated before deleted from the system. The default value is 30 days, you can choose between 1 to 180 days.
An end-user account can also be deleted using the Portal. In the User Management page, click the Remove User button to remove them immediately or schedule the deletion.
Alternatively, if you did not enable the "Delete Account" button in User Settings, you can implement the button in your app by yourself. You can schedule a deletion or delete immediately.
Here is an example:
GraphQL
Here is an example:
GraphQL
You may listen to the following events to integrate the deletion behavior to your apps.
Non-blocking events
user.disabled
user.reenabled
user.deletion_scheduled
user.deletion_unscheduled
user.deleted
Blocking event
user.pre_schedule_deletion
Event are generated and delivered to your hooks. You will be notified when important events such as new user signup happen.
Events are divided into two kinds, Blocking and Non-blocking.
Each event can have multiple hooks. The delivery order of non-blocking events is unspecified. Blocking events are delivered in the order as in the configuration.
Blocking events are triggered before the operation is performed, such as before user creation. The operation can be aborted by your hooks.
They are delivered to your hooks synchronously, right before changes are persisted to the database.
Your hooks must return a JSON document to indicate whether the operation should continue.
To let the operation proceed, return a JSON document with is_allowed
set to true
.
To abort the operation, return a JSON document with is_allowed
set to false
, and a non-empty reason
and title
.
If any of your hooks abort the operation, the operation is aborted. The reason
and title
will be shown to the end-user as an error message.
Each of your hooks must respond within 5 seconds. All of your hooks must complete within 10 seconds. Otherwise, the delivery will fail to due timeout.
Mutations by a hook are applied only when the operation is allowed to proceed. Mutations take effect only when all hooks allow the operation to proceed.
The mutations are specified in the hook response. Objects not appearing in mutations
are left intact. The mutated objects are NOT merged with the original ones.
The mutated objects are NOT validated, and are propagated along the hook chain. The mutated objects are validated after traversing the hook chain.
Mutations do NOT generate extra events to avoid infinite loops.
When a blocking event supports mutations on the user object, your hooks can respond a JSON document to allow the operation, and specify the mutations you want to apply on the user object.
To mutate the user object, include user
inside mutations
. Only standard_attributes
and custom_attributes
of the user object are mutable.
You must include the WHOLE
standard_attributes
orcustom_attributes
when you specify the mutations. Otherwise, missing attributes WILL BE deleted.
When a blocking event supports mutations on the JWT payload, your hooks can respond a JSON document to allow the operation, and specify additional fields that you want to include in the JWT payload. However, you MUST NOT change or remove any existing fields in the JWT payload, as they are essential to the validity of the JWT.
To add additional fields to the JWT payload, include jwt.payload
inside mutations
. You MUST add your own fields only.
You must include the WHOLE
jwt.payload
from the event object when you specify the mutations.
Non-blocking events are triggered after the operation is performed.
They are delivered to your hooks asynchronously after the operation is performed.
Your hooks must finish within 60 seconds. Otherwise, the delivery will fail to due timeout.
The response of your hooks is ignored.
Events have the following shape:
id
: The ID of the event.
seq
: A monotonically increasing signed 64-bit integer.
type
: The type of the event.
payload
: The payload of the event, varies with type.
context
: The context of the event.
context.timestamp
: signed 64-bit UNIX timestamp of when this event is generated. Retried deliveries do not affect this field.
context.user_id
: The ID of the user associated with the event. It may be absent. For example, the user has not been authenticated yet.
context.preferred_languages
: User-preferred languages, which are inferred from the request. Return values of the ui_locales
query if it is provided in the Auth UI, otherwise return languages in the Accept-Language
request header.
context.language
: User locale which is derived based on the user's preferred languages and the app's languages config.
context.triggered_by
: Triggered by indicates who triggered the events, values can be user
, admin_api
, system
, or portal
. user
means it is triggered by the end-user. admin_api
means it is triggered by Admin API or using Admin API operations via the portal. system
means the event originates from a background job. portal
means the event originates from the Authgear portal and is an operation that does not use the Admin API. Examples of operations that do not use the Admin API can be found in the screenshot below:
To configure "Sign in with Apple" for Authgear, you will need to fulfil the following:
Register an Apple Developer Account. Apple Enterprise Account does not support "Sign in with Apple"
Register your own domain.
Your domain must be able to send and receive emails.
Click "Configure" the Next to "Sign in with Apple". In "Primary App ID" field, select app ID created above.
Fill in and verify the domain created above, add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/apple
to Return URLs
In the portal, go to Authentication > Social / Enterprise Login.
Enable Sign in with Apple.
In Client ID, add the identifier of the Services ID you created in Apple. Not the ID of the App ID or the Client ID of your Authgear Application.
In Apple Developer Portal, view key information of the "Key" created above.
Jot down the Key ID and download the key text file (.p8
file).
Copy the content in the key text file to Client Secret text area in Authgear Portal..
Fill in Key ID field using the Key ID obtained from step 5.
In Apple Developer Portal, click username on the top right corner, click View Membership.
Find the Team ID from Membership Information, fill in Team ID field in Authgear portal.
Save the settings.
🎉Done! You have just added Sign in with Apple to your apps!
Learn how to update a User profile's custom attributes on sign-up using Hooks
Here are easy steps to achieve this:
Step 2. Go to User Profile → Custom Attributes page.
Step 3. Add 3 new attributes there, namely city, name, and timezone:
Step 4. Navigate to your Authgear Dashboard's Advanced->Hooks section.
Step 5. Add a new Blocking Event.
Step 6. Choose the Block Hook Type as the TypeScript and set the Event option to User pre-create. You will write a new Typescript function from scratch.
Step 7. Click on Edit Script under the Config option.
Step 8. Write a function logic for how you integrate any external API to populate custom attributes into the editor. For example.
Step 9. Now if you navigate to User Management and Add a new user.
Step 10. After the user is created, you should able to see custom attributes values have been updated for the user:
Optimize for email deliverability by using your own SMTP server to send Authgear Emails (such as forgot password, verifications) in your own domains.
To send Authgear emails to end-users with your own domain, e.g. support@myapp.com
. You will need to configure the external SMTP provider.
Authgear currently supports SendGrid and other custom SMTP Providers.
The sender address can be configured by changing the value of theemail.default.sender
key in the localization JSON. Go to Portal > Branding > Custom Text and add/change the value of email.default.sender
to your own email address, for example no-replay@myapp.com
, and Save the settings. The value can be set separately for each locale.
Before adding the email service provider to Authgear, make sure the sender domain is verified and authenticated on the email service. For example, your domain myapp.com
should be configured in your SendGrid account so Authgear can use the account to send emails with no-reply@myapp.com
.
Follow the instructions from the email service provider for setting up your domain:
The external SMTP provider can be set up in Portal > Advanced > Custom Email Provider. Enable the Use my own provider toggle to see the fields.
Log in to your SendGrid account
Create API Key in Settings > API Keys
Set the API Key Name for your reference the choose Restricted Access under API Key Permissions
Under Access Details, expand Mail Send and give Full Access to the Mail Send permission
Click Create & View. Copy the API key created and save it somewhere safe
In Authgear Portal, navigate to Custom Email Provider
Enable Use my own provider.
Choose SendGrid and paste the API key you copied, and Save
You can send a test email to check the configuration
Other SMTP providers can be set manually by providing the Host, Port, Username, and Password. They can be obtained from the documentation or instructions from your email service provider.
Guide on the different ways you can modify the profiles of the users of your application.
Authgear offers multiple ways for you (the admin) and your users to update user profiles. As an admin, you can modify profile attributes for any of the users of your Authgear project. End users on the other hand can modify their own profile using the Profile settings UI provided by Authgear or using a custom logic you implement in your code.
In this guide, we'll walk through all the options for updating user profiles.
To follow along, you need to have the following:
At least one registered user on your Authgear Project.
At the end of this post you'll be able to do the following:
Update a user profile as an admin from the Authgear Portal or using Admin API.
Update a user profile as an end user via the profile settings page.
You can update the profiles for your users as an admin using either the Authgear Portal or the Admin API. Below are guides on how to use both options.
This option provides an easier way to manage your users within the Authgear Portal.
Next, Navigate to User Management section to view all the users currently registered under your project.
Click on the ID (name, email, or phone number) for the user you wish to update their profile to open the edit user details page.
From the edit user details page, you can edit the selected user's standard attributes such as Given Name, Family Name, Birthday, etc. If you scroll down on the edit user details page, you'll find more fields like the custom attributes that you can also update.
Once you're done, click the Save button to keep your update.
To update a user profile via the Admin API, you need to create a mutation like the following:
First, create a variable with all the existing profile attributes for the user, then include new fields or update the value for the fields you wish to update. Note that omitting an existing attribute in your variable will cause Authgear to delete that attribute.
Variable
Mutation
Authgear provides a user settings page in addition to the default Auth UI for user registration and login.
Your users can update their profile from this settings page by following the steps below:
First, within your application, provide a link to the user settings page for your Authgear project. The URL should look like this: https://<YOUR_AUTHGEAR_ENDPOINT>/settings
. Note that users can not access this link directly without logging in first.
After a user logs in and visits the settings page, they can view their profile photo and other details.
Users can click on the Edit Profile button to update profile details such as name, gender, photo, and more.
To edit a profile attribute, the user should click on that attribute.
Learn how to track a user that signs up from a particular source or campaign.
In this guide, you'll learn how to track users from a particular source before and after they sign up. For example, knowing how many people sign up for your application through a signup link that you have included in a blog post or an email campaign.
To follow this guide, you need to have the following:
A free Authgear account.
An application in the Authgear Portal and note down the configuration of the application.
A client application that is written in your preferred language or framework.
For this guide, we'll build a demo Express application that has the following features:
Read a source
URL parameter defined by you (the developer).
Send the value of the source
parameter to the Authgear authorization server using the OAuth 2.0 state
parameter.
Read the value of state
returned after user authorization (sign up) and log the value in a database or analytics system like Mixpanel.
The authorization server (Authgear) will include the same state parameter value when redirecting the user-agent back to the client application. As a result, the client application can retrieve the value of state
returned to verify that it is the origin of the authorization request.
We will use the above behavior of the authorization process to track a user before and after they sign up.
The following steps show the steps for building a simple application that is capable of tracking users before and after they sign up.
1. Express:
2. Axios:
Next, inside the project directory, create a new app.js file then add the following code to the file:
You can get the correct configuration values (CLIENT_ID, CLIENT_SECRET, REDIRECT_URL, and AUTHGEAR_ENDPOINT) from the Applications section of the Authgear Portal.
In this step, we'll implement a /login
route in the demo application. This route will support a source
query parameter, for example, /login?source=002
.
Add the following code to the end of app.js to implement the /login
route:
The above code will check if the source parameter is included in the HTTP request to the /login
route. If there is a source
parameter, the value of the source will be added to the authorization URL's state parameter.
The following is an example of a login URL that includes the source parameter:
As described earlier, Authgear will return whatever value you put in the state
parameter of the authorization URL. In the last step, we will read the value of the source
parameter from the /login
route and pass it to the state
parameter. In this step, we'll read the state
parameter that Authgear returns in the redirect URI for the initial value we passed (source
).
To do this, we'll add a /
route to resolve our redirect URI. Add the following code to the end of app.js to implement the route:
The sourceFromState
constant holds the value for the state parameter in the redirect URI. You can save this value to a database to track that the user has successfully signed up using the link with the source value in your original campaign link. You may also send this link to an analytic tool like Mixpanel to track the user and source.
To run the demo app, run the following command in the terminal:
Then, open http://localhost:3000/login?source=002
on a browser. You can change 002 to any random string that you wish to use for tracking a source or campaign. Also, be sure to add http://localhost:3000
as a redirect URL for your application in the Authgear Portal.
A guide on recommended practices for setting password for a user account created by an admin
In some use cases, you (the admin) may need to create an account on behalf of a user. In such cases, the admin can do this either from the Portal or using the Admin API. A common question that arises when admins create accounts for users is how to handle the process of setting a password for the user.
In this post, we'll cover a few options and describe examples of automating the process of sending passwords to new users using Authgear Portal or webhooks.
Some of the options are:
Use the "Automatically create a password and send to the user" feature so that Authgear can auto-generate a secure password and send it to the user.
Set your own unique and secure password for the new user and let Authgear send it in an email to the user so they can log in with it.
To improve security, enable the "Ask user to change password on login" feature so that users are required to change the password set by an admin.
First, log in to Authgear Portal, select your project, then navigate to User Management > Users. From the Users page, click on the Create User button on the top right corner to open the Create User page.
On the Create User page, enter the user's email (only email
supports auto-sending of password from Authgear currently).
Next, enter a secure password you wish to set for the user in the Password field.
Check the "Send the password to user's email" box to enable Authgear to send the password entered in the Password field to the user.
If you're using a phone number instead of email for user identity, you need to use your own means to send the password to the user as Authgear only sends passwords to email at this time. For example, you can set up a webhook to send the password to a phone number as shown below.
Creating a new account on behalf of a user from either the Authgear Portal or using the Admin API will trigger the user.created
event.
To set up a webhook, navigate to Advanced > Hooks in the Authgear Portal. Next, click on the Add button under Non-blocking Events to add a new webhook.
Select Webhook under the Event dropdown and enter the URL for the webhook endpoint that will be listening for webhook events from Authgear. Or select TypeScript to run everything on Authgear. Click Save when you're done.
Here is an example of an event log entry for a user.created
event when a new user is created from the Portal:
You can use the value of context.triggered_by
to determine how the new user account was created then, only send a message when the account was created by an admin (admin_api
). You can extract the new user's phone number from payload.user.standard_attributes.phone_number
.
The following code shows what a TypeScript hook that listens for the user.created
event looks like:
The message you send to new users from your webhook after creating an account for them can look like this:
You can skip the step of creating a random secure password for your new user by selecting the "Automatically create a password and send to the user" radio button on the Create User page.
To do this, on the Create User page, click on the "Automatically create a password and send to the user" radio button.
In the Create User page, just below the "Send the password to user's email" checkbox, you'll find a "Ask user to change password on login" checkbox which should be checked by default.
If you wish to force users to change their password after they login using the password that was set for them in Authgear Portal either by an admin or automatically, make sure the "Ask user to change password on login" box is checked. Otherwise, uncheck it if you wish to allow users to continue using the password you set for them.
When you're done with the above steps, click on the Add User button on the top left corner of the Create User page to create the new account.
Users can still log in to their new account if they lose or can't find the password you set for them. To log in, they can click the Forgot Password button from the login page. A Verification code or link will be sent to the user via email or text message. Next, the user can then set a new password that they can continue using to log in to their account.
Alternative to the above steps, you can create a new user account from the Admin API and have Authgear send them their password using the following Admin API mutation:
The input parameter of the createUser
mutation includes the following objects and fields:
definition
: The value of this field is loginID
. In loginID, you define the identity type using the key
field and the actual value of the identity (eg. the user's email address) in the value
field.
password
: Enter the value for the password you wish to set for the user here.
sendPassword
: Use this field by setting the value to true
or false
to enable or disable the automatic sending of password to users.
setPasswordExpired
: Set to true
to force users to change their password on login.
The resetPassword
Admin API mutation also supports sendPassword
and setPasswordExpired
inputs. Hence, you can use it to set a password for a user you've already created and want to send them a new password and require them to change their password on their next log-in.
Example:
The steps described in this post, show how you can customize the post account creation experience for accounts created for a user by an admin.
For the particular case we considered, we described how to use webhooks to notify a user about their new account and what they should do next. Even if you use other tools to notify users about their new account, it's worth noting that Authgear's user.created
event can help you to know when a new account has been created.
Guide on how to use Authgear to secure Firebase services
Firebase is Google's flagship solution for building serverless web and mobile applications. Some of the services Firebase offers include Firestore database, Cloud Storage, Cloud Functions, and Authentication.
You can secure Firebase services like Firestore and Cloud Storage such that only authenticated users in your app have read and write access to certain parts or the entire database. This can be useful when your app allows users to generate content and you need to control who can add or view what.
In this guide, you'll learn how to use Authgear as a custom authentication system to secure Firestore database.
Authgear is a cloud-based solution that is 100% focused on user authentication and IAM. While Firebase, on the other hand, offers other cloud services such as Cloud Storage and real-time database Firestore that enable developers to build full-stack apps without the need for implementing their own backend. Hence, you can use Authgear as an authentication provider for your app that uses Firebase to enjoy all the security and login features it offers.
Custom Tokens is a feature in Firebase that allows you to authenticate users using secure JWT (JSON Web Tokens) from a third-party authentication system.
Typically, to authenticate users via Custom Tokens, your authentication system (e.g., Authgear) will authenticate users using your preferred method (e.g., username and password), then return a valid JWT to your client application.
The client application will pass the JWT to Firebase to create a Firebase user instance using the user's sub
attribute from Authgear.
The following flow diagram shows the complete sequence of using Firebase Custom Tokens and Authgear.
In this section, we'll cover a step-by-step guide for using Authgear JWT with Firebase Custom Tokens.
As part of the guide, we'll build a demo Todo app. The app will have the following features:
Users Login/Sign up
Add to-do tasks
Delete to-do tasks
Only logged-in users can add tasks
Data is stored on the cloud, and a user can only view/delete tasks they created.
In order to follow the steps in this guide, you should have the following:
Firebase project
Node.js installed on your computer
For this part, you'll login to your Firebase console and configure your project.
First, we'll create a Cloud Function that will verify the access token (JWT) from Authgear and use the uid
associated with the JWT to create a Firebase Custom Token.
Note: this may require you to upgrade your Firebase project to at least the Blaze plan.
Next, create a cloud_functions
folder in the root directory of the Authgear React example project you cloned earlier.
Change your working directory to the cloud_functions
folder:
Run the following command to install Firebase CLI:
After the CLI is installed, run the firebase login
command and follow the prompt to login to your Firebase project in the CLI.
Run the following command to initialize Cloud Function in the cloud_functions folder you created earlier:
Follow the prompt to create a v2 Cloud Function. Now you should have a function/index.js
file in your cloud_functions folder. This is where you'll write the code for your cloud function.
In this step, we'll implement a cloud function that does the following:
Accept HTTPS requests from your client application through an endpoint.
Read the value of your Authgear JWT from the HTTPS request authorization header.
Validate the JWT to ensure it is valid (not expired).
If the JWT is valid, the function will read the uid
attribute from it and use the value to call firebaseAdmin.auth().createCustomToken(uid)
. This will generate a new Firebase Custom Token that your client application can use to login to Firebase.
To implement the above function, open function/index.js
in your cloud_functions
folder and replace the content with the following:
Put your Authgear endpoint in const authgearEndpoint = "";
.
Run the following commands to install dependencies:
Finally, run firebase deploy
to deploy your new function.
On successful deploy, Firebase CLI will output the public endpoint for your function in the terminal. Copy the endpoint as you will use it later in your React app.
In this part, we'll implement the client application that will use Authgear and Firebase.
As mentioned in the prerequisites for this post, you can get the starter code for the application from our React example app repo.
Go to the Firebase Console and select your project. Next, click on Web as your target platform.
Enter the name of your app (e.g., My todo app), then click Register app.
In the Add Firebase SDK section, select Use npm, then run npm install firebase
from the root directory of the Authgear React example repo (confirm that you're not running the command in the cloud_functions folder).
Create a new firebase.js
file in the root directory of your React project.
Copy the code that includes your Firebase config, and paste it in the firebase.js
file.
Update firebase.js
to expose the Firebase services you'll be using:
Here we'll implement a to-do feature in our React app. The Todo component will contain all the code for implementing this feature.
The component will do the following:
Get the current user's access token from Authgear using the Authgear SDK.
Make an HTTPS request to your Firebase function endpoint using the fetch()
method of the Authgear SDK. The fetch()
method includes the user's access token in the HTTPS request's authorization header.
Use the custom token that is returned by the cloud function to sign in to Firebase.
Add a new todo item to the Firestore database
Display the todo items
Delete a todo item
Create a Todo.tsx
file in the src folder of your React project, then add the following code to the file:
Add your Cloud Function endpoint in const firebaseFunctionEndpoint = "";
Open App.tsx
and add the following route in <Routes>
:
Make sure to import the Todo in App.tsx.
Finally, add a router link to Home.tsx
just after the User Settings link:
You can click on the My Todos link to open the Todo page.
Return to your project in Firebase console, then navigate to Build > Firestore Database. Enable Firestore if it's not active for your project.
Go to the Rules tab, then change the security rule to the following:
The above rule will restrict read and write access to data in /todos/{userID} to only authenticated users. Click Publish to activate the new rule.
You should be able to authenticate with Authgear and add items to the to-do.
To get the container ID, log in to and navigate to the dashboard's homepage. You should find a list of all your containers and their ID. Note down the ID for the container you wish to connect to Authgear.
Note: Your project must be on an enterprise plan to use the Custom SMS Provider feature. for more details.
Note: Your project must be on an enterprise plan to use the Custom SMS Provider feature. for more details.
For this step, your Twilio account credentials such as Account SID, Auth Token (or API SID) are required. You can find these details in your console at .
Message Service ID is a feature on Twilio that lets you create multiple sender IDs based on different campaigns and conditions. Enter your Twilio Message Service ID to have Authgear use the multiple sender IDs under it. Learn more about Twilio Messaging Services .
The Export User API offers a means for exporting user data such as user ID, email, phone number, etc from your Authgear project into a or file.
To make HTTP(S) requests to Export User API endpoints, your application must be authenticated using an in the Bearer Authorization header. The API will return a "403 Forbidden" error if an invalid JWT is used.
See the for more details about the endpoints, inputs, and pointers.
See for a more detailed guide on how to get your key ID, and private key and generate Admin API JWT using different programming languages.
The user profiles contain information about your end-users such as name, email, addresses, and their unique identifier. You can manage the profiles via the Portal & Admin API. The end-users can also manage their own profile through the Profile section in the provided by the AuthUI.
The following attributes are built-in supported by Authgear. They are the set of . Some of them are default hidden from the Admin Portal and end-users. Their visibility and mutability can be configured through the Admin Portal.
The following attributes are coupled with the owned by the end-user. They represent the email addresses, phone numbers, or usernames the end-users are using to authenticate themselves on Authgear. If the end-user uses a third-party identity provider for authentication, these attributes will be coupled with the corresponding attributes returned by the provider.
The custom attribute name should consist of lowercase letters (a-z), digits (0-9) and underscore (_) only. It must start with lowercase letters (a-z), and NOT end with an underscore (_). The default display name will be the attribute name split with underscore and in title case. e.g. my_string
will render as My String
in the .
You can arrange the attribute order by drag-and-drop the handle in the custom attribute configuration in the Portal. This will control the order of how the attributes are shown to the end-users in the .
Through , developers ALWAYS have full access to ALL the standard attributes and custom attributes. The Admin API allows the developer to view or edit the standard attributes and the custom attributes.
The session bearer is someone who has a valid session cookie or a valid access token. The standard attributes of the end-user whom the session represents can be viewed by accessing and . The session bearer can be the end-user, the client mobile app, or the client website.
The end-user can view or edit the standard attributes through the Profile section in the provided by the AuthUI.
Authgear supports various . End-users can sign up and log in to your apps via these connections. Upon signup, these providers will return a set of user attributes about the end-user. Authgear will copy those attributes and populate the profile of the end-user.
More info about the population logic can be found in .
Roles and Groups can extend access management on your application that Authgear powers. Authgear includes a user's roles in the response from the and in the JWT access token.
It is up to you to create roles for your Authgear project based on your unique need and use case. You can create new roles using the Authgear Portal or the (using GraphQL).
Set up your custom code with the GraphQL endpoint. Or use the GraphiQL Explorer provided by Authgear (Navigate to Advanced > Admin API > GraphiQL Explorer in Authgear Portal to access).
Implement your own custom code that has . Alternatively, you can use the GraphiQL Explorer in Authgear Portal (Navigate to Advanced > Admin API > GraphiQL Explorer).
Then, click the Add Roles button, select a role from the drop-down menu, and click Add. If the drop-down is empty, it is possible that you have not created any roles yet. See .
To access any of the applications in your Authgear account, each user must have a profile in the account. contain information about your users such as name, contact information, and and you define. You can retrieve and manage user profiles in the following ways:
.
.
.
.
An Authgear account: You need an Authgear account to follow this guide. If you don't have one, you can on the Authgear website.
A Registered App: You need a (client) in Authgear.
Go to the .
Once Authgear completes authentication and returns control to your application, it provides the user profile to the application. Most developers prefer to use the Authgear SDKs to get the UserInfo object using the fetch user info function. To start using this function read relevant to the SDK of your choice. Here are some code snippets that call the fetch user info function for different Authgear SDKs:
See the for more details about the shape of user info and the available user profile attributes.
Authgear provides an GraphQL endpoint that allows applications and services to access and manipulate the User Profile object. The lets users interactively explore the Admin API. With the API Explorer, you can search for users' profiles or update their standard or custom attributes. See the example steps of how to achieve this below:
The OpenID Connect (OIDC) endpoint is a protected resource that provides information about a user when a service provider presents an access token that has been issued by your Authgear Token endpoint. The scopes in the access token specify the user attributes that are returned in the response of the user info endpoint. It is important to note that the openid
scope must be one of the access token claims.
Indicate if the user is anonymous, i.e. no or is provided
We are going to use cURL commands in our API calls or you can also use or similar tools.
You have successfully configured your application to use Authgear as an OIDC provider. See your for detailed steps.
See a detailed explanation of the structure and fields included in the response of the UserInfo endpoint .
See our post about how to to learn more.
An Authgear account. Create one for free .
And basic experience with Authgear.
Mandatory: Use the mandatory policy to require 2FA for all users. That means users who have not set up 2FA will not be able to log in if no grace period is set. To use this option, consider further actions like .
When users that could not set up their 2FA during the Global Grace Period contact you (the admin), enable individual grace period for them using the instructions in .
All custom attributes are returned in the response under the custom_attributes
field.
In Oct 2021, that all apps allowing users to create accounts should also provide ways for them to initiate account deletion within the apps, starting from January 31, 2022. It is also a good design to give your end-users more control over their data.
On Jan 22, 2022 to extend the deadline to June 30 2022.
In the pre-built page, you can show a button for the end-users to initiate account deletion. Users can access the Delete Account button under Advanced Settings in the User Settings page when you enable Account Deletion on your project.
Your backend server can invoke the mutation scheduleAccountDeletion
with the to initiate the account deletion.
Your backend server can invoke the mutation scheduleAccountDeletion
with the to initiate the account deletion.
See the event details in .
Your hooks can optionally apply mutation for certain blocking events. The supported mutation is specific for each type of blocking event. Refer to the to see what mutation is supported.
Set up (SPF) for your domain.
Set up (DKIM) for your domain.
Create an "App ID" by adding a new "Identifier" , choose app IDs, enable "Sign in with Apple" enabled.
Create a "Services ID" by adding a new "Identifier" , choose service IDs, enable "Sign in with Apple".
Create a "Key" following with "Sign in with Apple" enabled. Click "Configure" next to "Sign in with Apple" and select "Primary App ID" with app ID created above. Keep the private key safe, you need to provide this later.
Using you can put extra information into the user profile's programmatically. This is useful for where making your current customer data better by adding more details from outside sources.
Step 1. Make sure that you have an Authgear account. If you don't have one, you can on the Authgear website. Start by logging into your .
Once you learned how to update user profiles, now you can discover different ways of in Authgear.
An Authgear Account. You can create one for free .
To update user profiles using this method, first, log in to the , then select your project.
The second option available for updating user profiles is the Admin API. The Admin API is a GraphQL API that you can use to manage your users. You can access Admin API from the or by making requests to the API from your code or a client like Postman.
For a detailed guide on making a GraphQL query to update user profiles, see our dedicated post on updating.
Also, see the to learn how to update custom attributes of a user profile.
The includes an optional state
parameter. The value of the state
parameter can be any random string or number defined by a client application (e.g a web or mobile that uses Authgear for user authentication) before the client makes an authorization request. In simple terms, the state
parameter is added to the authorization URL as a URL query.
First, create a new project directory and open it. The demo application for this guide is a simple application that use Axios to make HTTP requests. Hence, install both packages using the following commands:
You can create accounts for users using Authgear Portal or and the password you set or a random auto-generated password will be sent to the user's email address. In addition, you can also configure the new accounts such that users are required to set a new password on login.
Note: Creating a user via the batch does not trigger user.created
. Also, you need to set up your webhook before you start creating new users.
The example app used for this guide is based on the Authgear React example repo (clone or download the code ). Once you get the code, you'll have to set up an Authgear client application with type "Single Page Application" in the Authgear portal. More details are in the README.md file for the repo.
Alternatively, you can view/download the complete code with the Firebase example from a separate GitHub repo .
Authgear account (sign up for free )
To create a Cloud Function, open and navigate to Build > Functions and enable the Cloud Function if it isn't already active for your project.
Edit the IAM settings for the service account linked to your project. To do this, go to and add Service Account Token Creator
to {randomNumbers}-compute@developer.gserviceaccount.com
.
Follow the instructions in the README.md
file for the Authgear React example app to configure the app with your Authgear project. Then run the app.
The full list of events
Occurs right before the user creation. User can be created by user signup, user signup as an anonymous user, or created by the admin via the Portal or Admin API.
Occurs right before the update of the user profile.
Occurs right before account deletion is scheduled.
This event does not support mutations.
Occurs right before the access token is issued. Use this event to add custom fields to the JWT access token.
Occurs after a new user is created. User can be created by user signup, user signup as an anonymous user, or created by the admin via the Portal or Admin API.
Occurs when the user profile is updated.
Occurs after the user logged in.
Occurs when the user was disabled.
Occurs when the user was re-enabled.
Occurs whenever an anonymous user is promoted to a normal user.
Occurs when an account deletion was scheduled.
Occurs when an account deletion was unscheduled.
Occurs when the user was deleted.
Occurs when a new email is added to an existing user. Email can be added by the user in the setting page, added by the admin through the Admin API or Portal.
Occurs when an email address is removed from an existing user. Email can be removed by the user in the setting page, removed by admin through admin API or Portal.
Occurs when an email address is updated. Email can be updated by the user on the setting page.
Occurs when an email address is change from unverified to verified for an existing user. Email can be verified by the user in the setting page, mark verified by admin through admin API or Portal.
Occurs when an email address is unverified. Email can be unverified using Admin API.
Occurs when a new phone number is added to an existing user. Phone numbers can be added by the user in the setting page, added by admin through admin API or Portal.
Occurs when a phone number is removed from an existing user. Phone numbers can be removed by the user on the setting page, removed by admin through admin API or Portal.
Occurs when a phone number is updated. Phone numbers can be updated by the user on the setting page.
Occurs when a phone number is change from unverified to verified for an existing user. Phone can be verified by the user in the setting page, mark verified by admin through admin API or Portal.
Occurs when a phone number is unverified. Phone numbers can be unverified using Admin API.
Occurs when a new username is added to an existing user. Username can be added by the user in setting page, added by admin through Admin API or Portal.
Occurs when the username is removed from an existing user. The username can be removed by the user on the setting page, removed by admin through admin API or Portal.
Occurs when the username is updated. The username can be updated by the user on the setting page.
Occurs when a user has connected to a new OAuth provider.
Occurs when a user is disconnected from an OAuth provider. It can be done by the user disconnecting their OAuth provider in the setting page, or the admin removing the OAuth identity through admin API or Portal.
Occurs when the user enabled biometric login.
Occurs when biometric login is disabled. It will be triggered only when the user disabled it from the settings page or the admin disabled it from the Admin API or portal.
The event may contain different objects. You can refer to the below for their attributes.
This event supports
This event supports
This event supports