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:

• Zero trust authentication architecture with (OIDC) standard.

• 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 a wide range of identity providers, such as , , and (AD).

• 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 drag-drop low-code dashboard.

• Various security features such as audit logs, brute force protection, smart account lockout, password policy, etc.

• APIs for further integration and customizations.

Most importantly, you can with Authgear for free.

Learn about Authgear

Authgear contains the following high-level components:

Authenticate on the Web/Mobile App

• 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.

• 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.

• Authentication Flow API (coming soon) - 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.

Backend Authentication and Integrations

• - 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

Management Portal

• Authgear Portal - You can configure your projects, manage users, check out , or customize the AuthUI

• Analytics Page - View reports of your total users and active users over a specific time interval on the .

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.

Get the Extension

The extension is included in the SDK. Please refer to the above section for getting the SDK.

Usage

Configure OkHttpClient to use AuthgearInterceptor as follows:

Authgear authgear = // Obtain the authgear instance.
OKHttpClient client = new OkHttpClient.Builder()
            .addInterceptor(AuthgearInterceptor(authgear))
            .build()

The client would then include the access token in every request and refresh the access token when necessary before the requests.

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.

Prerequisite

1. Create an app in the Linkedin Developers Portal.

2. In the "Products" section, choose "Sign In with LinkedIn"

3. In the details page of the created app, click the "Auth" tab

4. Take notes of "Client ID" and "Client Secret", add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/linkedin to "Redirect URLs" in "OAuth 2.0 settings" section

Configure Sign in with LinkedIn through the portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with LinkedIn.

3. Fill in Client ID.

4. Fill in Client Secret.

5. Save the settings.

🎉 Done! You have just added Linkedin Login to your apps!

Prerequisite

1. Setup your own AD FS server

2. 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.

Configure Sign in with Microsoft AD FS through the portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with Microsoft AD FS.

3. Fill in Client ID, Client Secret and Discovery Document Endpoint.

4. Save the settings.

🎉 Done! You have just added Microsoft AD FS Login to your apps!

Brand and customize login experience for your users where you can customize domain, email, and localize to handle different languages.

You can use your own translation or change the default text in the AuthUI.

1. Go to Portal > Localization > Manage Template Contents

2. Override translation by providing a JSON file in the text box.

You can monitor the Authgear app, and see and retrieve log event data.

If you have a traditional web application like Java EE, Express, PHP, GO, Laravel, or ASP.NET Core MVC and you want to integrate authentication features.

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.

Activity

The Analytics page shows two activity bar charts that show a weekly or monthly summary of user activities on your Authgear project.

Active user

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.

Total users

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.

Signup Conversion

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).

User Signup Methods

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.

If your API or backend service needs authentication, you can validate the JWT token in your application server code.

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:

Authgear provides token-based or cookie-based authentication. You will need to decide which approach you are going to use before starting the setup.

Token-based authentication

This approach is suitable for mobile apps or single-page web applications.

In Token-based authentication, Authgear returns the access token and refresh token to the client app after authentication.

The client SDK will automatically renew the access token with the refresh token for you, so you don't have to worry about it.

Your client app should call your backend with the access token in the Authorization header, and you can verify the access token by integrating Authgear with your backend. The HTTP requests can be authenticated by or .

Request example:

Cookie-based authentication

This approach is suitable for all types of websites, including server-side rendered applications.

In Cookie-based authentication, 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.

In this setting, if you have multiple applications under yourdomain.com, all applications would share the same session cookie automatically. After that, you can verify the cookies by integrating Authgear with your backend. The HTTP requests must be authenticated by .

Request example:

By using Authgear, you can add a login to your website easily. Authgear supports various authentication methods, that you can easily turn on and configure in the portal.

Prerequisites

To authenticate with cookies, you will need to set up a custom domain for Authgear, so that your website and Authgear are under the same root domains. e.g. Your website is yourdomain.com, and Authgear with a custom domain auth.yourdomain.com.

In this setting, if you have multiple applications under yourdomain.com, all applications would share the same session cookies automatically.

Overview

How it works

Your app server will receive a request with the cookie

Verify request in your app server

To verify the requests in your app server, you must Forward authentication to Authgear Resolver Endpoint.

Request example

Get Started

The following tutorials show you how to add user login to your website using Authgear.

1. Frontend Integration

2. Backend Integration

Authgear let your users login passwordlessly with WhatsApp OTP.

To enable this feature from the Portal:

1. Go to Authentication > Login Methods, we are going make few changes on this page.

2. In the top section of Select Login Methods, select Mobile.

3. In Authentication of Select Login Methods, select Passwordless.

4. In the tabs section below, switch to the tab Verification and OTP.

5. In the dropdown Verify phone number by, select either WhatsApp or SMS or WhatsApp only.

6. 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.

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.

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 create a demo account with email/phone and password by turning password on temporarily. In the project portal:

1. Go to Authentication > Login Methods.

2. In Select Login Methods, select Custom.

3. In the tabs section below, select the tab Custom Login Methods.

4. In Custom Login Methods, activate Password.

5. Go to User Management, press Add User in the command bar.

6. Create the demo user by entering the email address and password

7. Go to where you were in Step 4, deactivate Password.

8. Now you can login as the demo user in your app with the email and password.

9. Submit your app for review with the credentials.

You can add a privacy policy and a terms of service link to the sign up page.

Change in the Portal

These two links can be easily added in the project Portal

1. Go to UI Settings in the Portal

2. Fill in the Privacy Policy Link and Terms of Service Link in the Link Settings section

3. Save the settings.

The values will be used as the href of <a> HTML tag so they must be valid URL. If both of the links are left empty, the whole paragraph on the signup page will be hidden.

Edit translation.json

You can also add these links by including two special translation keys in translation.json.

The keys are terms-of-service-link and privacy-policy-link. The values will be used as the href of <a> HTML tag so they must be valid URL.

For example,

If you wish to hide the whole paragraph, set BOTH to empty string.

You can change how the end-users see Authgear in the UI Settings page in the Portal.

Colors

Authgear provides 7 theme color presets. You can also input color codes that match your brand.

Dark mode

Authgear can change the UI appearance based on the system settings of the end-users. Turn on Dark Theme to enable this feature.

App Logo

The app logo helps the end-users to identify your app, and it is shown in all pages, emails, etc. JPEG, PNG and GIF are supported.

Favicon

Change the favicon to match with your web or mobile app to provide a coherent experience for the end-users.

In the case of losing access to the MFA authenticators, the end-user can recover their account by using the emergency Recovery Codes. However they may have lost the codes and need customer support.

Set customer support link

You can add a customer support link in the Portal.

1. Go to UI Settings in the Portal

2. Fill in the Customer Support Link in the Link Settings section

3. Save the settings.

The value will be used as the href of <a> HTML tag. It can be a URL or a mailto: link.

Customize the label

You can also modify the text shown to the end-users by including two special translation keys in translation.json.

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.

Platform support and Multi-devices

The passkey standard is supported on the latest versions of Chrome, Safari, and Firefox browsers. On iOS 16 and macOS 13 (Ventura), Apple has added passkey support to the iCloud Keychain service. Passkeys are also supported on Android 9 (API level 28) or higher. A passkey is synchronized and relayed with an iCloud account and can be used across a user's devices.

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.

Hardware security keys

Besides the built-in support of all major desktop and mobile platforms, passkeys can also be stored in hardware security keys such as YubiKeys, which provide the highest security against attacks.

Add Passkeys to your apps with Authgear

Authgear adds a passkey feature to your apps and websites instantly. To enable it:

1. In your project portal, go to Authentication > Login Methods.

2. In the Select Login Methods section, turn on the Enable passkey support for compatible devices. toggle.

3. Press "Save" and your app now supports passkey login!

Support on different platforms

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.

Prerequisite

To configure "Sign in with Apple" for Authgear, you will need to fulfil the following:

1. Register an Apple Developer Account. Apple Enterprise Account does not support "Sign in with Apple"

2. Register your own domain.

3. Your domain must be able to send and receive emails.

4. Set up Sender Policy Framework(SPF) for your domain.

5. Set up DomainKeys Identified Mail(DKIM) for your domain.

6. Create an "App ID" by adding a new "Identifier" here, choose app IDs, enable "Sign in with Apple" enabled.

7. Create a "Services ID" by adding a new "Identifier" here, choose service IDs, enable "Sign in with Apple".

8. Click "Configure" the Next to "Sign in with Apple". In "Primary App ID" field, select app ID created above.

9. Fill in and verify the domain created above, add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/apple to Return URLs

10. Create a "Key" following this guide 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.

Configure Sign in with Apple in Authgear Portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with Apple.

3. Fill in the Client ID with the Service ID obtained above.

4. In Apple Developer Portal, view key information of the "Key" created above.

5. Jot down the Key ID and download the key text file (.p8 file).

6. Copy the content in the key text file to Client Secret text area in Authgear Portal..

7. Fill in Key ID field using the Key ID obtained from step 5.

8. In Apple Developer Portal, click username on the top right corner, click View Membership.

9. Find the Team ID from Membership Information, fill in Team ID field in Authgear portal.

10. Save the settings.

🎉Done! You have just added Sign in with Apple to your apps!

Prerequisite

1. Create an Azure Active Directory (Azure AD) account here

2. Setup a tenant by completing Quickstart: Set up a tenant

3. Register an application by completing Quickstart: Register an application with the Microsoft identity platform

4. 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

5. Configure "Redirect URI" with https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/azureadv2

6. Follow this 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.

Configure Sign in with Microsoft through the portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with Microsoft

3. Fill in Client ID with Application (client) ID of your just created Azure AD application.

4. Fill in Client Secret" with the secret you get after creating a client secret for your Azure AD application.

5. 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.

6. Save the settings.

🎉 Done! You have just added Azure Active Directory (Azure AD) Login to your apps!

Prerequisite

1. Sign in Microsoft Azure.

2. Create a B2C tenant by following this tutorial.

3. Enable self-service sign-up for the tenant by following this doc

4. Go back the main page of Microsoft Azure and search for "Azure AD B2C"

5. Create a app registration for Authgear by following this guide.

6. Configure "Redirect URI" with https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/azureadb2c.

7. Follow this guide to create a sign-up and sign-in user flow.

8. After creating the user flow, configure it

• Open "Application Claims".

• Make sure "Email Addresses" is checked.

Configure Sign in with Azure AD B2c through the portal

If you have finished the above prerequisite, you should have the following information:

1. The Tenant Name, obtained in Step 2

2. The Application (Client) ID, obtained in Step 5

3. The Policy (User flow) Name, obtained in Step 7

Then in Authgear portal, do the following:

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with Microsoft Azure AD B2C.

3. Fill in Client ID with the Application (Client) ID above.

4. Fill in Client secret with the client secret you get when you create the app registration.

5. Fill in Tenant with the Azure AD B2C Tenant Name.

6. Fill in Policy with the Policy (User Flow) Name. Normally it starts with b2c_.

7. Save the changes

🎉 Done! You have just added Azure AD B2C Login to your apps!

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.

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.

1. How to Navigate to the Password Settings 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).

2. Enable Reset Password by Phone Number

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:

3. Reset by Email using OTP Instead of Link

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.

To send Authgear emails to end-users with your own domain, e.g. [email protected]. You will need to configure the external SMTP provider.

Authgear currently supports SendGrid and other custom SMTP Providers.

Send from an email address under your domain

The sender address can be configured by changing the value of theemail.default.sender key in the localization JSON. Go to Portal > Localization > Translations and add/change the value of email.default.sender to your own email address, for example [email protected], and Save the settings. The value can be set separately for each locale.

Sender domain authentication

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 [email protected].

Follow the instructions from the email service provider for setting up your domain:

• How to set up domain authentication on SendGrid

Configure the external SMTP provider

The external SMTP provider can be set up in Portal > Custom Email Provider. Enable the Use my own provider toggle to see the fields.

Use SendGrid as external SMTP provider

1. Log in to your SendGrid account

2. Create API Key in Settings > API Keys

3. Set the API Key Name for your reference the choose Restricted Access under API Key Permissions

4. Under Access Details, expand Mail Send and give Full Access to the Mail Send permission

5. Click Create & View. Copy the API key created and save it somewhere safe

6. In Authgear Portal, navigate to Custom Email Provider

7. Enable Use my own provider.

8. Choose SendGrid and paste the API key you copied, and Save

9. You can send a test email to check the configuration

Using other SMTP Providers

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.

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:

1. User initiates the login process by entering their email address on the login page.

2. Authgear generates a unique, time-limited login link associated with the user's email address.

3. The link is sent to the user's email inbox, with a button prompting them to click on it to log in.

4. The user clicks on the link, and approve the login

5. 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:

1. In the Authgear Portal, go to "Authentication" > "Login Methods"

2. Select "Email" or "Mobile/Email" as login methods

3. Go to the "Verification and OTP" tab

4. Under "Email", in the "Verify email by" field, select "Login Link"

Single sign-on (SSO) is defined as login once, logged in all apps. If you have multiple mobile apps or websites that use the same Authgear project. You can configure your apps to turn on the SSO feature, so the end-users only have to enter their authentication credentials once.

If you are building cookie-based websites with the same root domain (e.g. app1.example.com / app2.example.com), you can skip this section. Sessions are shared among *.example.com automatically, see .

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.

Create an App in Facebook for Developers

If you are using Authgear in your existing Facebook Apps, you may skip to the next step to set up the OAuth client.

Prerequisite

You will need a Facebook developer Account. Register as one by clicking Get Started in the website.

Create an App

Click Create App in the panel and choose your app type.

Set up the OAuth Client

1. In the app panel, click Add Product next to Products in the sidebar.

2. Click the Set Up button in Facebook Login.

3. Go to Settings of Facebook Login.

4. Make sure Client OAuth Login and Web OAuth Login are enabled.

5. Add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/facebook to Valid OAuth Redirect URIs and save the changes.

Configure Login with Facebook in Authgear Portal

Get your OAuth Client details

After setting up the Facebook Login product, go to Settings -> Basic in the sidebar.

Your will need the App ID and App Secret to configure Facebook Login.

Configure in Authgear Portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Login with Facebook.

3. Fill in the Client ID with the App ID obtained from the previous step.

4. Fill in the Client Secret with the App Secret obtained from the previous step.

5. Save the settings.

🎉 Done! You have just added Facebook Login to your apps!

Your end-users can now sign in with Facebook on Authgear pre-built Log In and Sign Up page. Existing end-users can connect their account to Facebook in the page.

If your mobile app has security requirements similar to that of mobile banking applications, you may want the end-users to authenticate themselves every time they use your app.

By default, the SDK stores the refresh token in a persistent storage specific to your app. The end-user signs in once and their session lasts for a long period, even if they quit the app.

You can alter this behavior by switching to a transient storage by setting the tokenStorage option to TransientTokenStorage() when configuring the SDK. The refresh token will be removed after the app is cleared, therefore authentication will be required on every app launch.

Authgear is an easy-to-use authentication platform that you can add to your apps to manage user sign-ins and identities. It saves your team and company from spending money, time, and dealing with potential issues that can happen when you try to make your own user sign-in and identity system.

• You've made a great app and now you want users to be able to sign in using either a username/password or their social media accounts like Facebook or Google. You also want to access their profile information after they've signed in so you can customize the user interface to them and apply your own rules about what they can do.

• You've also created an API or backend service that you want to protect using .

• You've got more than one app, and you're looking to set up Single Sign-on (SSO), so users only need to sign in once.

• You've made a JavaScript web app and a mobile app, and you need them both to safely connect to your API.

• You have a web app that needs to confirm users' identities using the centralized authentication system.

• You think passwords aren't secure enough and want your users to log in with unique codes sent through email or text messages.

• If a user's email address gets leaked in a data breach on some other site, you want to know about it. You also want to warn the users, or even stop them from logging into your app until they've changed their password.

• If you notice a lot of failed login attempts from the same IP address, you want to be able to block it to prevent a DDoS attack.

• If you're part of a big company, you want to link your current employee directory service so that employees can use their existing work credentials to sign in to different internal and outside apps.

• You don't want to or don't know how to, build your own system for managing users. This includes resetting passwords, creating, giving access to, blocking, and deleting users, as well as a user interface for managing all this. You just want to focus on your app.

• You want to add an extra layer of security, multi-factor authentication (MFA), when users try to access sensitive information.

• You're looking for an identity solution to help you comply with the ever-increasing rules and regulations of standards like SOC2, GDPR, PCI DSS, HIPAA, and others.

• You want to keep an eye on users' activities on your site or app. You want to use this information to improve the user journey, measure how well you keep users, and improve your sign-up process.

By using Authgear, you can add the login feature to your mobile native app and single-page application easily. Authgear supports various authentication methods, that you can easily turn on and configure in the portal.

Overview

How it works

Your app server will receive a request with the access token

Verify request in your app server

To verify the request in your app server, you can choose to Forward authentication to Authgear Resolver Endpoint or Verify JSON Web Token (JWT) in your app server.

Request Example

Get Started

The following tutorials show you how to add user login to your native mobile or single-page app using Authgear.

1. Frontend Integration

Choose your platform below:

2. Backend Integration

Prerequisite

1. Follow the to create a OAuth App.

2. In "Authorization callback URL", use https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/github.

3. After the creation, click "Generate a new client secret". Remember the client secret.

Configure Sign in with GitHub through the portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with GitHub.

3. Fill in Client ID.

4. Fill in Client Secret.

5. Save the changes.

🎉 Done! You have just added GitHub integration to your apps!

Set up a custom domain to let your users to 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).

1. Add domain

• Go to Custom Domain 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.

2. Verify domain ownership

• Go to your domain provider's site, 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.

3. Activate your custom domain

• 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.

Actions in the settings page

The end-user can perform the following actions on the setting page:

• Change their password.

• Add or change their email, phone number or username.

• Connect or disconnect to identity providers.

• Manage the signed in sessions.

• Enable or disable 2-step verification.

• and many more.

Open the settings page in websites

Use the open method to open the built-in settings page

import authgear, { Page } from "@authgear/web";

const openSettings = () = {
    authgear.open(Page.Settings)
}

Open the settings page with the SDK in mobile apps

If you are working on a mobile apps, you can open the settings page using the SDK. When the end-user has signed in, the SDK provides a method to open the settings page in a webview.

import React, { useCallback } from "react";
import authgear, { Page } from "@authgear/react-native";
import { View, Button } from "react-native";

function SettingsScreen() {
  const onPressOpenSettingsPage = useCallback(() => {
    authgear.open(Page.Settings).then(() => {
      // When the promise resolves, the webview have been closed.
    });
  }, []);
  return (
    <View>
      <Button
        title="Open Settings Page"
        onPress={onPressOpenSettingsPage}
      />
    </View>
  );
}

Future<void> onPressOpenSettingsPage() async {
  await authgear.open(SettingsPage.settings);
}

async void OnOpenSettingsClicked(object sender, EventArgs args)
{
  await authgear.OpenAsync(SettingsPage.Settings);
}

func onPressOpenSettingsPage(sender: UIButton, forEvent event: UIEvent) {
    authgear.open(.settings) {
        // When the completion handler is called, the webview is closed.
    }
}

public void onClickOpenSettingsPage() {
    authgear.open(Page.Settings, null, new OnOpenURLListener() {
        @Override
        public void onClosed() {
            // The webview is closed.
        }

        @Override
        public void onFailed(Throwable throwable) {
            // Some error occured.
        }
    });
}

Back to my app button

In web-based application, you may want to add the "Back to my app" button to the settings page so the user can navigate back to your website after changing the settings.

1. Go to Portal > UI Settings

2. Provide the URL in Back to Your App Link and click Save

To use webhooks you need to:

1. Deploy a webhook on your server.

2. Configure Authgear to deliver events to your webhook.

Configure Authgear to deliver events to your webhook

hook:
  blocking_handlers:
    - event: "user.pre_create"
      url: 'https://myapp.com/check_user_create'
  non_blocking_handlers:
    # listen to all events and filter events by type in request
    - events: ["*"]
      url: 'https://myapp.com/all_events'
    - events: ["user.created"]
      url: 'https://myapp.com/sync_user_creation'

Protocol

Events are delivered to your webhooks via HTTPS, so your server must support HTTPS.

Events are delivered to your webhooks with POST requests. You webhooks must return a HTTP status code within 2xx range. Other status codes are considered as a failed delivery.

Verifying signature

The request to your webhooks is signed with a secret key shared between Authgear and your hooks. You are RECOMMENDED to verify the signature and reject any requests with invalid signatures. This ensures the request originates from Authgear.

The signature is calculated as the hex encoded value of HMAC-SHA256 of the request body and included in the HTTP header x-authgear-body-signature.

To obtain the secret key, visit the portal and go to Advanced -> Hooks -> Webhook Signature. You may need to reauthenticate yourselves before you can reveal the secret key.

Here is the sample code of how to calculate the signature and verify it.

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
)

// Obtain the secret in the portal.
const Secret = "SECRET"

// HMACSHA256String returns the hex-encoded string of HMAC-SHA256 code of body using secret as key.
func HMACSHA256String(data []byte, secret []byte) (sig string) {
    hasher := hmac.New(sha256.New, secret)
    _, _ = hasher.Write(data)
    signature := hasher.Sum(nil)
    sig = hex.EncodeToString(signature)
    return
}

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        b, err := io.ReadAll(r.Body)
        if err != nil {
            // Handle the error properly
            panic(err)
        }
        defer r.Body.Close()

        sigInHeader := []byte(r.Header.Get("X-Authgear-Body-Signature"))
        sig := []byte(HMACSHA256String(b, []byte(Secret)))

        // Prefer constant time comparison over == operator.
        if subtle.ConstantTimeCompare(sigInHeader, sig) != 1 {
            // The signature does not match
            // Do NOT trust the content of this webhook!!!
            panic(fmt.Errorf("%v != %v", string(sigInHeader), string(sig)))
        }

        // Continue your logic here.
    })
    http.ListenAndServe(":9999", nil)
}

Authgear supports the following social and enterprise identity providers. Please click the link below for setup instructions.

• Apple

• Google

• Facebook

• GitHub

• Linkedin

• Azure Active Directory

• Azure AD B2C

• Microsoft AD FS

• WeChat

Set up OAuth client on Google Cloud Platform

To configure Google OAuth client for Authgear, you will need to create an OAuth client on Google Cloud Platform first.

Create a new project

Create a project on Google Cloud Platform through console. If you are adding Authgear to your existing Google Cloud Platform projects, you may skip to the next step to create the OAuth client.

Create OAuth Consent Screen

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.

Create OAuth client ID

1. Go to -> APIs & services -> Credentials

2. Click Create Credentials -> OAuth client ID

3. 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.

4. Add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/google to redirect URIs.

5. After creating a client ID, you will see the client ID under the OAuth 2.0 Client IDs section of the Credentials page.

You can find more details in official Google Cloud Platform doc

Configure Sign in with Google in Authgear Portal

Get your OAuth Client details

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.

Configure in Authgear Portal

1. In the portal, go to Authentication > Social / Enterprise Login.

2. Enable Sign in with Google.

3. Fill in the Client ID and Client Secret with the values obtained from the previous step.

4. Save the settings.

🎉Done! You have just added Google Sign In to your apps!

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 User Settings page.

Using Hooks you can put extra information into the user profile's custom attributes programmatically. This is useful for Profile Enrichment where making your current customer data better by adding more details from outside sources.

Here are easy steps to achieve this:

Step 1. Make sure that you have an Authgear account. If you don't have one, you can create it for free on the Authgear website. Start by logging into your Authgear dashboard.

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 TypeSctipt 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.

		
export default async function(e: EventUserPreCreate): Promise
			 {
  // API Key for IP Geolocation
  const apiKey = 'MY_API_KEY';
  // Any random IP address
	const ipAddress = '8.8.8.8' 

  // Fetch data from the IP Geolocation API
  const response = await fetch(`https://api.ipgeolocation.io/ipgeo?apiKey=${apiKey}&ip=${ipAddress}`);
  const data = await response.json();

return {
    is_allowed: true,
    mutations:{
      user: {
          custom_attributes: {
            "city": data.city, 
            "country": data.country_name,
            "timezone": data.time_zone.name
        }
      }
    },
  };
}

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:

Next steps

Once you learned how to update user profiles, now you can discover different ways of accessing user profiles in Authgear.

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.

Step 1: Enable Password Expiry

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.

Step 2: Set Expiry Date

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.

You can build your own custom UI powered by the new Authentication Flow API. Here are some resources for getting started:

Sign In With Ethereum(also known as SIWE) introduces a new way of authenticating and identification of a user using their crypto-wallet addresses. Authgear saves you from all the complex setups and brings you the technology of the future with just a simple click.

Platform support

The Sign In With Ethereum standard is built on the specification, which is typically performed on Web3 providers.

To make this as simple as possible, the following mainstream consumer-facing web3 providers are selected to be the gateway connecting your application and users.

These providers are typically supported by browsers with WebExtensions API, namely Chrome, Firefox, Edge, and Brave.

Supported NFTs

To assist you in building the greatest NFT-gated application ever, Authgear adds extra information to the user info that indicates whether the user owns NFT/NFTs of your selected NFT collection.

At the current stage, the following token types are supported:

Wallet address and NFTs in UserInfo

In the object of a user, the wallet address and the NFTs owned can be found.

Here is an example of such user:

Add Sign In With Ethereum to your apps with Authgear

To enable "Sign In With Ethereum" to your apps and websites:

1. In your project portal, go to "Authentication > Ethereum & NFT"

2. Turn on the "Login With Ethereum" toggle

3. Select your favourite blockchain network from the "Network" dropdown below

4. Press "Save" then "Confirm" and 🎉 now your app supports Sign in with Ethereum!

To prevent Web2 and Web3 identities being mixed together, Authgear has made it so that enabling "Sign In With Ethereum" would disable all your previously enabled identities and primary authenticators.

To go back to using Web2 authentication methods, you will have to disable "Sign In With Ethereum" and reconfigure your identities and authenticators.

Add NFT collections to your apps with Authgear

To populate user info with NFT tokens from the collections of your choice:

1. In your project portal, go to "Authentication > Ethereum & NFT"

2. Ensure "Login With Ethereum" toggle is checked

3. Select the blockchain network from the "Network" for where your NFT collection is based on

4. In the "NFT Collections" section, press "Add Collection", this will add an extra text field to the section

5. Enter the contract address of the NFT collections in the "Contract Address" text field

6. Select the token type of the contract address

7. In the case of an ERC-1155 being selected, you will be prompted with a token tracking dialog

8. Enter the desire token IDs and press "Continue"

9. Press "Add" and you will see your collection is now in the pending collection list

10. Press "Save" then "Confirm" and 🎉 your app is now monitoring the NFT collection!

If an error is shown that states that your NFT collection is not supported, it is possible that the collection has an alternative implementation of the ERC-721 or ERC-1155 standard

If your application supports logging in using an OpenID Connect provider, you can use Authgear as the provider.

Setting up Authgear in the Portal

1. Go to Applications on the left menu bar.

2. Click ⊕Add Application in the top tool bar.

3. Input the name and select the application type OIDC Client Application. Click "Save".

4. You will see a link to this guide that can help you for setting up, then click "Next".

5. In the URIs section, fill in the Authorized Redirect URIs with your application's redirect uri.

6. Obtain the OpenID Connect configuration:

   1. You can obtain the Client ID and Client Secret from the Basic Info section.

   2. You can obtain the OIDC Endpoints from the Endpoints section.

7. Provide the OpenID Connect configuration to your application.

🎉 Done! You should be able to use Authgear to log in to your application.

WordPress Example

In this section, we are going to demonstrate how to use Authgear as the OIDC provider for WordPress login.

1. Follow the previous section () to setup an OIDC Client Application.

2. We are going to use plugin . Or you can use any other OIDC compatible plugin. Download and activate it in your WordPress site.

3. Go to Setting > OpenID Connect Client.

4. Fill in the form

   1. Client ID: Obtain the Client ID from the Basic Info section.

   2. Client Secret Key: Obtain the Client Secret from the Basic Info section.

   3. 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.

   4. Login Endpoint URL: Obtain Authorization Endpoint from the Endpoints section.

      • Example: https://{AUTHGEAR_APP_DOMAIN}/oauth2/authorize.

   5. Userinfo Endpoint URL: Obtain Userinfo Endpoint from the Endpoints section.

      • Example: https://{AUTHGEAR_APP_DOMAIN}/oauth2/userinfo.

   6. Token Validation Endpoint URL: Obtain Token Endpoint from the Endpoints section.

      • Example: https://{AUTHGEAR_APP_DOMAIN}/oauth2/token.

   7. End Session Endpoint URL: Keep it empty.

   8. 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.

   9. 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.

5. 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.

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.

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:

• The session cannot be shared via the browser cookies

• The session cannot be shared via a common token storage

Mechanism

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.

A detailed explanation on the technology can be found in .

Setting it up in Authgear

Configuration in the authorizing app

1. Go to the Application detail page of the authorizing app, i.e. the app which handles the app2app authentication requests.

2. Scroll to the bottom and you will see the App2App config panel.

3. Select Enable App2App login for this Application"

4. 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.

Configuration in the initiating app

1. Go to the Application detail page of the initiating app, i.e. the app which initiates the app2app authentication requests.

2. In the redirect URIs, a universal link that's capable of opening this app should be set.

Setting up the apps

1. Define and set up the universal links for both apps, for example:

   1. https://a.example.com/authorize should open the authorizing app (App A)

   2. https://b.example.com/redirect should open the initiating app (App B)

2. 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

3. 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.

4. 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.

5. 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.

The default behavior of the Authgear Mobile SDKs is to launch AuthUI in in iOS and in Android. The latest versions of the mobile SDKs include WebKitWebViewUIImplementation a UIImplementation which makes it possible to customize the above behavior. For example, setting the uiImplementation attribute in the configure() method of the Authgear Capacitor SDK to WebKitWebViewUIImplementation() will open AuthUI using on iOS and on Android.

Omitting the uiImplementation attribute in the configure() method will fall back to the default behavior (launching AuthUI in ASWebAuthenticationSession/Custom Tabs). You can also explicitly choose the default behavior by setting uiImplementation to DeviceBrowserUIImplementation().

Example: Setting UIImplementation

The following examples show how to set the uiImplementation attribute.

Setting uiImplementation to WebKitWebViewUIImplementation in the above example will change the behavior of your application from the default to using WKWebView on iOS and android.webkit.WebView on Android.

Customizing the WebKitWebView UI

WebKitWebViewUIImplementation allows you to customize some parts of the UI. You can do this by passing your customization options as parameters in WebKitWebViewUIImplementation(). You can customize the following parts of the UI:

Android

• actionBarBackgroundColor: Use this option to customize the color of the action bar on the WebView Activity screen. The value should be of type integer according to this encoding:

• actionBarButtonTintColor: This option can be used to set the color of the icons and texts on the action bar. The value should also be of type integer and use the encoding here: .

iOS

• navigationBarBackgroundColor: This option can be used to customize the color of the navigation bar on iOS. The value should be of type or an integer (React Native or Ionic SDKs) using the following encoding: .

• navigationBarButtonTintColor: This option sets the color of icons and texts on the navigation bar. The value should also be UIColor or an integer (React Native or Ionic SDKs) using the same encoding as navigationBarBackgroundColor.

• modalPresentationStyle: Sets the type of modal to be shown. The value can be any of the following: "automatic", "fullScreen", "pageSheet".

The following examples show how to set custom background color, tint color, and modal presentation style.

Implementing your Custom UIImplementation

You can implement your own custom UIImplementation when the WebKitWebViewUIImplementation does not meet the requirements of your use case.

The WebKitWebViewUIImplementation class itself is basically a class that implements UIImplementation and overrides the openAuthorizationURL()method. Hence your custom implementation may look like this:

Then, you can use your custom implementation like this:

To get a deeper understanding of how to implement your UIImplementation, see the code for the implementation.

Unsupported Features and Services

When you drop the default DeviceBrowserUIImplementation to use your own custom UI implementation that uses WebView, it is important to note that you'll be losing the following features and services:

1. Login with Google: Google prohibits the use of WebKitWebView with the Google SSO. Learn more here: . As a result WebKitWebViewUIImplementation and Google SSO cannot be used together.

2. Passkey: Passkey is not supported in WebKitWebView.

JavaScript / TypeScript Hooks are written as a . The module is executed by .

The module MUST have a of a function taking 1 argument. The argument is the . The function can either be synchronous or asynchronous.

If the Hook is registered for a blocking event, the function MUST return a value according to the .

The Hooks DO NOT have access to file, or environment. They only have access to external network.

The stdout and the stderr of the Hooks are both ignored. Your hooks MUST NOT assume anything on the arguments and the stdin of the module.

Configure Authgear to deliver events to your Hooks

Examples

Here is an example of a Hook for a blocking event.

An example to mutate a JWT token

Here is an example of a Hook for a non-blocking event.

TypeScript Definition

is a TypeScript definition that aids you in writing a Hook. You can see the full definition at

If you are a Visual Studio Code user, you can to take full advantage of the definition.

Alternatively, you can edit your hook and use the Deno CLI to typecheck.

Implementing custom login and signup screens in any native application (Flutter, React Native, Kotlin, or iOS) doesn't require much change to the code for your existing native apps that use Authgear.

At the moment, we don't support direct interaction between your native code and the Authentication Flow API that powers custom UIs. That means you'll need to use the platform-specific we already provide and call the authenticate method to start the authentication flow.

In this guide, we'll teach you how to implement custom authentication UIs in a Flutter app using the Flutter SDK and Authentication Flow API.

Part 1: Configure Authgear Project in Portal

The main factor that enables custom UI in your Authgear application is specifying a custom UI URL in Authgear. Once this value is set, calling the authenticate method in any of the native SDKs will open the custom login/signup UI in a Web View instead of the default Auth UI.

Step 1: Set up an Authgear Application

If you do not already have an Authgear application, login to Authgear Portal and navigate to Application > Add Application to create an application.

Enter your application name and select Native App as Application Type then click the Save button to continue.

Step 2: Set Authorized Redirect URI

In this step, you'll add a URI that Authgear will use to return your application to the front of the screen when authentication is complete.

For our example Flutter app, this URI will start with the package name for our app followed by ://host/path.

To set the Redirect URI, scroll down to the Authorized Redirect URI under the URIs section of your application configuration page. Enter the correct URI for your application then click Save.

Note: You can find the package name for your Flutter app in android/app/build.gradle under android > namespace.

Step 3: Set Custom UI URI

Setting a value for Custom UI URI in Authgear Portal will redirect users of your application to your custom authentication UI instead of the default Auth UI. Hence, this is the most important step in adding custom login and signup UIs to your native application.

To set the Custom UI URI, scroll down to the Custom UI section on your application configuration page in the Authgear Portal. Then, add the URL to your custom login/signup page in the Custom UI URI text field.

This URL is a publicly accessible link on the web that hosts the code that implements your custom UI and does the actual interaction with the Authentication Flow API. Check out our examples for implementing custom login and signup UI pages using and to learn more.

Part 2: Implement Flutter Application

If you have an existing Flutter app that implements the default AuthUI, it may not require any change to make use of the Custom UI URI you've set in the previous step.

But if you're creating a new application, follow these steps:

Step 1: Create a Flutter App

Run the following command to create a new Flutter application:

Make sure you have your local machine set up for Flutter development before you run the above command. See the official guide for setting up Flutter . Once you're down, open the new project folder in your preferred code editor (VS Code or Android Studio).

Step 2: Install Authgear Flutter SDK

Now install the Authgear Flutter SDK by running the following command from your project directory:

Step 3: Implement Authgear

To implement Authgear in your Flutter app use the SDK, please follow these instructions on the .

You can also find similar guides for other native platforms below:

Step 5: Test Your App

To test your application, run the following command:

Tap on the Authenticate button when your app runs on a physical device or emulator. You should see the custom UI instead of the default Auth UI.

Conclusion

A very important to remember from the above guide is that when using custom authentication UI with a native application you can set up your app as you usually would with the default Auth UI. However, the main difference is that you should provide a link to your custom UI in the Authgear portal.

To learn more about using Authgear in your Flutter app, check out this page about the .

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.

Pre-requisites

To follow along, you need to have the following:

• An Authgear Account. You can create one for free .

• At least one registered user on your Authgear Project.

What you'll learn

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.

1.0 Update User Profiles as an Admin

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.

1.1 How to Update User Profile from the Authgear Portal

This option provides an easier way to manage your users within the Authgear Portal.

To update user profiles using this method, first, log in to the , then select your project.

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.

1.2 Using Admin API to Update User Profiles

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.

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

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.

2 How End Users Can Update Their Own Profile

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. To access the edit profile page, the user should click on the More link under the My profile card.

On the edit profile page, the user can set their profile photo and update other details for their profile.

To edit an attribute, the user should click on the edit icon beside that attribute.

Build your own custom UI for login, signup, and more powered by the Authentication Flow API.

By default, when you set up an Authgear project, it makes use of the regular AuthUI offered by Authgear. Although AuthUI offers many customization options such as the ability to change the theme and color or add your brand logo to authentication pages, you might have more needs. With the Authentication Flow API, you can build your own authentication UI from the ground up, and using your preferred programming language and tool.

What is the Authentication Flow API?

The Authentication Flow API is an REST HTTP API that you can use to create and run an authentication flow. You can use this API to create your own custom UI for pages like login, signup, account recovery, 2FA, and more.

To use the API on its own you make an HTTP request to one of the valid endpoints as shown below:

Endpoint: {your-authgear-project-domain}/api/v1/authentication_flows

Request method: POST

Request header:

{
    "Content-Type": "application/json",
    "Accept": "application/json",
}

All requests to the API should include the above header.

Request body:

{
    "type": "login",
    "name": "default"
}

The following is a sample of the response you would get from the Authentication Flow API for the above request:

{
    "result": {
        "state_token": "authflowstate_VGHZ8SBCKGZK2KW84TCAKWGM8QZH0B69",
        "type": "login",
        "name": "default",
        "action": {
            "type": "identify",
            "data": {
                "options": [
                    {
                        "identification": "phone"
                    },
                    {
                        "identification": "email"
                    },
                    {
                        "identification": "oauth",
                        "provider_type": "google",
                        "alias": "google"
                    }
                ]
            }
        }
    }
}

The above response means you've successfully started a new login flow using the API.

To continue and finish the authentication flow, you can send the value for state_token from the above response in your next HTTP request to the api/v1/authentication_flows/states/input endpoint like the example shown below:

Endpoint: {your-authgear-project-domain}/api/v1/authentication_flows/states/input

Request method: POST

Request body:

{
    "state_token": "authflowstate_VGHZ8SBCKGZK2KW84TCAKWGM8QZH0B69",
    "batch_input": [
      {
            "identification": "email",
            "login_id": "[email protected]"
      },
      {
          "authentication": "primary_password",
          "password": "12345678"
      }
    ]
}

In this second request (or second step of the authentication flow), we use the state_token to pass the user ID and password for the user we want to log in to our application.

You may send more requests just like this second request depending on the number of steps required for your specific authentication flow.

To use the Authentication Flow API to build your custom UI, you need to configure a Custom UI URI in the Authgear portal. This URI should point to your custom authentication page.

How the Authentication Flow API Works

The following flowchart shows the steps in a simple Authentication Flow API implementation:

Step 1: Make Authorization Request

When you use the authentication flow API to power your custom UI, the authentication flow for your app will start with your app sending an authorization request to Authgear's authorization server as shown in step 1 in the figure above.

Step 2: Redirect to Custom UI

If you have Authentication Flow API enabled and a Custom UI URI set for your Authgear App, the authorization server will redirect your users to the custom UI as shown in step 2 above.

Step 3: Make HTTP Requests to Authentication Flow API Endpoints

In your custom UI, implement the code that interacts with the Authentication Flow API (using HTTP requests) as demonstrated in step 3 of the above figure.

Step 4: Finish the Authentication Flow

In an authentication flow with multiple steps, the custom UI and Authgear's authentication server may perform steps 3 and 4 in the above figure multiple times. In such cases, only the final response at the end of the authentication flow will include a finish_redirect_url.

You must redirect your user to the finish_redirect_url to complete the authentication flow.

To dive deeper into how to use the Authentication Flow API to power your custom UI, check out the following tutorials for your preferred programming languages and frameworks.

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.

Show "Delete Account" button in User Settings

In the pre-built page, you can show a button for the end-users to initiate account deletion.

Enable this button in the Advanced -> Account Deletion page in the Portal

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:

Deactivated User

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.

Schedule Deletion

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.

Initiate Deletion from the Portal

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.

Initiate Deletion from Admin API

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.

Schedule Deletion

Your backend server can invoke the mutation scheduleAccountDeletion with the to initiate the account deletion.

Here is an example:

GraphQL

Immediate Deletion

Your backend server can invoke the mutation scheduleAccountDeletion with the to initiate the account deletion.

Here is an example:

GraphQL

Webhook events

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

See the event details in .

Identity and access management

Identity and Access Management (IAM) is a framework that manages digital identities and their access to various resources within a network or systems. IAM technologies and practices enable the right individuals to access the right resources at the right times and for the right reasons. For example, if a user wants to access a resource, IAM management verifies the user and controls their access to the resources.

Authgear acts as an IAM provider that is a gatekeeper to the resources you provide to customers as web and mobile applications, APIs, etc. The gatekeeper initiates authorization as outlined in . The addition of the layer adds authentication to secure your users’ digital identities and your product.

Relying party

In the context of identity and access management, a "relying party" is a system or application that relies on a separate system such as Authgear client SDK or libraries to authenticate a user's identity. Essentially, the relying party trusts another system to tell it that a user is who they claim to be.

Here's an example to illustrate the concept:

1. A user wants to log into an online service (the relying party).

2. The relying party doesn't handle authentication directly but instead relies on a trusted third-party system like Authgear.

3. The user logs into the third-party system, which verifies their identity.

4. The third-party system tells the relying party that the user's identity has been verified.

5. The relying party then grants the user access based on this verification.

OAuth 2.0

The authorization framework is a protocol that allows a user to grant a third-party website or application access to the user's protected resources, without necessarily revealing their long-term credentials or even their identity. It’s the standard that allows third-party developers to rely on large social platforms like Facebook, Google, and Twitter for login. Authgear generates access tokens for API authorization scenarios, in (JWT) format. The permissions are represented by .

Open ID Connect

A simple identity layer that sits on top of OAuth 2.0, makes it easy to verify a user’s identity and obtain basic profile information from the identity provider. OIDC is another open standard protocol. You can Authgear as an Identity Provider (IdP) that uses OIDC standards.

JSON web tokens

(JWTs) are an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWTs can be verified and trusted because they’re digitally signed. They can be used to pass the identity of authenticated users between the identity provider and the service requesting the authentication. They also can be authenticated and encrypted.

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 implementing OAuth2 in your app with Authgear as the provider.

In this post, you'll learn how to add user authentication to an Express.js application using Authgear.

What You Will Learn

• How to create an Authgear Application

• How to sign in with Authgear from an Express app using an authorization code.

• How to request user info from Authgear

Pre-requisites

You'll need the following to follow along with this tutorial:

• Node.js Installed

• A free Authgear account. Sign up for one here.

How to Add User Authentication to Express.js App using Authgear

For this tutorial, 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 /login route that redirects users to the Authgear OAuth authorization page.

• 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.

Step 1: Configure Authgear Application

In order to use Authgear as an OAuth identity provider in your application, you need to configure an Authgear project. This project gives you all the credentials that you'll be using to send requests from your application.

Now let's create a new application.

Log in to the Authgear portal, and select your project. From the project dashboard, navigate to the Applications section and enter your application details as shown below:

Once you're done, click on Save to reveal the OAuth configuration. The application configuration page is where you can find your OAuth credentials like client ID, client secret, and a list of supported endpoints. Note down the configuration details as you'll use them later in your Express app.

Step 2: Set Redirect URI

You need to provide one or more URLs within your app for Authgear to redirect to after user authorization.

To add a URL, scroll to the URIs and click on the Add button. Enter the full URL for the page you wish to redirect users to after login. For our example app for this post, we'll set this URL to http://localhost:3000.

Step 3: Create Express App

It is now time to set up the Express app that will be interacting with Authgear. To do that, create a new folder with the name "express-auth-example", this will be your Express project folder. Next, run the following command from the project folder :

npm install express

We'll be using the Axios library to make HTTP requests in the example app. Install Axios to your project by running this command:

npm install axios

Once Express is installed, create a new app.js file in the root of your project folder and add the following code to the file:

const express = require('express');
const axios = require('axios');

const config = {
  client: {
    id: "",
    secret: "",
    redirect_url: "http://localhost:3000"
  },
  auth: {
    tokenHost: 'https://your-project.authgear.cloud',
    tokenPath: '/oauth2/token',
    authorizePath: '/oauth2/authorize',
  },
};

app.get("/", async (req, res) => {
  res.send(`
      <div style="max-width: 650px; margin: 16px auto; background-color: #EDEDED; padding: 16px;">
        <p>Hi there!</p>
        <p>This demo app shows you how to add user authentication to your Express app using Authgear</p>
          <p>Checkout <a href="https://docs.authgear.com">docs.authgear.com</a> to learn more about adding Authgear to your apps.</p>
        <a href="/login">Login</a>
      </div>
    `);
});

app.listen(3000, () => {
  console.log("server started!");
});

Note: Paste the correct values of client id, client secret, and redirect URL for your Authgear app inside the client object in the config variable. Also, set tokenHost to the hostname part of your Authgear app endpoint URL. That is the part before the first "/". For example, tokenHost for https://example.authgear.cloud/oauth2/token will be https://demo-1-ea.authgear.cloud.

Run your app.js file using the node app.js command. You should get a page like this on a web browser when you visit localhost:3000:

Step 4: Add Login Endpoint

Here we'll be implementing a local login endpoint in our Express app. This endpoint will handle requests from the above login link.

Add a new route to your express app using the following code:

app.get("/login", (req, res) => {
  res.redirect(`${config.auth.tokenHost}${config.auth.authorizePath}/?client_id=${config.client.id}&redirect_uri=${config.client.redirect_url}&response_type=code&scope=openid`);
});

Now if you save your code and restart your app, clicking on the login link should redirect to the Authgear authorization page.

Step 5: Exchange Authorization Code For Access Token

After the user logs in and grants authorization to your app on Authgear, they are redirected back to the redirect URL you specified earlier. In addition to this redirect, an authorization code is sent via a code URL query parameter.

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("/") route to the following:

app.get("/", async (req, res) => {

  if (req.query.code != null) {
    const data = {
      client_id: config.client.id,
      client_secret: config.client.secret,
      code: req.query.code,
      grant_type: 'authorization_code',
      response_type: 'code',
      redirect_uri: config.client.redirect_url,
      scope: "openid",
    };

    try {
      const getToken = await axios.post(`${config.auth.tokenHost}${config.auth.tokenPath}`, data, {
        headers: { "Content-Type": "application/x-www-form-urlencoded" }
      });

      const accessToken = getToken.data.access_token;
      console.log(accessToken);

      res.send("Welcome");

    } catch (error) {
      console.log(error);
      res.send("An error occoured! Could not complete login. Error data: " + error);
    }
  }

  else {
    res.send(`
      <div style="max-width: 650px; margin: 16px auto; background-color: #EDEDED; padding: 16px;">
        <p>Hi there!</p>
        <p>This demo app shows you how to add user authentication to your Express app using Authgear</p>
          <p>Checkout <a href="https://docs.authgear.com">docs.authgear.com</a> to learn more about adding Authgear to your apps.</p>
        <a href="/login">Login</a>
      </div>
    `);
  }
});

The above code sends an HTTP POST request to the token endpoint. 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 Axios response in response.data.access_token.

We can now use this access token to make authenticated requests to protected resources in our app or from Authgear endpoint. In the next step, we'll attempt to get the current user's info from Authgear using the access token.

Step 6: Get User Info

Authgear provides an endpoint where your application can request user info. 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, in app.js, replace this line :

res.send("Welcome");

with the following code:

//Now use access token to get user info.
const getUserInfo = await axios.get(`${config.auth.tokenHost}/oauth2/userinfo`, { headers: { "Authorization": "Bearer " + accessToken } });
const userInfo = getUserInfo.data;
res.send(`
   <div style="max-width: 650px; margin: 16px auto; background-color: #EDEDED; padding: 16px;">
           <p>Welcome ${userInfo.email}</p>
           <p>This demo app shows you how to add user authentication to your Express app using Authgear</p>
           <p>Checkout <a href="https://docs.authgear.com">docs.authgear.com</a> to learn more about adding Authgear to your apps.</p>
       
   </div>
`);

This code sends another HTTP 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]".

Conclusion

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.

Here's a link to the complete code for our example code on Github.

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.

This how-to guide will walk you through the process of adding custom fields such as User Profiles attributes to a JWT access token payload using Authgear and Javascript Hooks.

Here's an example of the fields in the JWT Access Tokens by default and an explanation of their values.

Prerequisites

• An Authgear account: You need an Authgear account to follow this guide. If you don't have one, you can create it for free on the Authgear website.

• A Registered App: You need a registered application (client) in Authgear.

Enable Access Token for your App

Make sure the option Issue JWT as access token is enabled in your Application settings in the Portal.

1. Log into your Authgear account.

2. Navigate to the Applications tab and choose the existing App.

3. On the App Configuration dashboard, locate the "Access token" section.

4. Make the toggle Issue JWT as access token switch on.

Create a new Event Hook

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 Events 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.

1. Navigate to your Authgear Dashboard's Advanced->Hooks section.

2. Add a new Blocking Event.

3. Choose the Block Hook Type as the TypeSctipt and set the Event option to JWT access token pre-create. You will write a new Typescript function from scratch.

1. Click on Edit Script under the Config option.

2. Copy and paste the following into the editor:

import { EventOIDCJWTPreCreate, HookResponse } from "https://deno.land/x/[email protected]/mod.ts";

export default async function(e: EventOIDCJWTPreCreate): Promise<HookResponse> {
  return {
    mutations:{
      jwt: {
        payload:{
          ...e.payload.jwt.payload,
          standard_attributes: e.payload.user.standard_attributes,
          custom_attributes: e.payload.user.custom_attributes
        }
      }
    },
    is_allowed: true
  };
}

1. Click on Finish Editing.

2. Back to the Hooks page from the navigation bar and click on the Save button at the top of the page.

In the above code, we are importing the necessary modules such as HookResponse and EventOIDCJWTPreCreate which are types from the Authgear Deno hook Typescript library. We modify the JWT payload by adding Standard Attributes(e.payload.user.standard_attributes) and Custom Attributes(e.payload.user.custom_attributes) of the user.

Verify the Custom Field in a JWT token

There are two ways to test it:

• You can do this by decoding the JWT token on your application server side using a JWT decoder and inspecting the payload.

• If you created the application type OIDC Client Application, you need to follow the steps below. Expand it to see instructions.

https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/authorize?client_id={YOUR_CLIENT_ID}&response_type=code&scope=openid

curl --request POST \
  --url 'https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data code={YOUR_AUTHORIZATION_CODE} \
  --data redirect_uri={YOUR_REDIRECT_URI} \
  --data 'client_id={YOUR_CLIENT_ID}' \
  --data client_secret={YOUR_CLIENT_SECRET} \
  --data scope=openid

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.

Accessing Admin API & Portal Audit Through the Admin API.

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:

query {
  auditLogs(first:5){
    edges{
      node{
        activityType
        clientID
        createdAt
        data
      }
    }
  }
}

Note: The above request will also include events triggered by users.

Log Events

The following is a list of the activity types that are logged:

Project Actions

User Mutations

Authgear allows you to add third-party user analytics tools to your project using Google Tag Manager.

What is 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.

Pre-requisites

In order to setup Google Tag Manager and Google Analytics with Authgear, you need to have the following:

1. Authgear account

2. Google Tag Manager Account

3. Google Analytics Account

Part 1: Connect Google Tag Manager to Authgear project

The process for connecting your GTM account to Authgear is simple and can be done in these two steps.

Step 1: Get GTM container ID

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.

To get the container ID, log in to GTM 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.

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.

Step 2: Add GTM container ID to Authgear

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.

Part 2: Track traffic 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.

Step 1: Set up Google Analytics data stream

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.

Step 2: Create a new user-defined variable in GTM

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.

Step 3: Create a click Trigger

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.

Step 4: Create Page View Tag

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.

Step 5: Create Event Tag

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.

Conclusion

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