Single Page Application

Step-by-step guide for JavaScript applications that run in the browser.

Native/Mobile Apps

Step-by-step guide on how to use Authgear to add user authentication to your mobile application.

Regular Web App

Guides for using Authgear in web applications that run on the server side.

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.

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 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. For example, build your own custom login and sign-up pages from the ground up powered by .

Most importantly, you can with Authgear for free.

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.

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

• - Import multiple users from another service to your project.

• - Export user data from Authgear into a CSV or file.

• - Link an OAuth provider to a user's account without AuthUI.

Management Portal

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

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

Security

• - Set account Lockout Policy to safeguard a user account from brute-force login attempts.

• - Bot protection tools to block automated attackers.

• - Learn how to set password strength and how the password strength is calculated.

Login Methods

• - Add biometric login to your application.

• - Enable 2FA in your Authgear project.

• - Allow users to log in without a password using a magic link.

• - Set up passkey for your project.

• - Allow users to log in to your application using their existing account with a social media site or enterprise login provider.

Customize User Interface (UI)

• - Customize the look and feel of AuthUI to match your branding.

• - Change the language for display texts.

User Management

Features for managing your users via Authgear Portal.

• - Create a new account for a user from Authgear Portal.

• - Delete a user account from your project.

• - Detailed guide on how to use Roles and Groups.

• - Guides on how to view and manage user profile information.

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:

import kotlinx.coroutines.*

class MyAwesomeViewModel(application: MyAwesomeApplication) : AndroidViewModel(application) {
    // Other methods

    // This is called when login button is clicked.
    fun login() {
        viewModelScope {
            withContext(Dispatchers.IO) {
                try {
                    val app = getApplication<MyAwesomeApplication>()
                    val state = app.authgear.authenticate(AuthenticateOptions(redirectUri = "com.myapp://host/path"))
                    // User is logged in!
                } catch (e: Throwable) {
                    // Something went wrong.
                }
            }
        }
    }
}

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

Authgear makes it easy to add user authentication and authorization to any application. In this guide, we'll show you how to get started with Authgear in 5 minutes.

Video Guide

1. Create Authgear account

To start using Authgear in your application, create a free Authgear account on authgear.com.

After you sign up, you'll see the onboarding screen that will guide you through the process of creating your first Authgear project.

2. Authgear Projects

An Authgear project is similar to a container that holds all your users, settings, and client applications. You need an Authgear project before you can start signing users up.

You can create multiple projects under one account based on your needs. When you create multiple projects, each project is isolated from the others. For example, you can create Project 1 for your e-commerce business and Project 2 for a fitness club you organize. Project 1 and Project 2 will not share the same users or settings.

To create an additional project, log in to your Authgear account then click on the Create Project button.

3. Testing your signup/login page

Now that you have created a project in Authgear, you're ready to integrate Authgear into your applications for your customers/users to sign up and log in. See our documentation for adding Authgear to your application or website here for your favourite framework and programming language.

Before any integration, you can try out the signup flow for your project from the "Getting Started" page.

You should be greeted with the AuthUI Login/Sign-up page. Use the form to create a new user account under your project.

4. User Settings Page

After logging in from the previous step, you can check out the Pre-Built User Settings Page. This page is the default page where users of your project can edit their profile and manage security settings.

Click on the More link under My profile to view and edit profile attributes such as first name, last name, photo, etc.

The Security section of the User Settings page has the following options:

• Password: users can change their password from here.

• 2-step verification: users can click on this option to view and manage 2-step authenticators for their account.

• Signed-in device: from this page, the user can view browsers and devices that their account is currently signed in on.

You can learn more about the User Settings page here.

5. Integrate Authgear with Your Application or Website

To get more from Authgear and use Authgear to add user authentication to your web or mobile application, you should integrate Authgear to your application or website.

Authgear has official SDKs for integrating Authgear with React, React Native, ionic, Native Android, iOS, and Flutter applications. See the Start Building section of Authgear documentation for detailed instructions for each SDK and using other frameworks without the official SDK.

6. View and Manage Your Users

Authgear offers multiple options for viewing and managing all users who sign up for your project. These options include:

• Authgear Portal

• Admin API

The quickest way to manage your users is from the Authgear Portal. To open the user management page in the Authgear Portal, click on the User Management link in the navigation bar on the left side.

Click on Users to view a list of all the users in your project. Click on a user from the list to view their complete profile and perform administrative operations like modify profile details, suspend/unsuspend user, delete account, etc.

You can also add new users to your project from the User Management page. To do that, click on the Create User button on the right.

7. Continue Exploring Authgear

Continue to navigate around the Authgear Portal to see all the features and settings available for your project.

You can also check out any of the following guides to learn more about Authgear:

• customize the look of AuthUI login and sign-up page to match your branding needs using the Design tool

• guides on how to integrate Authgear to your app.

• how to enable 2FA for your project.

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

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

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.

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:

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!

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.

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

There are multiple ways to achieve Single Sign-on, with various pros-and-cons:

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

The prompt="login" parameter which is defined in the can prompt Social/Enterprise Login Providers to always show their login screen. As a result, you can use the prompt="login" parameter to allow users to switch accounts when their previous authentication session on the provider is still stored.

In this post, you'll learn how to use prompt: "login" in Authgear SDKs to force OIDC providers to always show your users their login screen. You can also use prompt: "login" to allow users to switch accounts with a Social/Enterprise Login provider on the same device (or browser).

How to Force Social/Enterprise Login Providers to Show Login Page

Authgear SDKs have a prompt parameter that you can set in your application. The value of the prompt parameter will be passed to the Social/Enterprise Login provider. Hence, if you set prompt: "login" in the SDK, your Social/Enterprise Login provider will receive a prompt="login" parameter. The following code examples show how to use the prompt parameter in Authgear SDKs.

Prerequisite

1. Sign in .

2. Create a B2C tenant by following .

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

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

5. Create a app registration for Authgear by following .

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

7. Follow 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!

Force Login page

Azure AD B2C automatically logs in to the same account without requiring a username and password. To prevent this behaviour, you can use the prompt=login parameter to force Azure AD B2C to show the login page. See our in Authgear SDKs to learn more.

When user login / signup to Authgear, it usually starts with your application making a request to the authorization endpoint, which leads to a login or signup screen.

If the user is already signed in on the browser, the Single Sign On feature will show a "Continue Screen" instead as follows.

If your application do not want to utilize the Single Sign On feature, and always show the login / sign up screen instead, you can force Authgear to show login page by using prompt="login" at the authorize endpoint.

How to Force Authgear to Show Login Page

The prompt="login" parameter which is defined in the can force AuthUI to show the login page. Authgear SDKs have a prompt parameter that can be used to set prompt="login". Once the prompt parameter is set to login Authgear will always show the login screen when your application calls the SDK's authenticate method.

The following code shows how to set prompt: "login" in Authgear SDKs:

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:

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

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!

Force Login page

Azure Active Directory automatically logs in to the same account without requiring a username and password. To prevent this behaviour, you can use the prompt=login parameter to force Azure Active Directory to show the login page. See our guide on using the prompt=login parameter in Authgear SDKs to learn more.

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.

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.

When you try to publish a mobile app on the Apple AppStore, there will be an App Review process. 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.

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!

Force Users to Re-authenticate

Microsoft AD FS supports the prompt=login parameter. You can include this parameter in your request when you want users to re-authenticate. See our guide on using the prompt=login parameter in Authgear SDKs to learn more.

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 /api_path HTTP/1.1
> Host: yourdomain.com
> cookie: session=<AUTHGEAR_SESSION_ID>

Get Started

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

1. Frontend Integration

2. Backend Integration

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 /api_path HTTP/1.1
> Host: yourdomain.com
> Authorization: Bearer <AUTHGEAR_ACCESS_TOKEN>

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

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.

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,

{
  "terms-of-service-link": "https://mycompany.com/terms-of-service",
  "privacy-policy-link": "https://mycompany.com/privacy-policy"
}

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

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.

{
    "enter-recovery-code-instead-v1": "Having Trouble? <button class=\"btn secondary-btn\" type=\"submit\">Use recovery code</button>",
    "enter-recovery-code-instead-with-customer-support-v1": "Having Trouble? <button class=\"btn secondary-btn\" type=\"submit\">Use recovery code</button> or <a class=\"link\" target=\"_blank\" href={customerSupportLink}>contact customer support</a>",
}

You can use your own translation or change the default text in the AuthUI. To do this, you'll edit translation.json.

Custom Text enables the customization of specific UI texts in AuthUI for different languages.

Follow these steps to change any text in AuthUI.

1. Go to Portal > Branding > Custom Text

2. Override translation by adding the key-value pair or modifying the value of an existing key in the JSON object in the text box. See default translation.json here for a list of available keys and their default values.

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.

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"

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.

For Mobile App or Single Page Web App or Website, each request from the client to your application server should contain an access token or a cookie. Your backend server should validate them for each HTTP request.

There are different approaches to verify the requests based on whether you validate JWT (JSON Web Tokens) in your server, or forward authentication to Authgear Resolver Endpoint.

Validate JWT in your server

Authgear uses for secure data transmission, authentication, and authorization. Tokens should be parsed and validated in regular web, native, and single-page applications to make sure the token isn’t compromised and the signature is authentic.

Read more on guide.

JWT Token in Authorization Header

This approach is only available for and involves passing the JWT token within the HTTP Authorization header. This approach is widely used in OAuth 2.0 and OIDC implementations, providing a standardized way to authenticate users.

JWT Token in Cookies

JWT tokens can be stored in HTTP cookies and sent with each request. It is suitable for . Storing JWTs in cookies as a way to persist the user's session across requests. The server then uses JWKS to validate the token. This approach is useful in scenarios where you want to maintain user sessions across different services in a more traditional web application setup.

Forward Authentication to Authgear Resolver Endpoint

Forward Authentication is a process where an intermediate reverse proxy or API Gateway is responsible for authenticating a request before it reaches the intended application or service. This can add an extra layer of security and centralize the authentication logic. An intermediate service forwards each incoming HTTP request to the Authgear Resolver Endpoint to verify the access token or cookie in the HTTP header.

Read more on guide.

Forward Authorization Header

Before processing the request, your server or a reverse proxy forwards the request to an . This endpoint resolves and verifies the authentication information (such as an Access Token) from the request Authorization Header.

Forward Cookie in HTTP header

In this pattern, Access Token (JWT) is stored in a cookie, and your server or a reverse proxy may contact the to obtain more information or validate certain aspects of the request.

Comparison

Setup guides

Validate JSON Web Token (JWT) in your application server

Forward authentication with Authgear Resolver Endpoint

Pre-authenticated URLs is a feature that enables single sign-on (SSO) from a mobile application to a website. It allows users who are authenticated on a mobile application to open a website in an authenticated state.

An example use case for a pre-authenticated URL is opening a web application in a WebView.

Pre-requisites

To use pre-authenticated URLs, you must have the following:

• An Authgear application of type Native app.

• A second Authgear application that has pre-authentication URLs enabled.

How to Implement Pre-authentication URLs in your application

Step 1: Enable SSO in Native App client

First, ensure your mobile application uses an Authgear application with the Native App.

Your application must also enable SSO to allow pre-authenticated URLs to work. You can enable SSO by isSSOEnabled: true in the configure() method of Authgear SDK.

Step 2: Add Allowed Origin to Web App Client

Next, add an allowed origin to the web application client in Authgear. Navigate to Applications in the Authgear Portal, select the web application client, and scroll to the Allowed Origins section. Then, add the origin you wish to use for Pre-authentication URLs. Note that the origin should be of the format "protocol (scheme) + domain + port". For example, if the mobile application wants to open https://www.mywebapp.com/home?key=value, the origin must be https://www.mywebapp.com.

Step 3: Generate Pre-Authenticated URL

The Pre-Authenticated URL is a link that the Authgear SDK can generate for a mobile client that has the Pre-Authenticated URLs feature enabled. Your mobile application can open the Pre-Authenticated URL in a web view for users to start browsing the origin in an authenticated state.

To generate the Pre-Authenticated URL, call the makePreAuthenticatedURL() method of the Authgear SDK as shown below:

The makePreAuthenticatedURL() method accepts an object as a parameter. Inside the object, you should provide your web application's client ID and redirect URI.

The URL in YOUR_WEB_APP_URI should be a page on the web application that calls the authenticate() method of Authgear SDK with isSSOEnabled: true (or a page that initiates an authorization request) .

Step 4: Open Pre-Authenticated URL in a WebView

After the makePreAuthenticatedURL() return the URL, your mobile application should open the URL in a WebView. From there, users should be able to continue their current authenticated session (from the mobile app) on the web application.

The following code sample shows how to open the pre-authenticated URL using the Linking.openURL() method of React Native.

The user will see a "Continue Screen" and will not need to enter their credentials again to log in.

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 > Branding > Custom Text 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:

Configure the external SMTP provider

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

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.

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 occurred.
        }
    });
}

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

Authgear supports Two-Factor Authentication (2FA) or Multi-Factor Authentication (MFA) for additional layers of security in your application.

When you enable MFA on your application, Authgear will require your users to present two or more factors in order to log in. These factors could be their password and a One-time Password (OTP) that is sent to their registered email address or phone number. As a result, an attacker can not gain access to a user's account with only a compromised password.

In this post, you'll learn how to enable MFA or 2FA for your Authgear project and how to configure 2FA grace period.

Pre-requisites

• An Authgear account. Create one for free here.

• An Authgear Project.

• And basic experience getting started with Authgear.

1. How to Enable 2FA

Step 1: Open 2FA Settings Page

You can enable 2FA and configure other settings from the 2-Factor Authentication page in Authgear Portal.

To open the 2-Factor Authentication page, log in to Authgear Portal, select your project, then navigate to Authentication > 2FA.

Step 2: Select a 2FA Requirements Policy

Next, use the 2FA Requirements dropdown on the 2-Factor Authentication page to set when to require users to use 2-Factor Authentication to sign in.

The available options are:

• Disabled: When this is selected, 2FA will not be required to log in for any user, including users who already have 2FA set up for their account.

• Optional: This policy will only require 2FA to log in for users who already have 2FA set up for their account. Users who have not set up 2FA can continue to log in without it.

• Mandatory: Use the mandatory policy to require 2FA for all users. That means users who have not set up 2FA will not be able to log in if no grace period is set. To use this option, consider further actions like setting up a grace period for rollout.

Toggle the Show "Do not ask again on this device" for 2FA switch on if you wish to require 2FA only the first time a user logs in from a specific device.

Step 3: Add Available 2-Factor Methods

The Available 2-Factor sub-section on the 2-Factor Authentication page shows a list of supported second-factor authentication methods. The supported methods include:

• Google Authenticator/Authy

• Additional Password

• OTP Code/Login Link via Email

• OTP Code via Phone

Check the box for each 2FA method you wish to enable for your project.

Use the up and down allows on the right of each method to order the priority of the 2FA methods.

Once you're done, click on the Save button at the top-left of the 2-Factor Authentication page to keep your new settings.

2. Grace Period in Mandatory 2FA

The 2FA Grace Period feature grants your users some time to set up 2FA for their accounts. This is very helpful for the Mandatory enforcement of 2FA.

The following are the two types of 2FA grace periods you can set for your Authgear project:

Global Grace Period: When this type of grace period is enabled, all users who do not have 2FA set up for their account will be asked to set up 2FA the next time they log in. When the Global Grace Period is disabled, users who have not set up 2FA for their account cannot log in. Instead, they'll get an error message requesting them to contact an admin.

Individual Grace Period: This is a type of grace period that is set per user. It grants a user 10 days to set up 2FA for their account. This is ideal for allowing individual users to set up 2FA when the Global Grace Period is disabled.

How to roll out Mandatory 2FA

The following steps show how to roll out Mandatory 2FA using grace periods:

1. Change 2FA requirement policy to Mandatory

2. Enable Global Grace Period so that all users who haven't set up 2FA are required to do so the next time they login.

3. Use your own channel to notify user's about the duration of the global grace period you've decided.

4. Disable the Global Grace Period once the date you notified users of has passed. After you do this, users that still haven't set up 2FA will be unable to log in.

5. When users that could not set up their 2FA during the Global Grace Period contact you (the admin), enable individual grace period for them using the instructions in step 2.

Step 1: Enable Global Grace Period

To enable the Global Grace Period, navigate to Authentication > 2FA in the Authgear Portal. Then, set 2FA Requirements to Mandatory so that you can view the Enable global grace period switch.

Toggle the Enable global grace period switch on so that your users without 2FA will be required to set up 2FA the next time they log in. Or set Enable global grace period off, if you do not want users without 2FA to log in, or set up 2FA without contacting an admin.

Step 2: Enable Individual Grace Period

When you set the 2FA requirement for your project to Mandatory and Global Grace Period is turned off, you can still use the individual grace period to grant a specific user a grace period to set up 2FA for their account.

To set individual grace period, navigate to User Management > User in Authgear Portal. Then, select the user you wish to set individual grace period for by clicking on the row with their ID in your project's users' list.

From the selected user's details page, click on the Account Security tab, then the Grant grace period to set up 2FA button. You will see a prompt to confim your action, click Confirm to continue.

The duration of the individual grace period is 10 days. However, you can extend or cancel it from the user's details page.

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.

Use Authgear as SAML Identity Provider for Dropbox

Security Assertion Markup Language (SAML) is a standard that allows an Identity Provider (IdP) and a Service Provider (SP) to perform user authentication and authorization without exchanging a user's password.

In this post, you'll learn how to set up Authgear as an Identity Provider and Dropbox as a Service Provider.

Pre-requisites

• An Authgear account. Sign up for free.

• A Dropbox Business Advanced account.

Step 1: Create an Authgear Client Application

You need an Authgear client application of type OIDC/SAML Client Application to use Authgear as a SAML identity provider.

To create a new client application, log in to Authgear Portal, select your project then click on the Applications link from the navigation menu.

Next, click on Add Application to create a new client application. Alternatively, select an existing application of type OIDC/SAML Client Application and skip to step 2.

On the New Application page, enter Name and select OIDC/SAML Client Application as the Application Type.

Click Save to proceed.

Step 2: Enable SAML 2.0 in Client Application

By default, SAML 2.0 is not enabled for the client application.

To enable SAML for your client application, click on the SAML 2.0 tab then toggle the SAML 2.0 Support switch on.

Next, change NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Add the following URL (Dropbox post-back URL) in Allowed Assertion Consumer Service URLs (ACS URLs) field:

https://www.dropbox.com/saml_login

Click on Save to keep your changes.

Step 3: Get SAML IdP Configuration and Download Certificate

Scroll down to the Configuration Parameters section of your Authgear client application's SAML 2.0 tab. Note the value for the login URL.

Also, download the Identity Provider Certificate for the client application to your computer.

You'll use the Login URL and certificate later in the Dropbox Admin console.

Step 4: Add Authgear SAML IdP in Dropbox

Log in to your Dropbox Business Advanced account then click on Admin console in the navigation menu.

In the Dropbox Admin console navigate to Settings > Single sign-on.

Now in the Dropbox Single sign-on settings page, set Single sign-on to Required. Then, configure the following:

• Paste the value for your Authgear client application's Login URL in the Identity provider sign-in URL field.

• Under X.509 certificate, click on the Certificate upload button, then upload the Identity Provider Certificate you downloaded from your Authgear client application in the previous step.

Step 5: Login to Dropbox Using Authgear SAML

To test your SAML implementation, you need to add a new user to your Dropbox with an email address that is associated with a user account in your Authgear project.

To add a new user to your Dropbox, navigate to Admin console > People > Members > Invite member.

Accept the invite for the new user, and try to log in to Dropbox using the registered email address for the new user. You should be redirected to the Authgear SAML login page. On successful login to the Authgear account, you should be redirected and signed in to Dropbox.

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 SDKs 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 PHP and JavaScript(Express) 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:

flutter create myapp

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

flutter pub add flutter_authgear

Step 3: Implement Authgear

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

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

• React Native

• Android SDK

• iOS

• Xamarin

Step 5: Test Your App

To test your application, run the following command:

flutter run

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 Flutter SDK.

You can use Authgear's x_oauth_provider_alias parameter to add social/enterprise login to your application without showing any AuthUI pages. To do this, you must enable the Social/Enterprise only login method for your project in Authgear Portal.

In this post, you'll learn how to use the x_oauth_provider_alias parameter to skip AuthUI and take users directly to a social/enterprise login provider's authorization page.

Pre-requisite

• An Authgear account. Create one for free here.

What We Will Build

• In this post, we'll walk through the steps for adding only the social/enterprise login method to an Authgear application.

• We'll use the Authgear SDK for React Native to set the x_oauth_provider_alias parameter and show how to use x_oauth_provider_alias without the SDK in an example Express app.

The sequence diagram above demonstrates the flow for using x_oauth_provider_alias to skip AuthUI.

First, when the user clicks on the sign-in button, your application will call your Authgear project's authorize endpoint with the x_oauth_provider_alias parameter appended.

Next, when Authgear server receives the call, it redirects to the third-party OAuth (Social/EnterpriseLogin) provider's authorization server. The user is then shown the OAuth provider's login/authorization page for them to grant authorization. Once that is done, the OAuth provider returns an authorization code to Authgear.

In the next step, Authgear exchanges the authorization code for an access token, refresh token, and ID token and then starts creating a new user or logging the existing user in.

The rest of the flow from there involves the usual sending of the authorization code to the client application and the client application exchanging the authorization code for an access token, refresh token, and ID token.

Step 1: Configure a Social/Enterprise Login Provider

The first step is to add the Social/Enterprise login provider you wish to use to your Authgear project. For our example, we'll be adding Facebook.

To add a new provider, log in to Authgear Portal, select your project, then navigate to Authentication > Social/Enterprise Login.

Next, click on the Edit button, then enter the Client ID and Client Secret for the Social/Entreprise login provider then click Save. Also, note the value for Alias as you'll use it in a later step.

See our guide here for instructions on how to get a Client ID and Client Secret for Facebook Login.

Step 2: Enable Social/Enterprise Only Login Method

An important step for making Authgear to skip AuthUI is to enable the Social/Enterprise only login method. By doing this, Authgear will understand that the only login method your app will use is from a third-party OAuth provider. As a result, it's ok to skip showing AuthUI for login, registration, or login method selection and go to the OAuth provider's authorization page directly.

To enable Social/Enterprise only, navigate to Authentication > Login Methods. Next, select the Social/Enterprise only Login Method and click Save.

Step 3: Set x_oauth_provider_alias Parameter

Now that you've set up everything to allow your application to use only Social/Enterprise Login, you can open Authgear's authorize endpoint with the x_oauth_provider_alias parameter to start an authorization request that will skip AuthUI.

We will show 2 ways to do this. The first is using the SDK and the second is by passing x_oauth_provider_alias as a URL query parameter.

1. Adding x_oauth_provider_alias using Authgear SDK

The following example shows how to add x_oauth_provider_alias using the Authgear React Native SDK:

authgear
  .configure({
    clientID: '<YOUR_CLIENT_ID>',
    endpoint: '<YOUR_AUTHGEAR_PROJECT_ENDPOINT>',
  })
  .then(() => {
    authgear
      .authenticate({
        redirectURI: 'com.reactnativeauth://host/path',
        oauthProviderAlias: 'facebook',
      })
      .then(({userInfo}) => {
        Alert.alert('Login successful, welcome ' + userInfo.email);
      });
  });

The key thing about using the above option is the presence of oauthProviderAlias: 'facebook' in the authenticate() method of the Authgear SDK. This parameter tells Authgear to redirect directly to an OAuth provider, given that the Social/Enterprise provider is configured properly as shown in step 1. Also, the Social/Enterprise only Login method is enabled.

Note that the value for oauthProviderAlias must be the Alias for the social/enterprise provider you configured in step 1.

2. Add x_oauth_provider_alias to the Authorization URL

You can manually add x_oauth_provider_alias parameter to the Authgear authorization endpoint when you're not using the Authgear SDK.

The following example shows how to add x_oauth_provider_alias to the Authgear authorization endpoint:

app.get("/login", (req, res) => {
  const url = new URL("<YOUR_AUTHGEAR_PROJECT_ENDPOINT>/oauth2/authorize");
  url.searchParams.set('client_id', config.client.id);
  url.searchParams.set('redirect_uri', "http://localhost:3000");
  url.searchParams.set('scope', "openid offline_access");
  url.searchParams.set('x_oauth_provider_alias', 'facebook')

  res.redirect(url);

});

The above code will append &x_oauth_provider_alias=facebook to the authorization URL.

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.

authgear.configure({
    clientID: CLIENT_ID,
    endpoint: ENDPOINT,
    sessionType: "refresh_token",
    isSSOEnabled: true,
});

authgear.configure({
    clientID: CLIENT_ID,
    endpoint: ENDPOINT,
    isSSOEnabled: true,
});

var authgearOptions = new AuthgearOptions
{
    ClientId = CLIENT_ID,
    AuthgearEndpoint = ENDPOINT,
    IsSsoEnabled = true,
};
// Android
#if __ANDROID__
var authgear = new AuthgearSdk(GetActivity().ApplicationContext, authgearOptions);
#else
#if __IOS__
var authgear = new AuthgearSdk(UIKit.UIApplication.SharedApplication, authgearOptions);
#endif
#endif

Authgear(
    clientId: CLIENT_ID,
    endpoint: ENDPOINT,
    isSSOEnabled: true,
)

new Authgear(
    getApplication(),
    CLIENT_ID,
    ENDPOINT,
    new PersistentTokenStorage(getApplication()),
    true // isSsoEnabled = true
);

These type of SSO requires sharing the cookies between mobile apps and the system browsers on mobile, hence underlying it use ASWebAuthenticationSession on iOS and Custom Tab on Android, which will show a popup box like this:

If you want to avoid the said popup box, you will need to use WKWebView on iOS and WebKitWebView on Android for UIImplementation instead; And use App2App Login for sharing login session between mobile apps, and Pre-authenticated URLs between mobile and web instead.

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

Security Assertion Markup Language or short is a standard for exchanging security information between businesses. In SAML, one party acts as the Identity Provider (IdP) and the other party is the Service Provider (SP).

The Service Provider (SP) trust the Identity Provider to handle the process of user authentication. The Identity Provider handles user authentication and notifies the Service Provider once the user is authenticated.

In this guide, you'll learn how to set up SAML with Authgear as an Identity Provider (IdP) and Salesforce as the Service Provider (SP) in SAML.

Pre-requisites

• An Authgear account. for free.

• A Salesforce account.

Step 1: Create an Authgear Client Application

An Authgear Client application is required to set up Authgear as a SAML Identity Provider. To create an Authgear application, login to the Authgear Portal and navigate to the Applications in your project.

Click on Add Application to create a new application. Or, select an existing application that is of type OIDC/SAML Client Application and skip to step 2.

Now on the New Application page, enter a name for your application (e.g. My App) and set the Application Type to "OIDC/SAML Client Application".

Click Save to continue.

If prompted to view a tutorial, click Next to proceed to the application configuration page.

Step 2: Enable SAML 2.0 in Client Application

On the configuration page of your Authgear client application, switch to the SAML 2.0 tab. Toggle the SAML 2.0 Support switch on to enable SAML for the application.

Next, change NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Enter your Salesforce domain in the Allowed Assertion Consumer Service URLs (ACS URLs) field under SSO Settings. You can get value for your Salesforce domain from the My Domain page on the Salesforce Setup page.

Click on Save to keep your changes.

Step 3: Get SAML Identity Provider (IdP) Configuration and Download Certificate

Still, on the SAML 2.0 tab, scroll to the Configuration Parameters section and click on the Download Metadata button to download the Identity Provider Metadata XML file for your Authgear application to your computer.

Next, scroll to the Identity Provider Certificates section and click Download Certificate to download the certificate to your computer.

You will use the downloaded metadata file and certificate in later steps.

Step 4: Enable SAML in Salesforce

To enable SAML in Salesforce, login to your Salesforce account, click on the Settings icon on the top right corner then select Setup. This will open the Salesforce Setup page.

On the Setup page, type "single sign-on" in the Quick find search box on the left. Select Single Sign-On from the result to open the Single Sign-On Settings page.

Next, click on the Edit button under Select Single Sign-On Settings then check the SAML Enabled box under Federated Single Sign-On Using SAML. Click Save to keep your changes.

Step 5: Add Authgear as SAML IdP in Salesforce

To add Authgear as a SAML Identity Provider, return to the main page of Single Sign-On Settings.

Next, click on the New from Metadata File button. Then, click Choose file, and select the Metadata XML file you downloaded in . Click on Create to continue.

On the next screen, you should see configurations for your new SAML IdP, including the details from the metadata file. Edit the Name field to Authgear SAML. The value for the Name field will be visible on your Salesforce login page.

Next, click on the Choose file button next to Identity Provider Certificate then select the SAML IdP Certificate file you downloaded in from your computer.

Once you're done with the above configurations, click Save to finish.

Step 6: Enable Login with SAML in Salesforce

In order to log in with a specific SAML IdP, you must first enable the provider in Salesforce.

To enable your new SAML IdP (Authgear SAML) search for "my domain" in Quick find. Click on My Domain from the result. On the My Domain page, scroll to Authentication Configuration then click on the Edit button.

You should find your Authgear SAMP IdP under Authentication Service. Check the box next to Authgear SAML to enable it. Click Save to keep changes.

Once you have enabled your SAML Identity provider in this step, it will be visible on your Salesforce login page the next time you attempt login.

Step 7: Log in to Salesforce using Authgear SAML

Force you can log in to your Salesforce project using Authgear SAML, you need to create a user using an email address that is linked to a user account in your Authgear project.

To create a user in Salesforce, use type "users" in the Quick find search box, then select Users > Users from the result. This will take you to the All Users page.

From the All Users page, click on New User. Create a new user with an email address that's linked to an account on your Authgear project.

Now, to test your SAML implementation, log out of Salesforce and attempt logging in again. This time, you should see a Login with Authgear SAML button.

When you click on Login with Authgear SAML, you should be redirected to Authgear Login page. Login to the account on your Authgear project that has the same email address as the new user you created earlier in this step. You should be successfully logged in to your Salesforce project.

Authgear makes it easy for you to customize the built-in AuthUI to meet the specific branding needs of your application. You can customize UI elements such as the logo, text input fields, and buttons.

In this guide, you'll learn how to use all the customization options available.

Authgear Design Page

To open the new Authgear Design page, log in to the Authgear Portal and navigate to Branding > Design.

The Design page is divided into 2 columns. The left column shows a preview of your customizations in real time. The right column is the menu with all the customization options for different UI elements (e.g. Name, Logo, Favicon).

The Language drop-down on the top right corner allows you to customize AuthUI text such as Organisation Name, and (Privacy Policy, Terms of Service, and Customer Support) for specific languages.

Customization Options

1. Name

Use this option to set the application name you want to display in AuthUI (Login and Register pages).

2. Theme

The Theme options allow you to switch between Light Mode, Dark Mode, or Auto (User Preference) on the Design page and for your project. If you select a theme and click the Save button, that theme will be applied to your project.

When the Auto based on user preference theme option is selected, AuthUI will choose a theme based on a specific user's settings.

You can also use the Design page to select a theme (Dark mode or Light mode) to further customize it. Skip to the to learn more

3. Logo

The logo option allows you to replace the default Authgear logo in AuthUI with your own brand logo. You can add a PNG, JPG, or GIF image smaller than 100 KB.

4. Favicon

Use this option to add a custom favicon that will show in browser tabs. The size of the image you upload must be a multiple of 32px square, and be a PNG, JPG, or GIF file.

5. Card

The card option allows you to set the Alignment of the AuthUI card. By default, the AuthUI card is aligned to the Center. You change the alignment to either Left, Right, or Center.

6. Background

Use this option to change the background color of AuthUI pages. You can either use a background color (CSS hexadecimal color code) or upload a PNG, JPEG, or GIF image smaller than 1 MB.

7. Buttons

The button customization option lets you customize multiple properties of the buttons in AuthUI. The following are the properties you can customize:

Primary button: Use this field to set the fill color of the buttons.

Primary button label: Use this field to set the color of the text inside a button.

Border radius style: Set the type of border-radius you want here. Available options include square edges, curved edges, and full-rounded ends.

Border radius: The curved edges Border radius style allows further customization for the actual size of the border radius in pixels. Use this option to set the level of curved edges.

8. Links

Under the Links section, you'll find options to set the text color for links in AuthUI and also options for configuring , and that are linked on AuthUI.

Link color: Use this option to set the text color for links in AuthUI. The value should be a hexadecimal color code.

Link decoration: You can use this option to add the underline text-decoration to links that are displayed in AuthUI.

Privacy Policy: Use this option to add a link to your privacy policy page.

Terms of Service: Use this option to set a custom link for your terms of service

Customer Support: Use this option to add a link to your support page.

Note that when any of the link properties is unset AuthUI will fall back to the primary language's default settings.

9. Input field

The Input field section contains options for styling text input fields in AuthUI. The following are the various properties you can set:

Border radius style: Use this option to set the type of border-radius you want. The available options are square edges, curved edges, and full-rounded ends.

Border radius: You can use this option to further customize the level of curve of the curved edges Border radius style.

10. Back to your app

Use this option to add a button under the to navigate the user to your website.

11. Authgear branding

You can use this toggle to remove Authgear branding in the AuthUI for your project.

Customize Dark Mode and Light Mode

Attributes of the default AuthUI dark mode and light mode can be customized. For example, you can change the default color of the dark background in dark mode.

To customize an attribute, select the theme (light or dark mode) you wish to customize, then navigate to the attribute you wish to customize and modify it. Or select Auto based on user preference to see customization options for both themes at the same time.

The following are attributes you can customize for each theme:

• (fill color and label color)

Security Assertion Markup Language or short is a standard for exchanging security information between businesses. In SAML, one party acts as the Identity Provider (IdP), and the other party is the Service Provider (SP).

SAML allows the Identity Provider and Service Provider to authenticate and authorize without exchanging a user's password.

• The Service Provider (SP): In SAML, this is the service that trust the Identity Provider to handle the process of user authentication.

• The Identity Provider (IdP): handles user authentication and notifies the Service Provider once the user is authenticated.

Authgear supports the SAML protocol. Hence, you can set up third-party services like Salesforce, Dropbox, Figma, etc. to trust Authgear with the user authentication process.

Specific Instructions for Service Providers

See the following guides for some popular service providers:

How to Set up SAML in Authgear

To set up SAML in Authgear, you need to create an Authgear client application with the Application Type: OIDC/SAML Client. Then use the configuration for the Authgear client application to configure a SAML IdP on the Service Provider's platform.

The following steps show more details on how to set up an OIDC/SAML Client Application in Authgear Portal.

Step 1: Create Authgear Client Application

Log in to Authgear Portal, then click on Applications from the navigation menu.

Click on Add Application to create a new client application. Or select an existing client application with the OIDC/SAML Client type.

Enter a Name for the application and select OIDC/SAML Client Application as the Application Type.

Click Save to proceed.

Step 2: Enable SAML 2.0

By default, the SAML 2.0 Configuration is disabled for the client application.

Click on the SAML 2.0 tab then toggle SAML 2.0 Support switch to enable SAML 2.0.

You'll be required to enter at least one Allowed Assertion Consumer Service URLs (ACS URLs) before you can save your changes. Hence, get an ACS URL from the Service Provider you plan to use.

Step 3: Configure Authgear as IdP on a Service Provider

Visit the portal for the Service Provider you plan to use and add Authgear as an Identity Provider using the SAML configuration from your Authgear client application.

Refer to the following instructions for a generic SP:

Configuration on SP:

• Enter the Identity Provider Metadata URL provided by Authgear if it's supported by the SP. e.g. https://[AUTHGEAR_ENDPOINT]/saml2/metadata/[CLIENT_ID]

• If the SP does not support uploading an IDP metadata file, you can manually enter the parameters into the SP. These values can be copied from the application settings page:

  • Issuer: urn:[AUTHGEAT_ENDPOINT]

  • Login URL: https://[AUTHGEAR_ENDPOINT]/saml2/login/[CLIENT_ID]

  • Logout URL: https://[AUTHGEAR_ENDPOINT]/saml2/logout/[CLIENT_ID]

  • Identity Provider Certificates in PEM format: Download from the application settings page

Configuration on Authgear

• Upload the Metadata XML file provided by your client application into the Authgear Portal

• You may also manually enter the parameters into the application settings page in the Portal:

  • NameID Format

    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified , or

      • When the format is unspecified, you can choose to use the User ID, Email, Phone, or Username as the attribute value

    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  • Allowed Assertion Consumer Service URLs (ACS URLs)

  • Response Destination (Optional)

  • Subject Recipient (Optional)

  • Assertion Audience (Optional)

  • Assertion Valid Duration (seconds), Default: 1200

  • Enable/Disable Single Logout (SLO)

    • SLO Callback URL

    • Callback Binding

      • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect, or

      • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

  • Enable/Disable message signature verification

    • Upload the SP's certificate in PEM format

You may find more detailed guides for adding IdP on the Service Provider's documentation.

This guide shows how to connect your Authgear application to Facebook so users can log in using the Login with Facebook feature.

Step 1: 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

To create a new app, go to the Facebook Developers panel then click the Click Create App button.

On the next screen, select Other as your app use case then, click Next.

In the app type selection screen, pick the option that best meets your requirements. For our example, we'll select the Consumer app type.

Enter your app name on the next screen and finish the app creation process.

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

Step 3: Configure Login with Facebook in Authgear Portal

Get your OAuth Client details

After setting up the Facebook Login product, go to App settings > Basic in the sidebar.

You will need the App ID and App Secret to configure Facebook Login so, note them down.

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 Facebook Developers portal in the previous step.

4. Save the settings.

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

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

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

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!

In this section, we will explain how to set up a reverse proxy in NGINX to protect your app server from unauthorized access with the Authgear resolver. You can forward the requests without the request body to the resolver endpoint. Authgear will look at the Authorization and Cookie in the HTTP header, verify the token, and respond to HTTP 200 with X-Authgear- headers for session validity, the user id...etc.

If you use a popular reverse proxy on your deployment, such as NGINX, Traefik, or API Gateways such as Apache APISIX, you can configure it with a few simple lines of forward auth config. Your backend should read the returned headers to determine the identity of the user of the HTTP request.

You can also use the forward authentication features of the other popular reverse proxy. e.g.

• Traefik ForwardAuth middleware

Authgear Resolver Endpoint

Authgear provides an endpoint for forward authentication. Subrequests should be made to the following endpoint for authentication.

https://<your_app_endpoint>/_resolver/resolve

How Forward Authentication Works

1. After the user is logged in, send an application request to your server from the client app with access token/cookies.

2. Set up a reverse proxy in your infrastructure to authenticate HTTP requests. The reverse proxy will forward the incoming HTTP requests without the request body to the Authgear Resolver Endpoint.

3. Authgear resolver parses the access token and returns HTTP headers including the user login state. The headers are starting with x-authgear-.

4. You have to instruct your reverse proxy to include those extra headers, before forwarding the request to your backend server.

5. Your backend server looks at the headers and responds to the client app accordingly. e.g. Returns the user's content or HTTP 401 if the user is not logged in.

There are so many reverse proxies available in the wild. So here we are going to illustrate the idea of using Nginx as the reverse proxy.

Using Nginx as the reverse proxy

We will use the module auth_request in NGINX. The module is not built by default, it should be enabled with the --with-http_auth_request_moduleconfiguration parameter.

Run this command and verify that the output includes --with-http_auth_request_module:

$ nginx -V 2>&1 | grep -- 'http_auth_request_module'

The trick here is to declare an internal location and use auth_request to initiate a subrequest to the resolved endpoint.

Example configuration

server {
  # Use variable in proxy_pass with resolver to respect DNS TTL.
  # Note that /etc/hosts and /etc/resolv.conf are NOT consulted if resolver is used.
  # See https://www.nginx.com/blog/dns-service-discovery-nginx-plus/
  resolver 8.8.8.8;
  
  # Location that requires request authentication
  location / {
    set $backend http://www.mycompany.com;
    proxy_pass $backend;
    proxy_set_header Host $host;
    # Specify the auth_request directive to initiate subrequests to the to the internal location.
    # This corresponds to the Step 2.
    auth_request /_auth;

    # Copy the `x-authgear-*` headers from the response of the subrequest to Nginx variables.
    # This corresponds to the Step 3.
    auth_request_set $x_authgear_session_valid $upstream_http_x_authgear_session_valid;
    auth_request_set $x_authgear_user_id $upstream_http_x_authgear_user_id;
    auth_request_set $x_authgear_user_anonymous $upstream_http_x_authgear_user_anonymous;
    auth_request_set $x_authgear_user_verified $upstream_http_x_authgear_user_verified;
    auth_request_set $x_authgear_session_acr $upstream_http_x_authgear_session_acr;
    auth_request_set $x_authgear_session_amr $upstream_http_x_authgear_session_amr;
    auth_request_set $x_authgear_session_authenticated_at $upstream_http_x_authgear_session_authenticated_at;
    auth_request_set $x_authgear_user_can_reauthenticate $upstream_http_x_authgear_user_can_reauthenticate;

    # Include the headers in the request that will be sent to your backend server.
    # This corresponds to the Step 4.
    proxy_set_header x-authgear-session-valid $x_authgear_session_valid;
    proxy_set_header x-authgear-user-id $x_authgear_user_id;
    proxy_set_header x-authgear-user-anonymous $x_authgear_user_anonymous;
    proxy_set_header x-authgear-user-verified $x_authgear_user_verified;
    proxy_set_header x-authgear-session-acr $x_authgear_session_acr;
    proxy_set_header x-authgear-session-amr $x_authgear_session_amr;
    proxy_set_header x-authgear-session-authenticated-at $x_authgear_session_authenticated_at;
    proxy_set_header x-authgear-user-can-reauthenticate $x_authgear_user_can_reauthenticate;

    # Your backend must inspect the request headers to determine whether the request is authenticated or not.
    # This corresponds to the Step 5.
  }

  location = /_auth {
    # Set this location for internal use only
    internal;
    # Replace <YOUR_AUTHGEAR_ENDPOINT> with your authgear endpoint.
    # For example, https://example.authgear.cloud
    set $resolver <YOUR_AUTHGEAR_ENDPOINT>/_resolver/resolve;
    proxy_pass $resolver;
    # Set the host so that authgear knows which app is calling the resolver endpoint
    # Replace <YOUR_AUTHGEAR_ENDPOINT_HOST> with the host of your authgear endpoint.
    # For example, example.authgear.cloud
    proxy_set_header Host <YOUR_AUTHGEAR_ENDPOINT_HOST>;
    # The body is supposed to be consumed by your backend server.
    # Pass only the headers to the resolver
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
  }
}

Optimizing the performance

If the reverse proxy, Authgear, and your backend server are in different regions, authenticating every request could result in a huge downgrade in the performance.

You may consider enabling caching.

http {
  # ...
  proxy_cache_path /tmp/cache keys_zone=auth_cache:10m;

  # The server block.
  server {
    # ...
    location = /_auth {
      # ...
      proxy_cache auth_cache;
      proxy_cache_key "$cookie_session|$http_authorization";
      proxy_cache_valid 200 10m;  # Adjust cache duration as desired.
    }
  }
}

Reference on the headers

See the list of x-authgear- headers in the specs: https://github.com/authgear/authgear-server/blob/master/docs/specs/api-resolver.md

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

To help you understand the structure of the Authentication Flow API HTTP(S) request, here is an example of an actual request in Postman:

Request body:

{
    "state_token": "authflowstate_VGHZ8SBCKGZK2KW84TCAKWGM8QZH0B69",
    "input": {
        "identification": "email",
        "login_id": "[email protected]"
    }
}

In this second request (or second step of the authentication flow), we use the state_token from the response to the previous request in the request body to continue the authentication flow. The request body includes the input field that passes the type of identification the user will provide (for example, email) and the login_id which is the actual value for the user's identification.

The response to the above request should look like this:

{
    "result": {
        "state_token": "authflowstate_ABCJVB0IJKLQ2S1K2G34RX56R1C1E789",
        "type": "login",
        "name": "default",
        "action": {
            "type": "authenticate",
            "data": {
                "type": "authentication_data",
                "options": [
                    {
                        "authentication": "primary_password"
                    }
                ],
                "device_token_enabled": false
            }
        }
    }
}

You may send more requests just like this second request depending on the number of steps required for your specific authentication flow. For example, to complete the login authentication flow, send another request with the the authenticator (password) like this:

{
    "state_token": "authflowstate_ABCJVB0IJKLQ2S1K2G34RX56R1C1E789",
    "input": {
        "authentication": "primary_password",
        "password": "sup3r$tr0ngpa$$"
    }
}

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.

For more details about the Authentication Flow API endpoints, inputs, response, and more visit the API reference 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.

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 Single Sign-on 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 this specification.

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.

Set up a custom domain to let your users access the Authgear pages with your unique, brand-centric domain name. You can use a custom domain (e.g. auth.yourdomain.com) instead of the Authgear generated domain (e.g. <YOUR_APP>.authgear.cloud).

How to Set Up a Custom Domain

1. Add domain

• Go to Branding > Custom Domains in your project portal.

• Enter the custom domain name that you would like to connect to Authgear, and click Add.

• Your custom domain will appear on the list, click Verify to start the verification process.

2. Verify domain ownership

• Go to your domain provider's site, and add DNS records based on the values shown on the portal page.

• Click Verify after adding the DNS records, you may need to wait for the propagation of your updated DNS records.

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.

Configure Post-login link and Post-logout link

Users can access the login and logout pages directly in your Authgear project when you're using a custom domain. As a result, the post-login and post-logout links are available to help you determine where users are redirected when they access the above pages without an OAuth flow.

To configure these values, in Authgear Portal navigate to Branding > Custom Domains. Then scroll down to the Default Redirect URLs section.

Post-login link

Use this field to set the page where users will be redirected after login if they visit the login page directly instead of going through an OAuth flow.

Post-logout link

The URL you enter as a post-logout link is where users will be redirected after logout when they visit the logout page directly.

In this guide, you'll learn how to track users from a particular source before and after they sign up. For example, knowing how many people sign up for your application through a signup link that you have included in a blog post or an email campaign.

Pre-requisites

To follow this guide, you need to have the following:

• A free Authgear account.

• An application in the Authgear Portal and note down the configuration of the application.

• A client application that is written in your preferred language or framework.

What We'll Build

For this guide, we'll build a demo Express application that has the following features:

• Read a source URL parameter defined by you (the developer).

• Send the value of the source parameter to the Authgear authorization server using the OAuth 2.0 state parameter.

• Read the value of state returned after user authorization (sign up) and log the value in a database or analytics system like Mixpanel.

What is the OAuth 2.0 State Parameter?

The includes an optional state parameter. The value of the state parameter can be any random string or number defined by a client application (e.g a web or mobile that uses Authgear for user authentication) before the client makes an authorization request. In simple terms, the state parameter is added to the authorization URL as a URL query.

The authorization server (Authgear) will include the same state parameter value when redirecting the user-agent back to the client application. As a result, the client application can retrieve the value of state returned to verify that it is the origin of the authorization request.

We will use the above behavior of the authorization process to track a user before and after they sign up.

How to Track a User Who Signs Up from a Particular Source

The following steps show the steps for building a simple application that is capable of tracking users before and after they sign up.

Step 1: Set Up Your App to Use Authgear

First, create a new project directory and open it. The demo application for this guide is a simple application that use Axios to make HTTP requests. Hence, install both packages using the following commands:

1. Express:

2. Axios:

Next, inside the project directory, create a new app.js file then add the following code to the file:

You can get the correct configuration values (CLIENT_ID, CLIENT_SECRET, REDIRECT_URL, and AUTHGEAR_ENDPOINT) from the Applications section of the Authgear Portal.

Step 2: Add State Parameter to Authorization Request

In this step, we'll implement a /login route in the demo application. This route will support a source query parameter, for example, /login?source=002.

Add the following code to the end of app.js to implement the /login route:

The above code will check if the source parameter is included in the HTTP request to the /login route. If there is a source parameter, the value of the source will be added to the authorization URL's state parameter.

The following is an example of a login URL that includes the source parameter:

Step 3: Read the Value of State After Authorization

As described earlier, Authgear will return whatever value you put in the state parameter of the authorization URL. In the last step, we will read the value of the source parameter from the /login route and pass it to the state parameter. In this step, we'll read the state parameter that Authgear returns in the redirect URI for the initial value we passed (source).

To do this, we'll add a / route to resolve our redirect URI. Add the following code to the end of app.js to implement the route:

The sourceFromState constant holds the value for the state parameter in the redirect URI. You can save this value to a database to track that the user has successfully signed up using the link with the source value in your original campaign link. You may also send this link to an analytic tool like Mixpanel to track the user and source.

To run the demo app, run the following command in the terminal:

Then, open http://localhost:3000/login?source=002 on a browser. You can change 002 to any random string that you wish to use for tracking a source or campaign. Also, be sure to add http://localhost:3000 as a redirect URL for your application in the Authgear Portal.

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:

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