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 Edit Profile to edit and view profile attributes such as first name, last name, photo, etc.

Users can manage the identities (email address, phone number, or social media account) linked to their account under the My Account section of the User Settings page.

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

• Password: users can change their password from here.

• 2-step verification: users can click on this option to view and manage 2-step authenticators for their account. The option is only available when you enable 2FA for your project in Authgear Portal > Authentication > 2FA.

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

• Advanced Settings: contains additional settings. For example, when you enable Account Deletion for your project, users can click on this link to access the Delete Account button.

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.

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.

Integration Approaches

There are 3 different high-level approaches to integrating Authgear with your applications:

1. Mobile apps or single-page web applications: The frontend clients integrate with Authgear's SDKs, which handle full login flow and session management. It's important to validate the session in your backend server.

2. Regular Web Applications: Traditional server-side rendered web apps that run on the server can use OIDC protocol to authenticate with Authgear. The application server has full control over the session storage.

3. Software built by others: Integrate with other OIDC/SAML compatible applications like WordPress, Salesforce for Single Sign-On.

Mobile apps or single-page web applications

Client-side SDKs

Client-side SDKs are designed for developers to quickly implement authentication with Auth UI on your web and mobile applications. After login, it returns the user data for your apps. It can open a hosted for the user to manage their own account. The SDKs manage session token storage automatically and have built-in token ownership protection () against stolen refresh tokens.

Check out the following guides for your specific framework:

• Guides for Frontend JS SDK

• Guides for Mobile SDKs

Validate JWT in your backend server

After the frontend integration is complete, every request sent from your application to the backend server should include the Authgear session in its header. JWKS should be used to validate the requests and decode user information from the JWT access token. See for details and code examples.

Customization

You can to match your branding. can be used to stay notified and add functionality during the authentication process.

User Management through backend server

The Authgear Admin API enables comprehensive user management via a GraphQL endpoint for your backend server. The server can perform operations including searching for users, updating user details, deleting user accounts, and disabling user access.

For detailed implementation instructions and API capabilities, refer to the guide.

Custom UI

If you wish to use a custom UI instead of the pre-built UI for signup and login, you need to deploy another server and complete the signup/login process using Authentication Flow API. See for in-depth instructions.

Regular Web Applications

If your application is a traditional web app running on a server, you can leverage the OpenID Connect (OIDC) protocol to authenticate users via Authgear. A wide range of plug-and-play libraries can be found that simplify the integration process. These libraries handle crucial tasks such as authentication requests, session management, and redirecting users back to your application seamlessly.

See the following tutorials for your specific application framework:

Customization

You can to match your branding. can be used to stay notified and add functionality during the authentication process.

User Management

The Authgear Admin API enables comprehensive user management via a GraphQL endpoint for your server. The server can perform operations including searching for users, updating user details, deleting user accounts, and disabling user access.

For detailed implementation instructions and API capabilities, refer to the guide.

Custom UI

If you wish to use a custom UI instead of the pre-built UI for signup and login, you need to deploy another server and complete the signup/login process using Authentication Flow API. See for in-depth instructions.

Software built by others

When implementing identity management for your enterprise software, Authgear provides robust single sign-on (SSO) capabilities that seamlessly connect your workforce. Enterprise applications typically support standard authentication protocols like OpenID Connect (OIDC) and Security Assertion Markup Language (SAML)

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.

• Enable for your users to log into multiple web applications easily.

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

If your application is a traditional web app running on a server, for example, Java EE, Express, PHP, GO, Laravel, or Core MVC, you can leverage the OpenID Connect (OIDC) protocol to authenticate users via Authgear. A wide range of plug-and-play libraries can be found that simplify the integration process. These libraries handle crucial tasks such as authentication requests, session management, and redirecting users back to your application seamlessly.

By default, only the sub field of the UserInfo is included in the SAML assertion. To include other fields like users' email address, phone number, etc., you can set up SAML Attribute Mapping for the fields.

SAML Attribute Mapping allows you to configure your Authgear client application to include additional fields in the SAML assertion. This is a great way to pass additional data from Authgear to your SAML application that depends on Authgear as an Identity Provider.

Authgear supports using SAML attribute mapping to include additional fields in the SAML assertion using any field in the user profile attributes (UserInfo).

There's also support for a template that can be used to customize the values of the fields before including them in the SAML assertion. For example, the template {{.preferred_username}}@example.com will return the preferred_username field from the UserInfo prepended to '@example.com'.

Example of SAML Attribute Mapping

The above example creates three SAML attributes (family_name, given_name, placeholder_email) that will be added to the SAML assertion.

The value for pointer refers to a user profile attribute in the UserInfo object.

From an attribute that uses a template, the value in between the {{}} also refers to a user profile attribute in the UserInfo object.\

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.

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 enable "test mode" on a specific phone number or an email address so the demo account can authenticate with a fixed OTP 000000.

Please contact us at [email protected] if you need to enable test mode for a phone number or email address in your project.

The Authgear Android SDK provides an optional Okhttp interceptor which handles everything from refreshing the access token to putting the access token in the header.

Get the Extension

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

Usage

Configure OkHttpClient to use AuthgearInterceptor as follows:

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

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

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"

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.

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. In Client ID, add the identifier of the Services ID you created in Apple. Not the ID of the App ID or the Client ID of your Authgear Application.

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!

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

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 OIDC spec 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:

authgear
  .startAuthentication({
    redirectURI: "<AUTHGEAR_REDIRECT_URI>",
    prompt: PromptOption.Login,
  })

authgear
  .authenticate({
    redirectURI: 'com.reactnativeauth://host/path',
    prompt: PromptOption.Login,
  })

AuthenticateOptions options = new AuthenticateOptions("<AUTHGEAR_REDIRECT_URI>");
List<PromptOption> promptOptions = Arrays.asList(PromptOption.LOGIN);
options.setPrompt(promptOptions);
mAuthgear.authenticate(options, new OnAuthenticateListener() {
    @Override
    public void onAuthenticated(@Nullable UserInfo userInfo) {
        
    }

    @Override
    public void onAuthenticationFailed(@NonNull Throwable throwable) {
        Log.d(TAG, throwable.toString());
    }
});

authgear?.authenticate(
    redirectURI: "<AUTHGEAR_REDIRECT_URI>",
    prompt: "login"
)

_authgear.authenticate(
        redirectURI: "<AUTHGEAR_REDIRECT_URI>",
        prompt: "login",
      );

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.

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

Normally, the user should access the signup/login page through an OIDC flow, via the SDK or SAML. In such cases, the user will be redirected to the application specified by the flow.

Use the Endpoint Direct Access settings to configure what happens when users directly visit the endpoint URL (e.g. https://my-project.authgear.cloud) of an Authgear project unexpectedly.

By default, when users access the endpoint of a project directly, they'll see an error page that looks like this:

Show a "Back to home" link

Instead of the default error message, you can show a link to redirect the user away under your logo and project name. Go to Advanced > Endpoint Direct Access, select "Show a simple brand page with a back to home link" and provide the link.

Cookie-based Authentication

If you are using Cookie-based authentication, you can set Authgear to render the signup/login page even when the user is accessing the Endpoint URL directly. And therefore these options are only available when custom domain is enabled.

When user access the endpoint directly, they will be redirected to the /login page. After login, the user will be directed to the User Settings page (/settings).

Show the login page and redirect to the hosted settings page

When the user accesses the endpoint URL directly in their browser, show the authentication page. After the user is authenticated, they are redirected to the hosted User Settings page which they can manage their account.

Show the login page and redirect to a custom URL

When the user accesses the endpoint URL directly in their browser, show the authentication page. After the user is authenticated, they are redirected to a custom URL, which is usually your application website.

Post-logout URL

You should use the logout function in the SDK, the end-session endpoint for OIDC integration and Logout URL for SAML integration, in which the post-logout behaviour are specified according to the flows.

But if the user directly accesses the logout page, e.g. https://myproject.authgear.cloud/logout, the Post-Logout URL in Endpoint Direct Access settings controls where Authgear will redirect users after logout.

Use the Phone Number Validation Settings to configure your app to check the phone number your users enter without depending on SMS or WhatsApp for validation and verification.

Under the hood, the Phone Number Validation Settings uses the libphonenumber library. The library can parse, format, and validate phone numbers for all countries/regions in the world.

To access Phone Number Validation settings in your Authgear project, navigate to Authentication > Login Methods in the Authgear Portal.

Next, select a login method that uses mobile phone number as login ID (e.g., Mobile, Mobile/Email, or Custom with phone number enabled as login ID). Then, scroll down to the Phone Number Validation section. Select validate phone number with libphonenumber or validate only the country code and phone number length.

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), to the iCloud Keychain service. Passkeys are also (API level 28) or higher. A passkey is synchronized and relayed with an iCloud account and can be used across a user's devices.

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 , which provide the highest security against attacks.

Add Passkeys to your apps with Authgear

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

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

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

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

Support on different platforms

See the list of Passkey support via Authgear on different platforms.

• macOS 12: Passkey is supported on major browsers. However, the credentials are deleted when clearing browser data.

• iOS 15.5: Passkey is supported on Safari and stored locally a the device. Credential will be deleted by "Settings > Safari > Clear History and Website Data"

• iOS 16 Beta 3: Passkey is synced with iCloud Keychain. The individual credentials can be viewed and managed in "Settings > Passwords"

• Android 9 (API level 28) or higher: Supported.

Prerequisite

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

2. Setup a tenant by completing

3. Register an application by completing

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 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 in Authgear SDKs to learn more.

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.

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:

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!

Generative AI powered by large language models (LLMs) has revolutionized software development, giving rise to a new paradigm called “Vibe Coding.” This approach empowers individuals with ideas—regardless of their coding expertise—to create software quickly and intuitively. For developers, generative AI automates repetitive tasks, boosts productivity, and even enhances code quality in some cases.

While vibe coding is undeniably exciting, there’s one area where caution is essential: security. AI-generated code can sometimes be buggy or incomplete, and when deployed in real-world applications, critical aspects like user authentication and data protection cannot be left to chance.

Plug-and-Play Security with Authgear

To bridge this gap, Authgear offers a plug-and-play authentication solution that ensures your AI-generated applications are enterprise-grade secure. With the right prompts, developers can integrate robust security features into their projects in seconds. These features include:

• : Add an extra layer of security to user accounts.

• Email/Phone Verification with OTP: Ensure user identities are verified during sign-up or login.

• : Safeguard against unauthorized access attempts.

• : Keep malicious bots at bay.

By incorporating Authgear into your vibe coding workflow, you can focus on building innovative applications while ensuring top-notch security for your users.

Tips for using AI Codeing tools:

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

Change in the Portal

These two links can be easily added in the project Portal

1. Go to UI Settings in the Portal

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

3. Save the settings.

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

Edit translation.json

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

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

For example,

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

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.

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

Prerequisite

• A LinkedIn Developer profile. You can create one on the .

• LinkedIn App

Step 1: Create a LinkedIn App

Log in to the and create a new app or update the configuration for an existing one.

Go to the Auth tab of your LinkedIn app and take note of the "Client ID" and "Client Secret".

Also, add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/linkedin to "Authorized redirect URLs" under "OAuth 2.0 settings" section.

Next, open the Products tab of your LinkedIn app, and request access to "Sign In with LinkedIn using OpenID Connect."

Step 2: Configure Sign in with LinkedIn through the portal

In the Authgear Portal, go to Authentication > Social / Enterprise Login.

Enable Sign in with LinkedIn.

Then fill in the Client ID. and Client Secret from your LinkedIn app.

Save the settings.

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

This section covers mobile-specific integration patterns and configurations for Authgear.

If your API or backend service needs authentication, you can validate the session in your application server code. Each request from the client to your application server should contain an access token or a cookie. Your backend server should validate them for each HTTP request.

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

Simple: Validate JWT in your server

Authgear uses JSON Web Token (JWT) for secure data transmission, authentication, and authorization.

Authgear returns the access token and refresh token to the client app after authentication. Your client app should call the backend with the access token in the Authorization header. The tokens should be parsed and validated in the backend server to ensure they are not compromised and the signature is authentic.

Request example:

> GET /api_path HTTP/1.1
> Host: yourdomain.com
> Authorization: Bearer <AUTHGEAR_ACCESS_TOKEN_IN_JWT>

Read more on Validate JWT in your application server guide.

Advanced: 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 Forward Authentication to Authgear Resolver Endpoint guide.

Forward Access Token in Authorization Header

Instead of validating the access token in the backend, a reverse proxy forwards the request to an Authgear Resolver Endpoint. This endpoint resolves and verifies the access token in the Authorization Header of the request.

Forward Cookie in HTTP header

In this approach, instead of validating the token in authorization header, Authgear returns Set-Cookie headers and sets cookies to the browser. The cookies are HTTP only and share under the same root domains. So you will need to setup the custom domain for Authgear, such as identity.yourdomain.com.

If you have multiple applications under yourdomain.com, all applications would share the same session cookie automatically. After that, you can verify the cookies using the Resolver Endpoint.

Request example:

> GET /api_path HTTP/1.1
> Host: yourdomain.com
> cookie: session=<AUTHGEAR_SESSION_ID>

Security Assertion Markup Language or short SAML 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:

• https://github.com/authgear/docs/blob/main/authentication-and-access/single-sign-on/single-sign-on-with-saml/use-authgear-as-saml-identity-provider-for-salesforce.md

• https://github.com/authgear/docs/blob/main/authentication-and-access/single-sign-on/single-sign-on-with-saml/use-authgear-as-saml-identity-provider-for-dropbox.md

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.

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,
});

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.

In Authgear, a user's profile includes two types of attributes.

The first is the standard attributes which are basically common profile fields such as Primary Email, Primary Phone, Username, Name, Birthday, etc that are present by default.

The second type is the custom attributes an Authgear user can set for their project. This allows you to add custom fields to the profiles of your users. For example, you can add a Post Code custom attribute to your Authgear so users can provide this data for their profile.

All custom attributes are returned in the UserInfo response under the custom_attributes field.

In this post, you'll learn how to add new custom attributes to your Authgear project. You'll also learn how to manage existing custom attributes.

1. How to Add a New Custom Attribute

You can add new custom attributes to your project from the Authgear Portal. To do this, first, navigate to User Profile > Custom Attributes. Then, click on the Add New Attribute button to open the Add Custom Attribute page.

Enter the Attribute Name, a valid attribute name should consist of lowercase letters (a-z), digits (0-9), and underscore () only, must start with lowercase letters (a-z), and NOT end with an underscore (_).

Select the appropriate Attribute Type based on the type of data you expect users to enter in the custom attribute. The option you select will affect the type of input field (text field, dropdown, etc) users will see in their profile settings UI.

Once you're done, click the Save button to add the new custom attribute.

2. Set Who Can Access a Custom Attribute

Usually, the next key action to take after adding a new custom attribute will be to set the access right. An attribute's Access Right is a configuration that determines who can see (Read-only) or add or modify (Editable) the value of an attribute's field.

You can set the Access Right for an attribute under the following groups:

• Portal Admin: Access control for the user profile attributes in Admin Portal > User Management.

• Token Bearer: Access control for the user profile attributes in the UserInfo endpoint.

• End-user: Access control for the user profile attributes in the End-user settings page.

To set the access right for an attribute, navigate to User Profile > Custom Attributes in the Authgear Portal. On the Custom Attributes list, click the Access Right dropdown for the group and custom attribute you wish to update. Click Save when you're done to keep the changes.

Note: Selecting the Hidden access right, for any group will hide the field for the attribute from that group. For example, selecting Hidden for the post_code attribute for the Token Bearer group means the post_code field will be hidden (not included) in the UserInfo endpoint response.

3. Modify Custom Attribute Name

From the Custom Attributes list, click on the pencil icon to open the Edit Custom Attribute page.

Note: You can't modify the Attribute Type for an existing attribute. The alternative will be to create a new custom attribute with the new Type and migrate data from the old attribute to it. Also, rename and change the access right for the old attribute to make it obsolete.

4. Reorder Custom Attribute Position

You can set the order of how custom attributes appear in the UI.

To do that, in the Custom Attributes list, click and drag the stacked icon next to an attribute up or down to move the position.

5. Delete Custom Attribute

Delete is not supported. Instead, you should change the name and access right to make the attribute obsolete.

The prompt="login" parameter which is defined in the OIDC spec 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.

authgear
  .startAuthentication({
    redirectURI: "<AUTHGEAR_REDIRECT_URI>",
    prompt: PromptOption.Login,
  })

authgear
  .authenticate({
    redirectURI: 'com.reactnativeauth://host/path',
    prompt: PromptOption.Login,
  })

authgear?.authenticate(
    redirectURI: "<AUTHGEAR_REDIRECT_URI>",
    prompt: "login"
)

_authgear.authenticate(
        redirectURI: "<AUTHGEAR_REDIRECT_URI>",
        prompt: "login",
      );

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 , , or API Gateways such as , you can configure it with a few simple lines of forward auth config. Your backend should read the returned headers to determine the identity of the user of the HTTP request.

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

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:

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

Example configuration

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.

Reference on the headers

See the list of x-authgear- headers in the specs:

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.

Authgear is built based on OIDC 2.0 standard, you can integrate it into any application framework without SDK.

Supported grant types

Authorization Code Flow with Proof Key for Code Exchange (PKCE)

For public clients like mobile apps and SPAs, PKCE flow should be used. It uses code_challenge_method & code_challenge parameters in the authentication requests and the code_verifier parameter in the code exchange step. It ensures that the application that starts the code flow is the same one that finishes it.

OpenID Connect Configurations

This endpoint serves as a JSON document containing the OpenID Connect configuration of your Authgear project. That includes the authorization endpoint, the token endpoint, and the JWKs endpoint. The URL looks like:

Initiate Signup and Login

To singup or login, redirect the user to the /authorize endpoint. The URL should look like this:

Code Example

• “S256” is supported in code_challenge_method.

• The code_verifier is a string of length between 43 and 128 generated on the client side. It should be unique for each authorization request. The code_challenge is a SHA-256 hash of the verifier.

• The state parameter is optional. Authgear will include the value of the state parameter when redirecting the user back to the client application. Learn more at

• After login, the user will be redirected to [redirect_uri]?code=[AUTH_CODE], the AUTH_CODE is needed in the next step

• See the supported scopes at

Handling Callback

After receiving the AUTH_CODE in your application, make a POST request to the /token endpoint.

• Include the code_verifier used for generating the code_challenge to prove both requests come from the same client.

• The response may contain the ID token, the access token and the refresh token depending on the scope supplied by the previous step.

Logout

When the user logs out, revoke the refresh token by making a POST request to the revocation_endpoint with the refresh token in the body in application/x-www-form-urlencoded as content-type. The endpoint looks like https://AUTHGEAR_ENDPOINT/oauth2/revoke, it can be found in OpenID Connect configuration document.

Then clear the access token and refresh token stored locally in your app.

Verifying JWT Access Token

Include the access token in the Authorization headers of the frontend requests to verify your user’s identity. Follow this guide to learn about validating the JWT in your application server

Prerequisite

• Register a .

• Register a Web Application (网站应用).

See for more details.

Get the information from WeChat Open Platform

Once your mobile app is approved on the platform, you will see the word " 已通过" in the app details page.

• Get the appid (Client ID)

• Get the appsecret (Client Secret). It will only be shown once. You need to re-generate if you lose it.

• Get the 原始ID (Account ID) of your WeChat Open Platform account.

Configure Sign in with WeChat in the Authgear portal

1. Sign in to the Authgear portal.

2. Select your project.

3. In the navigation menu, go to Authentication > Social / Enterprise Login.

4. Click Add Connection.

5. Select WeChat Web / 网站应用.

6. Fill in Client ID with the appid.

7. Fill in Client Secret with the appsecret.

8. Fill in Account ID with the 原始ID.

9. Save.

Done!

No further changes are needed. The Sign in with WeChat button should be shown in the signup / login page now.

Appendix: Create web app on WeChat Open Platform

After logging into the Open Platform, go to the "网站应用" (Web App) and click "创建网站应用" to create a new web app

The following information are needed:

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 . 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. In Authorized JavaScript origins, add your Authgear endpoint, e.g. https://myproject.authgear.cloud

5. In Authorized redirect URIs, add https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/google. For example, https://myproject.authgear.cloud/sso/oauth2/callback/google

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

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

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)

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.

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.

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.

Prerequisites

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

• A native app using Authgear as authentication

• A web application using the same Authgear project as authentication

How to Implement Pre-authentication URLs in your application

Step 1: Enable SSO & Pre-authenticated URLs in Native Client App

First, ensure your mobile application uses an Authgear application with the Native App. Enable "preAuthenticatedURL" to allow pre-authenticated URLs to work.

authgear
  .configure({
    clientID: '<CLIENT_ID>',
    preAuthenticatedURLEnabled: true
  })

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:

const url = await authgear.makePreAuthenticatedURL({
    webApplicationClientID: "YOUR_WEB_APP_CLIENT_ID", // Replace with you web app client id
    webApplicationURI: "YOUR_WEB_APP_URI", // Replace with you web app uri
  });

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

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.

Browser.open({ url: url }).catch(err =>
      console.error("Couldn't load page", err),
);

Linking.openURL(url).catch(err =>
      console.error("Couldn't load page", err),
);

Step 5: Get authenticated state in the web application

The pre-authenticated URL is opened in the browser via the native app. In the web application, trigger authentication with the injected SSO session and get the authenticated state.

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

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

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

authgear.startAuthentication({
  redirectURI: import.meta.env.VITE_AUTHGEAR_REDIRECT_URL,
  prompt: PromptOption.None // use "None" to skip the continue screen
})
.then(
  () => {
    // started authentication, user should be redirected to Authgear
   },
  (err) => {
    // failed to start authorization
  }
);

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.

Prerequisites

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

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

Here are easy steps to achieve this:

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

Step 2. Go to User Profile → Custom Attributes page.

Step 3. Add 3 new attributes there, namely city, name, and timezone:

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

Step 5. Add a new Blocking Event.

Step 6. Choose the Block Hook Type as the TypeScript and set the Event option to User pre-create. You will write a new Typescript function from scratch.

Step 7. Click on Edit Script under the Config option.

Step 8. Write a function logic for how you integrate any external API to populate custom attributes into the editor. For example.

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

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

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

Step 9. Now if you navigate to User Management and Add a new user.

Step 10. After the user is created, you should able to see custom attributes values have been updated for the user:

Next steps

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

Authgear offers multiple ways for you (the admin) and your users to update user profiles. As an admin, you can modify profile attributes for any of the users of your Authgear project. End users on the other hand can modify their own profile using the Profile settings UI provided by Authgear or using a custom logic you implement in your code.

In this guide, we'll walk through all the options for updating user profiles.

Pre-requisites

To follow along, you need to have the following:

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

• At least one registered user on your Authgear Project.

What you'll learn

At the end of this post you'll be able to do the following:

• Update a user profile as an admin from the Authgear Portal or using Admin API.

• Update a user profile as an end user via the profile settings page.

1.0 Update User Profiles as an Admin

You can update the profiles for your users as an admin using either the Authgear Portal or the Admin API. Below are guides on how to use both options.

1.1 How to Update User Profile from the Authgear Portal

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

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

Next, Navigate to User Management section to view all the users currently registered under your project.

Click on the ID (name, email, or phone number) for the user you wish to update their profile to open the edit user details page.

From the edit user details page, you can edit the selected user's standard attributes such as Given Name, Family Name, Birthday, etc. If you scroll down on the edit user details page, you'll find more fields like the custom attributes that you can also update.

Once you're done, click the Save button to keep your update.

1.2 Using Admin API to Update User Profiles

The second option available for updating user profiles is the Admin API. The Admin API is a GraphQL API that you can use to manage your users. You can access Admin API from the API Explorer or by making requests to the API from your code or a client like Postman.

To update a user profile via the Admin API, you need to create a mutation like the following:

First, create a variable with all the existing profile attributes for the user, then include new fields or update the value for the fields you wish to update. Note that omitting an existing attribute in your variable will cause Authgear to delete that attribute.

Variable

{
  "standardAttributes": {
    "family_name": "John",
    "given_name": "Doe",
    "gender": "male"
  }
}

Mutation

mutation ($standardAttributes: UserStandardAttributes) {
  updateUser(input: {userID: "<ENCODED USER ID>", standardAttributes: $standardAttributes}) {
    user {
      id
      standardAttributes
    }
  }
}

For a detailed guide on making a GraphQL query to update user profiles, see our dedicated post on updating user's standard attributes using Admin API.

Also, see the Admin API example for updating custom attributes to learn how to update custom attributes of a user profile.

2 How End Users Can Update Their Own Profile

Authgear provides a user settings page in addition to the default Auth UI for user registration and login.

Your users can update their profile from this settings page by following the steps below:

First, within your application, provide a link to the user settings page for your Authgear project. The URL should look like this: https://<YOUR_AUTHGEAR_ENDPOINT>/settings. Note that users can not access this link directly without logging in first.

After a user logs in and visits the settings page, they can view their profile photo and other details.

Users can click on the Edit Profile button to update profile details such as name, gender, photo, and more.

To edit a profile attribute, the user should click on that attribute.

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 .

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

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

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:

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

The User Settings page provides a prebuilt user interface for logged-in users of an Authgear project to view and edit their account settings.

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 their signed-in sessions.

• Enable or disable 2-step verification.

• and many more.

Open the settings page in websites

Use the open() method of the Authgear Web SDK to open the built-in settings page.

Open the settings page with the SDK in mobile apps

If you are working on a mobile app, you can open the settings page using any of our mobile SDKs. When the end-user has signed in, the SDK provides a method to open the settings page in a Webview.

Back to my app button

In a 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.

To enable the back button, navigate to Branding > Design in Authgear Portal. Toggle the Show “Back to your app” button in the settings page switch on. Enter the destination URL for the 'Back to my app' button below the switch.

Click Save to apply your new settings.

Customize User Settings Page

You can customize the look and feel of the User Settings page using the tool in Authgear Portal.

Navigate to Branding > Design in Authgear Portal to customize the User Settings page.

The theme (dark, light, or auto), logo, colors, border, etc. you set for AuthUI will also apply to the User Settings page.

Out of the box, Authgear provides multiple languages that your application can display. If a language you wish to use is not in the list of built-in languages, you can still add your own translation.json to add support for the language.

Authgear will display text in a language based on your user's locale. In case the user's locale does not match any of the available languages for your project, the primary language will be used.

In this guide, you'll learn how to enable a supported language, set the primary language for your project, and add more languages using custom translation.

To access the Language settings for your project, navigate to the Languages section in the Authgear Portal.

1. Enable a Supported Language

You must enable a language before you can set it as a primary language or customize it. To enable a language, go to the Languages section in the portal, scroll to the language (built-in or custom translation), and check the box next to it. Finally, click on the Save button on the top left corner of the screen to keep your changes.

2. Set Primary Language

The primary language is the language that will be displayed when a user's locale does not match any of the supported languages.

Use the Language dropdown in the Primary Language subsection of Languages in the portal to set your project's primary language.

3. Add More Languages

You can add more languages using custom translation.json. To do this, first enable the language from the Custom Translation subsection of Languages in the portal. For example, enable a language such as Czech, Danish, or Estonian from the custom translation subsection and then proceed to write the translation.

Next, go to Branding > Custom Text in Authgear Portal. Then, select the language you wish to add from the dropdown at the top right corner.

Enter the in the translation.json text field to translate different UI texts for the language. See to learn more about editing translation.json.

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

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

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

AI-assisted IDEs like Cursor and Windsurf are increasingly popular among developers for enhancing productivity. These tools offer LLM-based agents for code suggestions, debugging, and understanding codebases.

Now, you’ve created an innovative software project consisting of a frontend application and a backend server. By leveraging generative AI with the right prompts, you can integrate robust security features into your project within seconds.

Create a project and an application on Authgear

First, create an account and a project in the the Authgear portal.

In the project creation wizard, choose how your users will perform signup and login. For example:

• By email with a password

• By receiving OTP via SMS or WhatsApp

Next, navigate to the “Applications” page and create an application of the type Single Page Application.

There are two values you will need for the subsequent steps:

• Client ID: An ID to identify your application application with Authgear

• Endpoint: The URL to identify your Authgear project and allow your application to connect to it.

Under “Authorized Redirect URIs,” add the URL of your local environment with /auth-redirect appended. For example, if your frontend application runs on port 4000, use: http://localhost:4000/auth-redirect there.

Save your changes.

Add user login to frontend code

To integrate login functionality into your frontend code, follow the corresponding documentation based on your framework:

• React: https://docs.authgear.com/get-started/single-page-app/react

• Vue: https://docs.authgear.com/get-started/single-page-app/vue

• Angular: https://docs.authgear.com/get-started/single-page-app/angular

In the chat, select the documentation as context and put in the following prompt.

Use `@authgear/web` package, Integrate Authgear as Authentication provider

Store these in .env for initializing Authgear:

- Authgear Client ID is [CLIENT ID]
- Authgear Endpoint is [Authgear Endpoint]
- Redirect URL is http://localhost:4000/auth-redirect

To show the login status in the home page, use the following prompt to change the appearance of the logged in status and add a button to the pre-built user settings page.

When logged in, show user id (sub) in user info, a logout button and a User settings button in the Home page
User Settings page is opened by `authgear.open(Page.Settings);`

Run the SPA with this prompt to verify the result.

Run dev frontend server at port 4000

Add protection to backend code

In the backend, add the following documentation as context:

• Validate JWT in your application server: https://docs.authgear.com/get-started/backend-api/jwt

# Use JWKS to verify the JWT

**Find the JWKS Endpoint**

Use the following method to get the JWKS URI (you'll need to URI to extract the public signing key from a JWT).

```
const appUrl = ""; //place your authgear app endpoint here
const getJwksUri = async (appUrl) => {
    const config_endpoint = appUrl + "/.well-known/openid-configuration";
    const data = await axios.get(config_endpoint);
    return data.data.jwks_uri;
}
```

**Extract JWT from Request Header**

Use the following code to extract only the token part from a `Bearer [token]` authorization header in your Express app:

```
const express = require("express");
const axios = require("axios");
const node_jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const app = express();
const port = 3002;
app.get('/', async (req, res) => {

    const requestHeader = req.headers;
    if (requestHeader.authorization == undefined) {
        res.send("Invalid header");
        return;
    }
    const authorizationHeader = requestHeader.authorization.split(" ");
    const access_token = authorizationHeader[1];

}
```

**Decode Access Token**

Next, decode the access token so that you can extract the JWT `kid` from the result. You'll need this `kid to get the public signing key. Use the following code to decode the JWT:

```
const decoded_access_token = node_jwt.decode(access_token, {complete: true});
```

**Get JWT Signing Keys and Verify the JWT**

Use the following code to extract the JWT public keys then verify the JWT using the keys:

```
const jwks_uri = await getJwksUri(appUrl);
    const client = jwksClient({
        strictSsl: true,
        jwksUri: jwks_uri
    });
    const signing_key = await client.getSigningKey(decoded_access_token.header.kid);

    try {
        const verify = node_jwt.verify(access_token, signing_key.publicKey, { algorithms: ['RS256'] });
        res.send(JSON.stringify(verify))
    }
    catch(error) {
        res.send(error);
    }
```

In the backend, create a protected api `/me`,
When user access with a JWT access token issued by Authgear, return the user id, if not, return 401 unauthorized error

Run the backend server with this prompt to verify the result.

Run dev backend server at port 3000

Similarly you can prompt the chat to protect any API endpoints in the backend.

Protect the API calls in the frontend

Now you have the a protected API in the backend, add a button in the frontend to test it out.

Include the corresponding frontend SPA docs to the "context" added in the previous step. Then use the following prompt to add a button the test the API call:

In the frontend, show a button to test the protected api `/me` both before and after logout. Use the `authgear.fetch("URL")` to call the API.

Run both the frontend and backend servers simultaneously. Your frontend should now feature a button that calls the protected API. Logged-in users will see their user ID retrieved successfully, while logged-out users will encounter an error message.

The user profiles contain information about your end-users such as name, email, addresses, and their unique identifier. You can manage the profiles via the Portal & Admin API. The end-users can also manage their own profile through the Profile section in the User Setting page provided by the AuthUI.

The complete information in the user profiles is a combination of standard attributes and custom attributes. Attributes are a way of grouping the fields of the user profile information. With standard attributes containing common fields, you'll find in a user profile, hence the names of these fields are set by Authgear. You set custom fields on the other hand based on the unique needs of your project.

Standard Attributes

The following attributes are built-in supported by Authgear. They are the set of Standard Claims defined by the OIDC specifications. Some of them are default hidden from the Admin Portal and end-users. Their visibility and mutability can be configured through the Admin Portal.