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 .

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

You can learn more about the User Settings page .

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

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:

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

• guides on how to .

• how to .

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.

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:

When you try to publish a mobile app on the Apple AppStore, there will be an . You need provide a demo user account for the reviewers to access the features of the app.

However, passwordless login via email/phone OTP cannot be used in the review because the reviewer do not have access to the email inbox or phone number of that demo account.

To work around this, you can enable "test mode" for a specific phone number or email address that allows the account to authenticate with a fixed OTP (e.g. 000000).

How to enable "test mode"

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

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.

For many business applications, it's important to restrict who can register for your platform. By disabling public signups in Authgear, you can ensure that new users are only added through your internal processes, such as the Admin API or the Authgear Portal.

When to Disable Public Signup

Disable public signup if you want to:

• Control user access and approval for your application.

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

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

Authgear simplifies the use of open industry standards like OAuth 2.0, and OIDC. Users can log into your applications with a variety of user login options. This set of how-to guides provides you with detailed instructions, code snippets, and configuration examples for each type of login method.

Prerequisite

1. Sign in Microsoft Azure.

2. Create a B2C tenant by following this tutorial.

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.

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

The Forgot/Reset Password settings tab allows you to configure the behaviour of the account recovery process for your Authgear project.

Enable Reset Password

Select a login method and navigate to the password settings tab. The login method chosen controls how the user can reset their password:

• Phone (OTP only)

• Email (link or OTP)

• Both

If both options are available, the user will be able to choose between using phone or email for account recovery.

Recovery via phone

You can choose how you want the OTP to be delivered. In the following example, the user will receive an OTP via "WhatsApp or SMS". This means the user can select their preferred method during reset.

The valid duration (in seconds) for the OTP or reset link can also be customized. This duration does not determine the minimum delay before resending OTPs or links.

As an example, if OTP is enabled as the recovery method, users will see the following screen to verify their identity during password reset:

Once you're done, save your changes to enable the new configuration.

Prerequisite

1. Follow the official guide 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

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

For creating accounts and sending users their passwords using Admin API, see createUser in the Admin API documentation.

In this post, we'll cover a few options and describe examples of automating the process of sending passwords to new users using the Authgear Portal or webhooks.

At this moment, Authgear only sends passwords to email accounts.

How to create a user and send the password via email

What happens if the user loses the preset password?

Users can still log in to their new account if they lose the password you set for them. They can click Forgot Password during login, and an OTP or link will be sent to the user. The user can then set a new password.

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:

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

If your application is a traditional web app running on a server, for example, Java EE, Express, PHP, GO, Laravel, or ASP.NET 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.

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.

How to reset a user's password via Authgear Portal

How to reset a user's password via AdminAPI

See under Reference > APIs > Admin API > API Queries and Mutations.

What happens if the user loses the preset password?

Users can still log in to their new account if they lose the password you set for them. They can click Forgot Password during login, and an OTP or link will be sent to the user. The user can then set a new password.

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

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.

In Authgear, you can build your own custom login and sign-up pages instead of using the built-in ones.

Example 1: Verifying multiple identities during signup

In Authentication > Login Methods, if Email and phone number are both enabled, the user will be able to choose between their preferred method during login.

In the example above, the user can choose to signup/login with either an email address or a phone number, but they cannot register with both at the same time.

Prerequisite

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

• LinkedIn App

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

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

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.

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.

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

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

Pre-requisites

To follow along, you need to have the following:

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

• At least one registered user on your Authgear Project.

What you'll learn

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

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

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

1.0 Update User Profiles as an Admin

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

1.1 How to Update User Profile from the Authgear Portal

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

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

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

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

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

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

1.2 Using Admin API to Update User Profiles

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

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

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

Variable

Mutation

For a detailed guide on making a GraphQL query to update user profiles, see our dedicated post on updating.

Also, see the to learn how to update custom attributes of a user profile.

2 How End Users Can Update Their Own Profile

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

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

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

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

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.

Use Authgear as SAML Identity Provider for Dropbox

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

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

Prerequisites

• An Authgear account. Sign up for free.

• A Dropbox Business Advanced account.

Step 1: Create an Authgear Client Application

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

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

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

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

Click Save to proceed.

Step 2: Enable SAML 2.0 in Client Application

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

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

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

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

Click on Save to keep your changes.

Step 3: Get SAML IdP Configuration and Download Certificate

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

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

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

Step 4: Add Authgear SAML IdP in Dropbox

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

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

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

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

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

Step 5: Login to Dropbox Using Authgear SAML

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

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

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

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 (SPF) for your domain.

5. Set up (DKIM) for your domain.

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

7. Create a "Services ID" by adding a new "Identifier" , 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 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.

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

Test mode allows for control over how OTPs are handled during development and testing.

Common use cases include:

• Internal testing (e.g. Allowing specific accounts to authenticate with fixed codes for ease of testing).

• Testing SMS, WhatsApp, or email login via OTP, but don't want to rely on the actual OTP delivery.

• App Store Reviewers. See Tips for Apple App Store Review with Passwordless Login.

How to enable test mode

In your portal, navigate to Advanced > Edit Config

Then add the following to the yaml:

How this works

• regex: Defines target emails/phone numbers the rule applies to using a regular expression

• fixed_code: A 6-digit code accepted as the OTP for targets

• suppressed: false by default. If true, messages will not be sent to the target

Examples

Case 1: Development

In development, you may want to use a fixed code for testing.

In this case,

• The rule in oob_otp matches all target so a fixed OTP 000000 will be used.

• SMS is not suppressed for +85291231234 only. They will receive 000000 via SMS so the SMS sending capability can be tested.

• No messages will be sent to WhatsApp or email channels

If the rules in sms were reversed in the example above, the .* regex would match all accounts first, making more specific rules unreachable.

Case 2: App review

During app review, you can enable "test mode" for a specific phone number or email address that allows the account to authenticate with a fixed OTP. So this account can be shared with the app reviewer to complete the passwordless login flow

In this example,

• Only +85291231234 can be passed with the fixed code 000000 and other accounts should use real OTP.

• SMS and WhatsApp are suppressed for +85291231234

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 OpenID Connect (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.

Backend Authentication and Integrations

• - explain the common approach of using Access Token or Cookies (JWT or random string) to authenticate an API or HTTP Requests.

• - allow your backend to interact directly with Authgear for user management purpose.

• - call external web endpoint or use the hosted type-script to customize the behaviour of Authgear. E.g. blocking certain type of sign up, or call external endpoint for each login.

Management Portal

• Authgear Portal - You can configure your projects, manage users, check out , or customize the AuthUI. 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.

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 you are building token-based websites or mobile apps, you can enable the SSO feature via the SDK.

When SSO-enabled is ON, the end-user will need to enter their authentication credentials when they login to the first app. Later on, when they login to the second app, they will see a continue screen so that they can log in with just a click, without authenticating themselves again.

When the end-user logout the SSO-enabled app, all the apps will be logged out at the same time.

You can turn on this feature when you configure the SDK by setting the is sso enabled option to true.

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

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

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.

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.

import authgear, { TransientTokenStorage } from "@authgear/react-native";

authgear.configure({
    clientID: CLIENT_ID,
    endpoint: ENDPOINT,
    tokenStorage: new TransientTokenStorage(),

final authgear = Authgear(
    clientID: CLIENT_ID,
    endpoint: ENDPOINT,
    tokenStorage: TransientTokenStorage(),
);

var authgearOptions = new AuthgearOptions
{
    ClientId = CLIENT_ID,
    AuthgearEndpoint = ENDPOINT,
    TokenStorage: new TransientTokenStorage(),
};
#if __ANDROID__

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

• Apple

• Google

• Facebook

What Are M2M Applications?

Machine-to-machine (M2M) applications enable backend services, CLIs, scheduled jobs, and smart devices to obtain access tokens and interact with APIs using dedicated credentials. Instead of human user authentication, these apps use their own credentials to securely access resources, streamlining automation and integration across your stack.

This may be familiar for users from UK, which many neobanks are using the app2app mechanism to authorize the money transfer from 1 bank app to another.

The App2App mechanism allows one app to authenticate the user using another apps connected to the auth server installed on the same device. This is achieved by universal links and the apps do not need to share the session via the system browser or the refresh tokens via the token storage.

Please note that this is not the Single Sign-on feature, if your are offering multiple apps under the same brand and wish the users to use a shared login session among their apps in the device, you may want to use instead. App2app should be used when:

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

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

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

Prerequisites

Authgear allows you to set a password policy for your project. This page walks through setting password requirements, password strength, keywords to exclude, and password expiry from the Authgear Portal.

You can configure your password policy in password settings.

1. Password Requirements

Choose a minimum character length, and use the checkboxes provided to include one or more requirements for a valid password.

To ensure your updated password policy applies to both existing and new users, toggle on "Force password change on next login". All users will be required to update their passwords if their current passwords do not meet the newly configured policy.

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

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

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

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

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.

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:

Prerequisite

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.

Prerequisite

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

2. Setup a tenant by completing

Primary and Secondary Passwords

In Authgear, a password can be Primary or Secondary. Secondary passwords can be enabled as part of Two Factor Authentication (2FA).

The password policies for Primary and Secondary passwords are not configured independently. Password policy settings apply to both types.

To configure your project's password policy, simply navigate to the password settings, and follow the corresponding guides.

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:

• Vue:

• Angular:

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

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 .

Run the SPA with this prompt to verify the result.

Add protection to backend code

In the backend, add the following documentation as context:

• Validate JWT in your application server:

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

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

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:

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.

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

Setting up Authgear in the Portal

1. Go to Applications on the left menu bar.

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

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

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

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

6. Obtain the OpenID Connect configuration:

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

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

7. Provide the OpenID Connect configuration to your application.

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

WordPress Example

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

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

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

3. Go to Setting > OpenID Connect Client.

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

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

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

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

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:

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.

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

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 on the Authgear website. Start by logging into your .

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

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

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

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