# Authgear Overview Authgear is a highly adaptable identity-as-a-service (IDaaS) platform for web and mobile applications **Authgear** is an authentication & user management solution that 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](https://openid.net/developers/how-connect-works/) (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. * Supports a wide range of identity providers, such as [Google](https://developers.google.com/identity), [Apple](https://support.apple.com/en-gb/guide/deployment/depa64848f3a/web), and [Azure Active Directory](https://azure.microsoft.com/en-gb/products/active-directory/) (AD). * Supports 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 for 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 [SSO with SAML](/get-started/single-sign-on-with-saml) for your users to log into multiple web applications easily. * [Session management](/authentication-and-access/sessions) with Authgear Portal, 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 customization. For example, build your own custom login and sign-up pages from the ground up powered by the [Authentication Flow API](/reference/apis/authentication-flow-api). Most importantly, you can [get started](https://accounts.portal.authgear.com/signup) **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 [Start Building](/get-started/start-building) for tutorials and API References. * **Auth UI** - the default batteries-included UI for login, signup and the settings page. You can customize the style via the **Portal**, including the CSS and HTML of each page. * [**Authentication Flow API**](/customization/custom-ui/authentication-flow-api) - for developers to implement their own login, signup and reauthentication UI (e.g. a mobile native view); or to define a customized login, signup and reauth flow. * [**Use Authgear as OpenID Connect Provider**](/get-started/oidc-provider) - for developers to use Authgear with other software that already supports OIDC login, you can use Authgear as an OpenID Connect Provider. #### Backend Authentication and Integrations * [**Backend/API Integration**](/get-started/backend-api) - explains the common approach of using Access Tokens or Cookies (JWT or random string) to authenticate API or HTTP requests. * [**Admin API**](/reference/apis/admin-api) - allows your backend to interact directly with Authgear for user management purposes. * [**Events and Hooks**](/customization/events-hooks) - call an external web endpoint or use hosted TypeScript to customize the behaviour of Authgear, e.g. blocking certain types of sign-up, or calling an external endpoint on each login. * [**User Import API**](/admin-and-operations/user-management/import-users-using-user-import-api) - Import multiple users from another service to your project. * [**Export User API**](/admin-and-operations/user-management/export-users-using-the-user-export-api) - Export user data from Authgear into a CSV or [ndjson](https://github.com/ndjson/ndjson-spec) file. * [**Link OAuth Provider using Account Management API**](/customization/custom-ui/manually-link-oauth-provider-using-account-management-api) - Link an OAuth provider to a user's account without AuthUI. #### Management Portal * **Authgear Portal** - You can configure your projects, manage users, check out [audit log](/admin-and-operations/monitor/audit-log), or customize the **AuthUI**. See the [5-minute quick start guide](/get-started/5-minute-guide) for Authgear Portal. * **Analytics Page** - View reports of all users and active users over a specific time interval on the [analytics page](/admin-and-operations/monitor/analytics). #### Security * [**Brute-force Protection**](/security/brute-force-protection) - Set account Lockout Policy to safeguard a user account from brute-force login attempts. * [**Bot Protection**](/security/bot-protection) - Bot protection tools to block automated attackers. * [**Fraud Protection**](/security/fraud-protection) - Detect and stop fraudulent traffic such as SMS pumping before it drives up your messaging costs. * [**Password Strength**](/authentication-and-access/authentication/passwords/password-policy) - Learn how to set password strength and how the password strength is calculated. #### Login Methods * [**Biometric Login**](/authentication-and-access/authentication/biometric) - Add biometric login to your application. * [**Two-Factor Authentication (2FA)**](/authentication-and-access/authentication/enable-two-factor-authentication-2fa) - Enable 2FA in your Authgear project. * [**Email Magic Link Login**](/authentication-and-access/authentication/add-email-magic-link-login) - Allow users to log in without a password using a magic link. * [**Passkeys Login**](/authentication-and-access/authentication/passkeys) - Set up passkey for your project. * [**Social Login / Enterprise Login**](/authentication-and-access/social-enterprise-login-providers) - 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 Built-in UI**](/customization/built-in-ui/branding) - Customize the look and feel of AuthUI to match your branding. * [**Language and Localization**](/customization/built-in-ui/languages-and-localization) - Change the language for display texts. #### User Management Features for managing your users via Authgear Portal * [**Create a new account on behalf of a user**](/authentication-and-access/authentication/passwords/how-to-handle-password-while-creating-accounts-for-users) - Create a new account for a user from Authgear Portal. * [**Account Deletion**](/admin-and-operations/user-management/account-deletion) - Delete a user account from your project. * [**User Roles and Groups**](/admin-and-operations/user-management/manage-users-roles-and-groups) - Detailed guide on how to use Roles and Groups. * [**User Profiles**](/integration/user-profiles) - Guides on how to view and manage user profile information. # 5-Minute Guide A quick guide on getting started with Authgear Authgear makes it easy to add user authentication and authorization to any application. In this guide, we'll show you how to get started with Authgear in 5 minutes. ### Video Guide {% embed url="" %} ### 1. Create Authgear account To start using Authgear in your application, create a free Authgear account on [authgear.com](https://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](/get-started/start-building) 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.
{% hint style="info" %} The flow for sign-up and login will differ based on the login method you enable for your Authgear project. For example, users can sign up using their phone number and password if you enable the **Mobile** login method. {% endhint %} ### 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](/admin-and-operations/user-management/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](/customization/built-in-ui/user-settings). ### 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](/get-started/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](/reference/apis/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](/customization/built-in-ui/branding) login and sign-up page to match your branding needs using the Design tool * guides on how to [integrate Authgear to your app](/get-started/start-building). * how to [enable 2FA for your project](/authentication-and-access/authentication/enable-two-factor-authentication-2fa). # Skills for AI Agent [Authgear Skills](https://github.com/authgear/authgear-skills) are installable skills for AI coding agents (Cursor, Claude Code, Codex, OpenCode, Gemini CLI, and similar) to integrate Authgear into your projects. To install all Authgear Skills, in your project use: ```shellscript npx skills add authgear/skills ``` Or clone [the repo](https://github.com/authgear/authgear-skills) and point the skills path of your coding agent to the `skills` folder. ### Available skills Once installed, these skills will be available for your project.
SkillWhen to use
/authgear-integrationIntegrate Authgear authentication into web, mobile, and backend applications
/authgear-custom-ui (coming soon)Build custom UI for signup/login
/authgear-authflow (coming soon)Set up custom authentication flow
### Example prompts You can try our these example prompts in your project: * "Add Authgear authentication to my React app with login/logout buttons and a protected dashboard page" * "Integrate Authgear into my React Native app with login flow and user setting screen" * "Protect my Express.js API endpoints with JWT token validation using Authgear" * "Create a user profile page that displays email and phone number from Authgear" # Start Building Choose the integration approach based on application type ## 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 [pre-built account settings page](/customization/built-in-ui/user-settings) for the user to manage their own account. The SDKs manage session token storage automatically and have built-in token ownership protection ([DPoP](https://oauth.net/2/dpop/)) against stolen refresh tokens. **Check out the following guides for your specific framework:** * Guides for Frontend JS SDK * [React](/get-started/single-page-app/react) * [Vue](/get-started/single-page-app/vue) * [Angular](/get-started/single-page-app/angular) * [Vanilla JS](/get-started/single-page-app/website) * Guides for Mobile SDKs * [iOS](/get-started/native-mobile-app/ios) * [Android](/get-started/native-mobile-app/android) * [React Native](/get-started/native-mobile-app/react-native) * [Flutter](/get-started/native-mobile-app/flutter) * [Capacitor (Ionic)](/get-started/native-mobile-app/ionic) * [Xamarin](/get-started/native-mobile-app/xamarin) * [Others](/get-started/native-mobile-app/using-authgear-without-sdk-client-side) ### 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 [Validate JWT in your application server](/get-started/backend-api/jwt) for details and code examples. ### Customization You can [customize the look and feel of Authgear prebuilt UI](/customization/built-in-ui/branding) to match your branding. [Events and hooks](/customization/events-hooks) 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 [Admin API ](/reference/apis/admin-api)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 [Custom UI ](/customization/custom-ui)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:** * [Next JS](/get-started/regular-web-app/nextjs) * [Express JS](/get-started/regular-web-app/express) * [PHP (Laravel)](/get-started/regular-web-app/laravel) * [Python (Flask)](/get-started/regular-web-app/python-flask-app) * [ASP.NET Core MVC](/get-started/regular-web-app/asp.net-core-mvc) * [Java (Spring Boot)](/get-started/regular-web-app/java-spring-boot) ### Customization You can [customize the look and feel of Authgear prebuilt UI](/customization/built-in-ui/branding) to match your branding. [Events and hooks](/customization/events-hooks) 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 [Admin API ](/reference/apis/admin-api)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 [Custom UI ](/customization/custom-ui)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) * [Integration with OIDC Protocol](/get-started/oidc-provider) * [Integration with SAML 2.0 Protocol](/get-started/single-sign-on-with-saml) # Single-Page App You need to protect a JavaScript SPA application that runs entirely in a browser {% content-ref url="/pages/OebXDnWVjMaHZWu9GwaM" %} [Angular](/get-started/single-page-app/angular) {% endcontent-ref %} {% content-ref url="/pages/cpJZRTXowaem5PW8JpMd" %} [JavaScript (Web)](/get-started/single-page-app/website) {% endcontent-ref %} {% content-ref url="/pages/-MbjniMzPmbpZ2MI29aV" %} [React](/get-started/single-page-app/react) {% endcontent-ref %} {% content-ref url="/pages/dfc7Z8f9qyNYOcOGTALB" %} [Vue](/get-started/single-page-app/vue) {% endcontent-ref %} # JavaScript (Web) Integrate Authgear to your website with the Web SDK In this guide, you'll learn how to integrate Authgear into your website using the Token Approach. In the token approach, the Authgear server returns an access token and a refresh token to your SPA application after successful user authentication. Your application can send the access token in subsequent HTTP requests to access protected resources. Follow this guide to add Authgear SDK to any web application in under 🕐 **10 minutes**. {% hint style="info" %} See and clone the full code for the demo app for this tutorial in [**the Github Repo here**](https://github.com/authgear/authgear-example-spa-js). {% endhint %} This guide uses the Authgear Web SDK for integrating Authgear with a SPA Web app. Supported browsers include: * Last 2 Firefox major versions * Last 2 Chrome major versions * Last 2 Edge major versions * Last 3 Safari major versions ## Setup Application in Authgear Signup for an Authgear Portal account in . Or you can use your self-deployed Authgear. From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project. ### **Step 1: Create an application in the Portal** Go to **Applications** on the left menu bar.
Click **⊕Add Application** in the top toolbar. Input the name of your application and select the application type **Single Page Application**. Click the **Save** button to proceed.

create spa application authgear portal

On the next screen you will see a list of tutorials for different frameworks, click on **Next** to skip to your client application configuration page. ### **Step 2: Configure the application** First, decide the paths in your website that users will be redirected to after they have authenticated with Authgear. To run the demo app in this tutorial offline, scroll to the URIs section of your client application page add the following URI: Under **Authorized Redirect URIs** add `http://localhost:3000/` {% hint style="info" %} Note that the trailing "/" in the above URLs must be included. {% endhint %} ![Edit an application](/files/zu5AjbBMwqQqGaiwoSuF) Click on the **Save** button to keep your changes. ## Add Authgear to any web page using JavaScript In this section, we'll create a simple web page and use the Authgear Web JavaScript SDK to add user authentication to the page. ### Step 1: Create a Basic Single Page Web Application For this guide, we'll create a basic web application with only one page. Follow these steps to set up the application. First, create a new directory on your computer for the project. You can do this in a terminal using the following commands: ```bash mkdir my-webapp cd my-webapp ``` ### Step 2: Create Web Server We'll create an Express.js server in the web project directory so that we can access the HTML page in a web browser using `http://localhost:3000`. Run the following commands from the root of your web project directory to install Express. First, generate a package.json file in your project directory: ```bash npm init -y ``` Install the Express npm package: ```bash npm install express ``` Install Nodemon (used for adding hot road to JavaScript development): ```sh npm install -D nodemon ``` Now create a `server.js` file in the root folder of your project. Add the following code to server.js: ```javascript const express = require("express"); const { join } = require("path"); const path = require("path"); const app = express(); // Serve static assets from the /public folder app.use(express.static(join(__dirname, "public"))); // Serve the index page for all other requests app.get(/.*/, (req, res) => { res.sendFile(path.join(__dirname, "index.html")); }); // Listen on port 3000 app.listen(3000, () => console.log("Application running on port 3000")); ``` Next, open the `package.json` in your project directory and add the following lines in the script section: ```json "start": "node server.js", "dev": "nodemon server.js" ``` {% hint style="info" %} Note that the above you may use your preferred tool/environment to serve the HTML file and skip the step of creating an Express server. {% endhint %} ### Step 3: Create Web Page Create a new file called `index.html` in the root of your project directory. Add the following code to the file: ```html Authgear SPA SDK Sample

SPA Authentication Sample

Welcome to our page!

``` The content `index.html` is a simple web page that contains some text, a Log in button, and a Log out button. In later steps, we will implement the `onclick` events for both steps such that each calls the correct function from the Authgear Web JavaScript SDK. ### Step 4: Install Authgear Web JavaScript SDK #### CDN The Web JS SDK is available on a CDN that you can include in any webpage using the following script tag: ```html ``` The Web JS SDK is also available as [an npm package](https://www.npmjs.com/package/@authgear/web). That can be installed using any of the following commands: #### NPM ```bash npm install --save --save-exact @authgear/web ``` #### Yarn ```bash yarn add @authgear/web --exact ``` We recommend that you use the npm package to add Authgear to your web application when you're using build tools like Vite and Webpack, and when building with frameworks like React, Vue, Angular, etc. The easiest way to add a JavaScript library such as the Authgear SDK to a generic Single Page Application (a basic `.html` file page), is to use a CDN. Hence, we'll use the CDN method to add the Authgear Web JavaScript SDK to our demo application for this tutorial. To install the Authgear SDK, add the Authgear SDK CDN \ ``` With that, we have added the Authgear SDK to a basic HTML page and we are ready to start making calls to its functions. #### Checkpoint At this point, the structure of your project folder should look like this: ``` my-webapp ├── index.html ├── server.js └── package.json ``` To test your progress so far save your files then run the `npm run dev` command. Next open `localhost:3000` on your preferred web browser and you should see a page that looks like this:

spa demo web app page

### Step 5: Initialize Authgear SDK Create a new `public/js` directory in the root of your project directory. Create a new file called `app.js` in the `public/js` directory. Add the following content to `app.js`: ```javascript let authgearClient = null; const configureClient = async () => { authgearClient = window.authgear.default; await authgearClient.configure({ endpoint: "", clientID: "", sessionType: "refresh_token", }).then( () => { console.log("Authgear client successfully configured!"); }, (err) => { console.log("Failed to configure Authgear"); } ); }; window.onload = async () => { await configureClient(); } ``` In app.js, the `configureClient()` function gets an instance of the Authgear Web SDK (`authgearClient`) and then calls the `configure()` function of the SDK to initialize Authgear. You can find value for `clientID` and `endpoint` from your Authgear client application configuration page. Finally, link `app.js` in `index.html` using `` just above the line with the Authgear CDN ` ``` ### Step 6: Start the authentication flow When the user clicks login/signup on your website, make a **start authorization** call to redirect them to the login/signup page (AuthUI). In this step, we'll implement the `login()` function that is called when the **Log in** button is pressed. Update `app.js` by adding the following code after the declaration of the `configureClient()` function: ```javascript const login = async () => { await authgearClient .startAuthentication({ redirectURI: "http://localhost:3000/", prompt: "login", }) .then( () => { console.log("Logged in!"); }, (err) => { console.log("Log in failed", err); } ); }; ``` {% hint style="info" %} Make sure you have added `http://localhost:3000/` as an Authorized Redirect URI in the portal for your Authgear client application. Note that the last "/" in the URL is required. {% endhint %} ### Step 7: Handling auth result in the redirectURI After the user authenticates on the login page, the user will be redirected to the `redirectURI` with a `code` parameter in the URL query. In the `redirectURI` of your application, make a **finish authorization** call to handle the authentication result. This will attempt to exchange the `code` for the access token and user info. Once authorization succeeds, the application should be able to display user info and access protected resources. To handle the redirect after authentication, we'll call the Authgear SDK's `finishAuthentication()` function when there's a code parameter in the URL of the current page. To do that, update the `window.onload` callback in app.js to the following: ```javascript window.onload = async () => { await configureClient(); updateUI(); const query = window.location.search; if (query.includes("code=")) { await authgearClient.finishAuthentication(); updateUI(); window.history.replaceState({}, document.title, "/"); } } ``` The `updateUI()` function will update the state of the webpage when the user's logged-in state changes. Add the following code to the end of app.js to implement `updateUI`: ```javascript const updateUI = async () => { const isAuthenticated = authgearClient.sessionState === "AUTHENTICATED"; document.getElementById("btn-logout").disabled = !isAuthenticated; document.getElementById("btn-login").disabled = isAuthenticated; }; ``` The complete content of app.js at the end of this step should look like this: ```javascript let authgearClient = null; const configureClient = async () => { authgearClient = window.authgear.default; await authgearClient.configure({ endpoint: "", clientID: "", sessionType: "refresh_token", }).then( () => { console.log("Authgear client successfully configured!"); }, (err) => { console.log("Failed to configure Authgear"); } ); }; const login = async () => { await authgearClient .startAuthentication({ redirectURI: "http://localhost:3000/", prompt: "login", }) .then( () => { console.log("Logged in!"); }, (err) => { console.log("Log in failed", err); } ); }; window.onload = async () => { await configureClient(); updateUI(); const query = window.location.search; if (query.includes("code=")) { await authgearClient.finishAuthentication(); updateUI(); window.history.replaceState({}, document.title, "/"); } } const updateUI = async () => { const isAuthenticated = authgearClient.sessionState === "AUTHENTICATED"; document.getElementById("btn-logout").disabled = !isAuthenticated; document.getElementById("btn-login").disabled = isAuthenticated; }; ``` #### Checkpoint At this point, your file structure should look like this: ``` my-webapp ├── index.html ├── server.js ├── public/js │ └── app.js └── package.json ``` Save all changes in your code, and rerun your app on a web browser. This time, clicking on the **Log in** button should redirect you to your Authgear project's user login page (AuthUI).
### Step 8: Open User Settings Page To add a User Settings button to your app, add the following tag to your `index.html` just below the Logout button: ```html ``` Next, add the following code to `app.js`: just below the `logout()` function: ```javascript const openUserSettings = () => { authgearClient.open("/settings"); } ``` Finally, add the following line to the end of your `updateUI()` function so that the User Settings button is displayed when the user is authenticated: ```javascript document.getElementById("btn-settings").disabled = !isAuthenticated; ``` Save your work and run your app again. When you click on the User Settings button, your web app should open the pre-built User Settings page. ### Step 9: Additional Actions #### Get the Logged In State When you start launching the application. You may want to know if the user has logged in. (e.g. Redirect users to log in if they haven't logged in). The `sessionState` reflects the user logged-in state in the SDK local state. That means even the`sessionState` is `AUTHENTICATED`, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call `fetchUserInfo` to update the `sessionState` as soon as it is proper to do so. ```javascript // After authgearClient.configure, it only reflect SDK local state. // value can be NO_SESSION or AUTHENTICATED let sessionState = authgearClient.sessionState; if (sessionState === "AUTHENTICATED") { authgearClient .fetchUserInfo() .then((userInfo) => { // sessionState is now up to date }) .catch((e) => { // sessionState is now up to date // it will change to NO_SESSION if the session is invalid }); } ``` The value of `sessionState` can be `UNKNOWN`, `NO_SESSION` or `AUTHENTICATED`. Initially the `sessionState` is `UNKNOWN`. After a call to `authgearClient.configure`, the session state would become `AUTHENTICATED` if a previous session was found, or `NO_SESSION` if such session was not found. #### Fetching User Info In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `fetchUserInfo` function to obtain the user info. ```javascript authgearClient.fetchUserInfo(); ``` See more user info [examples](/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo). #### Log the user out Use the `logout` function to log out the user. The user will be redirected to your Authgear endpoint to log out their session. You should provide the `redirectURI` for the user to return to your app. ```javascript authgearClient .logout({ // user will navigate to the redirectURI after logged out // make sure it is in the "Post Logout Redirect URIs" in the application portal redirectURI: "https://yourdomain.com", }) .then( () => { // logged out successfully }, (err) => { // failed to logout } ); ``` #### Calling an API Once you have logged-in user, you can start making authenticated requests to backend APIs as described below. #### Token-based authentication There are two ways to include the access token in the HTTP requests to your application server. #### Option 1: Using fetch function provided by Authgear SDK Authgear SDK provides the `fetch` function for you to call your application server. This `fetch` function will include the Authorization header in your application request, and handle refresh access token automatically. The `authgearClient.fetch` implements [fetch](https://fetch.spec.whatwg.org/). ```javascript authgearClient .fetch("YOUR_SERVER_URL") .then(response => response.json()) .then(data => console.log(data)); ``` #### Option 2: Add the access token to the HTTP request header You can get the access token through `authgearClient.accessToken`. Call `refreshAccessTokenIfNeeded` every time before using the access token, the function will check and make the network call to refresh the access token only if it is expired. Include the access token in the Authorization header of the application request. ```javascript authgearClient .refreshAccessTokenIfNeeded() .then(() => { // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid const accessToken = authgearClient.accessToken; // include Authorization header in your application request const headers = { Authorization: `Bearer ${accessToken}` }; }); ``` ## Next steps To protect your application server from unauthorized access. You will need to [integrate Authgear to your backend](/get-started/backend-api). {% content-ref url="/pages/xp8Yw44yzS7vmIMf3OOh" %} [Backend/API Integration](/get-started/backend-api) {% endcontent-ref %} ## JavaScript SDK Reference For detailed documentation on the JavaScript Web SDK, visit [@authgear/web Reference](https://authgear.github.io/authgear-sdk-js/docs/web/) # React Follow this quickstart tutorial to add authentication to your React application Authgear helps you add user logins to your React apps. It provides a pre-built login page and user settings page that can accelerate your development process. Follow this :clock1: **15-minute** tutorial to create a simple app using React with the Authgear SDK. {% hint style="info" %} **Check out and clone** [**the Sample Project on GitHub**](https://github.com/authgear/authgear-example-react)**.** {% endhint %} ## Setup Application in Authgear To use Authgear's features, you'll need an account and a Project. Sign up for a free account at and create a new Project to get started. After that, we will need to create an Application in the Project Portal. ### Create an application in the Portal To create a client application, go to **Applications** on the left menu bar in the Authgear Portal.

portal navigate to applications

Next, click **⊕Add Application** in the top toolbar. Enter the name of your application, e.g. "MyAwesomeApp", then select **Single Page Application** as the Application Type. Click the **Save** button to create the application. ### Configure Authorize Redirect URI The **Authorized Redirect URI** is a URL in you application where the user will be redirected to after login with Authgear. In this path, make a **finish authentication** call to complete the login process. Go to the URI section of the Authgear client application you just created and add a new **Authorized Redirect URI**. For this tutorial, add `http://localhost:4000/auth-redirect` to Authorize Redirect URIs. Click **Save** to keep all client app configuration changes before proceeding to the next steps.

Configure Authorized Redirect URIs

## Add Authgear to React App In this section, we'll create a simple React application and connect it to Authgear such that, users of the app will log in, view their user settings, and log out of their account. ### Step 1: Create a simple React project Here are some recommended steps to scaffold a React project. You can skip this part if you are adding Authgear to an existing project. See [#step-2-install-authgear-sdk-to-the-project](#step-2-install-authgear-sdk-to-the-project "mention") in the next section. #### Create a new React project using Vite Run the following command from your preferred folder to create a new React project with Vite: ```bash npm create vite@latest my-app -- --template react-ts ``` Next, run the following commands to open the new project directory and install the dependencies: ```sh cd my-app npm install ``` #### Change port In the `package.json` file, update the value of `dev` field in the `script.dev` section to: ``` "dev": "vite --port 4000", ``` This will enable the `npm run dev` command run the app in development mode on port 4000. The file structure in your project should look like this now: ```bash my-app ├── node_modules │ └── (...) ├── package-lock.json ├── package.json ├── index.html └── src ├── App.tsx └── main.tsx ``` Run `npm run dev` now to run the project and you will see the default "Vite + React" page when you open `http://localhost:4000` on a web browser. ### Step 2: Install Authgear SDK to the project Run the following command within your React project directory to install the Authgear Web SDK ```bash npm install --save --save-exact @authgear/web ``` In `src/main.tsx` , import `authgear` and call the `configure` function to initialize an Authgear instance on application loads. ```tsx import { createRoot } from 'react-dom/client' import App from './App.tsx' import authgear from "@authgear/web" async function init() { try { // configure Authgear container instance await authgear.configure({ endpoint: import.meta.env.VITE_AUTHGEAR_ENDPOINT, clientID: import.meta.env.VITE_AUTHGEAR_CLIENT_ID, sessionType: "refresh_token", }); } finally { createRoot(document.getElementById("root")!).render(); } } init().catch((e) => { // Error handling console.error(e) }); ``` The Authgear container instance takes `endpoint` and `clientID` as parameters. They can be obtained from the configuration page for the application created in [#setup-application-in-authgear](#setup-application-in-authgear "mention"). Create a `.env` file in the root directory of your project and add your Authgear client application configuration using the following fields: ```properties VITE_AUTHGEAR_CLIENT_ID= VITE_AUTHGEAR_ENDPOINT= VITE_AUTHGEAR_REDIRECT_URL=http://localhost:4000/auth-redirect ``` It is recommended to render the app after `configure()` resolves. So by the time the app is rendered, Authgear is ready to use. {% hint style="info" %} Run **`npm run dev`** now and you should see the default page again and no error message in the console if Authgear SDK is configured successfully {% endhint %} ### Step 3: Implement the Context Provider Since we want to reference the logged-in state everywhere in the app, let's put the state in a **context provider** with `UserProvider.tsx` in the `/src/context` folder. The `UserProvider.tsx` file will have an `isLoggedIn` boolean and a `setIsLoggedIn` function. The `isLoggedIn` boolean state can be auto-updated using the `onSessionStateChange` callback. This callback can be stored in `delegate` which is in the local SDK container. ```tsx // src/context/UserProvider.tsx import React, { createContext, useEffect, useState, useMemo } from "react"; import authgear from "@authgear/web"; interface UserContextValue { isLoggedIn: boolean; } export const UserContext = createContext({ isLoggedIn: false, }); interface UserContextProviderProps { children: React.ReactNode; } const UserContextProvider: React.FC = ({ children, }) => { // By default the user is not logged in const [isLoggedIn, setIsLoggedIn] = useState(false); useEffect(() => { // When the sessionState changed, logged in state will also be changed authgear.delegate = { onSessionStateChange: (container) => { // sessionState is now up to date // Value of sessionState can be "NO_SESSION" or "AUTHENTICATED" const sessionState = container.sessionState; if (sessionState === "AUTHENTICATED") { setIsLoggedIn(true); } else { setIsLoggedIn(false); } }, }; }, [setIsLoggedIn]); const contextValue = useMemo(() => { return { isLoggedIn, }; }, [isLoggedIn]); return ( {children} ); }; export default UserContextProvider; ``` ### Step 4: Implement the Auth Redirect Next, we will add an "AuthRedirect" page for handling the authentication result after the user has been authenticated by Authgear. First, install `react-router-dom` using the following command: ```sh npm install --save-exact react-router-dom ``` Create the `AuthRedirect.tsx` component file in the `src/` folder. Call the Authgear `finishAuthentication()` function in the Auth Redirect component to send a token back to Authgear server in exchange for an access token and a refresh token. Don't worry about the technical jargons, `finishAuthentication()` will do all the hard work for you and save the authentication data. When the authentication is finished, the `isLoggedIn` state from the UserContextProvider will be automatically set to `true`. Finally, navigate back to root (`/`) which is our Home page. The final `AuthRedirect.tsx` will look like this ```tsx // src/AuthRedirect.tsx import React, { useEffect, useRef } from "react"; import { useNavigate } from "react-router-dom"; import authgear from "@authgear/web"; const AuthRedirect: React.FC = () => { const usedToken = useRef(false); const navigate = useNavigate(); useEffect(() => { async function updateToken() { try { await authgear.finishAuthentication(); } finally { navigate("/"); usedToken.current = true; } } if (!usedToken.current) { updateToken().catch((e) => console.error(e)); } }, [navigate]); return <>; }; export default AuthRedirect; ``` {% hint style="info" %} Since in React 18 and later, useEffect will be fired twice in development mode, we need to implement a [cleanup function](https://beta.reactjs.org/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development) to stop it from firing twice. We will use an `useRef` Hook to stop the user token from being sent twice to the Authgear Endpoint. Without a cleanup function, an`useEffect`Hook will be fired twice and hence `finishAuthentication()` will send the token back to Authgear Endpoint for two times, which the second one will result in "Invalid Token" error since the token can only be used once. {% endhint %} ### Step 5: Add Routes and Context Provider to the App Now, we will add a "Home" page. Create a `Home.tsx` component file the `src/` folder. Then import **Home** and **AuthRedirect** as routes. And Import **UserContextProvider** and wrap the routes with it. Your final `App.tsx` should look like this: 
// src/App.tsx
import React from "react";
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Home from './Home';
import AuthRedirect from './AuthRedirect';
import UserContextProvider from './context/UserProvider';

const App: React.FC = () => {
  return (
    <UserContextProvider>
      <Router>
        <Routes>
          <Route path="/auth-redirect" element={<AuthRedirect />} />
          <Route path="/" element={<Home />} />
        </Routes>
      </Router>
    </UserContextProvider>
  );
}

export default App;
The file structure should now look like ``` src ├── App.tsx ├── AuthRedirect.tsx ├── Home.tsx ├── context │ └── UserProvider.tsx └── main.tsx ``` ### Step 6: Add a Login button First, we will import the Authgear dependency and the React Hook that we will use to `Home.tsx`. Then add the login button which will call `startAuthentication(ConfigureOptions)` through the `startLogin` on click callback. This will redirect the user to the login page. ```tsx // src/Home.tsx import React, { useEffect, useState, useCallback, useContext } from 'react'; import authgear, { PromptOption } from '@authgear/web'; const Home: React.FC = () => { const startLogin = useCallback(() => { authgear .startAuthentication({ redirectURI: import.meta.env.VITE_AUTHGEAR_REDIRECT_URL, prompt: PromptOption.Login, }) .then( () => { // started authentication, user should be redirected to Authgear }, err => { // failed to start authentication } ); }, []); return (

Home Page

); } export default Home; ``` You can now run **`npm run dev`** and you will be redirected to the Authgear Login page when you click the Login button. ![User will be redirected to the Authgear login page by clicking the login button](/files/Cs8I3NeFH4JSuG82EhKc) ### Step 7: Show the user information The Authgear SDK helps you get the information of the logged-in users easily. In the last step, the user is successfully logged in, so let's try to print the user ID (sub) of the user on the Home page. In `Home.tsx`, we will add a simple loading splash and a greeting message printing the Sub ID. We will add two conditional elements such that they are only shown when user is logged in. We can also change the login button to show only if the user is not logged in. Make use of `isLoggedIn` from the `UserContext` to control the components on the page. Fetch the user info by `fetchUserInfo()` and access its `sub` property. ```tsx // src/Home.tsx import React, { useEffect, useState, useCallback, useContext } from "react"; import authgear, { PromptOption } from "@authgear/web"; import { UserContext } from "./context/UserProvider"; const Home: React.FC = () => { const [greetingMessage, setGreetingMessage] = useState(""); const [isLoading, setIsLoading] = useState(false); const { isLoggedIn } = useContext(UserContext); useEffect(() => { async function updateGreetingMessage() { setIsLoading(true); try { if (isLoggedIn) { const userInfo = await authgear.fetchUserInfo(); setGreetingMessage("The current User sub: " + userInfo.sub); } } finally { setIsLoading(false); } } updateGreetingMessage().catch((e) => { console.error(e); }); }, [isLoggedIn]); const startLogin = useCallback(() => { authgear .startAuthentication({ redirectURI: "http://localhost:4000/auth-redirect", prompt: PromptOption.Login, }) .then( () => { // started authentication, user should be redirected to Authgear }, (err) => { // failed to start authentication } ); }, []); return (

Home Page

{isLoading && "Loading"} {greetingMessage ? {greetingMessage} : null} {!isLoggedIn && (
)}
); }; export default Home; ``` Run the app again, the User ID (sub) of the user should be printed on the Home page. ### Step 8: Add a Logout button Now, let's add a Logout button that is displayed when the user is logged in. In `Home.tsx`, we will use conditional elements to show a Logout button only for a user that is currently logged in. Find the following line in Home.tsx: ```tsx {!isLoggedIn && (
)} ``` Add the following code on a new line just after the above line: ```tsx {isLoggedIn && (
)} ``` Then, add the `logout` callback: ```tsx const logout = useCallback(() => { authgear .logout({ redirectURI: "http://localhost:4000/", }) .then( () => { setGreetingMessage(''); }, (err) => { console.error(err); } ); }, []); ``` Run the app again, we can now log out by clicking the Logout button. ### Step 9: Open User Settings Authgear provides a built-in UI for the users to set their attributes and change security settings. Use the `openURL` function to open the settings page at `/settings` In `Home.tsx` Add a conditional link to the existing elements. ```tsx {isLoggedIn && ( User Setting )} ``` And add the `userSetting` callback: ```tsx import authgear, { Page } from "@authgear/web"; const userSetting = useCallback((e: React.MouseEvent) => { e.preventDefault(); e.stopPropagation(); authgear.open(Page.Settings); }, []); ``` This is the resulting `Home.tsx`: ```tsx // src/Home.tsx import React, { useEffect, useState, useCallback, useContext } from "react"; import { UserContext } from "./context/UserProvider"; import authgear, { Page, PromptOption } from "@authgear/web"; const Home: React.FC = () => { const [greetingMessage, setGreetingMessage] = useState(""); const [isLoading, setIsLoading] = useState(false); const { isLoggedIn } = useContext(UserContext); useEffect(() => { async function updateGreetingMessage() { setIsLoading(true); try { if (isLoggedIn) { const userInfo = await authgear.fetchUserInfo(); setGreetingMessage("The current User sub: " + userInfo.sub); } } finally { setIsLoading(false); } } updateGreetingMessage().catch((e) => { console.error(e); }); }, [isLoggedIn]); const startLogin = useCallback(() => { authgear .startAuthentication({ redirectURI: "http://localhost:4000/auth-redirect", prompt: PromptOption.Login, }) .then( () => { // started authorization, user should be redirected to Authgear }, (err) => { // failed to start authorization console.error(err); } ); }, []); const logout = useCallback(() => { authgear .logout({ redirectURI: "http://localhost:4000/", }) .then( () => { setGreetingMessage(""); }, (err) => { console.error(err); } ); }, []); const userSetting = useCallback((e: React.MouseEvent) => { e.preventDefault(); e.stopPropagation(); authgear.open(Page.Settings); }, []); return (
{/* eslint-disable-next-line react/forbid-elements */}

Home Page

{isLoading && "Loading"} {greetingMessage ? {greetingMessage} : null} {!isLoggedIn && (
)} {isLoggedIn && ( )}
); }; export default Home; ``` ![Show the User ID, a link to User Settings and a logout button after login](/files/aXaPt110PmOPwURwSVtL) ## Next steps, Calling an API To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers. The Web SDK provides a `fetch` function which automatically handles this, or you can get the token with `authgear.accessToken`. #### Option 1: Using fetch function provided by Authgear SDK Authgear SDK provides the `fetch` function for you to call your application server. This `fetch` function will include the Authorization header in your application request, and handle the process of refreshing an access token automatically. The `authgear.fetch` implements [fetch](https://fetch.spec.whatwg.org/). ```javascript authgear .fetch("YOUR_SERVER_URL") .then(response => response.json()) .then(data => console.log(data)); ``` #### Option 2: Add the access token to the HTTP request header You can get the access token through `authgear.accessToken`. Call `refreshAccessTokenIfNeeded` every time before using the access token, the function will check and make the network call to refresh the access token only if it is expired. Include the access token into the Authorization header of the application requests. ```javascript authgear .refreshAccessTokenIfNeeded() .then(() => { // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid const accessToken = authgear.accessToken; // include Authorization header in your application request const headers = { Authorization: `Bearer ${accessToken}` }; }); ``` # Angular Follow this quickstart tutorial to add authentication to your Angular application Authgear helps you add user logins to your Angular apps. It provides prebuilt login page and user settings page that accelerate the development. Follow this :clock1: **15 minutes** tutorial to create a simple app using Angular with Authgear SDK. {% hint style="info" %} **Check out and clone** [**the Sample Project on GitHub**](https://github.com/authgear/authgear-example-angular)**.** {% endhint %} {% hint style="info" %} This tutorial targets **Angular 17 and above**, which use [standalone components](https://angular.dev/guide/components) and bootstrap the app without `NgModule`. The sample project is built with Angular 22 (standalone, zoneless change detection). If you are on an older Angular version that still uses `NgModule`, adapt the steps accordingly. {% endhint %} **Table of Content** * [Setup Application in Authgear](#setup-application-in-authgear) * [Create a simple Angular project](#step-1-create-a-simple-angular-project) * [Install Authgear SDK to the project](#step-2-install-authgear-sdk-to-the-project) * [Implement User Service](#step-3-implement-the-user-service) * [Implement the Auth Redirect page](#step-4-implement-the-auth-redirect) * [Add a Login button](#step-6-add-a-login-button) * [Show the user information](#step-7-show-the-user-information) * [Add a Logout button](#step-8-add-an-logout-button) * [Open User Settings](#step-9-open-user-settings) * [Calling an API](#next-steps-calling-an-api) ## Setup Application in Authgear Signup for an account in and create a Project. After that, we will need to create an Application in the Project Portal. ### Create an application 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 of your application, e.g. "MyAwesomeApp". 4. Select **Single Page Application** as the application type 5. Click "Save" to create the application ### Configure Authorize Redirect URI The Redirect URI is a URL in you application where the user will be redirected to after login with Authgear. In this path, make a **finish authentication** call to complete the login process. For this tutorial, add `http://localhost:4000/auth-redirect` to Authorize Redirect URIs. ### Configure Post Logout Redirect URI The Post Logout Redirect URI is the URL users will be redirected after they have logged out. The URL must be whitelisted. For this tutorial, add `http://localhost:4000/` to Post Logout Redirect URIs. **Save** the configuration before next steps. ![Configure Authorized Redirect URIs and Post Logout Redirect URIs.](/files/7iBL9afm3ZAuNTLSmCc8) ## Step 1: Create a simple Angular project Here are some recommended steps to scaffold an Angular project. You can skip this part if you are adding Authgear to an existing project. See [#step-2-install-authgear-sdk-to-the-project](#step-2-install-authgear-sdk-to-the-project "mention") in the next section. #### Install the Angular CLI To install the Angular CLI, open a terminal window and run the following command: ```bash npm install -g @angular/cli ``` {% hint style="info" %} For Windows clients, please find your reference in for more information on installing the Angular CLI. {% endhint %} #### Create initial workspace Run the following cli command to create a new workspace and initial app called `my-app` with routing enabled. ```bash # Create a workspace called my-app ng new my-app --routing --defaults # Move into the project directory cd my-app ``` On Angular 17+, this scaffolds a standalone application. The important generated files are: * `src/main.ts` — bootstraps the app with `bootstrapApplication(AppComponent, appConfig)` * `src/app/app.config.ts` — the application providers (this is where we will configure Authgear and the router) * `src/app/app.routes.ts` — the route definitions {% hint style="info" %} Newer versions of the Angular CLI generate component and service files **without** the `.component` / `.service` suffix (for example `app.ts` and class `App` instead of `app.component.ts` and class `AppComponent`). This tutorial and the sample project use the suffixed names. The code is identical either way — just match the file names and class names your CLI generated. {% endhint %} #### Edit script for launching the app In the `package.json` file, edit the `start` script in the `script` section ```bash # before "start": "ng serve" # after "start": "ng serve --port 4000" ``` The `start` script run the app in development mode on port 4000 instead of the default one. #### Edit the `app.component.html` file By default, the Angular CLI generated an initial application for us, but for simplicity, we recommend to modify some of these files to scratch. In the `src/app/app.component.html` file, remove all the lines and add the following line: ```html
Hello world
``` #### Run your initial app Run `npm start` now to run the project and you will see "Hello world" on `http://localhost:4000`. ## Step 2: Install Authgear SDK to the project Run the following command within your Angular project directory to install the Authgear Web SDK ```bash npm install --save-exact @authgear/web ``` Authgear must be configured **before** any other SDK call (for example `finishAuthentication()` or `fetchUserInfo()`), and configuration is asynchronous. The cleanest way to guarantee this in Angular is to run `authgear.configure()` during app initialization, so the app only renders after Authgear is ready. In `src/app/app.config.ts`, register an app initializer that calls `configure`: ```typescript // src/app/app.config.ts import { ApplicationConfig, provideAppInitializer, provideBrowserGlobalErrorListeners, } from '@angular/core'; import { provideRouter } from '@angular/router'; import authgear from '@authgear/web'; import { routes } from './app.routes'; export const appConfig: ApplicationConfig = { providers: [ provideBrowserGlobalErrorListeners(), provideRouter(routes), // Configure Authgear before the app renders. configure() must complete // before any other SDK call, so blocking bootstrap here avoids a race in // which the redirect page or home page runs before the SDK is ready. provideAppInitializer(async () => { try { await authgear.configure({ endpoint: '', clientID: '', sessionType: 'refresh_token', }); } catch (e) { // Don't block bootstrap if Authgear is unreachable; the app will // render in the logged-out state and login can be retried. console.error(e); } }), ], }; ``` The Authgear container instance takes `endpoint` and `clientID` as parameters. They can be obtained from the application page created in [#setup-application-in-authgear](#setup-application-in-authgear "mention"). Because the initializer is awaited, by the time any route renders Authgear is ready to use. {% hint style="info" %} Run **`npm start`** now and you should see a page with "Hello World" and no error message in the console if Authgear SDK is configured successfully {% endhint %} ## Step 3: Implement the User Service Since we want to reference the logged in state in anywhere of the app, let's put the state in a **service** with `user.service.ts` in the `/src/app/services/` folder. In `user.service.ts`, it will have an `isLoggedIn` state. The state is auto updated using the `onSessionStateChange` callback, which is stored in the `delegate` of the local SDK container. We expose the state as an Angular [signal](https://angular.dev/guide/signals) so the UI updates reactively (this also works with zoneless change detection, the default on newer Angular versions). ```typescript // src/app/services/user.service.ts import { Injectable, signal } from '@angular/core'; import authgear from '@authgear/web'; @Injectable({ providedIn: 'root', }) export class UserService { // By default the user is not logged in readonly isLoggedIn = signal(false); constructor() { // When the sessionState changed, logged in state will also be changed authgear.delegate = { onSessionStateChange: (container) => { // sessionState is now up to date // value of sessionState can be "NO_SESSION" or "AUTHENTICATED" const sessionState = container.sessionState; this.isLoggedIn.set(sessionState === 'AUTHENTICATED'); }, }; } } ``` The `onSessionStateChange` delegate fires while `configure()` runs, so the `UserService` must be instantiated **before** `configure()` — otherwise it would miss the initial state of an already-authenticated user. Update the app initializer in `src/app/app.config.ts` to inject the service first: ```typescript // src/app/app.config.ts import { inject, provideAppInitializer } from '@angular/core'; import authgear from '@authgear/web'; import { UserService } from './services/user.service'; // ... provideAppInitializer(async () => { // Instantiate UserService first so its onSessionStateChange delegate is // registered before configure() runs and can observe the initial state. inject(UserService); try { await authgear.configure({ endpoint: '', clientID: '', sessionType: 'refresh_token', }); } catch (e) { console.error(e); } }), ``` ## Step 4: Implement the Auth Redirect Next, we will add an "auth-redirect" page for handling the authentication result after the user have been authenticated by Authgear. Create the `auth-redirect` component using the following command: ```bash ng generate component auth-redirect ``` We will inject the router to navigate after the redirect is handled. Call the Authgear `finishAuthentication()` function in the Auth Redirect component to send a token back to Authgear server in exchange for access token and refresh token. Don't worry about the technical jargons, `finishAuthentication()` will do all the hard work for you and and save the authentication data. When the authentication is finished, the `isLoggedIn` state from the UserService will automatic set to `true`. Finally, navigate back to root (`/`) which is our Home page. The final `auth-redirect.component.ts` will look like this ```typescript // src/app/auth-redirect/auth-redirect.component.ts import { Component, OnInit, inject } from '@angular/core'; import { Router } from '@angular/router'; import authgear from '@authgear/web'; @Component({ selector: 'app-auth-redirect', templateUrl: './auth-redirect.component.html', styleUrl: './auth-redirect.component.css', }) export class AuthRedirectComponent implements OnInit { private readonly router = inject(Router); ngOnInit(): void { authgear .finishAuthentication() .catch((e) => console.error(e)) .then(() => { this.router.navigate(['']); }); } } ``` ## Step 5: Add Routes to the App Next, we will add a "Home" page . Create a `home` component using the following command: ```bash ng generate component home ``` Then import **HomeComponent** and **AuthRedirectComponent** as routes. We can add those routes in the `app.routes.ts` file that was generated with the workspace: ```typescript // src/app/app.routes.ts import { Routes } from '@angular/router'; import { HomeComponent } from './home/home.component'; import { AuthRedirectComponent } from './auth-redirect/auth-redirect.component'; export const routes: Routes = [ { path: '', component: HomeComponent }, { path: 'auth-redirect', component: AuthRedirectComponent }, ]; ``` The router is already provided in `app.config.ts` via `provideRouter(routes)` (added in Step 2). Make sure the root component renders the routed component by importing `RouterOutlet` and using it in the template. ```typescript // src/app/app.component.ts import { Component } from '@angular/core'; import { RouterOutlet } from '@angular/router'; @Component({ selector: 'app-root', imports: [RouterOutlet], templateUrl: './app.component.html', styleUrl: './app.component.css', }) export class AppComponent {} ``` Replace the lines in `src/app/app.component.html` with the following: ```html ``` The file structure should now look like ``` src ├── (...) ├── main.ts └── app ├── app.config.ts ├── app.routes.ts ├── app.component.ts ├── app.component.html ├── (...) ├── auth-redirect │ ├── auth-redirect.component.ts │ ├── auth-redirect.component.html │ └── (...) ├── home │ ├── home.component.ts │ ├── home.component.html │ └── (...) └── services └── user.service.ts ``` ## Step 6: Add a Login button First we will import the Authgear dependency and inject the UserService in `home.component.ts`. Then add the `startLogin` method which will call `startAuthentication(options)`. This will redirect the user to the login page. ```typescript // src/app/home/home.component.ts import { Component, inject } from '@angular/core'; import { UserService } from '../services/user.service'; import authgear, { PromptOption } from '@authgear/web'; @Component({ selector: 'app-home', templateUrl: './home.component.html', styleUrl: './home.component.css', }) export class HomeComponent { readonly user = inject(UserService); startLogin(): void { authgear .startAuthentication({ redirectURI: 'http://localhost:4000/auth-redirect', prompt: PromptOption.Login, }) .then( () => { // started authorization, user should be redirected to Authgear }, (err) => { // failed to start authorization console.error(err); } ); } } ``` {% hint style="info" %} `prompt` takes a `PromptOption` enum value (for example `PromptOption.Login`) in `@authgear/web` v5 and above. Importing and using the enum keeps the call type-safe. {% endhint %} Then you can add a button which will trigger the `startLogin` method in `home.component.html`: ```html

Home Page

``` You can now run **`npm start`** and you will be redirected to the Authgear Login page when you click the Login button. ![User will be redirected to the Authgear login page by clicking the login button](/files/NEfVntNC3LKqmRFZGSga) ## Step 7: Show the user information The Authgear SDK helps you get the information of the logged in users easily. In the last step, the user is successfully logged in so let's try to print the user ID (sub) of the user in the Home page. In `home` component, we will add a simple Loading splash and a greeting message printing the Sub ID. We will add two conditional elements such that they are only shown when user is logged in. We can also change the login button to show only if the user is not logged in. Make use of `isLoggedIn` from the `UserService` to control the components on the page. Fetch the user info by `fetchUserInfo()` and access its `sub` property. We store the loading and greeting state as signals so the template stays reactive. ```typescript // src/app/home/home.component.ts import { Component, OnInit, inject, signal } from '@angular/core'; import { UserService } from '../services/user.service'; import authgear, { PromptOption } from '@authgear/web'; @Component({ selector: 'app-home', templateUrl: './home.component.html', styleUrl: './home.component.css', }) export class HomeComponent implements OnInit { readonly user = inject(UserService); readonly isLoading = signal(false); readonly greetingMessage = signal(''); async updateGreetingMessage() { this.isLoading.set(true); try { if (this.user.isLoggedIn()) { const userInfo = await authgear.fetchUserInfo(); this.greetingMessage.set('The current User sub: ' + userInfo.sub); } } finally { this.isLoading.set(false); } } ngOnInit(): void { this.updateGreetingMessage().catch((e) => { console.error(e); }); } startLogin(): void { authgear .startAuthentication({ redirectURI: 'http://localhost:4000/auth-redirect', prompt: PromptOption.Login, }) .then( () => { // started authorization, user should be redirected to Authgear }, (err) => { // failed to start authorization console.error(err); } ); } } ``` In the `home.component.html`, use the new `@if` control flow and read each signal by calling it: ```html

Home Page

@if (isLoading()) { Loading } @if (greetingMessage()) { {{ greetingMessage() }} } @if (!user.isLoggedIn()) {
} ``` Run the app again, the User ID (sub) of the user should be printed on the Home page. ## Step 8: Add a Logout button Finally, let's add an Logout button when user is logged in. In `home.component.html`, we will add a conditional element in the markup: ```html @if (user.isLoggedIn()) {
} ``` And add the `logout` method: ```typescript logout(): void { authgear .logout({ redirectURI: 'http://localhost:4000/', }) .then( () => { this.greetingMessage.set(''); }, (err) => { console.error(err); } ); } ``` Run the app again, we can now logout by clicking the logout button. ## Step 9: Open User Settings Authgear provide a built-in UI for the users to set their attributes and change security settings. Use the `open` function to open the setting page at `/settings` In `home.component.html` append a conditional link to the logout button section. ```html @if (user.isLoggedIn()) { } ``` And add the `userSetting` method (note the added `Page` import): ```typescript import authgear, { Page, PromptOption } from '@authgear/web'; async userSetting(event: MouseEvent) { event.preventDefault(); event.stopPropagation(); await authgear.open(Page.Settings); } ``` This the resulting `home.component.ts`: ```typescript // src/app/home/home.component.ts import { Component, OnInit, inject, signal } from '@angular/core'; import { UserService } from '../services/user.service'; import authgear, { Page, PromptOption } from '@authgear/web'; @Component({ selector: 'app-home', templateUrl: './home.component.html', styleUrl: './home.component.css', }) export class HomeComponent implements OnInit { readonly user = inject(UserService); readonly isLoading = signal(false); readonly greetingMessage = signal(''); async updateGreetingMessage() { this.isLoading.set(true); try { if (this.user.isLoggedIn()) { const userInfo = await authgear.fetchUserInfo(); this.greetingMessage.set('The current User sub: ' + userInfo.sub); } } finally { this.isLoading.set(false); } } ngOnInit(): void { this.updateGreetingMessage().catch((e) => { console.error(e); }); } startLogin(): void { authgear .startAuthentication({ redirectURI: 'http://localhost:4000/auth-redirect', prompt: PromptOption.Login, }) .then( () => { // started authorization, user should be redirected to Authgear }, (err) => { // failed to start authorization console.error(err); } ); } logout(): void { authgear .logout({ redirectURI: 'http://localhost:4000/', }) .then( () => { this.greetingMessage.set(''); }, (err) => { console.error(err); } ); } async userSetting(event: MouseEvent) { event.preventDefault(); event.stopPropagation(); await authgear.open(Page.Settings); } } ``` This is the resulting home.component.html: ```html

Home Page

@if (isLoading()) { Loading } @if (greetingMessage()) { {{ greetingMessage() }} } @if (!user.isLoggedIn()) {
} @if (user.isLoggedIn()) { } ``` ![Show the User ID, a link to User Settings and a logout button after login](/files/aXaPt110PmOPwURwSVtL) ## Next steps, Calling an API To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers. The Web SDK provides a `fetch` function which automatically handle this, or you can get the token with `authgear.accessToken`. #### Option 1: Using fetch function provided by Authgear SDK Authgear SDK provides the `fetch` function for you to call your application server. This `fetch` function will include the Authorization header in your application request, and handle refresh access token automatically. The `authgear.fetch` implements [fetch](https://fetch.spec.whatwg.org/). ```javascript authgear .fetch("YOUR_SERVER_URL") .then(response => response.json()) .then(data => console.log(data)); ``` #### Option 2: Add the access token to the HTTP request header You can get the access token through `authgear.accessToken`. Call `refreshAccessTokenIfNeeded` every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token into the Authorization header of the application request. ```javascript authgear .refreshAccessTokenIfNeeded() .then(() => { // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid const accessToken = authgear.accessToken; // include Authorization header in your application request const headers = { Authorization: `Bearer ${accessToken}` }; }); ``` # Vue Follow this quickstart tutorial to add authentication to your Vue application Authgear helps you add user logins to your Vue apps. It provides a prebuilt login page and user settings page that accelerate the development. Follow this :clock1: **15-minute** tutorial to create a simple app using Vue with Authgear SDK. {% hint style="info" %} **Check out and clone** [**the Sample Project on GitHub**](https://github.com/authgear/authgear-example-vue)**.** {% endhint %} ## Setup Application in Authgear You need an Authgear account and a project to use Authgear. Sign up for a free account at and create a Project. After that, we will need to create an Application in the Project Portal. ### Create an application in the Portal In this step, we'll create an Authgear client application in the Authgear Portal. We'll use the configuration for this application in later steps to connect our Vue application to Authgear. To create a client application navigate to **Applications** on the left menu bar in Authgear Portal.

portal navigate to applications

Next, click **⊕Add Application** in the top toolbar to open the **New Application** page. Input the name of your application, e.g. "MyAwesomeApp" then select **Single Page Application** as the Application Type. Click **Save** to create the application.

create new client application

On the next screen, you'll see links to tutorials for different frameworks. Click **Next** to skip to the application configuration page ### Configure Authorize Redirect URI The Redirect URI is a URL in your application where the user will be redirected to after login with Authgear. In this path, make a **finish authentication** call to complete the login process. Scroll to the URI section of the configuration page for the client application you created in the last step. For this tutorial, add `http://localhost:4000/auth-redirect` to Authorize Redirect URIs. Click the **Save** button to save your changes before you proceed.

Configure Authorized Redirect URIs

## Add Authgear to Vue App In this section, we'll add Authgear to a Vue application and use the Authgear JavaScript SDK to implement the following features: * User Login/Sign-up * Read logged-in user's info * Open User Settings page * End user session using a Logout button ### Step 1: Create a simple Vue project Here are some recommended steps to scaffold a Vue project. You can skip this part if you are adding Authgear to an existing project. See [#step-3-install-authgear-sdk-to-the-project](#step-3-install-authgear-sdk-to-the-project "mention") in the next section. #### Install basic project dependencies Create the project folder and install the dependencies. We will use [Vite](https://vite.dev/guide/cli.html) as the build tool and the `vue-router` package. Also, we will use TypeScript in this tutorial. Run the following commands to create a new project: Create project and move into the project directory: ```sh npm create vite@latest my-app -- --template vue-ts cd my-app ``` Install dependencies: ```bash npm install ``` Install Vue router: ``` npm install --save-exact vue-router ``` #### Add port configuration for development mode As we are using port 4000 for this tutorial, we need to add the port information to the config. In the `vite.config.ts` file, modify the file with the following lines: ```typescript // vite.config.ts import { defineConfig } from "vite"; import vue from "@vitejs/plugin-vue"; // https://vitejs.dev/config/ export default defineConfig({ plugins: [vue()], server: { port: 4000, }, }); ``` After doing so, when you run `npm run dev` , the server will be running on port 4000. #### Create the `Home.vue` file Create a new file called `Home.vue` in the `src/components` folder with simply showing `Hello World` on the screen. Add the follow code to `Home.vue`: ```tsx // src/components/Home.vue ``` #### Edit the `App.vue` file The `App.vue` file is generated by `Vite` already but some sections of it might not be needed for this tutorial. Edit the content of `App.vue` to the following: ```tsx // src/components/App.vue ``` #### Delete unnecessary files Some of the files might not be used and thus can be deleted. You can perform the following script to delete these files: ```bash rm -rf src/assets src/components/HelloWorld.vue ``` #### File structure The file structure in your project is now: ```bash my-app ├── node_modules │ └── (...) ├── package-lock.json ├── package.json ├── vite.config.ts ├── (...) └── src ├── components │ └── Home.vue ├── App.vue ├── main.ts └── (...) ``` Run `npm run dev` now to run the project and you will see the default page with the title `Vite + Vue` and a "Hello World" message on `http://localhost:4000`. ### Step 2: Create routes for the project Create a `AuthRedirect.vue` file in the `src/components` folder with the same content as `src/components/Home.vue` at this moment. Create a file called `router.ts` in the `src/` folder. We will import `Home` and `AuthRedirect` component as the route and we will implement these components later. The content of this file will look like this: ```typescript // src/router.ts import { createRouter, createWebHistory } from "vue-router"; export const history = createWebHistory(); export const router = createRouter({ history, routes: [ { path: "/", // We will implement this component later component: () => import("./components/Home.vue"), }, { path: "/auth-redirect", // We will implement this component later component: () => import("./components/AuthRedirect.vue"), }, ], }); ``` ### Step 3: Install Authgear SDK to the project Run the following command within your Vue project directory to install the Authgear Web SDK ```bash npm install --save-exact @authgear/web ``` In `src/main.ts` , import `authgear` and call the `configure` function to initialize an Authgear instance on application loads. We will also import `router` and use it to build routes for us. Your `main.ts` file should look like this: ```typescript // src/main.ts import { createApp } from "vue"; import './style.css' import App from "./App.vue"; import { router } from "./router"; import authgear from "@authgear/web"; const app = createApp(App); async function init() { try { // configure Authgear container instance await authgear.configure({ endpoint: import.meta.env.VITE_AUTHGEAR_ENDPOINT, clientID: import.meta.env.VITE_AUTHGEAR_CLIENT_ID, sessionType: "refresh_token", }); } finally { app.use(router); app.mount("#app"); } } init().catch((e) => { // Error handling console.error(e) }); ``` The Authgear container instance takes `endpoint` and `clientID` as parameters. They can be obtained from the application page created in [#setup-application-in-authgear](#setup-application-in-authgear "mention"). Create a `.env` file in the root directory of your project and add your Authgear client application configuration using the following fields: ```properties VITE_AUTHGEAR_CLIENT_ID= VITE_AUTHGEAR_ENDPOINT= VITE_AUTHGEAR_REDIRECT_URL=http://localhost:4000/auth-redirect ``` It is recommended to render the app after `configure()` resolves. So by the time the app is rendered, Authgear is ready to use. {% hint style="info" %} Run **`npm run dev`** now and you should see the same page and no error message in the console if Authgear SDK is configured successfully {% endhint %} ### Step 4: Implement the Context Provider Since we want to reference the logged-in state everywhere in the app, let's put the state in a **context provider** with `UserProvider.vue` in the `/src/contexts` folder. In `UserProvider.vue`, will have a `isLoggedIn` boolean value. The `isLoggedIn` boolean state can be auto-updated using the `onSessionStateChange` callback. This callback can be stored in `delegate` which is in the local SDK container. ```tsx // src/contexts/UserProvider.vue ``` ### Step 5: Implement the Auth Redirect Next, we will add an "AuthRedirect" page for handling the authentication result after the user has been authenticated by Authgear. Create the `AuthRedirect.vue` component file in the `src/components/` folder. Call the Authgear `finishAuthentication()` function in the Auth Redirect component to send a token back to Authgear server in exchange for access token and refresh token. Don't worry about the technical jargons, `finishAuthentication()` will do all the hard work for you and and save the authentication data. When the authentication is finished, the `isLoggedIn` state from the UserContextProvider will automatically be set to `true`. Finally, navigate back to root (`/`) which is our Home page. The final `AuthRedirect.vue` will look like this ```tsx // src/components/AuthRedirect.vue ``` ### Step 6: Apply Routes and Context Provider to the App As we have already configured the routes in the previous section, we can simply add `` tag to the `App.vue`. We can then Import **UserProvider** and wrap the `router-view` with it. Your final `App.vue` should look like this: ```tsx // src/App.vue ``` The file structure should now look like ``` src ├── App.vue ├── main.ts ├── router.ts ├── vite-env.d.ts ├── contexts │ └── UserProvider.vue └── components ├── AuthRedirect.vue └── Home.vue ``` ### Step 7: Add a Login button First, we will import the Authgear dependency. Then add the login button which will call `startAuthentication(ConfigureOptions)` through `startLogin` callback on click. This will redirect the user to the login page. ```tsx // src/components/Home.vue ``` You can now run **`npm run dev`** and you will be redirected to the Authgear Login page when you click the Login button. ![User will be redirected to the Authgear login page by clicking the login button](/files/Cs8I3NeFH4JSuG82EhKc) ### Step 8: Show the user information The Authgear SDK helps you get the information of the logged-in users easily. In the last step, the user is successfully logged in so let's try to print the user ID (sub) of the user in the Home page. In `Home.vue`, we will add a simple Loading splash and a greeting message printing the Sub ID. We will add two conditional elements such that they are only shown when user is logged in. We can also change the login button to show only if the user is not logged in. Make use of `isLoggedIn` from the `UserProvider` to control the components on the page. Fetch the user info by `fetchUserInfo()` and access its `sub` property. The Login button can be also rendered conditionally which only visible if the user is not logged in. ```tsx // src/components/Home.vue ``` Run the app again, the User ID (sub) of the user should be printed on the Home page. ### Step 9: Add a Logout button Finally, let's add a Logout button when a user is logged in. In `Home.vue`, we will add the following conditional elements in the template: ```tsx
``` And add the `logout` callback: ```tsx const logout = () => { authgear .logout({ redirectURI: "http://localhost:4000/", }) .then( () => { greetingMessage.value = ""; }, (err) => { console.error(err); } ); }; ``` Run the app again, we can now log out by clicking the **Logout** button. ### Step 10: Open User Settings Authgear provides a built-in UI for the users to set their attributes and change security settings. Use the `open` function to open the settings page at `/settings` In `Home.vue` append a conditional link to the logout button section like this: ```tsx ``` And add the `userSetting` callback: ```tsx import authgear, { PromptOption, Page } from "@authgear/web"; const userSetting = async () => { await authgear.open(Page.Settings); }; ``` This is the resulting `Home.vue`: ```tsx // src/components/Home.vue ``` ![Show the User ID, a link to User Settings and a logout button after login](/files/k99wS67RsU3iJkOoRGeo) ## Next steps, Calling an API To access restricted resources on your backend application server, the HTTP requests should include the access token in their Authorization headers. The Web SDK provides a `fetch` function which automatically handles this, or you can get the token with `authgear.accessToken`. #### Option 1: Using fetch function provided by Authgear SDK Authgear SDK provides the `fetch` function for you to call your application server. This `fetch` function will include the Authorization header in your application request, and handle the refresh access token automatically. The `authgear.fetch` implements [fetch](https://fetch.spec.whatwg.org/). ```javascript authgear .fetch("YOUR_SERVER_URL") .then(response => response.json()) .then(data => console.log(data)); ``` #### Option 2: Add the access token to the HTTP request header You can get the access token through `authgear.accessToken`. Call `refreshAccessTokenIfNeeded` every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token into the Authorization header of the application request. ```javascript authgear .refreshAccessTokenIfNeeded() .then(() => { // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid const accessToken = authgear.accessToken; // include Authorization header in your application request const headers = { Authorization: `Bearer ${accessToken}` }; }); ``` # Native/Mobile App If you are developing mobile or desktop applications, choose from one of these SDKs for your platform to get started. {% content-ref url="/pages/JAyUCdyydxw7WN5n45Uz" %} [Android SDK](/get-started/native-mobile-app/android) {% endcontent-ref %} {% content-ref url="/pages/YtcrWkc6l9FXHnGcFjaU" %} [Flutter SDK](/get-started/native-mobile-app/flutter) {% endcontent-ref %} {% content-ref url="/pages/LzMAOMrajRTN1xwCp51w" %} [iOS SDK](/get-started/native-mobile-app/ios) {% endcontent-ref %} {% content-ref url="/pages/Dn1akGNmYT8XruQHU4bR" %} [React Native SDK](/get-started/native-mobile-app/react-native) {% endcontent-ref %} {% content-ref url="/pages/g4tCcrjleuzgU3xxOK1S" %} [Ionic SDK](/get-started/native-mobile-app/ionic) {% endcontent-ref %} {% content-ref url="/pages/IKTtMHiNmizfVOt8cDPE" %} [Xamarin SDK](/get-started/native-mobile-app/xamarin) {% endcontent-ref %} # iOS SDK Integrate your iOS application with Authgear iOS SDK This guide provides instructions on integrating Authgear with an iOS app. The Authgear iOS SDK supports **iOS 11.0 and higher**. This tutorial builds the demo app with Apple's Observation framework (`@Observable`) and Swift Concurrency (`async`/`await`), which require **iOS 17.0 or higher**, **Xcode 16 or later**, and the **Swift 6** language mode. If you need to support older iOS versions, you can apply the same structure using `ObservableObject` and the SDK's completion handlers instead. Follow this guide to add Authgear to your iOS app in 🕐 10 minutes. {% hint style="info" %} You can find the full code for the demo app for this tutorial in [this Github repo](https://github.com/authgear/authgear-example-ios/) {% endhint %} ## Setup Application in Authgear Sign up for an Authgear Portal account at [https://portal.authgear.com/](https://portal.authgear.com). Or you can use your self-deployed Authgear. From the Project listing, create a new Project or select an existing Project. After that, we will need to create an Authgear client application in the project. ### **Step 1: Create an application in the Portal** Go to **Applications** on the left menu bar.
Click **⊕Add Application** in the top toolbar. Input the name of your application and select **Native App** as the application type. Click "Save". ![Create an application](/files/7wywVJAvi44Ch5FG30h3) You will see a list of guides that can help you for setting up, then click "Next". ### **Step 2: Configure the application** Here you'll need to define a custom URI scheme that Authgear will use to redirect users back to your app after authentication. For our example app, the custom URL scheme is `com.example.authgeardemo`, and the full **Redirect URI** built on top of it is `com.example.authgeardemo://host/path`. For further instructions on setting up a custom URI scheme in iOS, see the official documentation [here](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app). Head back to Authgear Portal, and add `com.example.authgeardemo://host/path` as Redirect URI. Click "Save" button and note the **Client ID**. and **Endpoint** for your new client application as you'll use them later in your iOS application. You can also obtain the Client ID again from the Applications list later. ![Fill in the Authorized Redirect URI](/files/PQMB3LwKqqICXuaPU6YX) ## Add Authgear to your iOS Application In this step, we'll add user authentication to a simple iOS app using the Authgear iOS SDK and the client application we created in the previous steps. ### Pre-requisites To follow the steps in this guide seamlessly, you should have the following: * [Xcode](https://developer.apple.com/xcode/) 16 or later * A project targeting iOS 17.0 or later, using the Swift 6 language mode * Some knowledge of SwiftUI and Swift Concurrency (`async`/`await`) ### Step 1: Create new iOS project For the purpose of this guide, we'll create a new project in Xcode. Skip this step if you're adding Authgear to your existing app. To create a new project, open Xcode and navigate to **File** > **New** > **Project**. Create your new project with the following details: * **Project Name:** `my_demo_app` * choose `SwiftUI` as **Interface** Leave other fields unchanged and proceed to create the project.

Xcode new project

### Step 2: Install Authgear SDK The Authgear iOS SDK makes it easy to interact with Authgear services from your iOS project. To add Authgear SDK to your project, in Xcode navigate to **File** > **Add Package Dependencies** and enter `https://github.com/authgear/authgear-sdk-ios.git` in the Package URL text field. Select the **Up to Next Major Version** dependency rule starting from `2.0.0`. Click **Add Package** to proceed.

Xcode package manager

On the next screen, select your application under **Add to Target** then click on **Add Package**.

xcode add package

Alternatively, if your project uses cocoapods, install the SDK using: ``` pod 'Authgear', :git => 'https://github.com/authgear/authgear-sdk-ios.git' ``` ### Step 3: Create the authentication model We'll keep all authentication logic in one place — an `@Observable` model that owns a single `Authgear` instance and exposes a small, UI-friendly state. The view (next step) just renders that state and calls the model's methods. Create a new Swift file named `AuthenticationModel.swift` and add the following: ```swift // AuthenticationModel.swift import Authgear import Observation // Sendable snapshots produced *inside* the SDK's completion handlers so that // no non-Sendable Authgear type crosses the `await` boundary. private enum AuthOutcome: Sendable { case signedIn(userID: String) case cancelled case failed(message: String) } private enum VoidOutcome: Sendable { case ok case failed(message: String) } @MainActor @Observable final class AuthenticationModel { enum State: Equatable { case loading case signedOut case signedIn(userID: String) } private(set) var state: State = .loading // Non-nil drives an error alert in the view. var errorMessage: String? private let authgear: Authgear private var didConfigure = false init() { authgear = Authgear( clientId: "", endpoint: "" ) } // Configure the SDK once and restore any existing session. func configure() async { guard !didConfigure else { return } didConfigure = true let outcome: VoidOutcome = await withCheckedContinuation { continuation in authgear.configure { result in switch result { case .success: continuation.resume(returning: .ok) case let .failure(error): continuation.resume(returning: .failed(message: error.localizedDescription)) } } } switch outcome { case .ok: // Refresh the session if the user has an existing one. if authgear.sessionState == .authenticated { await refreshCurrentUser() } else { state = .signedOut } case let .failed(message): errorMessage = message state = .signedOut } } // Start the interactive login flow. func logIn() async { state = .loading let outcome: AuthOutcome = await withCheckedContinuation { continuation in authgear.authenticate(redirectURI: "com.example.authgeardemo://host/path") { result in switch result { case let .success(userInfo): continuation.resume(returning: .signedIn(userID: userInfo.sub)) case let .failure(error): if let authgearError = error as? AuthgearError, case .cancel = authgearError { continuation.resume(returning: .cancelled) } else { continuation.resume(returning: .failed(message: error.localizedDescription)) } } } } apply(outcome) } // Log out and clear the local session. func logOut() async { state = .loading let outcome: VoidOutcome = await withCheckedContinuation { continuation in authgear.logout { result in switch result { case .success: continuation.resume(returning: .ok) case let .failure(error): continuation.resume(returning: .failed(message: error.localizedDescription)) } } } switch outcome { case .ok: state = .signedOut case let .failed(message): errorMessage = message // The SDK's session state is authoritative after a failed logout. if authgear.sessionState == .authenticated { await refreshCurrentUser() } else { state = .signedOut } } } // Open the pre-built user settings page. func openUserSettings() { authgear.open(page: .settings) } // Refresh the signed-in user's info; downgrades to signed-out if the // refresh token is no longer valid. private func refreshCurrentUser() async { let outcome: AuthOutcome = await withCheckedContinuation { continuation in authgear.fetchUserInfo { result in switch result { case let .success(userInfo): continuation.resume(returning: .signedIn(userID: userInfo.sub)) case let .failure(error): continuation.resume(returning: .failed(message: error.localizedDescription)) } } } apply(outcome) } private func apply(_ outcome: AuthOutcome) { switch outcome { case let .signedIn(userID): state = .signedIn(userID: userID) case .cancelled: state = .signedOut case let .failed(message): errorMessage = message state = .signedOut } } } ``` Replace **"\"** and **"\"** with the client ID and endpoint from the configuration page of the client project you [created earlier](#step-2-configure-the-application). {% hint style="info" %} **Why the `AuthOutcome` / `VoidOutcome` enums?** The Authgear SDK ships completion-handler APIs, and its result types (`UserInfo`, `SessionState`, `AuthgearError`) are not `Sendable`. To stay clean under the Swift 6 language mode, each call is wrapped with `withCheckedContinuation`, and the completion closure captures **only** the continuation and resumes with a small `Sendable` value extracted inside the closure. That way no non-`Sendable` SDK type crosses the `await` boundary, so the model compiles under strict concurrency checking without extra annotations. In the demo app repo, the client ID, endpoint, and redirect URI are factored into a small `Constants.swift` enum instead of being hard-coded in the initializer — a good pattern for real projects. {% endhint %} Here's what each method does: * `configure()` — initializes the SDK once (guarded by `didConfigure`) and, if a previous session exists, refreshes it so returning users land straight on the signed-in screen. * `logIn()` — runs the interactive authentication flow. User cancellation is handled distinctly from real errors, so cancelling the login sheet doesn't raise an error alert. * `logOut()` — ends the current session. On failure it treats the SDK's `sessionState` as authoritative rather than assuming the user is signed out. * `openUserSettings()` — opens Authgear's pre-built User Settings page, where users can view and modify their profile attributes and security settings. * `refreshCurrentUser()` — calls `fetchUserInfo` to update `sessionState` and retrieve the user's `sub` (a unique user ID). This also detects a session that has been revoked remotely: `sessionState` becomes `.noSession` and the model drops back to signed-out. ### Step 4: Build the ContentView Now replace the contents of `ContentView.swift` with a state-driven view that observes the model. It triggers `configure()` from `.task` when the view first appears, wraps the async actions in `Task {}`, and surfaces any `errorMessage` with an `.alert`: ```swift // ContentView.swift import SwiftUI struct ContentView: View { @State private var model = AuthenticationModel() var body: some View { VStack(spacing: 16) { switch model.state { case .loading: ProgressView() case .signedOut: signedOutView case let .signedIn(userID): signedInView(userID: userID) } } .padding() .task { await model.configure() } .alert( "Something went wrong", isPresented: Binding( get: { model.errorMessage != nil }, set: { isPresented in if !isPresented { model.errorMessage = nil } } ), presenting: model.errorMessage ) { _ in Button("OK", role: .cancel) {} } message: { message in Text(message) } } private var signedOutView: some View { VStack(spacing: 16) { Image(systemName: "globe") .imageScale(.large) .foregroundStyle(.tint) Text("My Demo App") Button("Login") { Task { await model.logIn() } } } } private func signedInView(userID: String) -> some View { VStack(spacing: 16) { Text("Welcome user \(userID)") Button("User Settings") { model.openUserSettings() } Button("Logout") { Task { await model.logOut() } } } } } #Preview { ContentView() } ``` The view has no direct SDK calls — it only reads `model.state` and invokes the model's methods. When signed out it shows the **Login** button; while an operation is in flight it shows a `ProgressView`; once signed in it greets the user and offers **User Settings** and **Logout**. #### Checkpoint Run your app now. It should launch and settle on the **Login** screen. Tapping **Login** will attempt to open the authentication page — but it won't return to your app yet. We'll register the redirect URI scheme next.
### Step 5: Register the URI Scheme for the Redirect URI For Authgear to redirect back into your app after authentication, register the custom URL **scheme** — the part of the redirect URI before `://`. For our redirect URI `com.example.authgeardemo://host/path`, the scheme is `com.example.authgeardemo`. Open your project's `Info.plist` or project settings UI in Xcode and add the following: {% tabs %} {% tab title="Xcode" %} Navigate to **Targets** > **{Your project}** > **Info** and expand the **URL Types** section. Add a new URL scheme with the following details: **Identifier**: `CFBundleURLTypes` **URL Schemes**: `com.example.authgeardemo` **Role**: Editor

xcode project properties

{% endtab %} {% tab title="Info.plist" %} 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <!-- Other entries -->
        <key>CFBundleURLTypes</key>
        <array>
            <dict>
                <key>CFBundleTypeRole</key>
                <string>Editor</string>
                <key>CFBundleURLName</key>
                <string>CFBundleURLTypes</string>
                <key>CFBundleURLSchemes</key>
                <array>
                    <string>com.example.authgeardemo</string>
                </array>
            </dict>
        </array>
    </dict>
</plist>
{% endtab %} {% endtabs %} {% hint style="warning" %} Register the bare scheme `com.example.authgeardemo` in `CFBundleURLSchemes` — **not** the full redirect URI `com.example.authgeardemo://host/path`. `CFBundleURLSchemes` expects only the scheme (the text before `://`). The full redirect URI is what you register in the Authgear Portal and pass to `authenticate(redirectURI:)`. {% endhint %} ### Step 6: Run and test Run your app again and try logging in. Because the redirect scheme is now registered, Authgear will redirect back to your app after authentication and the view will switch to the signed-in screen. Try the full flow: * **Login** — completes authentication and shows "Welcome user \". * **User Settings** — opens Authgear's pre-built settings page. * **Logout** — ends the session and returns to the Login screen. If configuration fails (for example, a wrong endpoint) or authentication errors out, the `.alert` you added in Step 4 surfaces the message instead of failing silently. ## Understanding session state You may want to know whether the user has logged in (for example, to show a Login button only when they haven't). The `sessionState` reflects the user's logged-in state in the SDK's local state. Even if `sessionState` is `.authenticated`, the session may be invalid if it was revoked remotely. Hence, after initializing the SDK, call `fetchUserInfo` to update `sessionState` as soon as it is proper to do so — which is exactly what `configure()` → `refreshCurrentUser()` does in the model above. The value of `sessionState` can be `.unknown`, `.noSession` or `.authenticated`. Initially it is `.unknown`. After a call to `authgear.configure`, it becomes `.authenticated` if a previous session was found, or `.noSession` if no such session existed. ## Using the Access Token in HTTP Requests Call `refreshAccessTokenIfNeeded` every time before using the access token; it checks and makes a network call only if the access token has expired. Then include the access token in the `Authorization` header of your request. As with the other SDK calls, you can bridge the completion handler into `async`/`await` with a continuation: ```swift func callProtectedAPI() async throws { try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in authgear.refreshAccessTokenIfNeeded { result in continuation.resume(with: result) } } // The access token is ready to use. It can be empty if the user is not // logged in or the session is invalid. guard let accessToken = authgear.accessToken else { // The user is not logged in, or the token is expired. return } // Example only — use your own networking library. var urlRequest = URLRequest(url: URL(string: "YOUR_SERVER_URL")!) urlRequest.setValue("Bearer \(accessToken)", forHTTPHeaderField: "authorization") // ... continue making your request } ``` ## Next steps To protect your application server from unauthorized access. You will need to **integrate your backend with Authgear**. {% content-ref url="/pages/xp8Yw44yzS7vmIMf3OOh" %} [Backend/API Integration](/get-started/backend-api) {% endcontent-ref %} ## iOS SDK Reference For detailed documentation on the iOS SDK, visit [iOS SDK Reference](https://authgear.github.io/authgear-sdk-ios/). # Android SDK How to use authgear android SDK This guide provides instructions on integrating Authgear with an Android app. Supported platforms include: * Android 5.0 (API 21) or higher Follow this guide to add Authgear to your Android app in 🕐 10 minutes. {% hint style="info" %} You can find the full code for the demo app for this tutorial in [this Github repo](https://github.com/authgear/authgear-example-android) {% endhint %} ## Setup Application in Authgear Sign up for an Authgear Portal account at [https://portal.authgear.com](https://portal.authgear.com/). Or you can use your self-deployed Authgear. From the Project listing, create a new Project or select an existing Project. After that, we will need to create an application in the project. ### **Step 1: Create an application in the Portal** Go to **Applications** on the left menu bar.
Click **⊕Add Application** in the top toolbar. Input the name of your application and select **Native App** as the application type. Click "Save". You will see a list of guides that can help you for setting up, then click "Next". ![Create an application](/files/7wywVJAvi44Ch5FG30h3) ### **Step 2: Configure the application** Define a custom URI scheme that Authgear will use to redirect users back to your app after they have authenticated. The scheme should be based on the package name for your Android app. For the demo app, we'll be creating in this guide the scheme is: `com.example.authgeardemo://host/path`. To learn more about setting up a custom URI scheme in Android, see the official documentation [here](https://developer.android.com/training/app-links/deep-linking). Head back to Authgear Portal, and add the URL scheme you have defined as a Redirect URI. For our demo app, add the following URI: ``` com.example.authgeardemo://host/path ``` Click "Save" in the top toolbar and note the **Client ID** as you'll use it later in your Android app. You can also obtain it again from the Applications list later. ![Fill in the Redirect URI](/files/PQMB3LwKqqICXuaPU6YX) ## Add Authgear to an Android Application In this step, we'll add user authentication to an Android application using the Authgear client application we set up in the previous steps. The Authgear SDK works with both **Jetpack Compose** and the classic **View/XML** UI toolkit. [Step 4](#step-4-implement-authentication) below provides the implementation for each — pick the tab that matches your app. ### Pre-requisites To follow along, you need to have the following: * Android Studio installed on your computer * Basic knowledge of Kotlin or Java ### Step 1: Create an Android App project For the purpose of this guide, we'll be creating a new simple Android app project. Feel free to skip this step if you are adding Authgear to your existing app. Open Android Studio and create a new project with the following details: * On the Activity selection screen, choose **Empty Activity** (Jetpack Compose) or **Empty Views Activity** (XML) — this guide covers both. The current Android Studio default, **Empty Activity**, uses Jetpack Compose. * **Name**: My Demo App * **Build configuration language**: Groovy DSL {% hint style="info" %} The reason for recommending you use Groovy DSL as **Build configuration language** for this guide is to make it easier to copy and paste the Gradle configurations we've provided without having to make many rewrites. {% endhint %} ### Step 2: Add Authgear SDK to your project The Authgear Android SDK makes it easier to interact with Authgear endpoints and services from your Android app. The SDK is published on Maven Central. Make sure the `mavenCentral()` repository is available to your project. It is included by default in new Android Studio projects; if it is missing, add it to your project's `settings.gradle` file: ```groovy dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { mavenCentral() } } ``` Next, add the Authgear SDK to the `dependencies` section of your app-level (`/app/build.gradle`) `build.gradle`: ```groovy dependencies { // Other implementations implementation 'com.authgear:android-sdk:3.0.0' } ``` `3.0.0` is the latest version at the time of writing. Check for newer releases on [Maven Central](https://central.sonatype.com/artifact/com.authgear/android-sdk) or the [release tags](https://github.com/authgear/authgear-sdk-android/tags). #### Enable Java 8+ API desugaring support To enable Java 8+ API desugaring support for your project, make the following changes to the app-level `build.gradle` file. 1. Add `coreLibraryDesugaringEnabled true` to the `android` > `compileOptions` section: ```gradle compileOptions { coreLibraryDesugaringEnabled true } ``` 2. Then add the coreLibraryDesugaring to the dependencies section: ```gradle dependencies { // Other implementations coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3' } ``` Learn more about Java 8+ API desugaring support [here](https://developer.android.com/studio/write/java8-support#library-desugaring). {% hint style="warning" %} Your app's **window theme** must descend from a `Theme.AppCompat` theme. The SDK's authentication screens (`OAuthActivity`, `OAuthRedirectActivity`) are `AppCompatActivity`, and Android throws `You need to use a Theme.AppCompat theme (or descendant) with this activity` on login if the app theme is a plain framework theme. An **Empty Views Activity** project already uses a Material Components (AppCompat-descendant) theme. If you created a **Jetpack Compose** project, open `res/values/themes.xml` and make sure your app theme uses an AppCompat or Material 3 parent, for example: ```xml

Protected View

Welcome: @Model.Username

Current Access Token: @Model.AccessToken

Current Refresh Token: @Model.RefreshToken

``` And `ProtectedModel.cs` class to which `Authorize` the attribute is applied requires authorization. ```csharp [Authorize] public class ProtectedModel : PageModel { public string Username { get; set; } public string AccessToken { get; set; } public string RefreshToken { get; set; } private readonly TokenClient tokenClient; public ProtectedModel(TokenClient tokenClient) { this.tokenClient = tokenClient; } public async Task OnGet() { ClaimsPrincipal user = this.User; var givenName = user.FindFirstValue("given_name"); var familyName = user.FindFirstValue("family_name"); this.Username = $"{givenName} {familyName}"; this.AccessToken = await this.tokenClient.GetAccessToken(this.HttpContext); this.RefreshToken = await this.tokenClient.GetRefreshToken(this.HttpContext); } public async Task OnPostRefreshToken() { await this.tokenClient.RefreshAccessToken(this.HttpContext); this.AccessToken = await this.tokenClient.GetAccessToken(this.HttpContext); this.RefreshToken = await this.tokenClient.GetRefreshToken(this.HttpContext); return Page(); } public async Task OnPostLogout() { await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme); await HttpContext.SignOutAsync(OpenIdConnectDefaults.AuthenticationScheme); } } ``` To see protected data, users need to go through the authentication process via Authgear.
If a user has not authenticated yet, `Unauthenticated.chtml` the page is rendered, an OpenID Connect redirect flow is triggered and the user needs to authenticate through the Authgear login page. See **Run the Application** section After successful authentication, you should see the protected page with the following details:
#### Step 4: Get and Use Refresh Token As part of the OAuth 2.0 standard, we can use the refresh token returned by the token endpoint to get a new access token. Doing so enables our application to replace an expired access token without requiring the user to repeat the entire login process. The following code in `ProtectedModel.cs` is responsible for doing that: ```csharp public async Task OnPostRefreshToken() { await this.tokenClient.RefreshAccessToken(this.HttpContext); this.AccessToken = await this.tokenClient.GetAccessToken(this.HttpContext); this.RefreshToken = await this.tokenClient.GetRefreshToken(this.HttpContext); return Page(); } ``` **Note:** You must include `offline_access` in your OAuth 2.0 scope for the Authgear authorization server to return a refresh token. #### Step 5: Logout The Logout button on the `Protected.cshtml` page calls the `OnPostLogout()` method in ProtectedModel.cs. The method will delete the current user session and redirect to Authgear's end session endpoint for the user to complete the logout process. The code sample below shows the implementation of the `OnPostLogout()` method: ```csharp public async Task OnPostLogout() { await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme); await HttpContext.SignOutAsync(OpenIdConnectDefaults.AuthenticationScheme); } ``` #### Step 6: Set up and run the application Start by cloning the project into your local machine: ```bash git clone ``` Make the project directory your current working directory: ```bash cd authgear-example-dotnet ``` Update the following configuration variables in the `appsettings.json` file with your Authgear app settings values from **Part1** such as `Issuer`, `ClientId`, `ClientSecret`, and Authgear endpoint: ```bash { "OpenIDConnect": { "ClientId": "{your-client-id}", "ClientSecret": "{your-client-secret}", "Issuer": "{your-authgear-app-endpoint}", "Scope": "openid offline_access", "PostLogoutRedirectUri": "", "TokenEndpoint": "{your-authgear-app-endpoint}/oauth2/token" }, "Urls": "", "Logging": { "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" } } } ``` Execute the following command to run the [ASP.NET](http://asp.net/) Core web application: ```bash dotnet build dotnet run ``` You can now visit to access the application. When you click on the **"View Protected Data"** button, [ASP.NET](http://asp.net) Core takes you to the **Authgear’s Login page**.
Your users can log in to your application through a page hosted by Authgear, which provides them with a secure, standards-based login experience that you can customize with your own branding and various authentication methods, such as [social logins](https://www.authgear.com/features/social-login), [passwordless](https://www.authgear.com/features/passwordless-authentication), [biometrics logins](https://www.authgear.com/features/biometric-authentication), [one-time-password (OTP)](https://www.authgear.com/features/whatsapp-otp) with SMS/WhatsApp, and multi-factor authentication (MFA).
After you have authenticated, a protected view is rendered. The application receives an Access token that it uses to present user data on the screen, and tokens that could be used in upstream requests to some backend API, to access data on behalf of the user.
#### Next steps This guide showed how to quickly implement an end-to-end OpenID Connect flow in .NET with Authgear. Only simple code is needed, after which protected views are secured with built-in UI login pages. # Laravel Authentication for Laravel websites with Authgear and OAuth2 In this guide, you'll learn how to add user authentication to a Laravel app using Authgear as an OIDC provider. Authgear supports multiple ways to allow users to log in to apps such as passwordless sign-in, phone OTP, and 2FA. In this post, we'll show you how to enable all these options in your Laravel app without worrying about the underlying logic. This guide targets **Laravel 12** and **PHP 8.2+**. ### What You Will Learn * How to create an Authgear Application. * How to request an OAuth 2.0 authorization code from Authgear. * How to get user info from Authgear using an OAuth 2.0 access token. * How to replace Breeze's local password login with Authgear, linking users by their Authgear subject (`sub`). ### Prerequisites To follow along with the example, you should have the following in place: * A free Authgear account. [Sign up](https://accounts.portal.authgear.com/signup) if you don't have an account yet. * PHP 8.2 or later, Composer 2, and Node.js 18 or later. You can also clone the finished app from the [Laravel Example GitHub repo](https://github.com/authgear/authgear-example-laravel) and follow along. #### What We Will Build The example app we'll build uses Laravel Breeze for its UI scaffolding — the Blade layout, dashboard, and profile pages. Authgear is the only identity provider. We remove Breeze's local register, login, password-reset, and email-verification flows, so users sign in through Authgear and nothing else. By handing authentication to Authgear, you get passwordless sign-in, phone OTP, 2FA, and more without writing or maintaining that logic yourself.
### How to Add User Authentication to Laravel with Authgear as an OAuth Provider In this section, we'll walk through the complete steps for building the example app. #### Step 1: Configure Authgear Application Before you can use Authgear as an OAuth identity provider, set up an application on the Authgear portal. Log in to Authgear and select a project. Navigate to the **Applications** section for your project. Create a new application or configure an existing one with **OIDC Client Application** as the Application Type, as shown below:
Click **Save** to go to the application configuration page. This page reveals the application credentials and OAuth 2.0 endpoints.
Note down the Client ID, Client Secret, and the endpoints. You'll use them later in your Laravel project. #### Step 2: Add a Redirect URI While you're still on the application configuration page, scroll down to the URL section and click **Add URI**. Enter `localhost:8000/oauth/callback` in the text field if you'll run your Laravel app on your local machine. Click **Save**. Authgear redirects users to this URI after authorization, so it must point to a valid route in your Laravel app. #### Step 3: Create a Laravel Project Create a new Laravel project by running the following command. This installs Laravel 12: ```sh composer create-project laravel/laravel authgear-laravel-example ``` Open the project folder in your editor. Delete `resources/views/welcome.blade.php` and create a new `resources/views/index.blade.php` with this content: ```html Authgear + Laravel Demo

Authgear + Laravel demo

This demo shows adding user authentication to a Laravel app with Authgear (OIDC / OAuth 2.0).

@if ($errors->any())

{{ $errors->first() }}

@endif

Login with Authgear

``` Then point the root route at this view. Open `routes/web.php` and set: ```php Route::get('/', function () { return view('index'); }); ``` Run `php artisan serve` and open `localhost:8000` in a browser. You should see the landing page with a login link.
#### Step 4: Install Laravel Breeze Breeze is the official starter kit for Laravel. Here we use it only for UI scaffolding — the Blade layout, dashboard, and profile pages — while Authgear handles authentication. Install Breeze: ```sh composer require laravel/breeze --dev ``` Run the installer to scaffold the resources: ```sh php artisan breeze:install ``` During setup, select `blade` as the stack and leave the other options as default. Next, add an `oauth_uid` column to the `users` table. This field stores a user's unique ID from Authgear after a successful login. In Laravel 12, the users table is defined in `database/migrations/0001_01_01_000000_create_users_table.php` (this single file also creates the `sessions` and cache tables — there's no date-stamped users migration). Add the following line inside the `Schema::create('users', ...)` block: ```php $table->string('oauth_uid')->nullable()->index(); ``` Then add `oauth_uid` to the `$fillable` array in `app/Models/User.php` so the field can be mass-assigned: ```php protected $fillable = [ 'name', 'email', 'oauth_uid', 'password', ]; ``` This example uses SQLite, so you don't need a database server. A fresh Laravel project already ships with `DB_CONNECTION=sqlite` in `.env`. Create the database file and run the migrations: ```bash touch database/database.sqlite php artisan migrate ``` #### Step 5: Add the Authgear Configuration Keep your Authgear settings in a dedicated config file rather than calling `env()` from your controllers. This is what lets `php artisan config:cache` work in production — once the config is cached, `env()` returns `null` outside config files. Create `config/authgear.php` with the following content: ```php env('AUTHGEAR_PROJECT_URL', ''), 'client_id' => env('AUTHGEAR_APP_CLIENT_ID', ''), 'client_secret' => env('AUTHGEAR_APP_CLIENT_SECRET', ''), 'redirect_uri' => env('AUTHGEAR_APP_REDIRECT_URI', ''), // OAuth 2.0 / OIDC scopes requested during authorization. 'scopes' => env('AUTHGEAR_SCOPES', 'openid email profile'), // OIDC endpoints derived from the project URL. 'authorize_endpoint' => env('AUTHGEAR_PROJECT_URL', '').'/oauth2/authorize', 'token_endpoint' => env('AUTHGEAR_PROJECT_URL', '').'/oauth2/token', 'userinfo_endpoint' => env('AUTHGEAR_PROJECT_URL', '').'/oauth2/userInfo', 'end_session_endpoint' => env('AUTHGEAR_PROJECT_URL', '').'/oauth2/end_session', ]; ``` Add your Authgear application's credentials to your project's `.env` file: ``` AUTHGEAR_PROJECT_URL= AUTHGEAR_APP_CLIENT_ID= AUTHGEAR_APP_CLIENT_SECRET= AUTHGEAR_APP_REDIRECT_URI=http://localhost:8000/oauth/callback ``` {% hint style="info" %} Your Authgear project URL is the hostname of any of your endpoint URLs. For a project with an authorization endpoint of `https://laravel-app.authgear.cloud/oauth2/authorize`, the project URL is `https://laravel-app.authgear.cloud`. {% endhint %} #### Step 6: Bind the OAuth Provider We'll use the `league/oauth2-client` package to talk to Authgear's OAuth endpoints. Install it: ```sh composer require league/oauth2-client ``` Bind a single configured `GenericProvider` in the service container so it can be injected into your controller. This keeps the OAuth setup in one place and makes the controller testable. Open `app/Providers/AppServiceProvider.php` and add the binding to the `register()` method: ```php app->singleton(GenericProvider::class, function () { return new GenericProvider([ 'clientId' => config('authgear.client_id'), 'clientSecret' => config('authgear.client_secret'), 'redirectUri' => config('authgear.redirect_uri'), 'urlAuthorize' => config('authgear.authorize_endpoint'), 'urlAccessToken' => config('authgear.token_endpoint'), 'urlResourceOwnerDetails' => config('authgear.userinfo_endpoint'), ]); }); } public function boot(): void { // } } ``` #### Step 7: Send the OAuth Authorization Request In this step, you'll create the route that redirects users from your app to Authgear's authorization page, where they grant your app access to their account. If you've signed in to a site using Google before, you've seen an authorization page like this. Create the controller that handles all OAuth operations: ```sh php artisan make:controller OAuthController ``` Open `app/Http/Controllers/OAuthController.php`. Inject the provider through the constructor and add the `startAuthorization()` method: ```php provider->getAuthorizationUrl([ 'scope' => config('authgear.scopes'), ]); // Persist the state value to validate it on the callback (CSRF protection). $request->session()->put('oauth2state', $this->provider->getState()); return redirect()->away($authorizationUrl); } } ``` `startAuthorization()` stores the OAuth `state` value in the session before redirecting. You'll check it on the callback to protect against CSRF. Now register the routes. Open `routes/web.php` and replace its contents with: ```php name('login'); Route::get('/oauth/callback', [OAuthController::class, 'handleRedirect']); Route::post('/logout', [OAuthController::class, 'logout'])->name('logout'); Route::get('/dashboard', function () { return view('dashboard'); })->middleware(['auth'])->name('dashboard'); Route::middleware('auth')->group(function () { Route::get('/profile', [ProfileController::class, 'edit'])->name('profile.edit'); Route::patch('/profile', [ProfileController::class, 'update'])->name('profile.update'); Route::delete('/profile', [ProfileController::class, 'destroy'])->name('profile.destroy'); }); ``` The `/login` route is named `login` so Breeze's `auth` middleware redirects unauthenticated users to Authgear. You'll add the `handleRedirect()` and `logout()` methods in the next steps. Because Authgear is now the only identity provider, you no longer need Breeze's local-auth routes. Delete `routes/auth.php` entirely — it defined the register, login, password-reset, and email-verification routes. The route file above already drops the `require __DIR__.'/auth.php';` line that Breeze added to `web.php`. You can also delete the matching controllers in `app/Http/Controllers/Auth/` and their Blade views if you want to keep the project tidy. At this point, visiting `/login` should redirect to the Authgear authorization page.
#### Step 8: Handle the Redirect After a user authorizes your app, Authgear redirects back to `/oauth/callback` with an authorization code. The `handleRedirect()` method validates the request, exchanges the code for an access token, and fetches the user's info. Add the `handleRedirect()` method to `OAuthController`: ```php public function handleRedirect(Request $request): RedirectResponse { $state = $request->query('state'); $expectedState = $request->session()->pull('oauth2state'); if (empty($state) || ! is_string($expectedState) || ! hash_equals($expectedState, $state)) { return redirect('/')->withErrors(['oauth' => 'Invalid OAuth state. Please try logging in again.']); } $code = $request->query('code'); if (empty($code)) { return redirect('/')->withErrors(['oauth' => 'Authorization code missing.']); } try { $accessToken = $this->provider->getAccessToken('authorization_code', [ 'code' => $code, ]); $userInfo = $this->provider->getResourceOwner($accessToken)->toArray(); } catch (IdentityProviderException $e) { report($e); return redirect('/')->withErrors(['oauth' => 'Failed to authenticate with Authgear.']); } if (empty($userInfo['sub'])) { return redirect('/')->withErrors(['oauth' => 'Authgear did not return a user identifier.']); } $user = $this->findOrCreateUser($userInfo); Auth::guard('web')->login($user); $request->session()->regenerate(); return redirect()->intended('/dashboard'); } ``` A few things this method does that protect your app: * **Validates `state`.** It compares the returned `state` against the value stored in Step 7 using `hash_equals`. A mismatch rejects the request, which blocks CSRF attacks against the callback. * **Reads from the request, not `$_GET`.** Using `$request->query()` keeps the code consistent with the rest of Laravel and testable. * **Fails gracefully.** Any error during the token exchange or userinfo call is reported and turned into a friendly redirect, instead of dumping an exception to the browser. If you dump the `$userInfo` array (`dd($userInfo)`), you'll see the claims Authgear returns: ```json [ "custom_attributes" => [] "email" => "users-email@gmail.com" "email_verified" => true "https://authgear.com/claims/user/can_reauthenticate" => true "https://authgear.com/claims/user/is_anonymous" => false "https://authgear.com/claims/user/is_verified" => true "sub" => "e1234323-f123-4b99-91d8-c2ca55a6a3dc" "updated_at" => 1683898685 ] ``` The `sub` and `email_verified` claims drive the account-linking logic in the next step. #### Step 9: Link the Authgear User to a Laravel Session `handleRedirect()` calls `findOrCreateUser()` to map the Authgear user to a local Laravel user, so your app can start a normal authenticated session and guard protected routes. Add the `findOrCreateUser()` method to `OAuthController`: ```php private function findOrCreateUser(array $userInfo): User { // Match on the stable Authgear subject identifier, never on email alone. $user = User::query()->where('oauth_uid', $userInfo['sub'])->first(); if ($user) { return $user; } // Link to an existing local account by email ONLY when Authgear reports // the email as verified. Linking on an unverified email would allow // account takeover. if (! empty($userInfo['email']) && ($userInfo['email_verified'] ?? false) === true) { $existing = User::query()->where('email', $userInfo['email'])->first(); if ($existing) { $existing->oauth_uid = $userInfo['sub']; $existing->save(); return $existing; } } return User::create([ 'name' => $userInfo['email'] ?? $userInfo['sub'], 'email' => $userInfo['email'] ?? null, 'oauth_uid' => $userInfo['sub'], 'password' => Hash::make(Str::random(40)), ]); } ``` How this resolves a user: 1. **Match on `sub` first.** The Authgear subject identifier (`sub`) is stable and unique per user, so it's the reliable key. Email addresses can change or be reassigned. 2. **Link by email only when verified.** If no local user has this `sub` yet, link to an existing account by email — but only when `email_verified` is `true`. Linking on an unverified email would let an attacker claim someone else's account. 3. **Otherwise create a new user.** New users get a random local password they never use, since they always sign in through Authgear. {% hint style="info" %} This example doesn't store the access or refresh token in the session, and it doesn't request the `offline_access` scope. The scopes are `openid email profile`. The app reads the user's identity once at login and relies on the Laravel session from then on. {% endhint %} Find the complete `OAuthController` [here](https://github.com/authgear/authgear-example-laravel/blob/main/app/Http/Controllers/OAuthController.php). Now run the app, open the landing page, and click the login link. You're redirected to the Authgear authorization page. After you authorize, Authgear sends you back to the callback route, and on success you land on the Breeze dashboard:
#### Step 10: Logout To log a user out, clear the local Laravel session and then end the Authgear session so the user is fully signed out. Use the OIDC `end_session` endpoint rather than revoking a token — the app doesn't hold any tokens to revoke. Add the `logout()` method to `OAuthController`: ```php public function logout(Request $request): RedirectResponse { Auth::guard('web')->logout(); $request->session()->invalidate(); $request->session()->regenerateToken(); // If Authgear is configured, end its session too for a full sign-out. if (! empty(config('authgear.project_url'))) { return redirect()->away(config('authgear.end_session_endpoint')); } return redirect('/'); } ``` The `POST /logout` route is already wired up in `routes/web.php` from Step 7, so any Breeze logout button that posts to the `logout` route will trigger this method. #### Verify It Works The example repo ships a feature test in `tests/Feature/OAuthTest.php` that covers the state check, the code exchange, and account linking. Run the suite to confirm the flow behaves as expected: ```bash php artisan test ``` ### What's Next Try enabling the different login methods on Authgear from the portal — 2FA, passwordless login, phone OTP, and more — without changing any code in your app. The two hardening choices in this guide are worth keeping in any production integration: validating the OAuth `state` on the callback, and linking accounts by email only when Authgear reports the email as verified. Find the complete code for the example app in the [Laravel Example GitHub repo](https://github.com/authgear/authgear-example-laravel). # PHP Authentication for PHP websites with Authgear and OAuth2 Using OAuth, you can use Authgear to add user authentication in a vanilla PHP application. In this guide, we'll cover how to implement OAuth 2.0 login in a regular PHP web application with Authgear as the Identity Provider. ### What You Will Learn At the end of this post, you'll learn the following: * How to create an Authgear Application * How to enable email and password sign-in * How to sign in with Authgear from a PHP app * How to request user info from Authgear * How to use a refresh token * And finally how to log users out and revoke access tokens. ### Prerequisites To follow along, you'll need the following: * PHP runtime (E.g XAMPP for testing offline on Windows devices) * An Authgear account. [Sign up](https://accounts.portal.authgear.com/signup) for free if you don't have an account yet. * [Composer](https://getcomposer.org/download/) (PHP package manager) installation * Your preferred code editor (e.g VS Code). #### What We Will Build In this guide, we'll build a basic PHP application that lets a user sign in with their registered email and password. The application will welcome the user with their email address after they sign in successfully. If the user is not signed in, the application will display links to Register or Login. The following screenshot shows what the User Interface for the app will look like:
### How to Add User Authentication to PHP with Authgear Now let's dive into the actual steps of how to add Authgear to a PHP application. ### Part 1: Configure an Authgear Application Under this section, we will cover the steps for configuring the Authgear application our PHP website will be connecting to. We'll do all these configurations in the Authgear Portal. #### Step 1: Set up Authgear Application The first step you need to take is to create a new application or configure an existing application on the Authgear [Portal](https://portal.authgear.com). To do that, log in to the Authgear Portal, and select your project (or create a new one if you don't have any yet). From your project dashboard navigate to the **Applications** section and enter the details for your new application as shown below:
Once you're done, click on the Save button to continue. Then, click on Next to see the configuration page for your application.
The application configuration page contains basic information like `Client ID` and `Client Secret` that we'll use later in this tutorial. Hence, try to note the values down. In addition to basic information, you can find other configuration information including endpoints and Authorized Redirect URIs. #### Step 2: Authorized Redirect URIs The Authorized Redirect URIs section contains a link to the page you want Authgear to redirect users to after login. Update the value for Authorized Redirect URIs to a page on your application. For our example PHP application the value will be `http://localhost` because we plan to test run it offline using XAMPP. Also, try to note this value down as we'll be using it in later steps. ### Part 2: Implement PHP Project Here we will cover the steps for implementing a PHP website that interacts with Authgear using the Open ID Connect (OIDC) standard. #### Step 1: Create a PHP Project Create a new PHP project on your computer and add an `index.php` file to the root of the project folder. Add the following code to index.php to create the User Interface of the example app. ```php PHP Demo - Home

Hello world!

This demo app shows you how to add user authentication to your app using Authgear

Checkout docs.authgear.com to learn more about adding Authgear to your apps.

Login

Logout

``` **Note**: The Login and Logout links in the above code currently point to login.php and logout.php respectively, we'll create both files later. #### Step 2: Add Authgear Configuration to PHP Project In this step, we'll add our Authgear application configuration to the PHP project. We'll use the [OAuth 2.0 Client](https://github.com/thephpleague/oauth2-client) PHP package for the configuration. Install the package manually from Github or via Composer by running the following command from your PHP project's root directory: ```sh composer require league/oauth2-client ``` Next, after the package is installed, create a new `config.php` file in the PHP project folder. Add the following code to the file: ```php $clientID, // The client ID assigned to you by the provider (authgear). 'clientSecret' => $clientSecret, // The client secret is assigned to you by the provider. 'redirectUri' => $redirectUri, // The authorized Redirect URI you specified in your authgear app. 'urlAuthorize' => $appUrl.'/oauth2/authorize', 'urlAccessToken' => $appUrl.'/oauth2/token', 'urlResourceOwnerDetails' => $appUrl.'/oauth2/userInfo', 'scopes' => 'openid offline_access' ]); ?> ``` **Note**: Replace the values for `clientId`, `clientSecret`, `redirectUri` with corresponding values from the Authgear application you created in Step 1. Including the `offline_access` scope is required to get a refresh token from Authgear. #### Step 3: Add Login Authorization The flow for Login on our app is as follows: 1. The user clicks on the Login button 2. User is redirected to the Authgear authorization page where they can sign in using email and password or any other sign-in methods you have enabled for your Authgear project. 3. The user is redirected back to your website with an authorization code. In order to implement the above, you need to create a `login.php` file in your project's root directory. Add the following code to the login.php file: ```php getAuthorizationUrl(); // Redirect the user to the authorization URL. header('Location: ' . $authorizationUrl); exit; } ?> ``` At this point, if you try running the example app in a browser and click the Login link in index.php, your app should redirect to the Authgear login page. If you sign in successfully, you should be redirected back to the redirect URL you specified earlier in your project configuration.
Authgear will redirect to your Authorized Redirect URI with extra parameters like `code` or an error message in the URL. The value for the code parameter is your authorization code. In the next step, we'll use the authorization code to generate an access token. #### Step 4: Get Access Token and Request User Info Usually, after successful sign-in, you'll want to start using the current user's info to offer custom experience in your app. In this step, we'll use the PHP OAuth 2.0 Client once more to interact with our Authgear app. First, open `index.php` and search for the line with the following code: ```php $appUrl = "REPLACE WITH YOUR AUTHGEAR PROJECT URL"; ``` Replace the above line with this code: ```php include "config.php"; session_start(); // if code is set, get access token if (isset($_GET['code'])) { $code = $_GET['code']; try { $accessToken = $provider->getAccessToken('authorization_code', [ 'code' => $code ]); $_SESSION['accessToken'] = $accessToken; $_SESSION['refreshToken'] = $accessToken->getRefreshToken(); //store refresh token so that you can use it later } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) { // Failed to get the access token or user details. exit($e->getMessage()); } } ``` The above code exchanges the authorization code returned in the redirect for an access token. It then stores the access token in the PHP session so that we can use this token in future requests to protected resources. Now that we have the access token, let's try to get the current user's details. To do that, update the HTML part in index.php like this: ```php

Hello world!

This demo app shows you how to add user authentication to your app using Authgear

Checkout docs.authgear.com to learn more about adding Authgear to your apps.

getResourceOwner($storedAccessToken); $userInfo = $resourceOwner->toArray(); echo "Welcome back " . $userInfo['email']; echo "
"; echo 'Logout'; } else { ?>

Login

``` Now test the app on your browser again and you should get the following page after login:
We've successfully added user authentication to our PHP app using Authgear as the identity provider. The above page displays a welcome message with the email address the user registered with on your Authgear project. You can display other info about the user from the value of `$userInfo` variable. #### Step 5: Getting and Using a Refresh Token In OAuth 2.0, a refresh token is a key that's usually included in the response from the token endpoint when a client application exchanges the authorization code for an access token. Access tokens expire after some time. Hence, we can use this refresh token to request a new access token without requiring our application users to log in again. In this step, we'll show you how to use the refresh token. In the last step, we stored the value for the refresh token in the `$_SESSION['refreshToken']` variable. So, to get the refresh token, simply read the value from that variable. Now, add the following code to index.php to read and use the refresh token to get a new access token: First, find the line with the following code: ```php $resourceOwner = $provider->getResourceOwner($storedAccessToken); ``` Replace that line with the following blocks of code: ```php if ($storedAccessToken->hasExpired()) { $newAccesstoken = $provider->getAccessToken('refresh_token', [ 'refresh_token' => $_SESSION['refreshToken'] ]); $_SESSION['accessToken'] = $newAccesstoken; $resourceOwner = $provider->getResourceOwner($newAccesstoken); } else { $resourceOwner = $provider->getResourceOwner($storedAccessToken); } ``` **Note:** It is required to include **offline\_access** in your OAuth 2.0 scopes to get a refresh token from Authgear. #### Step 6: Logout Authgear provides a token revoke endpoint that you can use to revoke a refresh token and all the access associated with it. To use the token revoke endpoint to log users out of your application, create a new `logout.php` file in your project directory then add the following code to the file: ```php $_SESSION['refreshToken']]); $request = $provider->getRequest( 'POST', $appUrl. '/oauth2/revoke', $options ); $provider->getResponse($request); $_SESSION['accessToken'] = null; $_SESSION['refreshToken'] = null; } ``` The above code will revoke your refresh token and delete all the session variables. ### Summary In this post, we covered how to get started with adding Authgear to a regular web app built with PHP and no framework. We also tried out an example of using the Authgear authorization code to retrieve an access token, then we used the token to access the user info endpoint. Here's a link complete source code for [our example app on Github](https://github.com/authgear/authgear-example-php). There's so much more you can do with Authgear and you can continue learning by checking out more topics on the [documentation page](https://docs.authgear.com/get-started). # Backend/API Integration An API or service protected by Authgear If your API or backend service needs authentication, you can validate the session in your application server code. Each request from the client to your application server should contain an access token or a cookie. Your backend server should validate them for each HTTP request. There are different approaches to verify the requests based on whether you validate JWT (JSON Web Tokens) in your server, or forward authentication to Authgear Resolver Endpoint. | | Validate JSON Web Token (JWT) in your application server | Forward Authentication to Authgear Resolver Endpoint | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Reliability |

Medium
JWT only updates when expire. That means before the token expires, your application may see the user as valid even if they have been disabled.

|

High
Update near real-time, based on your reserve proxy cache setting

| | Integration difficulties |

Easy
You only need to add code in your application to validate and decode JWT

|

Medium
Need to setup extra reverse proxy to resolve authentication information

| | Transportation of session | **Access Token** in `Authorization` header |

Session ID in Cookies or
Access Token in Authorization header

| ## Simple: Validate JWT in your server Authgear uses [JSON Web Token (JWT)](https://jwt.io/?_gl=1*1ybgym6*rollup_ga*MTI1NDM1NjUwMy4xNjg3NzEyNTIz*rollup_ga_F1G3E656YZ*MTY5MTEzNjEzNS45NS4xLjE2OTExMzYxNDguNDcuMC4w*_ga*MTI1NDM1NjUwMy4xNjg3NzEyNTIz*_ga_QKMSDV5369*MTY5MTEzNjEzNS44Ny4xLjE2OTExMzYxNDguNDcuMC4w&_ga=2.165043391.1472871049.1691063710-1254356503.1687712523) for secure data transmission, authentication, and authorization. ```mermaid sequenceDiagram autonumber participant app as Mobile/Single Page Application app->>Authgear: User authenticates with Authgear Authgear-->>app: Access token & refresh token participant server as Your app server app->>server: User sends request with access token server->>server: Verify request server -->> app: Server responds with requested information ``` 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: ```bash > GET /api_path HTTP/1.1 > Host: yourdomain.com > Authorization: Bearer ``` Read more on [Validate JWT in your application server](/get-started/backend-api/jwt) guide. {% content-ref url="/pages/NBU5LasbVvo4StH1QZjP" %} [Validate JWT in your backend](/get-started/backend-api/jwt) {% endcontent-ref %} ## 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](/get-started/backend-api/nginx) guide. ### Forward Access Token in Authorization Header ```mermaid sequenceDiagram autonumber Browser ->> Authgear: User authenticate with Authgear Authgear -->> Browser: Access token and refresh token Browser ->> Reverse Proxy: Request with access token participant Resolver as Authgear Resolver Endpoint rect rgb(191, 223, 255) note left of Resolver: Verify access token Reverse Proxy ->> Resolver: Forward request authorization header Resolver -->> Reverse Proxy: Response with "x-authgear-headers" end participant App as Your app server Reverse Proxy ->> App: Pass request with updated headers App -->> Reverse Proxy: Response Reverse Proxy -->> Browser: Response ``` Instead of validating the access token in the backend, a reverse proxy forwards the request to an [Authgear Resolver Endpoint](/get-started/backend-api/nginx#authgear-resolver-endpoint). This endpoint resolves and verifies the access token in the **Authorization Header** of the request. ### Forward Cookie in HTTP header ```mermaid sequenceDiagram autonumber Browser ->> Authgear: User authenticate with Authgear Authgear -->> Browser: Authgear sets cookies Browser ->> Reverse Proxy: Request with cookies participant Resolver as Authgear Resolver Endpoint rect rgb(191, 223, 255) note left of Resolver: Verify cookie Reverse Proxy ->> Resolver: Forward request cookie header Resolver -->> Reverse Proxy: Response with "x-authgear-headers" end participant App as Your app server Reverse Proxy ->> App: Pass request with updated headers App -->> Reverse Proxy: Response Reverse Proxy -->> Browser: Response ``` 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](/get-started/backend-api/nginx). Request example: ```javascript > GET /api_path HTTP/1.1 > Host: yourdomain.com > cookie: session= ``` # Client SDK to make authorized API calls to backend How to make authorized request to your application server after login with Authgear ## Using Authgear SDK to call your application server In this section, we are going to explain how to make an authorized request to your backend API by using Authgear SDK. Authgear SDKs make it easy to refresh access token if needed and maintain session state. If you are using **Cookie-based authentication** in your web application, you can skip this section as session cookies are handled by the browser automatically. ## Overview 1. To determine which user is calling your server, you will need to include the Authorization header in every request that send to your application server. 2. On your Backend/API, you will need to set up [Backend integration](/get-started/backend-api). Authgear will help you to handle the Authorization header to determine whether the incoming HTTP request is authenticated or not. In the below section, we will explain how to set up SDK to for the purpose of making authorized API calls to your backend. ## SDK Setup Configure the Authgear SDK with the Authgear endpoint and client id. The SDK must be properly configured before use by calling `configure`. No network call will be triggered during `configure`. {% tabs %} {% tab title="Javascript" %} ```javascript authgear .configure({ clientID: "", endpoint: "", }) .then(() => { // configured successfully }) .catch((e) => { // failed to configured }); ``` {% endtab %} {% tab title="iOS" %} ```swift let authgear = Authgear(clientId: clientId, endpoint: endpoint) authgear.configure() { result in switch result { case .success(): // configured successfully case let .failure(error): // failed to configured } } ``` {% endtab %} {% tab title="Android" %} ```java ConfigureOptions configureOptions = new ConfigureOptions(); Authgear authgear = new Authgear(getApplication(), clientID, endpoint); authgear.configure(configureOptions, new OnConfigureListener() { @Override public void onConfigured() { // configured successfully } @Override public void onConfigurationFailed(@NonNull Throwable throwable) { // failed to configured } }); ``` {% endtab %} {% tab title="Xamarin" %} ```csharp var authgearOptions = new AuthgearOptions { ClientId = "", AuthgearEndpoint: "", }; #if __ANDROID__ var authgear = new AuthgearSdk(GetActivity().ApplicationContext, authgearOptions); #else #if __IOS__ var authgear = new AuthgearSdk(UIKit.UIApplication.SharedApplication, authgearOptions); #endif #endif await authgear.ConfigureAsync(); ``` {% endtab %} {% endtabs %} ## UserInfo and Session State `sessionState` reflect the user logged in state. However the session state is cached locally and only updated after each server call. Usually right after login/signup via `authorize`,You will call `fetchUserInfo` as soon as possible with `authgear.sessionState` became `AUTHENTICATED` {% tabs %} {% tab title="Javascript" %} ```javascript // value can be NO_SESSION or AUTHENTICATED // After authgear.configure, it only reflect SDK local state. let sessionState = authgear.sessionState; if (sessionState === "AUTHENTICATED") { authgear .fetchUserInfo() .then((userInfo) => { // sessionState is now up to date // read the userInfo if needed }) .catch((e) => { // sessionState is now up to date // it will change to NO_SESSION if the session is invalid }); } ``` {% endtab %} {% tab title="iOS" %} ```swift // value can be .noSession or .authenticated. // After authgear.configure, it only reflect SDK local state. let sessionState = authgear.sessionState // call fetchUserInfo to see if the session is valid if authgear.sessionState == .authenticated { authgear.fetchUserInfo { userInfoResult in // sessionState is now up to date // it will change to .noSession if the session is invalid let sessionState = authgear.sessionState switch userInfoResult { case let .success(userInfo): // read the userInfo if needed case let .failure(error): // failed to fetch user info // the refresh token maybe expired or revoked } } ``` {% endtab %} {% tab title="Android" %} ```java // value can be NO_SESSION or AUTHENTICATED // After authgear.configure, it only reflect SDK local state. SessionState sessionState = authgear.getSessionState(); if (sessionState == SessionState.AUTHENTICATED) { authgear.fetchUserInfo(new OnFetchUserInfoListener() { @Override public void onFetchedUserInfo(@NonNull UserInfo userInfo) { // sessionState is now up to date // read the userInfo if needed } @Override public void onFetchingUserInfoFailed(@NonNull Throwable throwable) { // sessionState is now up to date // it will change to NO_SESSION if the session is invalid } }); } ``` {% endtab %} {% tab title="Xamarin" %} ```csharp // value can be NoSession or Authenticated // After Authgear.ConfigureAsync, it only reflects local state. var sessionState = authgear.SessionState; if (sessionState == SessionState.Authenticated) { try { var userInfo = await authgear.FetchUserInfoAsync(); // sessionState is now up to date } catch (Exception ex) { // sessionState is now up to date // it will change to NoSession if the session is invalid } } ``` {% endtab %} {% endtabs %} ## Makeing an API call When you make a API call to Backend API, you will need to include the access token in the `Authorization` header. Access token is also short lived and need to be regularly rotated by Refresh token for security purpose. Authgear SDKs provide the following functions to simplify both steps. ### **The `fetch` function (JavaScript Only)** **Javascript Only**. Authgear SDK provides `fetch` function for you to call your application server. The `fetch` function will include Authorization header in your application request, and handle refresh access token automatically. `authgear.fetch` implement [fetch](https://fetch.spec.whatwg.org/). If you are using another networking library, you will need to use `refreshAccessTokenIfNeeded().` and include the `Authorization` header yourself, as described in the next paragraph. {% tabs %} {% tab title="Javascript" %} ```javascript authgear .fetch("YOUR_SERVER_URL") .then(response => response.json()) .then(data => console.log(data)); ``` {% endtab %} {% endtabs %} ### The refreshAccessTokenIfNeeded function You will need to include the Authorization header in your application request. Call `refreshAccessTokenIfNeeded` every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token into the Authorization header of your application request. {% tabs %} {% tab title="Javascript" %} ```java authgear .refreshAccessTokenIfNeeded() .then(() => { // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid const accessToken = authgear.accessToken; // include Authorization header in your application request const headers = { Authorization: `Bearer ${accessToken}` }; }); ``` {% endtab %} {% tab title="iOS" %} ```swift authgear.refreshAccessTokenIfNeeded() { result in switch result { case .success(): // access token is ready to use // accessToken can be empty // it will be empty if user is not logged in or session is invalid // include Authorization header in your application request if let accessToken = authgear.accessToken { // example only, you can use your own networking library var urlRequest = URLRequest(url: "YOUR_SERVER_URL") urlRequest.setValue( "Bearer \(accessToken)", forHTTPHeaderField: "authorization") // ... continue making your request } case let .failure(error): // failed to refresh access token // the refresh token maybe expired or revoked } } ``` {% endtab %} {% tab title="Android" %} ```java // Suppose we are preparing an http request in a background thread. // Setting up the request, e.g. preparing a URLConnection try { authgear.refreshAccessTokenIfNeededSync(); } catch (OauthException e) { // failed to refresh access token // the refresh token maybe expired or revoked } // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid String accessToken = authgear.getAccessToken(); HashMap headers = new HashMap<>(); headers.put("authorization", "Bearer " + accessToken); // Submit the request with the headers... ``` {% endtab %} {% tab title="Xamarin" %} ```csharp try { await authgear.RefreshAccessTokenIfNeededAsync(); } catch (OauthException ex) { // failed to refresh access token // the refresh token maybe expired or revoked } // access token is ready to use // accessToken can be string or undefined // it will be empty if user is not logged in or session is invalid var accessToken = authgear.AccessToken; var client = GetHttpClient(); // Get the re-used http client of your app, as per recommendation. var httpRequestMessage = new HttpRequestMessage(myHttpMethod, myUrl); httpRequestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); // Send the request with the headers... ``` {% endtab %} {% endtabs %} ## Handle revoked sessions If the session is revoked from the management portal, the client will call your Backend API with an invalid access token. Your application server can check that by looking at the [resolver headers](/get-started/backend-api/nginx). For example, you application may return HTTP status code 401 for unauthorized requests. Depending on your application flow, you may want to show your user login page again or reset the SDK `sessionState` to `NO_SESSION` locally. To clear the `sessionState`, you can use `clearSessionState` function. {% tabs %} {% tab title="Javascript" %} ```javascript // example only // if your application server return HTTP status code 401 for unauthorized request async function fetchAppServer() { var response = await authgear.fetch("YOUR_SERVER_URL"); if (response.status === 401) { // if you want to clear the session state locally, call clearSessionState // `authgear.sessionState` will become `NO_SESSION` after calling await authgear.clearSessionState(); throw new Error("user session invalid"); } // ... } ``` {% endtab %} {% tab title="iOS" %} ```swift // example only // if your application server return HTTP status code 401 for unauthorized request if let response = response as? HTTPURLResponse { if response.statusCode == 401 { // if you want to clear the session state locally, call clearSessionState // `authgear.sessionState` will become `.noSession` after calling authgear.clearSessionState { result in switch result { case .success(): // clear SDK session state locally // `authgear.sessionState` becomes `.noSession` case let .failure(error): // failed to clear session state } } } } ``` {% endtab %} {% tab title="Android" %} ```java // example only // if your application server return HTTP status code 401 for unauthorized request responseCode = httpConn.getResponseCode(); if (responseCode == HttpURLConnection.Unauthorized) { // if you want to clear the session state locally, call clearSessionState // `authgear.getSessionState()` will become `NO_SESSION` after calling authgear.clearSessionState(); } ``` {% endtab %} {% tab title="Xamarin" %} ```csharp // example only // if your application server return HTTP status code 401 for unauthorized request statusCode = httpResponseMessage.StatusCode; if (statusCode == HttpStatusCode.Unauthorized) { // if you want to clear the session state locally, call ClearSessionState // `authgear.SessionState` will become `NoSession` after calling authgear.ClearSessionState(); } ``` {% endtab %} {% endtabs %} # Validate JWT in your backend Authenticate the incoming HTTP requests by validating JWT in your application server In this section, we will go through how to decode the JWT token to obtain the currently logged-in user. {% hint style="info" %} Building with **NestJS**? The [`@authgear/nestjs`](/get-started/backend-api/nestjs) SDK provides a ready-made module, guard, and decorators so you don't have to wire up JWT validation by hand. {% endhint %} Before we start, make sure the option **Issue JWT as access token** is enabled in your Application settings in the Portal.

Enable this option in application settings in the portal

With the **Issue JWT as access token** option turned on in your application, Authgear will issue JWT as access tokens. The incoming HTTP requests should include the access token in their `Authorization` headers. Without setting the reverse proxy, your backend server can use your Authgear **JWKS** to verify the request and decode user information from the JWT access token. ## Payload of the JWT access token See the claims in the access token in this reference: [JWT Access Token](/reference/tokens/jwt-access-token). Learn more about [Add custom fields to a JWT Access Token or ID Token](/integration/add-custom-fields-to-a-jwt-access-token) for adding claims into the JWT. ## Find the JSON Web Key Sets (JWKS) endpoint This Discovery endpoint serves as a JSON document containing the OpenID Connect configuration of your app. It includes the authorization endpoint, the token endpoint, and the JWKS endpoint. `https:///.well-known/openid-configuration` The JSON Web Key Sets (JWKS) endpoint can be found in `jwks_uri` in the configuration. **OpenID Connect Configuration JSON Example** Here is [an example of how it looks](https://accounts.portal.authgear.com/.well-known/openid-configuration). ```json { "issuer": "https://project-id.authgear.cloud", "authorization_endpoint": "https://project-id.authgear.cloud/oauth2/authorize", "jwks_uri": "https://project-id.authgear.cloud/oauth2/jwks", // the JWKS endpoint ... } ``` ## Decode user from an access token Follow this step-by-step example to verify and decode the JWT token. {% tabs %} {% tab title="Python" %} **Step 1: Install packages** ```bash pip install cryptography pip install PyJWT ``` **Step 2: Find the JSON Web Key Sets (JWKS) endpoint** Define a function to find the JWKS endpoint from the OpenID Connect configuration. Use your Authgear endpoint as the `base_address` ```python import json from contextlib import closing from urllib.request import urlopen base_address = "https://" def fetch_jwks_uri(base_address): doc_url = base_address + "/.well-known/openid-configuration" with closing(urlopen(doc_url)) as f: doc = json.load(f) jwks_uri = doc["jwks_uri"] if not jwks_uri: raise Exception('Failed to fetch jwks uri.') return jwks_uri ``` **Step 3: Get the JWT token from the Authorization header** Define a function to extract the access token from the Authorization header in the incoming request. It should look like `Authorization: Bearer `. ```python def parse_header(authz_header): parts = authz_header.split(" ") if len(parts) != 2: return scheme = parts[0] if scheme.lower() != "bearer": return return parts[1] ``` **Step 4: Verify and decode the JWT token** Here we show an example of using the Flask web framework to guard a path. You may need to adjust some of the codes to suit your technologies. ```python from flask import request import jwt from jwt import PyJWKClient @app.route("/hello") def hello(): authz_header = request.headers.get("Authorization") if not authz_header: return { "message": "authz header not found" } # get jwt token from Authorization header token = parse_header(authz_header) if token: try: # fetch jwks_uri from the Authgear Discovery Endpoint jwks_uri = fetch_jwks_uri(base_address) # Reuse PyJWKClient for better performance jwks_client = PyJWKClient(jwks_uri) signing_key = jwks_client.get_signing_key_from_jwt(token) user_data = jwt.decode( token, signing_key.key, algorithms=["RS256"], audience=base_address, options={"verify_exp": True}, ) return { "message": "Hello!", "user_data": user_data } except: return { "message": "JWT decode failed" } else: return { "message": "no token" } ``` {% endtab %} {% tab title="Node.js" %} **Step 1: Install dependencies** ```bash npm install --save axios jwks-rsa jsonwebtoken ``` **Step 2: 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). ```javascript 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; } ``` **Step 3: 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: ```javascript 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]; } ``` **Step 4: 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: ```javascript const decoded_access_token = node_jwt.decode(access_token, {complete: true}); ``` **Step 5: 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: ```javascript 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); } ``` Here's what your Express app should look like after putting the code in all the steps together: ```javascript const express = require("express"); const axios = require("axios"); const node_jwt = require('jsonwebtoken'); const jwksClient = require('jwks-rsa'); const app = express(); const port = 3002; const appUrl = "https://demo-1-ea.authgear.cloud"; const getJwksUri = async (appUrl) => { const config_endpoint = appUrl + "/.well-known/openid-configuration"; const data = await axios.get(config_endpoint); return data.data.jwks_uri; } 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]; const decoded_access_token = node_jwt.decode(access_token, {complete: true}); 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); } }); app.listen(port, () => { console.log(`server started on port ${port}`); }); ``` {% endtab %} {% tab title="Go" %} Use your Authgear endpoint as `base_address` ```go import ( "context" "encoding/json" "fmt" "net/http" "time" "github.com/lestrrat-go/jwx/v3/jwk" "github.com/lestrrat-go/jwx/v3/jwt" ) var ( baseAddress = "https://" ) type OIDCDiscoveryDocument struct { JWKSURI string `json:"jwks_uri"` } func FetchOIDCDiscoveryDocument(endpoint string) (*OIDCDiscoveryDocument, error) { resp, err := http.DefaultClient.Get(endpoint) if err != nil { return nil, err } defer resp.Body.Close() if resp.StatusCode != http.StatusOK { return nil, fmt.Errorf( "failed to fetch discovery document: unexpected status code: %d", resp.StatusCode, ) } var document OIDCDiscoveryDocument err = json.NewDecoder(resp.Body).Decode(&document) if err != nil { return nil, err } return &document, nil } func FetchJWK(baseAddress string) (jwk.Set, error) { doc, err := FetchOIDCDiscoveryDocument( baseAddress + "/.well-known/openid-configuration", ) if err != nil { return nil, err } set, err := jwk.Fetch(context.Background(), doc.JWKSURI) return set, err } // DecodeUser parse request Authorization header and obtain user id and claims func DecodeUser(r *http.Request) (string, bool, bool, error) { // fetch jwks_uri from Authgear // you can cache the value of jwks using jwk.Cache to have better performance set, err := FetchJWK(baseAddress) if err != nil { return "", false, false, fmt.Errorf("failed to fetch JWK: %s", err) } // parse jwt token token, err := jwt.ParseRequest( r, // This may not work out of the box depending on the jwk.Set. // Please read about requirements for "kid" and "alg" (and possibly // "WithDefaultKey") when using jwk.Set in the jwt.WithKeySet documentation. jwt.WithKeySet(set), ) if err != nil { return "", false, false, fmt.Errorf("invalid token: %s", err) } // validate jwt token err = jwt.Validate(token, jwt.WithClock(jwt.ClockFunc( func() time.Time { return time.Now().UTC() }, )), jwt.WithAudience(baseAddress), ) if err != nil { return "", false, false, fmt.Errorf("invalid token: %s", err) } var verified bool var anonymous bool // ignore errors -- if the claim does not exist, it doesn't matter _ = token.Get("https://authgear.com/claims/user/is_verified", &verified) _ = token.Get("https://authgear.com/claims/user/is_anonymous", &anonymous) // In jwx v3, Subject() returns (value, ok). sub, _ := token.Subject() return sub, verified, anonymous, nil } func handler(w http.ResponseWriter, r *http.Request) { // decode user example userid, isUserVerified, isAnonymousUser, err := DecodeUser(r) // ... your handler logic } ``` {% endtab %} {% tab title="Java" %} The following example uses Spring Boot. **Step 1: Install dependencies** Add the following dependencies to your build.gradle file: ```gradle dependencies { implementation("com.nimbusds:nimbus-jose-jwt:10.2") implementation("org.json:json:20250107") } ``` Then add the following imports to the top of your controller file: ```java import com.nimbusds.jose.jwk.JWKSet; import com.nimbusds.jose.jwk.RSAKey; import com.nimbusds.jwt.JWTClaimsSet; import com.nimbusds.jwt.SignedJWT; import java.io.BufferedReader; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import java.util.List; ``` **Step 2: Get JWKS Endpoint** Implement the following method to fetch the JWKS URI: ```java private static String fetchJwksUri(String baseAddress) throws Exception { String docUrl = baseAddress + "/.well-known/openid-configuration"; HttpURLConnection conn = (HttpURLConnection) new URL(docUrl).openConnection(); conn.setRequestMethod("GET"); try (BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()))) { StringBuilder response = new StringBuilder(); String line; while ((line = reader.readLine()) != null) { response.append(line); } String jwksUri = new org.json.JSONObject(response.toString()).getString("jwks_uri"); if (jwksUri == null || jwksUri.isEmpty()) { throw new Exception("Failed to fetch JWKS URI."); } return jwksUri; } } ``` **Step 3: Get Signing Key** Get the signing key from the JWK using the following method: ```java private static RSAKey getSigningKeyFromJwks(String jwksUri, String token) throws Exception { JWKSet jwkSet = JWKSet.load(new URL(jwksUri)); List keys = jwkSet.getKeys(); SignedJWT signedJWT = SignedJWT.parse(token); String keyId = signedJWT.getHeader().getKeyID(); return keys.stream() .filter(jwk -> jwk.getKeyID().equals(keyId)) .findFirst() .map(jwk -> (RSAKey) jwk) .orElse(null); } ``` **Step 4: Validate JWT** To demonstrate how to validate a JWT, we'll implement a `validateJWT` endpoint in a Spring Boot application. The endpoint will read access tokens from the bearer authorization header. It will call the `fetchJwksUri()` and `getSigningKeyFromJwks()` from steps 1 and 2 to get the JWK URI and signing key required to parse the JWT. ```java import java.io.BufferedReader; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import java.util.List; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestHeader; import org.springframework.web.bind.annotation.RestController; import com.nimbusds.jose.jwk.JWKSet; import com.nimbusds.jose.jwk.RSAKey; import com.nimbusds.jwt.JWTClaimsSet; import com.nimbusds.jwt.SignedJWT; @SpringBootApplication @RestController public class DemoApplication { //paste implementation for fetchJwksUri() method below this line. //paste implemetation of getSigningKeyFromJwks() method below this line. private static final String BASE_ADDRESS = ""; //place your authgear app endpoint here @GetMapping("/validateJwt") public Object validateJwt(@RequestHeader("Authorization") String authorizationHeader) { if (authorizationHeader == null || !authorizationHeader.startsWith("Bearer ")) { return new ResponseMessage("authorization header not found"); } String token = authorizationHeader.substring(7); // Extract token try { // Fetch JWKS URI dynamically String jwksUri = fetchJwksUri(BASE_ADDRESS); // Get signing key from JWKS RSAKey signingKey = getSigningKeyFromJwks(jwksUri, token); if (signingKey == null) { return new ResponseMessage("JWT decode failed: Signing key not found"); } // Validate and decode JWT SignedJWT signedJWT = SignedJWT.parse(token); JWTClaimsSet claimsSet = signedJWT.getJWTClaimsSet(); return new ResponseMessage("Hello!", claimsSet.toJSONObject()); } catch (Exception e) { return new ResponseMessage("JWT decode failed: " + e.getMessage()); } } private static String fetchJwksUri(String baseAddress) throws Exception { String docUrl = baseAddress + "/.well-known/openid-configuration"; HttpURLConnection conn = (HttpURLConnection) new URL(docUrl).openConnection(); conn.setRequestMethod("GET"); try (BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()))) { StringBuilder response = new StringBuilder(); String line; while ((line = reader.readLine()) != null) { response.append(line); } String jwksUri = new org.json.JSONObject(response.toString()).getString("jwks_uri"); if (jwksUri == null || jwksUri.isEmpty()) { throw new Exception("Failed to fetch JWKS URI."); } return jwksUri; } } private static RSAKey getSigningKeyFromJwks(String jwksUri, String token) throws Exception { JWKSet jwkSet = JWKSet.load(new URL(jwksUri)); List keys = jwkSet.getKeys(); SignedJWT signedJWT = SignedJWT.parse(token); String keyId = signedJWT.getHeader().getKeyID(); return keys.stream() .filter(jwk -> jwk.getKeyID().equals(keyId)) .findFirst() .map(jwk -> (RSAKey) jwk) .orElse(null); } static class ResponseMessage { public String message; public Object user_data; public ResponseMessage(String message) { this.message = message; } public ResponseMessage(String message, Object user_data) { this.message = message; this.user_data = user_data; } } } ``` {% endtab %} {% tab title="PHP" %} **Step 1: Install Packages** First, install the dependencies required by running these com ```bash composer require firebase/php-jwt ``` ```bash composer require guzzlehttp/guzzle ``` **Step 2: Find the JWKS Endpoint** Create a function that finds the JWKS endpoint from your Authgear application endpoint using the following code: ```php request('GET', $configEndpoint); $responseObject = json_decode($response->getBody()); return $responseObject->jwks_uri; } ``` **Step 3: Get Signing Key** Add the following code to your application to get the JWT signing key: ```php $jwksUri = getJwksUri($appUrl); $httpClient = new Client(); $jwksUriResponse = $httpClient->request('GET', $jwksUri); $keysObject = json_decode($jwksUriResponse->getBody()); $jwks = (array) ($keysObject->keys)[0]; $parsedKey = JWK::parseKey($jwks, "RS256"); $signingKey = $parsedKey->getKeyMaterial(); ``` **Step 4: Extract the JWT From the Request Header** To extract the access token from the HTTP request use the following code: ```php if (!isset($_SERVER['HTTP_AUTHORIZATION'])) throw new Exception("Invalid authorization header"); $authorizationHeader = $_SERVER['HTTP_AUTHORIZATION']; $jwt = (explode(" ", $authorizationHeader))[1]; ``` **Step 5: Validate and Decode JWT** Finally, decode the JWT signing key. ```php $decoded = JWT::decode($jwt, new Key($signingKey, 'RS256')); echo json_encode($decoded); ``` {% endtab %} {% tab title="ASP.NET" %} **Step 1: Install NuGet packages** ```bash dotnet add package NSwag.AspNetCore ``` then add these imports to the top of your program.cs file: ```c# using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.IdentityModel.Tokens; ``` **Step 2: Configure JWT Authentication** This tells ASP.NET Core to use JWT Bearer tokens for authentication ```c# var builder = WebApplication.CreateBuilder(args); var config = builder.Configuration; builder.Services.AddAuthentication(x => { x.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme; x.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme; x.DefaultScheme = JwtBearerDefaults.AuthenticationScheme; }).AddJwtBearer(x => // here we configure what to validate in JWT tokens { // .NET will automatically fetch JWKS keys from {authority}/.well-known/openid-configuration x.Authority = ""; // place your authgear app endpoint here, x.RequireHttpsMetadata = false; // Allow HTTP for development x.TokenValidationParameters = new TokenValidationParameters { ValidIssuer = x.Authority, ValidateAudience = false, // set to true if you validate audience ValidateLifetime = true, ValidateIssuerSigningKey = true, }; }); ``` **Step 3: Add authorization** ```c# builder.Services.AddAuthorization(); ``` **Step 4: Configure middleware pipeline** Order is important! Authentication must come before Authorization ```c# app.UseAuthentication(); app.UseAuthorization(); ``` **Step 5: Create a protected endpoint** The following example uses the Minimal API model ```c# app.MapGet("/", (HttpContext context) => { var user = context.User; Console.WriteLine($"Authorization header: {context.Request.Headers.Authorization}"); Console.WriteLine($"User authenticated: {user.Identity?.IsAuthenticated}"); if (user.Identity?.IsAuthenticated == true) { var claims = user.Claims.ToDictionary(c => c.Type, c => c.Value); return Results.Ok(claims); } return Results.Json(new { error = "Unauthorized" }, statusCode: 401); }).RequireAuthorization(); // require auth from this endpoint ``` For Controller-based APIs, simply add \[Authorize] to your controller class or individual action methods to protect them {% endtab %} {% endtabs %} ### Check the validity of JWT The `auth_time` claim in an **OIDC ID token** represents the time **when the user authentication occurred**. Extract the `auth_time` claim from the token, which should represent the time of the original authentication in seconds. If the difference between the current time and `auth_time` exceeds your threshold (for example, 5 minutes), initiate the [re-authentication](/authentication-and-access/authentication/reauthentication) process. See an example of how to verify the signature of the ID token, and then validate the claims `auth_time` inside [here](/authentication-and-access/authentication/reauthentication#backend-integration). ## Decode user from cookies Validating JWT in your application server is *currently* only available for **Token-based authentication**. {% hint style="info" %} For Cookie-based authentication, JWT in cookies is not supported yet. [You can track the issue here](https://github.com/authgear/authgear-server/issues/1180). {% endhint %} # Forward Authentication to Authgear Resolver Endpoint Authenticate the incoming HTTP requests by forwarding Authentication to Authgear Resolver Endpoint In this section, we will explain how to set up a reverse proxy in NGINX to protect your app server from unauthorized access with the Authgear resolver. You can forward the requests without the request body to the resolver endpoint. Authgear will look at the `Authorization` and `Cookie` in the HTTP header, verify the token, and respond to HTTP 200 with `X-Authgear-` headers for session validity, the user id...etc. If you use a popular reverse proxy on your deployment, such as [NGINX](https://www.nginx.com/), [Traefik](https://traefik.io/traefik/), or API Gateways such as [Apache APISIX](https://apisix.apache.org/), you can configure it with a few simple lines of forward auth config. Your backend should read the returned headers to determine the identity of the user of the HTTP request. You can also use the forward authentication features of the other popular reverse proxy. e.g. * [Traefik ForwardAuth middleware](https://doc.traefik.io/traefik/v2.0/middlewares/forwardauth/) ## Authgear Resolver Endpoint Authgear provides an endpoint for forward authentication. Subrequests should be made to the following endpoint for authentication. `https:///_resolver/resolve` ## How Forward Authentication Works ![](/files/-MbicWRgOJ0qakVbcKnx) 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_module`configuration parameter. Run this command and verify that the output includes `--with-http_auth_request_module`: ```bash $ nginx -V 2>&1 | grep -- 'http_auth_request_module' ``` The trick here is to declare an internal `location` and use `auth_request` to initiate a subrequest to the resolved endpoint. ### Example configuration ``` server { # Use variable in proxy_pass with resolver to respect DNS TTL. # Note that /etc/hosts and /etc/resolv.conf are NOT consulted if resolver is used. # See https://www.nginx.com/blog/dns-service-discovery-nginx-plus/ resolver 8.8.8.8; # Location that requires request authentication location / { set $backend http://www.mycompany.com; proxy_pass $backend; proxy_set_header Host $host; # Specify the auth_request directive to initiate subrequests to the to the internal location. # This corresponds to the Step 2. auth_request /_auth; # Copy the `x-authgear-*` headers from the response of the subrequest to Nginx variables. # This corresponds to the Step 3. auth_request_set $x_authgear_session_valid $upstream_http_x_authgear_session_valid; auth_request_set $x_authgear_user_id $upstream_http_x_authgear_user_id; auth_request_set $x_authgear_user_anonymous $upstream_http_x_authgear_user_anonymous; auth_request_set $x_authgear_user_verified $upstream_http_x_authgear_user_verified; auth_request_set $x_authgear_session_acr $upstream_http_x_authgear_session_acr; auth_request_set $x_authgear_session_amr $upstream_http_x_authgear_session_amr; auth_request_set $x_authgear_session_authenticated_at $upstream_http_x_authgear_session_authenticated_at; auth_request_set $x_authgear_user_can_reauthenticate $upstream_http_x_authgear_user_can_reauthenticate; # Include the headers in the request that will be sent to your backend server. # This corresponds to the Step 4. proxy_set_header x-authgear-session-valid $x_authgear_session_valid; proxy_set_header x-authgear-user-id $x_authgear_user_id; proxy_set_header x-authgear-user-anonymous $x_authgear_user_anonymous; proxy_set_header x-authgear-user-verified $x_authgear_user_verified; proxy_set_header x-authgear-session-acr $x_authgear_session_acr; proxy_set_header x-authgear-session-amr $x_authgear_session_amr; proxy_set_header x-authgear-session-authenticated-at $x_authgear_session_authenticated_at; proxy_set_header x-authgear-user-can-reauthenticate $x_authgear_user_can_reauthenticate; # Your backend must inspect the request headers to determine whether the request is authenticated or not. # This corresponds to the Step 5. } location = /_auth { # Set this location for internal use only internal; # Replace with your authgear endpoint. # For example, https://example.authgear.cloud set $resolver /_resolver/resolve; proxy_pass $resolver; # Set the host so that authgear knows which app is calling the resolver endpoint # Replace with the host of your authgear endpoint. # For example, example.authgear.cloud proxy_set_header Host ; # The body is supposed to be consumed by your backend server. # Pass only the headers to the resolver proxy_pass_request_body off; proxy_set_header Content-Length ""; } } ``` {% hint style="info" %} See docs for `auth_request` in NGINX for more details. {% endhint %} ## Optimizing the performance If the reverse proxy, Authgear, and your backend server are in different regions, authenticating every request could result in a huge downgrade in the performance. You may consider enabling caching. ``` http { # ... proxy_cache_path /tmp/cache keys_zone=auth_cache:10m; # The server block. server { # ... location = /_auth { # ... proxy_cache auth_cache; proxy_cache_key "$cookie_session|$http_authorization"; proxy_cache_valid 200 10m; # Adjust cache duration as desired. } } } ``` ## Reference on the headers See the list of `x-authgear-` headers in the specs: # NestJS API Protect a NestJS API with Authgear using the @authgear/nestjs SDK Protect a [NestJS](https://nestjs.com/) API with Authgear using the `@authgear/nestjs` SDK. The SDK validates Authgear **JWT access tokens** offline (via OIDC discovery and JWKS) and gives you a NestJS module, an authentication guard, and decorators — so protecting a route takes just a few lines. A complete example application is available at [authgear/authgear-example-nestjs](https://github.com/authgear/authgear-example-nestjs). {% hint style="info" %} This SDK is for the **resource server** side — it verifies the access tokens your API receives. It does not perform the login flow. Your users log in through a separate client (a [Single-Page App](/get-started/single-page-app), a [mobile app](/get-started/native-mobile-app), or any OAuth client), which then calls your NestJS API with the access token. {% endhint %} **What you will build:** * A public route (`GET /health`) that needs no token * A protected route (`GET /me`) that returns the authenticated user's claims *** ### Setting Up Your Application in Authgear #### Step 1: Enable JWT access tokens The SDK validates JWT access tokens offline, so the application that issues the tokens your API will accept must issue JWTs. 1. Sign in to the [Authgear Portal](https://portal.authgear.com/) 2. Select your Project, then go to **Applications** and open the application your client uses to log in (or [create one](/get-started/single-page-app) — e.g. a **Single Page Application**) 3. Under the **Access Token** section, turn on **Issue JWT as access token** 4. Note down your **Endpoint** (e.g. `https://your-project.authgear.cloud`) and **Client ID** — you will need these shortly 5. Click **Save** {% hint style="warning" %} Without **Issue JWT as access token**, Authgear issues opaque access tokens, which this SDK cannot validate offline. Requests would be rejected with `401`. {% endhint %} *** ### Building Your NestJS Application #### Step 1: Create a NestJS Project ```bash npm i -g @nestjs/cli nest new my-api cd my-api ``` #### Step 2: Install the Authgear SDK ```bash npm install @authgear/nestjs ``` This also installs `@nestjs/config`, which we use to read configuration from the environment: ```bash npm install @nestjs/config ``` #### Step 3: Configure Environment Variables Create a `.env` file in the project root: ```bash AUTHGEAR_ENDPOINT=https://your-project.authgear.cloud AUTHGEAR_CLIENT_ID=your-client-id ``` {% hint style="info" %} `AUTHGEAR_CLIENT_ID` is optional. When set, the SDK additionally asserts that the token's `client_id` claim matches it. {% endhint %} #### Step 4: Register the Authgear Module Register `AuthgearModule` in your root module. Setting `global: true` registers the guard as a global guard, so **every route is protected by default** unless explicitly marked public. ```typescript // src/app.module.ts import { Module } from '@nestjs/common'; import { ConfigModule, ConfigService } from '@nestjs/config'; import { AuthgearModule } from '@authgear/nestjs'; import { AppController } from './app.controller'; @Module({ imports: [ ConfigModule.forRoot({ isGlobal: true }), AuthgearModule.forRootAsync({ global: true, inject: [ConfigService], useFactory: (config: ConfigService) => ({ endpoint: config.getOrThrow('AUTHGEAR_ENDPOINT'), clientID: config.get('AUTHGEAR_CLIENT_ID'), }), }), ], controllers: [AppController], }) export class AppModule {} ``` {% hint style="info" %} If your configuration is static, you can use `AuthgearModule.forRoot({ endpoint: '...', global: true })` instead of `forRootAsync`. {% endhint %} #### Step 5: Protect Your Routes With the guard registered globally, mark public routes with `@Public()`. Read the authenticated user with the `@CurrentUser()` parameter decorator. ```typescript // src/app.controller.ts import { Controller, Get } from '@nestjs/common'; import { Public, CurrentUser, AuthgearClaims } from '@authgear/nestjs'; @Controller() export class AppController { // Public — no token required @Public() @Get('health') health() { return { status: 'ok' }; } // Protected — requires a valid Authgear access token @Get('me') me(@CurrentUser() user: AuthgearClaims) { return { sub: user.sub, isVerified: user.isVerified, isAnonymous: user.isAnonymous, }; } } ``` `AuthgearClaims` exposes the common claims (`sub`, `iss`, `aud`, `clientID`, `isVerified`, `isAnonymous`, `canReauthenticate`) plus the full decoded payload as `raw` for any custom claims. {% hint style="info" %} Prefer to protect routes individually instead of globally? Omit `global: true` and apply the guard per controller or handler with `@UseGuards(AuthgearAuthGuard)`. {% endhint %} *** ### Running the Application ```bash npm run start:dev ``` The API listens on . *** ### Testing the Integration The public route works without a token: ```bash curl -i http://localhost:3000/health # 200 {"status":"ok"} ``` The protected route is rejected without a valid token: ```bash curl -i http://localhost:3000/me # 401 {"message":"Missing bearer token","error":"Unauthorized","statusCode":401} ``` To call the protected route, send an Authgear access token as a Bearer token: ```bash curl -i http://localhost:3000/me \ -H "Authorization: Bearer " # 200 {"sub":"...","isVerified":true,"isAnonymous":false} ``` {% hint style="info" %} Obtain an access token by logging a user in through a client application. The [example project](https://github.com/authgear/authgear-example-nestjs) includes a small frontend that signs in and calls the protected API for you. To build your own client, see the [Single-Page App](/get-started/single-page-app) or [Native/Mobile App](/get-started/native-mobile-app) guides. {% endhint %} *** ### Module Options `forRoot()` and the object returned by the `forRootAsync()` factory accept: | Option | Type | Required | Default | Description | | ----------------------- | --------- | -------- | ------- | ----------------------------------------------------------------------- | | `endpoint` | `string` | ✓ | — | Authgear project endpoint. Used for OIDC discovery and JWKS. | | `clientID` | `string` | | — | If set, the verifier also asserts the token's `client_id` claim. | | `global` | `boolean` | | `false` | Register the guard as a global `APP_GUARD` so all routes are protected. | | `jwksCacheMaxAge` | `number` | | — | JWKS cache max age in milliseconds. | | `clockToleranceSeconds` | `number` | | `0` | Leeway in seconds for `exp`/`iat` checks. | You can also inject `AuthgearTokenService` to verify a token outside of the guard. *** ### Next Steps * [JWT access token reference](/reference/tokens/jwt-access-token) — the full list of claims * [Validate JWT in your backend](/get-started/backend-api/jwt) — the framework-agnostic approach * [`@authgear/nestjs` documentation & API reference](https://authgear.github.io/authgear-sdk-nestjs/) # Machine-to-Machine (M2M) Applications Enable secure, automated authorization for your backend systems, microservices, and IoT devices, ensuring only trusted apps and devices can access your APIs. ### 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. ## Common Use Cases * **Application Backends:** Facilitates secure transfer of data, files, or logs between microservices or external systems. * **CLI Tools:** Allows tools running on developer or deployment machines to access APIs with short-lived tokens. * **Scheduled Jobs & Daemons:** Empowers background tasks (e.g., cronjobs, queuing systems) to access protected resources safely. * **IoT Devices:** Enables each smart device to authenticate independently and send data securely to cloud APIs. ## Set Up M2M Applications in Authgear ### 1. Register Your API Resources Go to the **API Resources** page in the Authgear portal: * Create the API resource your apps/devices will access. * When registering the resource, specify its **identifier**—this acts as the unique URI representing your API (for example, `https://myapi.com/api`). * This identifier will be set as the `aud` (audience) claim in the JWT access tokens issued for this resource. * Define **scopes** for granular permissions, such as `read:data`, `write:data`, or `manage:config`. * Scopes specify exactly **what** operations clients can perform on your API. ### 2. Register Your Application In the **Applications** page: * Create a client application for each backend service, CLI tool, job, or device that needs API access. * Assign the relevant **API resources** and **scopes** to the application, ensuring least-privilege access. * After creating the application, you’ll be able to view its **Client ID** and **Client Secret** in the portal. Keep the Client Secret secure. It should never be exposed in client-side code or public repositories. ### 3. Request a Token Using the Client Credentials Flow The **Client Credentials Flow** defined in [OAuth 2.0 RFC 6749, section 4.4](https://tools.ietf.org/html/rfc6749#section-4.4) is designed for non-user, automated access. To obtain an access token in your backend, use the Client ID and Client Secret from your registered application in the portal: {% tabs %} {% tab title="curl" %} ``` curl --request POST \ --url https://myproject.authgear.cloud/oauth2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data resource=IDENTIFIER_OF_API_RESOURCE \ --data client_id=CLIENT_ID \ --data client_secret=CLIENT_SECRET ``` {% endtab %} {% tab title="Python" %} ```python import urllib.parse import urllib.request import json url = "https://myproject.authgear.cloud/oauth2/token" headers = { "Content-Type": "application/x-www-form-urlencoded" } data = { "grant_type": "client_credentials", "resource": "IDENTIFIER_OF_API_RESOURCE", "client_id": "CLIENT_ID", "client_secret": "CLIENT_SECRET" } encoded_data = urllib.parse.urlencode(data).encode('utf-8') req = urllib.request.Request(url, data=encoded_data, headers=headers, method='POST') with urllib.request.urlopen(req) as response: response_status = response.getcode() response_body = response.read().decode('utf-8') print("Response Status Code:", response_status) print("Response Body:", json.loads(response_body)) ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "io/ioutil" "net/http" "net/url" "strings" ) func main() { data := url.Values{} data.Set("grant_type", "client_credentials") data.Set("resource", "IDENTIFIER_OF_API_RESOURCE") data.Set("client_id", "CLIENT_ID") data.Set("client_secret", "CLIENT_SECRET") req, _ := http.NewRequest("POST", "https://myproject.authgear.cloud/oauth2/token", strings.NewReader(data.Encode())) req.Header.Add("Content-Type", "application/x-www-form-urlencoded") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) fmt.Println("Response Status Code:", resp.StatusCode) fmt.Println("Response Body:", string(body)) } ``` {% endtab %} {% tab title="Node JS" %} ```javascript async function makeRequest() { const url = "https://myproject.authgear.cloud/oauth2/token"; const data = new URLSearchParams(); data.append("grant_type", "client_credentials"); data.append("resource", "IDENTIFIER_OF_API_RESOURCE"); data.append("client_id", "CLIENT_ID"); data.append("client_secret", "CLIENT_SECRET"); const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", }, body: data, }); const responseBody = await response.json(); console.log("Response Status Code:", response.status); console.log("Response Body:", responseBody); } makeRequest(); ``` {% endtab %} {% endtabs %} You’ll receive an access token that includes only the permitted scopes for the client. For details on token structure and claims, see [M2M Tokens](/reference/tokens/m2m-tokens). ### 4. Access Protected APIs Send requests to your API by including the access token in the `Authorization` header: ``` Authorization: Bearer ``` Your backend can now verify the token and authorize the permitted operations. ### 5. Verify Tokens on the API Server Always validate incoming JWT tokens in your API servers: * Verify issuer, audience, scopes, expiration, and signature. * Reject requests with invalid or expired tokens. Find sample code and best practices at [Validate JWT in your backend](/get-started/backend-api/jwt). # Integration by OIDC Using Authgear as an OpenID Connect Provider for any OIDC compatible applications for Single Sign-On. 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 ([Setting up Authgear in the Portal](#setting-up-authgear-in-the-portal)) to setup an **OIDC Client Application**. 2. We are going to use plugin [OpenID Connect Generic Client](https://wordpress.org/plugins/daggerhart-openid-connect-generic/). Or you can use any other OIDC compatible plugin. Download and activate it in your WordPress site. 3. Go to **Setting** > **OpenID Connect Client**. 4. Fill in the form 1. **Client ID**: Obtain the **Client ID** from the **Basic Info** section. 2. **Client Secret Key**: Obtain the **Client Secret** from the **Basic Info** section. 3. **OpenID Scope**: Space separated list of scopes the plugin could access. * Example: `openid offline_access https://authgear.com/scopes/full-userinfo`. * `https://authgear.com/scopes/full-userinfo` is needed to obtain user's profile (e.g. email). Otherwise the plugin will be able to get the user id only. 4. **Login Endpoint URL**: Obtain **Authorization Endpoint** from the **Endpoints** section. * Example: `https://{AUTHGEAR_APP_DOMAIN}/oauth2/authorize`. 5. **Userinfo Endpoint URL**: Obtain **Userinfo Endpoint** from the **Endpoints** section. * Example: `https://{AUTHGEAR_APP_DOMAIN}/oauth2/userinfo`. 6. **Token Validation Endpoint URL**: Obtain **Token Endpoint** from the **Endpoints** section. * Example: `https://{AUTHGEAR_APP_DOMAIN}/oauth2/token`. 7. **End Session Endpoint URL**: Keep it empty. 8. **Identity Key**: Where in the user claim to find the user's identification data. * Suggest to use `sub` which is the user id in Authgear. 9. Setup the user claim keys based on your project login method setting. * If your project is using **email** to login * **Nickname Key**: Set it to `email`. * **Email Formatting**: Set it to `{email}`. * If your project is using **phone** to login * **Nickname Key**: Set it to `phone_number`. * **Email Formatting**: Clear it. * If your project is using **username** to login * **Nickname Key**: Set it to `preferred_username`. * **Email Formatting**: Clear it. 5. At the bottom of the plugin settings page, you will be able to obtain the **Redirect URI**. Go to Authgear portal, add the uri to the **Authorized Redirect URIs**. # Integration by SAML Guides on how to use Authgear as a SAML Identity Provider for Single Sign-On Security Assertion Markup Language or short [SAML](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) 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: * [Use Authgear as SAML Identity Provider for Salesforce](/get-started/single-sign-on-with-saml/use-authgear-as-saml-identity-provider-for-salesforce) * [Use Authgear as SAML Identity Provider for Dropbox](/get-started/single-sign-on-with-saml/use-authgear-as-saml-identity-provider-for-dropbox) ## 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. ## Tools for troubleshooting * Online Base64 decode/encode: # Use Authgear as SAML Identity Provider for Salesforce A guide on how to use Authgear as a SAML Identity Provider IdP in Salesforce Security Assertion Markup Language or short [SAML](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) 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 * An Authgear account. [Sign up](https://authgear.com) for free. * A Salesforce account. ### Step 1: Create an Authgear Client Application An Authgear Client application is required to set up Authgear as a SAML Identity Provider.\ To create an Authgear application, login to the Authgear Portal and navigate to the **Applications** in your project.
Click on **Add Application** to create a new application. Or, select an existing application that is of type `OIDC/SAML Client Application` and skip to step 2. Now on the New Application page, enter a name for your application (e.g. My App) and set the Application Type to "OIDC/SAML Client Application".
Click **Save** to continue. If prompted to view a tutorial, click **Next** to proceed to the application configuration page. ### Step 2: Enable SAML 2.0 in Client Application On the configuration page of your Authgear client application, switch to the **SAML 2.0** tab. Toggle the **SAML 2.0 Support** switch on to enable SAML for the application.
Next, change **NameID Format** to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. Enter your Salesforce domain in the **Allowed Assertion Consumer Service URLs (ACS URLs)** field under SSO Settings. You can get value for your Salesforce domain from the My Domain page on the Salesforce Setup page.
Click on **Save** to keep your changes. ### Step 3: Get SAML Identity Provider (IdP) Configuration and Download Certificate Still, on the SAML 2.0 tab, scroll to the **Configuration Parameters** section and click on the **Download Metadata** button to download the Identity Provider Metadata XML file for your Authgear application to your computer. Next, scroll to the Identity Provider Certificates section and click **Download Certificate** to download the certificate to your computer. You will use the downloaded metadata file and certificate in later steps. ### Step 4: Enable SAML in Salesforce To enable SAML in Salesforce, login to your Salesforce account, click on the Settings icon on the top right corner then select Setup. This will open the Salesforce Setup page.
On the Setup page, type "single sign-on" in the **Quick find** search box on the left. Select **Single Sign-On** from the result to open the **Single Sign-On Settings** page.
Next, click on the **Edit** button under Select Single Sign-On Settings then check the **SAML Enabled** box under **Federated Single Sign-On Using SAML**. Click **Save** to keep your changes.
### Step 5: Add Authgear as SAML IdP in Salesforce To add Authgear as a SAML Identity Provider, return to the main page of Single Sign-On Settings.
Next, click on the **New from Metadata File** button. Then, click Choose file, and select the Metadata XML file you downloaded in [Step 3](#step-3-get-saml-identity-provider-idp-configuration-and-download-certificate). Click on Create to continue. On the next screen, you should see configurations for your new SAML IdP, including the details from the metadata file. Edit the **Name** field to Authgear SAML. The value for the Name field will be visible on your Salesforce login page. Next, click on the Choose file button next to Identity Provider Certificate then select the SAML IdP Certificate file you downloaded in [Step 3](#step-3-get-saml-identity-provider-idp-configuration-and-download-certificate) from your computer.
Once you're done with the above configurations, click **Save** to finish. ### Step 6: Enable Login with SAML in Salesforce In order to log in with a specific SAML IdP, you must first enable the provider in Salesforce. To enable your new SAML IdP (Authgear SAML) search for "my domain" in Quick find. Click on My Domain from the result. On the My Domain page, scroll to **Authentication Configuration** then click on the Edit button.
You should find your Authgear SAMP IdP under **Authentication Service**. Check the box next to Authgear SAML to enable it. Click **Save** to keep changes. Once you have enabled your SAML Identity provider in this step, it will be visible on your Salesforce login page the next time you attempt login. ### Step 7: Log in to Salesforce using Authgear SAML Force you can log in to your Salesforce project using Authgear SAML, you need to create a user using an email address that is linked to a user account in your Authgear project. To create a user in Salesforce, use type "users" in the Quick find search box, then select **Users** > **Users** from the result. This will take you to the All Users page. From the All Users page, click on **New User**. Create a new user with an email address that's linked to an account on your Authgear project.
Now, to test your SAML implementation, log out of Salesforce and attempt logging in again. This time, you should see a Login with Authgear SAML button. When you click on Login with Authgear SAML, you should be redirected to Authgear Login page. Login to the account on your Authgear project that has the same email address as the new user you created earlier in this step. You should be successfully logged in to your Salesforce project.
# Use Authgear as SAML Identity Provider for Dropbox Guide on how to use Authgear as a SAML IdP for Dropbox ## 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: ``` https://www.dropbox.com/saml_login ``` Click on **Save** to keep your changes. ### Step 3: Get SAML IdP Configuration and Download Certificate Scroll down to the Configuration Parameters section of your Authgear client application's SAML 2.0 tab. Note the value for the login URL. Also, download the **Identity Provider Certificate** for the client application to your computer. You'll use the Login URL and certificate later in the Dropbox Admin console.
### Step 4: Add Authgear SAML IdP in Dropbox Log in to your Dropbox Business Advanced account then click on **Admin console** in the navigation menu.
In the Dropbox Admin console navigate to **Settings** > **Single sign-on**.
Now in the Dropbox Single sign-on settings page, set Single sign-on to **Required**. Then, configure the following: * Paste the value for your Authgear client application's `Login URL` in the `Identity provider sign-in URL` field. * Under **X.509 certificate**, click on the Certificate upload button, then upload the Identity Provider Certificate you downloaded from your Authgear client application in the previous step.
### Step 5: Login to Dropbox Using Authgear SAML To test your SAML implementation, you need to add a new user to your Dropbox with an email address that is associated with a user account in your Authgear project. To add a new user to your Dropbox, navigate to **Admin console** > **People** > **Members** > **Invite member**. Accept the invite for the new user, and try to log in to Dropbox using the registered email address for the new user. You should be redirected to the Authgear SAML login page. On successful login to the Authgear account, you should be redirected and signed in to Dropbox. # SAML Attribute Mapping By default, Authgear includes only the `sub` field in the SAML assertion. SAML Attribute Mapping lets you add other UserInfo fields, such as email, phone number, or name, so your SAML service provider receives the user data it needs. You can map fields directly from the user profile, or transform them with a Go text template before they go into the assertion. ### How attribute mapping works Each mapping has two parts: * **Definition**: declares a SAML attribute by name. This becomes the `Name` of the `` element in the assertion. * **Mapping**: sets the value of that attribute, either from a UserInfo field or from a text template. ### Enable SAML Attribute Mapping #### Prerequisites * A client application with **SAML 2.0 support** enabled. See [Integration by SAML](/get-started/single-sign-on-with-saml) to set one up. #### Steps 1. Open the Authgear Portal and go to **Advanced > Edit Config**. 2. Find your application under `saml.service_providers` by matching its `client_id`. 3. Add an `attributes` block under that service provider with `definitions` and `mappings`. Use the example below as a starting point. 4. Save the config. #### Example Add the `attributes` block under the service provider matching your `client_id`. Leave the existing fields (`acs_urls`, `audience`, `nameid_format`, etc.) untouched, they were set when the SAML application was created. ```yaml saml: service_providers: - client_id: YOUR_CLIENT_ID # ...existing fields, leave as-is... attributes: definitions: - name: family_name - name: given_name - name: placeholder_email mappings: - from: user_profile: pointer: /given_name to: saml_attribute: given_name - from: user_profile: pointer: /family_name to: saml_attribute: family_name - from: text_template: template: '{{.preferred_username}}@example.com' to: saml_attribute: placeholder_email ``` The `attributes` block adds three attributes: `family_name`, `given_name`, and `placeholder_email` to every SAML assertion issued to this service provider. ### Configuration reference #### `definitions` Each entry declares one SAML attribute. | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `name` | string | Yes | The attribute name. Used as the `Name` of the `` element in the assertion. | | `name_format` | string | No | Sets the `NameFormat` attribute. See [SAML Core 2.7.3.1](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). | | `friendly_name` | string | No | Sets the `FriendlyName` attribute. | #### `mappings` Each mapping sets the value of one declared attribute. Two source types are supported. **Map from a user profile field** Use a JSON pointer to reference any field in the UserInfo object. ```yaml - from: user_profile: pointer: /email to: saml_attribute: email ``` | Field | Description | | --------------------------- | ------------------------------------------------------------------------------------------------ | | `from.user_profile.pointer` | JSON pointer to a UserInfo field, e.g. `/sub`, `/email`, `/phone_number`, `/preferred_username`. | | `to.saml_attribute` | Name of the target SAML attribute. Must match one declared in `definitions`. | The SAML value type is derived from the JSON type: strings become `xs:string`, numbers become `xs:decimal`, booleans become `xs:boolean`, and arrays produce multiple `` elements. {% hint style="info" %} A field referenced by `pointer` must exist in the UserInfo. Missing fields produce an attribute with no ``. {% endhint %} **Map from a text template** Use a [Go text template](https://pkg.go.dev/text/template) to build the value. The template receives the UserInfo object as its context. ```yaml - from: text_template: template: '{{.preferred_username}}@example.com' to: saml_attribute: placeholder_email ``` The output is always rendered as `xs:string`. Missing fields render as empty strings. {% hint style="warning" %} Mapping order matters. If two mappings write to the same `saml_attribute`, the later one overrides the earlier one. {% endhint %} # Authentication Implement Authgear to control access to your applications Authgear simplifies the use of open industry standards like OAuth 2.0, and OIDC. Users can log into your applications with a variety of user login options. This set of how-to guides provides you with detailed instructions, code snippets, and configuration examples for each type of login method. # Passwords Configure settings for both Primary and Secondary passwords ## 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. ## Primary password settings 1. Navigate to **Authentication** > **Login Methods**. 2. Select your **Login Method**. The login method selected determines the options available to customize. 3. Click on the **Passwords** tab to reveal the settings.
**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). ## Secondary password settings Navigate to **Authentication > 2FA.** You will be able to view the password settings if you enable "Additional Password" as a 2nd-factor authentication. Please note that it is not recommended to use a password for both primary and secondary authentication at the same time.
{% hint style="info" %} In Multi Factor Authentication, users should provide multiple different forms of identification for extra security. {% endhint %} # Change Forgot/Reset Password settings Configure password reset/account recovery processes. 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. # Password Policy Setting format and strength requirements for passwords 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. ## 2. Password Strength #### What is password strength? Password strength is simply a measure of how difficult it is to guess or crack a password. Authgear currently uses the [zxcvbn](https://github.com/dropbox/zxcvbn) password strength estimator library, which goes beyond basic requirements (like length or character variety) and uses pattern matching to recognize common insecure passwords.
How password strength is calculated in Authgear A password is scored for how uncommon and guessable it is using the zxcvbn algorithm. The following table shows the scores for the various minimum password strength levels in Authgear. | Password Strength Level | Score | Description | | ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------------- | | N/A | - | Totally ignore the Advance password strength score and use the Basic password policy. E.g. Minimum password length. | | Extremely guessable | 0 | Too guessable: risky password. (guesses < 10^3) | | Very guessable | 1 | Very guessable: protection from throttled online attacks. (guesses < 10^6) | | Fair | 2 | Somewhat guessable: protection from unthrottled online attacks. (guesses < 10^8) | | Very unguessable | 3 | Safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10^10) | | Extremely unguessable | 4 | Very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10^10) |
### How to set password strength for your Authgear project Scroll down to the Advanced sub-section of the Password tab, then click select your preferred option from the **Min. password strength level** dropdown.
## 3. Prevent Password Reuse Toggle on **Prevent Password Reuse** to ensure a new, unique password is set during password changes. In the following example, the new password cannot match any password used within the 90 days, or any last 3 previously used passwords.
## 4. Keywords to be Excluded from Password You can also disallow specific keywords in the user's password. Simply add them to the "Keywords to be excluded" field, and the admin or user will not be able to set a password containing the listed keywords.
## 5. Password Expiry See [Password Expiry](/authentication-and-access/authentication/passwords/password-expiry) Once you're done, remember to hit **Save** to keep your changes. # Password Expiry Requiring users to reset their password if they haven't logged in after specific number of days You can set up your Authgear project such that a user's password expires after a specific number of days. When a user logs in after the password expiry date, they'll see a prompt to change their password before they're redirected back to your app. {% hint style="info" %} By default, password expiry is turned **off** for your Authgear project. [Recent security research](https://www.ncsc.gov.uk/blog-post/problems-forcing-regular-password-expiry) shows that forcing users to change their passwords after some time can do more harm than good. {% endhint %} ## Enable Password Expiry Navigate to the password settings 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.
## Set Expiry Date You can use the field **Force change since last update (days)** to specify the number of days after which a user's password should expire. For example, setting the value to 90 means the user's password will expire 90 days after the day they set or updated their password. Once you're done, hit the **Save** button to keep your changes. # How to Handle Password While Creating Accounts for Users Recommended practices for setting password for a user account created on the Authgear Portal For creating accounts and sending users their passwords using Admin API, see `createUser` in the [Admin API documentation](https://docs.authgear.com/authentication-and-access/authentication/passwords/pages/k9OsUIA7hmhGI2gB4Ilq#id-2.3.-createuser). 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. {% hint style="info" %} For security reasons, it is not recommended to send users their passwords via text. SMS is unencrypted and insecure for transmitting passwords. {% endhint %} ## How to create a user and send the password via email {% stepper %} {% step %} Navigate to **User Management** > **Users**. From the Users page, click on the **Create User** button in the top right corner.
{% endstep %} {% step %} Enter the user's credentials and input a secure password you wish to set for the user, or click on **Generate** to have Authgear automatically create a new password.
{% endstep %} {% step %} Check the "Send the password to user's email" box to enable Authgear to send the new password to the user. If you wish to force users to change their password upon logging in with the password you set for them, enable "Ask user to change password on login" as well. Otherwise, users can continue using the password you set for them. {% endstep %} {% endstepper %} ## 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. # Reset Password for Users Guide on resetting a user's password via the Authgear Portal or AdminAPI ## How to reset a user's password via Authgear Portal {% stepper %} {% step %} In your project, navigate to **User Management** > **Users**. Then click on the user whose password you would like to reset.
{% endstep %} {% step %} Go to the user's **Account Security** tab, and click on Change Password. You can also require the user to change their password on login by enabling the **Ask to change password on login** toggle.
{% endstep %} {% step %} You can either enter a secure password you wish to set for the user in the **Password** field, or click on **Generate** to have Authgear automatically create a new password for the user. Check the "**Send the password to user's email**" box to enable Authgear to send the password entered in the **Password** field to the user. If you wish to force users to change their password upon logging in with the password you set for them, enable "Ask user to change password on login". Otherwise, users can continue using the password you set for them.
Finally, remember to click **Change** to save your changes. {% endstep %} {% endstepper %} ## How to reset a user's password via AdminAPI See [resetPassword](https://docs.authgear.com/authentication-and-access/authentication/passwords/pages/k9OsUIA7hmhGI2gB4Ilq#id-2.9.-resetpassword) 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. # Add Passkeys Login Passkeys give users a simple and secure way to sign in to your apps and websites across platforms without passwords. Passkeys replace passwords and other passwordless login methods. It is built on the WebAuthn standard (also known as FIDO Sign-in), which uses public key cryptography to authenticate the user. With 1 click, Authgear upgrades your app to support this cutting-edge auth technology. #### Platform support and Multi-devices The passkey standard is supported on the latest versions of Chrome, Safari, and Firefox browsers. On iOS 16 and macOS 13 (Ventura), [Apple has added passkey support](https://developer.apple.com/passkeys/) to the iCloud Keychain service. Passkeys are also [supported on Android 9](https://developers.google.com/identity/passkeys/supported-environments#android-passkey-support) (API level 28) or higher. A passkey is synchronized and relayed with an iCloud account and can be used across a user's devices. Users can log in to their accounts using their biometrics easily. On Apple devices, Touch ID and Face ID authorize the use of the passkey which then authenticates the user on the app or website. #### Hardware security keys Besides the built-in support of all major desktop and mobile platforms, passkeys can also be stored in hardware security keys such as [YubiKeys](https://www.yubico.com/blog/passkeys-and-the-future-of-modern-authentication/), 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! {% hint style="info" %} It will take time for the passkey technology to be available on everyone's devices. In the transition stage, it is recommended to enable "Password" or "Passwordless via Email/Phone" in your project so users with non-compatible devices can access your app. If you want to use ONLY passkeys in your app, it's perfectly supported too! Select **Custom** and deactivate all authenticators in the **Custom Login Methods** tab. Remember to keep **Enable Passkey support for compatible devices.** turned on. {% endhint %} ## 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. # Add WhatsApp OTP Login Allow users to log into your app via OTP with WhatsApp, as a secure alternative to SMS ## Enable WhatsApp OTP in your project 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 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. ## Set up your own WhatsApp Business account By default, WhatsApp OTP are sent via a shared Authgear sender. If you want them to be sent with your own WhatsApp numbers, you need a WhatsApp Business account and a Meta App. This guide shows you how to set up a WhatsApp Business number for Authgear OTP authentication. You will need an unused phone number, and a Facebook account. ### Step 1: Create a business portfolio {% hint style="warning" %} Skip this if you already have an existing business portfolio {% endhint %} 1. Go to [business.facebook.com](https://business.facebook.com/) in a desktop browser. You will also use this address to log into Meta Business Suite. If you already have access to Meta Business Suite, you can also click the dropdown menu located at the top of the left menu. Then skip to Step 4. 2. Click **Create account**. 3. Log into your personal Facebook account. If you don’t have an account, click **Create account** to sign up for one. 4. Click **Create a business portfolio**. 5. Enter your business details. * **Business portfolio name**. It should match the public name of your business or organization, since it will be visible across Meta. It can't contain special characters. * **Your name**. * **Business email**. Meta will use this email to contact you about your business. It won't be visible to your customers. 6. Click **Submit** or **Create** to create your portfolio. You’ll get an email asking to confirm your business email address. ### Step 2: Register Phone number as a new WhatsApp Business Account 1. Go to “Settings” in Meta Businss Suite 2. Under “Accounts”, go to “WhatsApp accounts” and then “Create a new WhatsApp Business account”
3. Enter the display name and set up the profile image, which will be shown to your users 4. Use a unregistered phone number for the account, Follow the on-screen instructions to verify the phone number 5. Set up payment method in this business portfolio and link the WhatsApp account with the payment method. ### Step 3: Set up Message template 1. Go to “WhatsApp Manager” in Meta Business Suite, if the item is not available in the nav bar, search WhatsApp in “All tools” 2. Go to “Manage templates” and “Create Template”, make sure the correct WhatsApp business account is selected on the top right dropdown.
3. Select “Authentication” type
4. For each language you wish to support, create a template named `one_time_password` 1. Select “Copy Code” under **Code delivery setup** 2. Select “Add security recommendation” under **Content** 3. Set Validity period to 10 minutes
5. The template page should look like this after adding the required languages
### Step 4: Set up Application In this step, we will create a “Meta App” 1. Go to and create a new app 2. Enter an identifier for the meta app and your contact email 3. In User cases, select “**Other**” 4. App type, select “Business” 5. Link to the business portolio created in step 1. 6. After creating the app, select “WhatsApp” in “Add product to your app”
7. In “API Setup”, tap “Generate access token” and select the WhatsApp account we created in Step 2. Then click continue.\ ![](/files/K0Hyqkk269Nx8mdOOypv) 8. Under “From” dropdown, select the phone number we registered in Step 2. Note the “**Phone number ID**” and “**WhatsApp Business Account ID**”. Here if your enter a valid “To” number, you should be able to receive a testing “Hello World” message.
9. Go to “App Settings”, add “Privacy Policy” link; and note the **"App ID"**, and **"App secret"** on this page.
10. Switch App mode to “**Live**” (You may be asked to enter business details for review.) ### Step 5: Set up “System User” 1. Go back to **Meta Business Suite** [business.facebook.com](http://business.facebook.com) 2. Go to “Settings” > “Users” > “System users” 3. Add a new system user 4. Assign the App we created in Step 4 with “Develop app” access 5. Assign the WhatsApp account created in Step 2 with "Message templates (view only)” and “Phone Numbers (view and manage)” access 6. Click “**Generate token**” and note the token created. {% hint style="success" %} Now, give Authgear team the following items: * **Phone number ID** * **WhatsApp Business Account ID** * **Access Token of the System user** * **App ID** * **App Secret** And we will help you set up the connection in the backend {% endhint %} ### Step 6: Set up Automatic SMS Fallback To support automatic fallback to SMS when the WhatsApp delivery failed, we will need to set up a webhook between Meta and the Authgear server to check the delivery status of messages. {% hint style="info" %} You can share app access with the Authgear Team for assistance with this step. {% endhint %} 1. Go back to and manage the app we created 2. Under WhatsApp, go to “Configuration” 3. Fill in the 1. Callback URL: `https://{authgear_endpoint}/whatsapp/webhook` 2. Verify token: A random string 1. e.g. Use `openssl rand -hex 16` command to generate a 32-character sequence 4. Share the **“Verify token”** to the Authgear Team for backend configuration 5. Press “Verify and save”
6. In The “Webhooks” page, select “WhatsApp Business Account” under Product, and then enable the `messages` webhook subscription.
7. Subscribe to the WhatsApp Business Account 1. This step is required to let your facebook app to receive notifications from your whatsapp business account.\ Note, you must be logged in to an account with access to both your Facebook app and Whatsapp Business account to perform these steps: 1. Go to 2. In "Meta App", select your facebook app 3. In User or Page, select "User Token" 4. In "Add a permission", select: * whatsapp\_business\_management * whatsapp\_business\_messaging 5. Press Generate Access Token 6. Then, type `{WABA_ID}/subscribed_apps` as the request path. Replace `{WABA_ID}` with your whatsapp business account ID. 7. Change the request method to `POST`. 8. Press "Submit" 9. Change the request method to `GET`, submit and confirm a new item is created. You should an item like this: ```json { "whatsapp_business_api_data": { "link": "https://www.facebook.com/games/?app_id=1234567890987654", "name": "YOUR APP NAME", "id": "1234567890987654" } }, ``` {% hint style="success" %} Now, give Authgear team the following items: * **Phone number ID** * **WhatsApp Business Account ID** * **Access Token of the System user** * **App ID** * **App Secret** * **Verify Token** And we will help you set up the connection in the backend {% endhint %} # Add Email Magic Link Login Passwordless login with email links Email Login Links, also known as "**magic link**", is a passwordless authentication method that allows users to log into a website or application without using a traditional password. Instead, it relies on a unique link sent to the user's email address. Here's how it works: 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**"
# Add Biometric Login ## Overview {% hint style="info" %} Biometric login is supported for the following operating systems: * iOS 11.3 or higher * Android 6.0 (API 23) or higher {% endhint %} Authgear supports enabling biometric login in the native mobile application. You will need to 1. Enable biometric login in your application via the portal. 2. In the mobile app, use the mobile SDK to enable biometric login for your users. A pair of cryptographic keys will be generated upon registering biometric login. The private key will be stored securely in the device (using Keystore in Android and Keychain in iOS), while the public key is stored in the Authgear server. To authenticate the user, fingerprint or face is presented to unlock the private key, and a digital signed message is sent to the server to proof the authenticity of the user. **Fig 1.0. The following figure shows the sequence for enabling Biometric Login on a supported device:**

Enable Biometric Login

The Client App that is already logged in to a user's account will check if biometrics is supported by the user's device. If the device supports biometric login, it is then enabled. The public key is sent to Authgear server and associated with the logged-in user's account. The flow is then completed and biometric login is enabled for the user on the Client App. **Fig 2.0. The following figure shows the sequence for a user logging in with Biometric:**

Logging in with Biometric

With biometric login already enabled for the user, the next time they need to log in they can initiate a biometric authentication flow which will follow the sequence shown in Fig 2.0 above. Once the biometric login is successful, Authgear server will return an access token and a refresh token. The client application can then use the access token to make authenticated requests. Sounds overwhelming? Authgear's magic handles all these for you. Follow this guide to enable biometric login with a few lines of code in your app. ## Enable biometric authentication for your project 1. In the portal, go to **Authentication > Biometric**. 2. Turn on **Enable biometric authentication**. 3. **Save** the settings. ## Set reasonably short token lifetimes for client applications Biometric login is usually used when you want the user to re-login after a relatively short period of time. For sensitive applications such as financial apps, it's ***recommended*** to use a short refresh token lifetime and a short idle timeout. 1. In the Authgear Portal, go to **Applications** 2. Select the client application that represent the integration with the mobile app 3. Set a short **Refresh Token Lifetime** to say 3,600 seconds (1 hour) 4. Enable **Expire after idling** 5. Set a short **Idle Timeout**, to say 1,800 seconds (30 minutes) By doing so, the end-user's session will be expired 1 hour after their login, or after 30 minutes of inactivity. The end-user will need to authenticate themself again with biometric, even if the app process has not yet been killed. ## Configure SDK so users must re-login after app closed Apart from the short token lifetimes, it's also common for sensitive apps to ask the user to re-login by biometric after the app process is killed and relaunched. The SDK should be configured to use TransientTokenStorage so the tokens are stored in memory, and will be cleared when the app is closed. So the end-users must authenticate with biometrics again. {% tabs %} {% tab title="iOS" %} {% code fullWidth="true" %} ```swift let authgear = Authgear( clientId: "{your_client_id}", endpoint: "{your_app_endpoint}", tokenStorage: TransientTokenStorage()) authgear.configure() { result in switch result { case .success(): // configured successfully case let .failure(error): // failed to configured } } ``` {% endcode %} {% endtab %} {% tab title="Android" %} ```kotlin public class MyAwesomeApplication extends Application { // The client ID of the oauth client. private static final String CLIENT_ID = "a_random_generated_string" // Deployed authgear's endpoint private static final String AUTHGEAR_ENDPOINT = "http://.authgear.cloud/" private Authgear mAuthgear; public void onCreate() { super.onCreate(); mAuthgear = new Authgear(this, CLIENT_ID, AUTHGEAR_ENDPOINT, new TransientTokenStorage()); mAuthgear.configure(new OnConfigureListener() { @Override public void onConfigured() { // Authgear can be used. } @Override public void onConfigurationFailed(@NonNull Throwable throwable) { Log.d(TAG, throwable.toString()); // Something went wrong, check the client ID or endpoint. } }); } public Authgear getAuthgear() { return mAuthgear; } } ``` {% endtab %} {% tab title="React Native" %} ```javascript import React, { useCallback } from "react"; import { View, Button } from "react-native"; import authgear, { TransientTokenStorage } from "@authgear/react-native"; function LoginScreen() { const onPress = useCallback(() => { // Normally you should only configure once when the app launches. authgear .configure({ clientID: "client_id", endpoint: "http://.authgear.cloud", tokenStorage: new TransientTokenStorage() }) .then(() => { authgear .authenticate({ redirectURI: "com.myapp.example://host/path", }) .then(({ userInfo }) => { console.log(userInfo); }); }); }, []); return ( ``` We do not use a package manager such as [Webpack](https://webpack.js.org/), we will retrieve the Authgear Web SDK from Authgear's CDN using IIFE(Immediately-invoked Function Expression) bundle. We can reference a script in our HTML directly: ```html ``` > You can install the Authgear Web SDK as a dependency of your application, it is useful if you are building React or React Native apps. See how to [install the package](https://docs.authgear.com/get-started/single-page-app/website#install-the-authgear-web-sdk). ### Create a main.css file Create a new folder called `public` folder in the project root folder and create another folder called `css` inside the `public` folder. Add a new file in there called `main.css`. This will be used to determine how the log-in and log-out button elements will be hidden on the main page depending on whether a user is authenticated or not. Open the newly-created `public/css/main.css` file and add the following CSS: ```css .hidden { display: none; } label { margin-bottom: 10px; display: block; } ``` After creating an HTML file and applying CSS styles, see now how our page looks like by running `npm run dev` and accessing it at .
### Create an app.js file To add some action to the page, we create a new directory in the `public` folder called `js`, and add a new file there called `app.js`. Copy and paste the following JS code that reads `authgear_config.json` file Authgear app-specific values (`endpoint` and `clientId`) from the endpoint using `fetchAuthConfig` function. Also, it configures a new Authgear client, and defines login and logout logic: ```jsx let authgearClient = null; const fetchAuthConfig = () => fetch("/authgear_config.json"); const configureClient = async () => { const response = await fetchAuthConfig(); const config = await response.json(); authgearClient = window.authgear.default; await authgearClient.configure({ endpoint: config.endpoint, clientID: config.clientID, sessionType: "refresh_token", }).then( () => { console.log("Authgear client successfully configured!"); }, (err) => { console.log("Failed to configure Authgear"); } ); }; const login = async () => { await authgearClient .startAuthentication({ redirectURI: window.location.origin, prompt: "login", }) .then( () => { console.log("Logged in!"); }, (err) => { console.log("Log in failed", err); } ); }; const logout = () => { authgearClient .logout({ redirectURI: window.location.origin, }) .then( () => { console.log("Logged out successfully"); }, (err) => { console.log("Failed to logout"); } ); }; window.onload = async () => { await configureClient(); updateUI(); const query = window.location.search; if (query.includes("code=")) { updateUI(); window.history.replaceState({}, document.title, "/"); } } const updateUI = async () => { const isAuthenticated = authgearClient.sessionState === "AUTHENTICATED"; document.getElementById("btn-logout").disabled = !isAuthenticated; document.getElementById("btn-login").disabled = isAuthenticated; }; ``` ### Understanding the whole picture Let’s breakdown down `app.js` code in the previous section and understand how authentication is achieved with Authgear: **Configure the Authgear client** `fetchAuthConfig`: Firstly, this function makes a request to the `/authgear_config.json` the endpoint we exposed in `server.js` to fetch Authgear app setting values from `authgear_config.json`file. `configureClient`: Once we retrieve the configuration information for the Authgear client from the `authgear_config.json` file and we set up the Authgear client with these settings. It also logs a message to the console, informing whether the configuration was successful or not. **Login flow** `login`: The function is called by the **Login** button previously defined on the HTML page. It performs the login action by calling `authgearClient.startAuthentication` Authgear’s function. It redirects the user to the Auhthgear login page. After the user logs in successfully, they will be redirected back to the same page we set in `redirectURI`. Run the project and click the **Login** button. You should be taken to the **Authgear Login Page** configured for your application.
Go ahead and create a new user or log in using an email (we specified the Passwordless Email login method in the first part). When you try to log in with your email, you should receive a [magic link](https://docs.authgear.com/strategies/email-login-link) to your email box to confirm login operation.
After authenticating successfully, you will be redirected to the page you were before. **Logout flow** `logout`: This function logs the user out and redirects them back to the original page (at). It uses Authgear’s `logout` function and logs a message to the console indicating the result of the operation. **Update the UI** `window.onload`: This is a function that runs when the page loads. It configures the Authgear client and updates the UI. If the page's URL contains a "code=" it means the user is authenticated (`code` the query will be received from the Authgear server), it updates the UI again and removes the "code=" from the URL. **Evaluate the authentication state** `updateUI`: This function updates the status of the login and logout buttons based on whether the user is authenticated or not. In Authgear, you can check if the user has logged in or not with `sessionState` the attribute. If the user is authenticated, we disable the login button and enable the logout button, and vice versa if the user is not authenticated. # Disable Public Signup 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. * Provision users only via admin tools. * Prevent the general public from self-registering. ### How to Disable Public Signup To turn off public registration: 1. Navigate to **Portal** > **Advanced** > **Edit Config**. 2. Find or add the following configuration in your YAML file: ```yaml authentication: public_signup_disabled: true # other configurations... ``` 3. Save your changes # Custom Authentication Flow Allow users to authenticate with a custom flow. Authgear lets you define exactly how users sign up and log in. Instead of using the default UI, you can configure a custom authentication flow — a sequence of steps that controls which identifiers you accept, how you verify them, and how users authenticate. Configure flows in the Authgear portal under **Portal > Advanced > Edit Config**, in the `authentication_flow` section of the YAML. ### Key concepts Before reading the examples, here are the building blocks you'll see throughout the YAML: | Term | What it does | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `signup_flows` | Defines steps for registering a new user | | `login_flows` | Defines steps for authenticating a returning user | | `signup_login_flows` | A single flow that detects whether the user is new or returning, then routes to the appropriate `signup_flow` or `login_flow` | | `type: identify` | A step that asks the user for an identifier (email, phone, etc.) | | `type: verify` | A step that confirms the user owns the identifier (e.g. via OTP) | | `type: authenticate` | A step that authenticates the user with a registered credential | | `type: create_authenticator` | A step that registers a new authenticator for the user | | `one_of` | Lists the allowed options for a step. Required even when there is only one option. | | `target_step` | Links a `verify` or `create_authenticator` step back to the `identify` step that collected the credential | *** ### Prerequisites The examples on this page use OTP-based passwordless authentication over email and SMS. Before adding the YAML config, enable the right login method in the portal: 1. Go to **Authentication > Login Methods** 2. Select **Mobile / Email** 3. Under **Authentication**, select **Passwordless** If you use a different login method (e.g. password-based), the `primary_oob_otp_email` and `primary_oob_otp_sms` authenticators in the examples will not work — adjust the `authentication` values to match your chosen method.
### Example: Signup requiring both email and phone By default, when both email and phone are enabled, users can choose one identifier to sign up with — not both. This example changes that: it requires users to provide and verify both an email address and a phone number during signup. After signup, they can log in with either. {% code lineNumbers="true" %} ```yaml authentication_flow: signup_flows: - name: default steps: - name: setup_email type: identify one_of: - identification: email steps: - type: verify target_step: setup_email - type: create_authenticator name: authenticate_primary_email one_of: - authentication: primary_oob_otp_email target_step: setup_email - name: setup_phone type: identify one_of: - identification: phone steps: - type: verify target_step: setup_phone - type: create_authenticator name: authenticate_primary_phone one_of: - authentication: primary_oob_otp_sms target_step: setup_phone ``` {% endcode %} The signup flow has two sequential steps: `setup_email`, then `setup_phone`. Each step collects one identifier and immediately verifies it with a one-time passcode. The `create_authenticator` step then registers that identifier as a login method, so the user can use it to log in later. `target_step` is required here because the `verify` and `create_authenticator` steps are nested inside an `identify` step — they need to explicitly reference the parent step that collected the credential. {% hint style="warning" %} This config only defines a `signup_flow`. It does not include login steps. Disable **"Automatically sign up a new user if a login ID is not found during login"** in the portal, or returning users may trigger a signup instead of a login. {% endhint %} *** ### Example: Combined signup and login, with both identifiers collected on signup `signup_login_flows` handles new and returning users in one flow. The user enters an identifier (email or phone), and Authgear checks whether an account exists: * Account found → routes to `login_flow` * No account found → routes to `signup_flow` This means your UI only needs one screen — no separate "Log in" and "Sign up" buttons required. The example below combines this with the two-identifier requirement from the previous example. Users log in with whichever identifier they have. New users must verify both a phone number and an email during signup, so they can use either to log in in the future. ```yaml authentication_flow: signup_login_flows: - name: default steps: - type: identify one_of: - identification: phone login_flow: default signup_flow: default - identification: email login_flow: default signup_flow: default login_flows: - name: default steps: - type: identify one_of: - identification: phone steps: - type: authenticate one_of: - authentication: primary_oob_otp_sms - identification: email steps: - type: authenticate one_of: - authentication: primary_oob_otp_email signup_flows: - name: default steps: - type: identify name: setup_id1 one_of: - identification: phone steps: - type: verify target_step: setup_id1 - type: identify name: setup_id2 one_of: - identification: email steps: - type: verify target_step: setup_id2 - identification: email steps: - type: verify target_step: setup_id1 - type: identify name: setup_id3 one_of: - identification: phone steps: - type: verify target_step: setup_id3 - type: create_authenticator one_of: - authentication: primary_oob_otp_sms - authentication: primary_oob_otp_email ``` #### How each part works **`signup_login_flows`** The user picks an identifier — phone or email. Both options point to the same `login_flow: default` and `signup_flow: default`. Authgear looks up the identifier and routes the user automatically. **`login_flows`** For returning users. After identifying themselves, the user receives a one-time passcode — by SMS if they entered a phone number, or by email if they entered an email address. **`signup_flows`** For new users. The flow collects and verifies both identifiers, regardless of which one the user entered first. * **User starts with phone** (`setup_id1: phone`): Authgear verifies the phone number, then asks for an email address (`setup_id2`) and verifies that too. * **User starts with email** (`setup_id1: email`): Authgear verifies the email address, then asks for a phone number (`setup_id3`) and verifies that too. Once both identifiers are verified, the `create_authenticator` step registers the OTP method the user will use to authenticate on future logins. {% hint style="info" %} `setup_id2` and `setup_id3` are separate named steps because the second identifier collected depends on which one the user started with. Each path needs its own named step so `target_step` can reference the right one. {% endhint %} {% hint style="warning" %} When using `signup_login_flows`, disable **"Automatically sign up a new user if a login ID is not found during login"** in the portal. That setting conflicts with the routing logic in `signup_login_flows`. {% endhint %} *** ### Further reading * [Overview of Authentication Flow API](/customization/custom-ui/authentication-flow-api) — use the API to build a fully custom login UI * [Authentication Flow API specification](/reference/apis/authentication-flow-api) — full reference for all flow types, step types, and options # Sessions Control how long users stay signed in, and whether their session survives after the browser is closed. When a user signs in through Authgear on the built-in UI or your [Custom UI](/customization/custom-ui), Authgear remembers the signed-in user with a session cookie on your Authgear domain (e.g. `myproject.authgear.cloud` or your custom domain). Every app in the same project shares this session and it powers Single Sign-On (SSO) across your apps. Control the behavior and expiration of this session in **Authgear Portal** > **Advanced** > **Session**. {% hint style="info" %} Token-based apps (SPAs and native apps using the SDKs) keep their own sessions with refresh tokens. Their lifetimes are configured per application in **Portal** > **Applications**. See [Refresh Token](/reference/tokens/refresh-token) for details. An SDK configured with `isSSOEnabled: false` skips the shared session cookie entirely, see [SSO with mobile apps / websites](/authentication-and-access/single-sign-on/sso-with-mobile-app-web-spa). {% endhint %} ## Session Behavior Session Behavior controls whether a signed-in session survives after the user closes the browser. * **Keep users signed in** (default): The session cookie is persistent. Users stay signed in across browser restarts, until the session expires according to the [Session Expiration](#session-expiration) settings below. * **End session on browser close**: The session cookie is dropped when the user closes the browser, so the user must sign in again next time. Choose this when devices are shared among multiple users, such as kiosks or terminals. {% hint style="warning" %} **End session on browser close** relies on the browser discarding the session cookie. Browsers with session restore enabled (e.g. Chrome's "Continue where you left off") may keep session cookies across restarts. The server-side session still expires according to the Session Expiration settings. {% endhint %} ## Session Expiration Session Expiration controls how long a session can last before the user must sign in again. It applies regardless of the Session Behavior setting. * **Maximum session lifetime**: The longest a session can last before it expires, even if the user stays active. The default is `31449600` seconds (52 weeks). When it expires, the user must sign in again to every app that shares the session. * **Expire after idling** and **Idle timeout**: When enabled (default), the session expires after the user has been inactive for the idle timeout. The default is `2592000` seconds (30 days). For example, with a maximum session lifetime of 52 weeks and an idle timeout of 30 days, a user who visits your apps at least once a month stays signed in for up to a year, while a user who is away for more than 30 days must sign in again. ## Configure with authgear.yaml If you self-host Authgear, the same settings are available under the `session` key in `authgear.yaml`: ```yaml session: # End session on browser close. Default is false (keep users signed in). use_session_cookie: false # Maximum session lifetime in seconds. Default is 31449600 (52 weeks). lifetime_seconds: 31449600 # Whether the session expires after idling. Default is true. idle_timeout_enabled: true # Idle timeout in seconds. Default is 2592000 (30 days). idle_timeout_seconds: 2592000 ``` # Single Sign-on Overview Provide a seamless user experience across multiple applications with the single sign-on feature. Single sign-on (SSO) is defined as login once, logged in all apps. If you have multiple mobile apps or websites that wants to streamline the user experiences. You can configure your apps to turn on the SSO feature, so the end-users only have to enter their authentication credentials once. There are multiple ways to achieve Single Sign-on, with various pros-and-cons: | | Related Feature | Technical Remarks | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | SSO between Websites with the same apex domain | [Cookie-based Deployment](/get-started/backend-api#forward-cookie-in-http-header) | Requires all of the websites with the same "root domain" (e.g. app1.**example.com** and app2.**example.com**) | | SSO between Mobile Apps and Browsers | [SSO between Mobile App / Websites](/authentication-and-access/single-sign-on/sso-with-mobile-app-web-spa) | Requires the use of `ASWebAuthentication` and `Custom Tab` on iOS/Android respectively | | SSO between two independent mobile apps | [App2App Login](/authentication-and-access/single-sign-on/app2app-authorization) | Based on OIDC App2App | | SSO from a Mobile App to Website | [Pre-Authenticated URLs](/authentication-and-access/single-sign-on/pre-authenticated-urls) | Open a URL from Mobile App and pass the user session along, based on OIDC Token Exchange | | SSO between Mobile Apps from the same publisher |

Keychain Sharing / Android Account Manager

(Contact us if you need it)

| Requires both apps published by the same publisher from App Store. | # App2App Login Perform faster authentication flow via another app installed on the same device. This may be familiar for users from UK, which many neobanks are using the app2app mechanism to authorize the money transfer from 1 bank app to another. The App2App mechanism allows one app to authenticate the user using another apps connected to the auth server installed on the same device. This is achieved by universal links and the apps do not need to share the session via the system browser or the refresh tokens via the token storage. {% hint style="info" %} This is an Enterprise feature, please contact us for using the App2App flow in your project at {% endhint %} 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](/authentication-and-access/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 {% embed url="" %} Demo of the App2App login flow {% endembed %} ### 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.

App2App flow in iOS

A detailed explanation on the technology can be found in [this specification](https://github.com/authgear/authgear-server/blob/main/docs/specs/app2app.md). ### Setting it up in Authgear {% hint style="info" %} This is an Enterprise feature, please contact us for enabling the App2App flow in your project at {% endhint %} #### 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. # App2Web (Pre-authenticated URLs) Use the pre-authenticated URLs feature to open a website from a native app in an authenticated state. Pre-authenticated URLs is a feature that enables single sign-on (SSO) from a mobile application to a website. It allows users who are authenticated on a mobile application to open a website in an authenticated state. An example use case for a pre-authenticated URL is opening a web application in a WebView. ### 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. {% tabs %} {% tab title="Ionic" %} ```javascript authgear .configure({ clientID: '', preAuthenticatedURLEnabled: true }) ``` {% endtab %} {% endtabs %} ### Step 2: Add Allowed Origin to Web App Client Next, add an allowed origin to the web application client in Authgear. Navigate to **Advanced > Edit Config** in the Authgear Portal, find the **web application client** and add the origins you wish to use for Pre-authentication URLs in the `x_pre_authenticated_url_allowed_origins` key. Also set `x_pre_authenticated_url_enabled` to true. ```yaml oauth: clients: - client_id: x_pre_authenticated_url_enabled: true x_pre_authenticated_url_allowed_origins: - - - ... ... ``` 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: {% tabs %} {% tab title="Ionic" %} ```javascript 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 }); ``` {% endtab %} {% endtabs %} 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. {% tabs %} {% tab title="Ionic" %} The following code sample shows how to open the pre-authenticated URL using the `Browser.open()` method in Ionic. 
Browser.open({ url: url }).catch(err =>
      console.error("Couldn't load page", err),
);
{% endtab %} {% tab title="React Native" %} The following code sample shows how to open the pre-authenticated URL using the `Linking.openURL()` method of React Native. 
Linking.openURL(url).catch(err =>
      console.error("Couldn't load page", err),
);
{% endtab %} {% endtabs %} ### 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. {% tabs %} {% tab title="Web" %} In the web application, enable SSO to allow pre-authenticated URLs to work. You can initialize the SDK as following ```typescript import authgear, { PromptOption } from "@authgear/web"; authgear.configure({ endpoint: "AUTHGEAR_ENDPOINT", clientID: "CLIENT_ID", sessionType: "refresh_token", isSSOEnabled: true }); ``` And in the web application URI, trigger authentication as following. Note here `prompt: PromptOption.None` is used to skip the SSO continue screen. ```typescript 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 } ); ```

Use prompt parameter to skip the SSO Continue Screen

In a normal login flow, for example the user browses the web page in the browser rather than from a link in the native app, the prompt should not be used because it will hinder the user from opening the login page. Only use this prompt when an SSO session is surely set in the browser, for instance in conjunction with this Pre-authentication URL feature. {% endtab %} {% endtabs %} # Web2App (From Mobile Apps to Browsers) 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. {% hint style="info" %} It is important that when the SSO feature is ON, don't set the `prompt` parameter when authenticating (e.g. `prompt=login`), it will force to show the login screen. {% endhint %} 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`. {% tabs %} {% tab title="Web" %} ```typescript authgear.configure({ clientID: CLIENT_ID, endpoint: ENDPOINT, sessionType: "refresh_token", isSSOEnabled: true, }); ``` {% endtab %} {% tab title="React Native" %} ```typescript authgear.configure({ clientID: CLIENT_ID, endpoint: ENDPOINT, isSSOEnabled: true, }); ``` {% endtab %} {% tab title="Flutter" %} ```dart final authgear = Authgear( clientID: CLIENT_ID, endpoint: ENDPOINT, isSsoEnabled: true, ); ``` {% endtab %} {% tab title="Xamarin" %} ```csharp var authgearOptions = new AuthgearOptions { ClientId = CLIENT_ID, AuthgearEndpoint = ENDPOINT, IsSsoEnabled = true, }; // Android #if __ANDROID__ var authgear = new AuthgearSdk(GetActivity().ApplicationContext, authgearOptions); #else #if __IOS__ var authgear = new AuthgearSdk(UIKit.UIApplication.SharedApplication, authgearOptions); #endif #endif ``` {% endtab %} {% tab title="iOS" %} ```swift Authgear( clientId: CLIENT_ID, endpoint: ENDPOINT, isSSOEnabled: true, ) ``` {% endtab %} {% tab title="Android" %} ```java new Authgear( getApplication(), CLIENT_ID, ENDPOINT, new PersistentTokenStorage(getApplication()), true // isSsoEnabled = true ); ``` {% endtab %} {% endtabs %} 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](/authentication-and-access/single-sign-on/app2app-authorization) for sharing login session between mobile apps, and [Pre-authenticated URLs](/authentication-and-access/single-sign-on/pre-authenticated-urls) between mobile and web instead. # Force Authgear to Show Login Page Force Authgear to always show login page even if the user have already logged in. When user login / signup to Authgear, it usually starts with your application making a request to the authorization endpoint, which leads to a login or signup screen. If the user is already signed in on the browser, the Single Sign On feature will show a "Continue Screen" instead as follows.
If your application do not want to utilize the Single Sign On feature, and always show the login / sign up screen instead, you can force Authgear to show login page by using `prompt="login"` at the `authorize` endpoint. ### How to Force Authgear to Show Login Page The `prompt="login"` parameter which is defined in the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 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: {% tabs %} {% tab title="Next.js" %} ```typescript import { PromptOption } from "@authgear/nextjs"; // via hook const { signIn } = useAuthgear(); signIn({ prompt: PromptOption.Login }); // via component Sign In ``` {% endtab %} {% tab title="JavaScript" %} ```javascript authgear .startAuthentication({ redirectURI: "", prompt: PromptOption.Login, }) ``` {% endtab %} {% tab title="React Native" %} ```typescript authgear .authenticate({ redirectURI: 'com.reactnativeauth://host/path', prompt: PromptOption.Login, }) ``` {% endtab %} {% tab title="Android" %} ```java AuthenticateOptions options = new AuthenticateOptions(""); List 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()); } }); ``` {% endtab %} {% tab title="iOS" %} ```swift authgear?.authenticate( redirectURI: "", prompt: "login" ) ``` {% endtab %} {% tab title="Flutter" %} ```dart _authgear.authenticate( redirectURI: "", prompt: "login", ); ``` {% endtab %} {% endtabs %} # Social/Enterprise Login Providers Overview Add third-party identity providers to enable frictionless sign in for your users Authgear supports the following social and enterprise identity providers. Please click the link below for setup instructions. * [Apple](/authentication-and-access/social-enterprise-login-providers/social-login-providers/apple) * [Google](/authentication-and-access/social-enterprise-login-providers/social-login-providers/google) * [Facebook](/authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook) * [GitHub](/authentication-and-access/social-enterprise-login-providers/social-login-providers/github) * [Linkedin](/authentication-and-access/social-enterprise-login-providers/social-login-providers/linkedin) * [Azure Active Directory](/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadv2) * [Azure AD B2C](/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadb2c) * [Microsoft AD FS](/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/adfs) * [Mobile application with WeChat Login](/authentication-and-access/social-enterprise-login-providers/social-login-providers/wechat-mobile) * [Website with WeChat Login](/authentication-and-access/social-enterprise-login-providers/social-login-providers/wechat-web) # Social Login Providers # Connect Apps to Apple ## 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](https://en.wikipedia.org/wiki/Sender_Policy_Framework)(SPF) for your domain. 5. Set up [DomainKeys Identified Mail](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail)(DKIM) for your domain. 6. Create an "App ID" by adding a new "Identifier" [here](https://developer.apple.com/account/resources/identifiers/list), choose app IDs, enable "Sign in with Apple" enabled. 7. Create a "Services ID" by adding a new "Identifier" [here](https://developer.apple.com/account/resources/identifiers/list), 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.

Select here to see Services IDs

9. Fill in and verify the domain created above, add `https:///sso/oauth2/callback/apple` to **Return URLs** 10. Create a "Key" following [this guide](https://developer.apple.com/help/account/manage-keys/create-a-private-key) 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. {% hint style="info" %} Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} ## 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! # Connect Apps to Google Add Google Sign in to your apps in less than 5 minutes. ## Set up OAuth client on Google Cloud Platform To configure Google OAuth client for Authgear, you will need to create an OAuth client on Google Cloud Platform first. ### Create a new project Create a project on Google Cloud Platform through [console](https://console.cloud.google.com/). 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:///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. ![OAuth Client ID in the Credentials page](/files/-McJOJ3udcqQVoWtkIC4) {% hint style="info" %} Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} You can find more details in [official Google Cloud Platform doc](https://support.google.com/cloud/answer/6158849) ## 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. ![Get your OAuth Client ID and Secret in the details page](/files/-McJPyCf7dBJNuKM3wbr) You will need the values of **Client ID**, **Client secret** to configure Google Sign In. ### Configure in Authgear Portal 1. In the portal, go to **Authentication > Social / Enterprise Login**. 2. Enable **Sign in with Google**. 3. Fill in the **Client ID** and **Client Secret** with the values obtained from the previous step. 4. **Save** the settings. 🎉Done! You have just added Google Sign In to your apps! Your end-users can now sign in with Google on Authgear pre-built Log In and Sign Up page. Existing end-users can connect their account to Google in the [User Settings](/customization/built-in-ui/user-settings) page. !["Sign in with Google" in Log in and Sign up page](/files/-McJU398f7UHlO5uhNxO) ![Your end-users can connect to their Google account in User Settings page](/files/-McJU396Aj4hNZi3-9Tl) # Connect Apps to Facebook Add Facebook Sign in to your apps in less than 5 minutes. This guide shows how to connect your Authgear application to Facebook so users can log in using the Login with Facebook feature.
## 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 [Facebook for Developers](https://developers.facebook.com/) website. ### Create an App To create a new app, go to the Facebook Developers [Apps](https://developers.facebook.com/apps) panel then click the Click **Create App** button.
On the "**Use cases**" screen, select **Others** and "**Authenticate and request data from users with Facebook Login**" as your app **use case** then, click **Next**.
Follow the on-screen instructions to finish the app creation process. ## Step 2: Add "email" permission 1. Go to "Use Cases" configuration in your application just created. 2. Customize the "Authenticate and request data from users with Facebook Login" use case. 3. Enable "email" permission, make sure both "public\_profile" and "email" are enabled.
## Step 3: Set up the OAuth Client 1. In the use case settings, make sure **Client OAuth Login** and **Web OAuth Login** are enabled. 2. Add `https:///sso/oauth2/callback/facebook` to **Valid OAuth Redirect URIs** and save the changes.
{% hint style="info" %} Redirect URI has the form of `https:///sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. See [Your Authgear Endpoint](/reference/glossary#your-authgear-endpoint) for instructions on how to get the value for `YOUR_AUTHGEAR_ENDPOINT`. {% endhint %} ## Step 4: Configure Login with Facebook in Authgear Portal ### Get your OAuth Client details After setting up the OAuth Client, 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. App review submission maybe needed to complete this step. Please follow the on-screen instructions. ### 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, and **Client Secret** with the **App Secret** 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 [User Settings](/customization/built-in-ui/user-settings) page. ![Your end-users can connect to their Facebook account in User Settings page](/files/-McNqWHx3umxmzdNPuX2) # Connect Apps to GitHub ## Prerequisite 1. Follow the [official guide](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) to create a OAuth App. 2. In "Authorization callback URL", use `https:///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! # Connect Apps to LinkedIn Guide on how to add LinkedIn as a social login provider ## Prerequisite * A LinkedIn Developer profile. You can create one on the [LinkedIn Developers Portal](https://developer.linkedin.com/). * LinkedIn App ### Step 1: Create a LinkedIn App Log in to the [LinkedIn Developers Portal](https://developer.linkedin.com/) 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:///sso/oauth2/callback/linkedin` to "Authorized redirect URLs" under "OAuth 2.0 settings" section.

LinkedIn app, "Auth" tab

{% hint style="info" %} The redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal {% endhint %} Next, open the **Products** tab of your LinkedIn app, and request access to "Sign In with LinkedIn using OpenID Connect."

LinkedIn app product list

### 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! # Connect Mobile Apps to WeChat {% hint style="info" %} **WeChat Open Platform account (微信开放平台账号)** is different from **WeChat Official account (微信公众平台账号)**. Authgear supports integrating WeChat Login with a WeChat Open Platform account. {% endhint %} ## Prerequisite * Register a [WeChat Open Platform account (微信开放平台账号)](https://open.weixin.qq.com/). * Register a Mobile Application (移动应用). * For **iOS**, the **Associated Domains and Universal Links** supports are required in your app. See [the official documentation](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/) from Apple for details. * For **Android**, the **MD5 fingerprint of the signing keystore** is required See [Appendix: Create mobile app on WeChat Open Platform](#appendix-create-mobile-app-on-wechat-open-platform) for more details. {% hint style="warning" %} **WeChat login is incompatible with Passkey** Login with WeChat requires the use of `WebKitWebViewUIImplementation` which does not support the use of Passkey APIs. At the moment, either passkey or WeChat login can be enabled in your mobile applications. {% endhint %} ## Get the information from WeChat Open Platform Once your mobile app is approved on the platform, you will see the word ":white\_check\_mark:已通过" in the app details page. * Get the `appid` (**Client ID**).
where to find appid

where to find appid

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

where to find appsecret

* Get the `原始ID` (**Account ID**) of your WeChat Open Platform account.
where to find account ID

where to find account ID

## 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 Mobile / 移动应用**. 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. Add a WeChat Redirect URI. This is typically a custom URI with the scheme being your iOS bundle identifier or your Android package name. For example, `com.myapp://authgear/open_wechat_app`. 10. Save. ## Integrate the WeChat SDK into your iOS app {% hint style="info" %} You can skip this section if you do not have an iOS app. {% endhint %} {% hint style="info" %} This section assumes you install the WeChat SDK with [CocoaPods](https://cocoapods.org/). {% endhint %} To integrate the WeChat SDK into your iOS app, you have to read [the official integration guide](https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Access_Guide/iOS.html). This section reminds you some of the important points that you may miss in the official integration guide. ### Install the latest version of the WeChat SDK for iOS ``` pod "WechatOpenSDK-XCFramework", "~> 2.0.4" ``` The latest version can be found at [this URL](https://cocoapods.org/pods/WechatOpenSDK) As of the time of writing, the latest version is `2.0.4`. ### Specify your WeChat `appid` in Info.plist ``` CFBundleURLTypes CFBundleTypeRole Editor CFBundleURLName weixin CFBundleURLSchemes wxYOUR_WECHAT_APPID ``` ### Specify LSApplicationQueriesSchemes in Info.plist ``` LSApplicationQueriesSchemes weixin weixinULAPI weixinURLParamsAPI ``` In case you have other schemes, you need to make sure the WeChat ones are the first 50 items. ### Make sure `OTHER_LDFLAGS` contains `-ObjC` {% hint style="info" %} If you fail to do so, you will encounter [this error](https://developers.weixin.qq.com/community/develop/article/doc/000e8e316d4590c7ef92ec1a366c13). {% endhint %} The WeChat SDK for iOS depends on the Objective-C runtime. Therefore, your app has to link to the Objective-C runtime. To do so, you need to make sure `OTHER_LDFLAGS` contains `-ObjC`. The `-ObjC` flag is so special in CocoaPods that you **CANNOT** add it with CocoaPods [post\_install](https://guides.cocoapods.org/syntax/podfile.html#post_install) hook. If your iOS app is written in [React Native](https://reactnative.dev/), the app is likely to have `OTHER_LDFLAGS` including `-ObjC` already, as React Native depend on the Objective-C runtime. In other case, you need to manually edit your Build Settings to include the `-ObjC` flag. ### Add the integration code for the WeChat SDK for iOS {% tabs %} {% tab title="Swift WeChat SDK" %} In your `AppDelegate.swift` ```swift @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate, WXApiDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Insert this line to register your WeChat mobile application. WXApi.registerApp("wxYOUR_WECHAT_APPID", universalLink: "https://myapp.com/wechat/") return true } func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { // Forward the URL to the WeChat SDK. // If the URL is about WeChat integration, onResp will be called. WXApi.handleOpen(url, delegate: self) return true } func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool { // Forward the URL to the WeChat SDK. // If the URL is about WeChat integration, onResp will be called. WXApi.handleOpen(url, delegate: self) return true } func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool { // Forward the NSUserActivity to the WeChat SDK. // If the NSUserActivity is about WeChat integration, onResp will be called. WXApi.handleOpenUniversalLink(userActivity, delegate: self) return true } // Implements WXApiDelegate. // You need not do any thing special in this method. func onReq(_ req: BaseReq) {} // The WeChat SDK will call this method if the forwarded callbacks are about WeChat. func onResp(_ resp: BaseResp) { guard let authResp = resp as? SendAuthResp else { return } let errCode = WXErrCode(rawValue: authResp.errCode) if errCode == WXSuccess { let state = authResp.state let code = authResp.code // Forward code to Authgear SDK. } else { // Handle the error returned by the WeChat SDK properly to deliver good user experience. } } } ``` In your `SceneDelegate` (if you have one) ```swift class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { // Assume your AppDelegate is the single point of handling WeChat callback, // you need to get it back. let appDelegate = UIApplication.shared.delegate as? AppDelegate // Forward the NSUserActivity to the WeChat SDK. // If the NSUserActivity is about WeChat integration, onResp on AppDelegate will be called. WXApi.handleOpenUniversalLink(userActivity, delegate: appDelegate) } } ``` {% endtab %} {% tab title="Objective-C WeChat SDK" %} In your `AppDelegate.h` ```objc // Import the WeChat SDK header file. #import // Declare your AppDelegate to be a WXApiDelegate. @interface AppDelegate : UIResponder @end ``` In your `AppDelegate.m` ```objc @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Insert this line to register your WeChat mobile application. [WXApi registerApp:@"wxYOUR_WECHAT_APPID" universalLink:@"https://myapp.com/wechat/"]; return true; } - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url { // Forward the URL to the WeChat SDK. // If the URL is about WeChat integration, onResp will be called. [WXApi handleOpenURL:url delegate:self]; return true; } - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { // Forward the URL to the WeChat SDK. // If the URL is about WeChat integration, onResp will be called. [WXApi handleOpenURL:url delegate:self]; return true; } - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray> * __nullable restorableObjects))restorationHandler { // Forward the NSUserActivity to the WeChat SDK. // If the NSUserActivity is about WeChat integration, onResp will be called. [WXApi handleOpenUniversalLink:userActivity delegate:self]; return true; } // Implements WXApiDelegate. // You need not do any thing special in this method. -(void) onReq:(BaseReq*)req { } // The WeChat SDK will call this method if the forwarded callbacks are about WeChat. -(void) onResp:(BaseResp*)resp { if([resp isKindOfClass:[SendAuthResp class]]) { SendAuthResp *sendAuthResp = (SendAuthResp*)resp; if (sendAuthResp.errCode == WXSuccess) { NSString *state = sendAuthResp.state; NSString *code = sendAuthResp.code; // Forward code to Authgear SDK. } else { // Handle the error returned by the WeChat SDK properly to deliver good user experience. } } } @end ``` In your `SceneDelegate.m` (if you have one) ```objc @implementation SceneDelegate - (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity { // Assume your AppDelegate is the single point of handling WeChat callback, // you need to get it back. AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate]; // Forward the NSUserActivity to the WeChat SDK. // If the NSUserActivity is about WeChat integration, onResp on AppDelegate will be called. [WXApi handleOpenUniversalLink:userActivity delegate:appDelegate]; } @end ``` {% endtab %} {% endtabs %} ## Integrate the WeChat SDK into your Android app {% hint style="info" %} You can skip this section if you do not have an Android app. {% endhint %} To integrate the WeChat SDK into your Android app, you have to read [the official integration guide](https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Access_Guide/Android.html). This section reminds you some of the important points that you may miss in the official integration guide. ### Install the latest version of the WeChat SDK for Android ``` implementation "com.tencent.mm.opensdk:wechat-sdk-android:6.8.34" ``` The latest version can be found at [this URL](https://central.sonatype.com/artifact/com.tencent.mm.opensdk/wechat-sdk-android) As of the time of writing, the latest version is `6.8.34`. ### Declare `` in your `AndroidManifest.xml` You need to declare in your `AndroidManifest.xml` that your app is supposed to query the existence of the WeChat app at runtime. Add this to your `AndroidManifest.xml`. ```xml ``` ### Declare your callback Activity in your `AndroidManifest.xml` The WeChat SDK opens the Activity `PACKAGE_NAME.wxapi.WXEntryActivity`. You need to implement that Activity and declare it in your `AndroidManifest.xml`. ```xml android:name="com.myapp.wxapi.WXEntryActivity" android:exported="true" android:launchMode="singleTask" android:taskAffinity="com.myapp" android:theme="@android:style/Theme.Translucent.NoTitleBar"> ``` ### Implement the callback Activity The full Java name of the Activity must be `PACKAGE_NAME.wxapi.WXEntryActivity`. If the package name you tell WeChat Open Platform is `com.myapp`, then the full Java name of the Activity must be `com.myapp.wxapi.WXEntryActivity`. Here is an example implementation that is based on BroadcastReceiver: ```java import com.tencent.mm.opensdk.constants.ConstantsAPI; import com.tencent.mm.opensdk.modelbase.BaseReq; import com.tencent.mm.opensdk.modelbase.BaseResp; import com.tencent.mm.opensdk.modelmsg.SendAuth; import com.tencent.mm.opensdk.openapi.IWXAPI; import com.tencent.mm.opensdk.openapi.IWXAPIEventHandler; import com.tencent.mm.opensdk.openapi.WXAPIFactory; public class WXEntryActivity extends Activity implements IWXAPIEventHandler { private IWXAPI api; @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); api = WXAPIFactory.createWXAPI(this, "wxYOUR_WECHAT_APPID", true); api.registerApp("wxYOUR_WECHAT_APPID"); try { Intent intent = getIntent(); api.handleIntent(intent, this); } catch (Exception e) { e.printStackTrace(); } } @Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); setIntent(intent); api.handleIntent(intent, this); } @Override public void onReq(BaseReq req) { } @Override public void onResp(BaseResp resp) { String error = null; switch (resp.errCode) { case BaseResp.ErrCode.ERR_OK: break; case BaseResp.ErrCode.ERR_USER_CANCEL: error = "errcode_cancel"; break; case BaseResp.ErrCode.ERR_AUTH_DENIED: error = "errcode_deny"; break; case BaseResp.ErrCode.ERR_UNSUPPORT: error = "errcode_unsupported"; break; default: error = "errcode_unknown"; break; } if (resp.getType() == ConstantsAPI.COMMAND_SENDAUTH) { SendAuth.Resp authResp = (SendAuth.Resp)resp; String state = authResp.state; Intent intent = new Intent(state); intent.putExtra("state", state); intent.setPackage(this.getApplicationContext().getPackageName()); if (error != null) { intent.putExtra("error", error); } else { intent.putExtra("code", authResp.code); } this.getApplicationContext().sendBroadcast(intent); } finish(); } } ``` ### Make sure your Android app is signed by the keystore you tell WeChat Open Platform On WeChat Open Platform, you need to tell it the MD5 fingerprint of the keystore you use to sign your Android app. If you use Google Play Console to distribute your Android app, it is likely that you are using [Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en). With Play App Signing, you tell Google the fingerprint of the keystore you originally sign your app. Google removes the signature and uses its managed keystore to sign the app before distributing the app to Play Store. The final app running on the device of course bears the signature of the managed keystore. This is also the signature the WeChat SDK sees when it validates the signature. To get the MD5 fingerprint of the managed keystore, refer to the following screenshot:
where to find the MD5 fingerprint of the managed keystore

where to find the MD5 fingerprint of the managed keystore

Note that the MD5 fingerprint you see on Google Play Console is a **colon-delimited uppercase hex string**, while WeChat Open Platform expects you to provide a **plain lowercase hex string**. For example, suppose the MD5 fingerprint you get from Google Play Console is `D4:1D:8C:D9:8F:00:B2:04:E9:80:09:98:EC:F8:42:7E`, you can use the following shell command to do the conversion. ```sh $ echo "D4:1D:8C:D9:8F:00:B2:04:E9:80:09:98:EC:F8:42:7E" | sed 's/://g' | tr 'A-Z' 'a-z' d41d8cd98f00b204e9800998ecf8427e ``` The output `d41d8cd98f00b204e9800998ecf8427e` is in the expected WeChat Open Platform format. For those of you who produce the final signature of your app using your own keystore, you can use the following shell command to output the MD5 fingerprint. ```sh keytool -exportcert -keystore "$STORE_FILE" -storepass "$STORE_PASSWORD" -alias "$KEY_ALIAS" -rfc | openssl x509 -noout -fingerprint -md5 ``` Where * `STORE_FILE` is an environment variable pointing to the keystore file on your machine, for example, `./mykeystore.jks`. * `STORE_PASSWORD` is an environment variable containing the password of the keystore. * `KEY_ALIAS` is an environment variable indicating which key in the keystore to use. ## Configure Authgear SDK for WeChat You have 2 actions to take: 1. Switch to `WebKitWebViewUIImplementation` when you initialize the Authgear SDK. 2. Implement the callback / delegate of `WebKitWebViewUIImplementation`. ### Switch to `WebKitWebViewUIImplementation` {% tabs %} {% tab title="iOS WebKitWebViewUIImplementation" %} ```swift import Authgear let uiImplementation = WKWebViewUIImplementation() // Put the WeChat redirect URI you added in the Authgear portal here. uiImplementation.wechatRedirectURI = URL(string: "com.myapp://authgear/open_wechat_app")! // You need to implement the delegate to bridge between the WeChat SDK and the Authgear SDK. uiImplementation.authgearDelegate = self self.authgear = Authgear( clientId: "AUTHGEAR_CLIENT_ID", endpoint: "https://myapp.authgear.cloud", uiImplementation: uiImplementation ) ``` {% endtab %} {% tab title="Android WebKitWebViewUIImplementation" %} ```java WebKitWebViewUIImplementation impl = new WebKitWebViewUIImplementation(); impl.setWechatRedirectURI(Uri.parse("com.myapp://authgear/open_wechat_app")); impl.setAuthgearDelegate(this); boolean isSsoEnabled = false; boolean isPreAuthenticatedURLEnabled = false; this.mAuthgear = new Authgear( this.getApplicationContext(), "AUTHGEAR_CLIENT_ID", "https://myapp.authgear.cloud", new TransientTokenStorage(), impl, isSsoEnabled, isPreAuthenticatedURLEnabled, null, null ); ``` {% endtab %} {% tab title="React Native WebKitWebViewUIImplementation" %} ```typescript import authgear, { WebKitWebViewUIImplementation, } from '@authgear/react-native'; authgear.configure({ clientID: "AUTHGEAR_CLIENT_ID", endpoint: "https://myapp.authgear.cloud", uiImplementation: new WebKitWebViewUIImplementation({ ios: { wechatRedirectURI: "com.myapp://authgear/open_wechat_app", }, android: { wechatRedirectURI: "com.myapp://authgear/open_wechat_app", }, // You need to implement this callback to bridge between the WeChat SDK and the Authgear SDK. sendWechatAuthRequest, }), }) ``` {% endtab %} {% tab title="Flutter WebKitWebViewUIImplementation" %} ```dart import 'package:flutter_authgear/flutter_authgear.dart'; var authgear = Authgear( clientID: "AUTHGEAR_CLIENT_ID", endpoint: "https://myapp.authgear.cloud", uiImplementation: WebKitWebViewUIImplementation( options: WebKitWebViewUIImplementationOptions( ios: WebKitWebViewUIImplementationOptionsIOS( wechatRedirectURI: "com.myapp://authgear/open_wechat_app", ), android: WebKitWebViewUIImplementationOptionsAndroid( wechatRedirectURI: "com.myapp://authgear/open_wechat_app", ), // You need to implement this callback to bridge between the WeChat SDK and the Authgear SDK. sendWechatAuthRequest: sendWechatAuthRequest, ), ), ) ``` {% endtab %} {% endtabs %} ### Implement the callback / delegate of `WebKitWebViewUIImplementation` {% hint style="info" %} This section assume you have integrated the WeChat SDK according to * [Add the integration code for the WeChat SDK for iOS](#add-the-integration-code-for-the-wechat-sdk-for-ios) * [Implement the callback Activity](#implement-the-callback-activity) In particular, * On iOS, you implement `WXApiDelegate` on your `AppDelegate`. * On Android, your `WXEntryActivity` sends a broadcast with `state` being the Intent action. {% endhint %} {% tabs %} {% tab title="iOS Authgear WeChat" %} In your `AppDelegate.swift` ```swift import Authgear @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate, WXApiDelegate, AuthgearDelegate { // authgear is assumed to be initialised somewhere else. var authgear: Authgear! // Implements AuthgearDelegate func sendWechatAuthRequest(_ state: String) { // Open WeChat using the WeChat SDK. let req = SendAuthReq() req.scope = "snsapi_userinfo" req.state = state WXApi.send(req) } // Implements WXApiDelegate func onResp(_ resp: BaseResp) { guard let authResp = resp as? SendAuthResp else { return } let errCode = WXErrCode(rawValue: authResp.errCode) if errCode == WXSuccess { let state = authResp.state let code = authResp.code // Forward code to Authgear SDK. self.authgear?.wechatAuthCallback(code: code, state: state) { result in switch result { case .success(): // The code was sent to Authgear successfully. // The end-user will proceed the login in the WebView. // You do not need to do anything here. break case let .failure(error): // Handle the error returned by the Authgear SDK properly to deliver good user experience. } } } else { // Handle the error returned by the WeChat SDK properly to deliver good user experience. } } } ``` {% endtab %} {% tab title="Android Authgear WeChat" %} In your `MainActivity.java` ```java public class MainActivity extends AppCompatActivity implements AuthgearDelegate { private IWXAPI mWeChatAPI; // mAuthgear is assumed to be initialised somewhere else. private Authgear mAuthgear; @Override public void sendWechatAuthRequest(String state) { if (!this.mWeChatAPI.isWXAppInstalled()) { // Handle WeChat not installed. return; } Context ctx = this.getApplicationContext(); IntentFilter intentFilter = new IntentFilter(state); BroadcastReceiver br; br = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { String state_ = intent.getStringExtra("state"); if (state_ != null && state_.equal(state)) { ctx.unregisterReceiver(br); String code = intent.getStringExtra("code"); String error = intent.getStringExtra("error"); if (code != null) { mAuthgear.wechatAuthCallback(code, state, new OnWechatAuthCallbackListener() { @Override public void onWechatAuthCallback() { // No need to do anything here. } @Override public void onWechatAuthCallbackFailed(Throwable throwable) { // Handle error. } }); } else { // Handle error. } } } } ContextCompat.registerReceiver(ctx, br, intentFilter, ContextCompat.RECEIVER_NOT_EXPORTED); SendAuth.Req req = new SendAuth.Req(); req.scope = "snsapi_userinfo"; req.state = state; this.mWeChatAPI.sendReq(req); } } ``` {% endtab %} {% tab title="React Native Authgear WeChat" %} In your React Native TypeScript code ```typescript import { NativeModules, } from "react-native"; import authgear from '@authgear/react-native'; // This is the callback you pass to WebKitWebViewUIImplementation. async function sendWechatAuthRequest(state: string) { // MyWeChatModule is the Native Module you need to implement yourselves to bridge // between the WeChat SDK and the Authgear SDK. const { code } = await NativeModules.MyWeChatModule.sendWechatAuthRequest(state); await authgear.wechatAuthCallback(code, state); } ``` In your iOS Native Module `MyWeChatModule.h` ```objc #import static NSString *const kMyWeChatModuleNotification = @"MyWeChatModuleNotification"; @interface MyWeChatModule : NSObject @end ``` In your iOS Native Module `MyWeChatModule.m` ```objc #import "MyWeChatModule.h" #import #import @interface MyWeChatModule() @property (nonatomic, strong) RCTPromiseResolveBlock sendWechatAuthResolve; @property (nonatomic, strong) RCTPromiseRejectBlock sendWechatAuthReject; @end @implementation MyWeChatModule RCT_EXPORT_MODULE(MyWeChatModule); - (instancetype)init { if ((self = [super init])) { // Listen to the notification posted by your WXApiDelegate. [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleWechatAuthResult:) name:kMyWeChatModuleNotification object:nil]; } return self; } RCT_EXPORT_METHOD(sendWechatAuthRequest:(NSString *)state resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject) { self.sendWechatAuthResolve = resolve; self.sendWechatAuthReject = reject; dispatch_async(dispatch_get_main_queue(), ^{ SendAuthReq* req = [[SendAuthReq alloc] init]; req.scope = @"snsapi_userinfo"; req.state = state; [WXApi sendReq:req completion:nil]; }); } - (void)handleWechatAuthResult:(NSNotification *)notification { if (notification.userInfo[@"code"]) { self.sendWechatAuthResolve(notification.userInfo); } else { NSString *error = notification.userInfo[@"error"]; self.sendWechatAuthReject(RCTErrorUnspecified, error, error); } [self cleanup]; } - (void)cleanup { self.sendWechatAuthResolve = nil; self.sendWechatAuthReject = nil; } @end ``` In your `WXApiDelegate` ```objc -(void) onResp:(BaseResp*)resp { if ([resp isKindOfClass:[SendAuthResp class]]) { SendAuthResp *sendAuthResp = (SendAuthResp*)resp; NSDictionary *payload; if (sendAuthResp.errCode == WXSuccess) { payload = @{ @"code": sendAuthResp.code, @"state": sendAuthResp.state, }; } else { NSString *error; switch (resp.errCode) { case WXErrCodeUserCancel: error = @"errcode_cancel"; break; case WXErrCodeAuthDeny: error = @"errcode_deny"; break; case WXErrCodeUnsupport: error = @"errcode_unsupported"; break; default: error = @"errcode_unknown"; break; } payload = @{ @"error": error, }; } // Send the notification to your MyWeChatModule. [[NSNotificationCenter defaultCenter] postNotificationName:kMyWeChatModuleNotification object:nil userInfo:payload]; } } ``` In your Android Native Module `MyWeChatModule` ```java import android.content.BroadcastReceiver; import android.content.Context; import android.content.IntentFilter; import androidx.core.content.ContextCompat; import com.facebook.react.bridge.ReactContextBaseJavaModule; import com.tencent.mm.opensdk.openapi.IWXAPI; import com.tencent.mm.opensdk.openapi.WXAPIFactory; public class MyWeChatModule extends ReactContextBaseJavaModule { private IWXAPI wechatAPI; WechatAuthModule(ReactApplicationContext context) { super(context); wechatAPI = WXAPIFactory.createWXAPI(context, "wxYOUR_WECHAT_APPID", true); wechatAPI.registerApp("wxYOUR_WECHAT_APPID"); } @Override public String getName() { return "MyWeChatModule"; } @ReactMethod public void sendWechatAuthRequest(String state, Promise promise) { if (!wechatAPI.isWXAppInstalled()) { promise.reject(new Exception("You have not installed the WeChat client app")); return; } Context ctx = this.getReactApplicationContext(); IntentFilter intentFilter = new IntentFilter(state); BroadcastReceiver br; br = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { String state_ = intent.getStringExtra("state"); if (state_ != null && state_.equal(state)) { ctx.unregisterReceiver(br); String code = intent.getStringExtra("code"); String error = intent.getStringExtra("error"); if (code != null) { WritableMap result = new WritableNativeMap(); result.putString("code", code); result.putString("state", state); promise.resolve(result); } else { promise.reject(error, error); } } } } ContextCompat.registerReceiver(ctx, br, intentFilter, ContextCompat.RECEIVER_NOT_EXPORTED); SendAuth.Req req = new SendAuth.Req(); req.scope = "snsapi_userinfo"; req.state = state; wechatAPI.sendReq(req); } } ``` {% endtab %} {% tab title="Flutter Authgear WeChat" %} In your Flutter code ```dart import 'package:flutter/services.dart'; import 'package:flutter_authgear/flutter_authgear.dart'; // authgear is assumed to be initialised somewhere else. var authgear; const _nativeMethodChannel = MethodChannel("MyWeChatMethodChannel"); // This is the callback you pass to WebKitWebViewUIImplementation. Future sendWechatAuthRequest(String state) async { try { final code = await _nativeMethodChannel.invokeMethod("sendWechatAuthRequest", { "state": state, }); await authgear.wechatAuthCallback(state: state, code: code); } on PlatformException catch (e) { print("exception: $e"); } } ``` In your `AppDelegate.swift` ```swift import Flutter @main @objc class AppDelegate: FlutterAppDelegate, WXApiDelegate { private var wechat = [String: FlutterResult]() override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { let controller = window?.rootViewController as! FlutterViewController let channel = FlutterMethodChannel(name: "MyWeChatMethodChannel", binaryMessenger: controller.binaryMessenger) channel.setMethodCallHandler { (call: FlutterMethodCall, result: @escaping FlutterResult) -> Void in let arguments = call.arguments as! Dictionary let state = arguments["state"] as! String self.wechat[state] = result let req = SendAuthReq() req.scope = "snsapi_userinfo" req.state = state WXApi.send(req) } GeneratedPluginRegistrant.register(with: self) return super.application(application, didFinishLaunchingWithOptions: launchOptions) } override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { WXApi.handleOpen(url, delegate: self) return super.application(app, open: url, options: options) } override func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool { WXApi.handleOpen(url, delegate: self) return super.application(application, open: url, sourceApplication: sourceApplication, annotation: annotation) } override func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool { WXApi.handleOpenUniversalLink(userActivity, delegate: self) return super.application(application, continue: userActivity, restorationHandler: restorationHandler) } @objc func onReq(_ req: BaseReq) { } @objc func onResp(_ resp: BaseResp) { guard let authResp = resp as? SendAuthResp else { return } guard let state = authResp.state else { return } guard let result = wechat.removeValue(forKey: state) else { return } var error: String switch WXErrCode(rawValue: authResp.errCode) { case WXErrCodeUserCancel: error = "errcode_cancel" case WXErrCodeAuthDeny: error = "errcode_deny" case WXErrCodeUnsupport: error = "errcode_unsupported" default: error = "errcode_unknown" } switch WXErrCode(rawValue: authResp.errCode) { case WXSuccess: let code = authResp.code result(code) default: result(FlutterError(code: error, message: error, details: nil)) } } } ``` In your `MainActivity.kt` ```kotlin class MainActivity: FlutterFragmentActivity() { private var api: IWXAPI? = null override fun configureFlutterEngine(flutterEngine: FlutterEngine) { super.configureFlutterEngine(flutterEngine) MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "MyWeChatMethodChannel").setMethodCallHandler { call, result -> handleMethodCall(call, result) } } private fun handleMethodCall(call: MethodCall, result: MethodChannel.Result) { val api = api!! if (!api.isWXAppInstalled) { result.error("errcode_not_installed", "errcode_not_installed", null) return } val state = call.argument("state")!! val req = SendAuth.Req() req.scope = "snsapi_userinfo" req.state = state var broadcastReceiver: BroadcastReceiver? broadcastReceiver = object : BroadcastReceiver() { override fun onReceive(context: Context?, intent: Intent?) { val state_ = intent.getStringExtra("state") if (state_ == state) { this@MainActivity.applicationContext.unregisterReceiver(broadcastReceiver) val code = intent.getStringExtra("code") val error = intent.getStringExtra("error") if (code != null) { result.success(code) } else { result.error(error, error, nil) } } } } val intentFilter = IntentFilter(state) ContextCompat.registerReceiver(this.applicationContext, broadcastReceiver, intentFilter, ContextCompat.RECEIVER_NOT_EXPORTED) api.sendReq(req) } } ``` {% endtab %} {% endtabs %} ## Appendix: Create mobile app on WeChat Open Platform **Prerequisite**: A WeChat account is required for registering the app. These information are required for creating the application on the platform, prepare them before creating the application: ### Basic Information | Field | Meaning in English | Usage | | --------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 移动应用名称 | Mobile app name | The app name shown to the end-user when they login | | 英文名称 | Mobile app name in English | The app name shown to an English end-user when they login | | 移动应用简介 | Mobile app description | A description for the approver to understand the app | | 英文简介 | Mobile app description in English | Optional field | | 应用官网 | Official website of the mobile app | The webpage should show the description of the app and offer links to download it on app stores | | 移动应用图片 | App Icon | A 28x28 and a 108x108 icon | | 应用市场 | Is the app released on any app stores for Chinese users? |

Choose between:
- Unreleased: the login is rate limited to 100 per day
- Released: A Chinese ICP license is required (App备案号), for example: 粤B2-00000000-0000A

| | 应用类目 | App category | Choose from the list of categories defined by the platform that best describe your app | | 应用运行流程图 | Images of app flow | Any flowchart or screenshots showing how the app works | | 申请/修改应用说明 | Application details | Reasons for application, any testing account and testing instruction. | | 管理员身份设置 | Set Admin | Scan the QR code from the WeChat mobile app to prove the admin identity of the app. | ### App configuration #### iOS * Bundle ID * 测试 Bundle (Testing Bundle ID) * Universal Links * 备用 Universal Links (Backup Universal Links) #### Android * 应用包名 (Package name) * 应用签名 (App Signature) # Connect Websites to WeChat {% hint style="info" %} **WeChat Open Platform account (微信开放平台账号)** is different from **WeChat Official account (微信公众平台账号)**. Authgear supports integrating WeChat Login with a WeChat Open Platform account. {% endhint %} ## Prerequisite * Register a [WeChat Open Platform account (微信开放平台账号)](https://open.weixin.qq.com/). * Register a Web Application (网站应用). See [Appendix: Create web app on WeChat Open Platform](#appendix-create-web-app-on-wechat-open-platform) for more details. ## Get the information from WeChat Open Platform Once your mobile app is approved on the platform, you will see the word ":white\_check\_mark: 已通过" in the app details page. * Get the `appid` (**Client ID**)
where to find appid

where to find appid

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

where to find appid

* Get the `原始ID` (**Account ID**) of your WeChat Open Platform account.
where to find account ID

where to find account ID

## 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: | Field | Meaning in English | Usage | | ---------- | --------------------------------------------- | -------------------------------------------------------------------------------------- | | 网站应用名称 | Web app name | The app name shown to the end-user when they login | | 英文名称 | Web app name in English | The app name shown to an English end-user when they login | | 网站应用简介 | Web app description | A description for the approver to understand the app | | 英文简介 | Mobile app description in English | Optional field | | 应用官网 | Official website of the web app | The webpage should show the description of the app | | 网站应用图片 | App Icon | A 28x28 and a 108x108 icon | | 网站信息登记表扫描件 | Scanned copy of the Website Registration Form | A signed registration form about the web app and the business nature and company info. | | 授权回调域 | Authorized redirect domain | Domain of your Authgear endpoint for example: `*.authgear.cloud` | # Enterprise Login Providers # Connect Apps to Microsoft Entra ID (Azure AD) {% hint style="info" %} **Microsoft Entra ID** is the new name for **Azure Active Directory (Azure AD)**. Microsoft renamed the product in 2023; existing Azure AD configurations and integrations continue to work without change. This page uses the current name, but you may still see "Azure AD" in older portals or documentation. {% endhint %} ## Prerequisite 1. Create a Microsoft Entra ID account [here](https://azure.microsoft.com/free) 2. Setup a tenant by completing [Quickstart: Set up a tenant](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant) 3. Register an application by completing [Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) 4. Choose "Supported account types", the following options are supported: * Single tenant only - \ (Accounts in this organizational directory only) * Multiple Entra ID tenants (Accounts in any organizational directory - Multitenant) * Any Entra ID tenant + Personal Microsoft accounts (Multitenant and personal Microsoft accounts, e.g. Skype, Xbox) "Personal 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:///sso/oauth2/callback/azureadv2`. See [How to add a redirect URI to your application](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri). 6. Follow [this](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) 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. {% hint style="info" %} Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} ## 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 Microsoft Entra ID application. 4. Fill in **Client Secret**" with the secret you get after creating a client secret for your Microsoft Entra ID application. 5. For **Tenant** field: * If **single tenant (first option)** is chosen, fill in the **Directory (tenant) ID** of your Microsoft Entra ID 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 Microsoft Entra ID (Azure AD) Login to your apps! ### Force Login page Microsoft Entra ID 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 Microsoft Entra ID to show the login page. See our [guide on using the prompt=login parameter](/authentication-and-access/social-enterprise-login-providers/force-social-enterprise-login-providers-to-show-login-screen) in Authgear SDKs to learn more. # Connect Apps to Microsoft AD FS ## 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:///sso/oauth2/callback/adfs`. {% hint style="info" %} Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} ## 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](/authentication-and-access/social-enterprise-login-providers/force-social-enterprise-login-providers-to-show-login-screen) in Authgear SDKs to learn more. # Connect Apps to Azure AD B2C ## Prerequisite 1. Sign in [Microsoft Azure](https://portal.azure.com/). 2. Create a B2C tenant by following [this tutorial](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-tenant). 3. Enable self-service sign-up for the tenant by following [this doc](https://docs.microsoft.com/en-us/azure/active-directory/external-identities/self-service-sign-up-user-flow#enable-self-service-sign-up-for-your-tenant) 4. Go back the main page of [Microsoft Azure](https://portal.azure.com/) and search for "Azure AD B2C" 5. Create a app registration for Authgear by following [this guide](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga). 6. Configure "Redirect URI" with `https:///sso/oauth2/callback/azureadb2c`. 7. Follow [this guide](https://docs.microsoft.com/en-us/azure/active-directory-b2c/add-sign-up-and-sign-in-policy?pivots=b2c-user-flow) 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 [guide on using the prompt=login parameter](/authentication-and-access/social-enterprise-login-providers/force-social-enterprise-login-providers-to-show-login-screen) in Authgear SDKs to learn more. # Account Linking Connect a social or enterprise login to an existing account that shares the same email, instead of creating a duplicate user or rejecting the signup. When you add social login to an app that already has users, some of them will click **Continue with Google** even though they originally signed up with an email and password. Both identities carry the same email address, but by default Authgear treats the Google signup as an attempt to create a second account and rejects it with an "account already exists" error. Account linking changes what happens next. Instead of an error, Authgear detects that the incoming Google account matches an existing user, asks the user to log in to that account once to prove they own it, then attaches the Google identity to it. The user ends up with one account and two ways to sign in. {% hint style="info" %} Account linking runs automatically **during signup**. To let an already signed-in user connect a provider from your own UI, see [Link and Unlink Social/Enterprise Provider with the SDK](/authentication-and-access/social-enterprise-login-providers/link-and-unlink-social-enterprise-provider-with-the-sdk). Users can also manage their connections on the [User Settings](/customization/built-in-ui/user-settings) page. {% endhint %} ## When to use it Enable account linking when the same person can reach your app through more than one signup method and you want them to keep a single account. Typical situations: * **You added Google login to an app with existing password users.** A user who signed up with `alice@example.com` and a password clicks **Continue with Google**. Their Google account uses the same email. With account linking they log in with their password once, and from then on can sign in with either method. * **You offer several social providers.** A user signs up with Google today and taps **Continue with Apple** on their phone next month. Both accounts share one email; linking keeps them on one Authgear account instead of two. * **You migrated users into Authgear and later enabled an enterprise provider.** Imported users match their Microsoft Entra ID or ADFS accounts by email, so their first enterprise login attaches to the account you imported rather than creating a fresh one. ## How it works When a user signs up with a social or enterprise provider, Authgear reads a claim from the provider's user profile (the email, by default) and compares it against the identities of existing users. What happens on a match depends on the `action` you configure: | Action | Behavior | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `error` | Reject the signup with a "duplicated identity" error. This is the default when account linking is not configured. | | `login_and_link` | Show the user their existing account and ask them to log in to it. After they authenticate, add the new provider identity to that account and continue the signup. | {% hint style="warning" %} The login step in `login_and_link` prevents account takeover. Some identity providers let anyone register with an unverified email, so an email match alone doesn't prove ownership. Without the login step, an attacker could register `alice@example.com` at such a provider and hijack Alice's account. {% endhint %} ## Enable account linking This walkthrough uses Google, but the same configuration works for any provider you have set up. ### Prerequisites * A Google login provider configured in the Portal under **Authentication > Social / Enterprise Login**, with an alias. This guide assumes the alias `google`. See [Connect Apps to Google](/authentication-and-access/social-enterprise-login-providers/social-login-providers/google) if you haven't set this up. ### Add the configuration Configure account linking in your project's YAML config. In the Portal, go to **Advanced > Edit Config** and add an `account_linking` section: ```yaml account_linking: oauth: - alias: google oauth_claim: pointer: "/email" user_profile: pointer: "/email" action: login_and_link ``` Save the config. The change takes effect immediately. Each entry under `account_linking.oauth` defines one linking rule: | Field | Meaning | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `alias` | Which provider this rule applies to. Must match the alias of a provider under **Social / Enterprise Login**. | | `oauth_claim` | A JSON pointer to the claim to read from the incoming provider profile. `/email` reads the email Google reports. | | `user_profile` | A JSON pointer to the attribute to match against existing users' identities. `/email` matches users whose email login ID or standard attribute is the same. | | `action` | What to do on a match: `error` or `login_and_link`. | {% hint style="info" %} `oauth_claim` and `user_profile` accept only `/email`, `/phone_number`, and `/preferred_username`. Matching by email covers Google and most social providers; `/preferred_username` is useful for enterprise providers such as ADFS that identify users by username. {% endhint %} ### What the user experiences With the config above in place, here is the full flow for a user who already has a password account under `alice@example.com`: 1. On the signup page, the user clicks **Continue with Google** and completes Google's consent screen. 2. Authgear finds the existing account and shows an **Existing account found** page listing it with a masked identifier, such as `al***@example.com`. 3. The user selects the account and logs in with their existing method, in this case their password. 4. Authgear links the Google identity to the account. If your signup flow requires steps the account doesn't satisfy yet (for example, setting up two-factor authentication), the user completes them now; steps the account already satisfies are skipped. 5. The user is signed in. From now on, both the password and Google sign the user in to the same account. ## Linking email, phone, or username signups Account linking also covers the reverse direction: a user who signed up with Google first, then tries to sign up with the same email address and a password. Configure it under `account_linking.login_id`: ```yaml account_linking: login_id: - key: email user_profile: pointer: "/email" action: login_and_link ``` `key` names the login ID type (`email`, `phone`, or `username` by default). When a signup with that login ID matches an existing user, the user logs in to the existing account (in this case, through Google) and the new email login ID is added to it. Without this config, the conflicting signup fails with an error, as before. ## Advanced: different rules per signup flow If you define [custom authentication flows](/authentication-and-access/authentication/custom-authentication-flow), you can override a linking rule inside a specific signup flow step. Give the rule a `name` in `account_linking`, then reference that name in the step to override its `action` or pick which login flow handles the login: ```yaml account_linking: oauth: - name: google_linking alias: google oauth_claim: pointer: "/email" user_profile: pointer: "/email" action: error authentication_flow: signup_flows: - name: customer_signup steps: - name: identify type: identify one_of: - identification: oauth account_linking: oauth: - name: google_linking action: login_and_link login_flow: customer_login ``` Here Google linking fails with an error everywhere except the `customer_signup` flow, which allows it and runs the `customer_login` flow for the login step. When `login_flow` is not set, Authgear uses the login flow with the same name as the current signup flow. ## Account linking in Custom UI If you build your own signup UI with the [Authentication Flow API](/customization/custom-ui/authentication-flow-api), account linking appears as an `identify` action whose `data.type` is `account_linking_identification_data`. The data contains the list of matched accounts with masked display names; your UI submits the index of the account the user picks, and the flow continues into the login steps. See the [Authentication Flow API reference](https://github.com/authgear/authgear-server/blob/main/docs/specs/authentication-flow-api-reference.md) for the exact schema. # Force Social/Enterprise Login Providers to Show Login Screen Use OIDC prompt parameter to force OAuth providers to show login screen. The `prompt="login"` parameter which is defined in the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 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. {% tabs %} {% tab title="JavaScript" %} ```javascript authgear .startAuthentication({ redirectURI: "", prompt: PromptOption.Login, }) ``` {% endtab %} {% tab title="React Native" %} ```typescript authgear .authenticate({ redirectURI: 'com.reactnativeauth://host/path', prompt: PromptOption.Login, }) ``` {% endtab %} {% tab title="Android" %} ```java AuthenticateOptions options = new AuthenticateOptions(""); List 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()); } }); ``` {% endtab %} {% tab title="iOS" %} ```swift authgear?.authenticate( redirectURI: "", prompt: "login" ) ``` {% endtab %} {% tab title="Flutter" %} ```dart _authgear.authenticate( redirectURI: "", prompt: "login", ); ``` {% endtab %} {% endtabs %} # Link and Unlink Social/Enterprise Provider with the SDK Let signed-in users connect a social or enterprise login provider to their account, and disconnect it later, from your own UI. This guide uses Google as the example provider, but the same code works for any OAuth provider you have configured. {% hint style="info" %} These SDK methods are currently available in the **web SDK (`@authgear/web`) only**. For other SDKs, use the [User Settings](/customization/built-in-ui/user-settings) page and users can manage their Social/Enterprise connection there. {% endhint %} ### What you will build A page in your app, such as an account details page, that: 1. Reads the signed-in user's linked identities. 2. Shows a **Link** button when the provider is not connected, or an **Unlink** button when it is. 3. Links the provider by redirecting to Google's consent screen, then back to your app. 4. Unlinks the provider by redirecting to an Authgear-hosted confirmation page, then back to your app. Both actions use a browser redirect. The user leaves your app, completes the step on Google's or Authgear's page, and returns to a redirect URI you control. Your callback code calls a `finish` method to complete the action. ### Prerequisites * The `@authgear/web` SDK installed and configured in your app. See [Getting Started](/get-started/start-building). * The user is **already signed in**. Linking and unlinking require an authenticated session. Both methods throw if no valid session exists. * The OAuth provider is configured in the Authgear Portal under **Social / Enterprise Login**, with an alias. This guide uses the alias `google`. * The redirect URI you pass to each method is registered under your application's **Redirect URIs** in the Portal. The examples assume your app configures the SDK with `sessionType: "refresh_token"`. ### Step 1: Check whether the provider is linked Call `fetchUserInfo()` to get the user's info, then inspect the `identities` array. Each OAuth identity has `type === IdentityType.OAuth` and an `oauthProviderAlias` that matches the alias you configured in the Portal. ```typescript import authgear, { IdentityType } from "@authgear/web"; const PROVIDER_ALIAS = "google"; async function isProviderLinked() { const userInfo = await authgear.fetchUserInfo(); return (userInfo.identities ?? []).some( (identity) => identity.type === IdentityType.OAuth && identity.oauthProviderAlias === PROVIDER_ALIAS ); } ``` The raw `identities` claim from the [UserInfo endpoint](/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo) looks like this: ```json { "https://authgear.com/claims/user/identities": [ { "type": "login_id", "login_id_key": "email", "login_id_type": "email" }, { "type": "oauth", "oauth_provider_type": "google", "oauth_provider_alias": "google" } ] } ``` ### Step 2: Show the Link or Unlink button Render the button that matches the current state. {% tabs %} {% tab title="React" %} ```tsx import { useEffect, useState } from "react"; import authgear, { IdentityType } from "@authgear/web"; const PROVIDER_ALIAS = "google"; function ProviderLinkButton() { const [linked, setLinked] = useState(null); useEffect(() => { authgear.fetchUserInfo().then((userInfo) => { const isLinked = (userInfo.identities ?? []).some( (i) => i.type === IdentityType.OAuth && i.oauthProviderAlias === PROVIDER_ALIAS ); setLinked(isLinked); }); }, []); if (linked === null) { return

Loading…

; } return linked ? ( ) : ( ); } ``` {% endtab %} {% tab title="JavaScript" %} ```html
``` {% endtab %} {% endtabs %} ### Step 3: Link the provider Call `startLinkOAuth()`. The SDK redirects the browser to Google's consent screen, where the user signs in and approves the link. After approval, Google redirects back to your `redirectURI`. ```typescript function startLink() { authgear .startLinkOAuth({ oauthProviderAlias: PROVIDER_ALIAS, redirectURI: "https://myapp.com/oauth-callback", state: "link_oauth", }) .catch((err) => { console.error(err); }); } ``` | Option | Type | Required | Description | | -------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- | | `oauthProviderAlias` | string | Yes | The provider alias configured in the Portal, e.g. `google`. | | `redirectURI` | string | Yes | Where the browser returns after the flow. Must be registered in the Portal. | | `state` | string | No | An OAuth state value returned to your callback. You can use it to tell link, unlink, and sign-in callbacks apart. | ### Step 4: Unlink the provider Call `startUnlinkOAuth()`. The SDK redirects the browser to an Authgear-hosted page with an unlink button. The user confirms there, and Authgear redirects back to your `redirectURI`. ```typescript function startUnlink() { authgear .startUnlinkOAuth({ oauthProviderAlias: PROVIDER_ALIAS, redirectURI: "https://myapp.com/oauth-callback", state: "unlink_oauth", }) .catch((err) => { console.error(err); }); } ``` The options are the same as `startLinkOAuth()`. Use a different `state` value so your callback knows which action to finish. ### Step 5: Handle the callback When the user returns to your `redirectURI`, finish the action. Read the `state` query parameter to choose between `finishLinkOAuth()` and `finishUnlinkOAuth()`, then send the user back to your account details page. {% tabs %} {% tab title="React" %} ```tsx import { useEffect } from "react"; import authgear from "@authgear/web"; function OAuthCallback() { useEffect(() => { async function finish() { // configure() must run before any finish method. await authgear.configure({ clientID: "your-client-id", endpoint: "https://myapp.authgear.cloud", sessionType: "refresh_token", }); const state = new URL(window.location.href).searchParams.get("state"); try { if (state === "link_oauth") { await authgear.finishLinkOAuth(); } else if (state === "unlink_oauth") { await authgear.finishUnlinkOAuth(); } // Both actions are done. Return to the account details page. window.location.replace("/account"); } catch (err) { console.error(err); } } finish(); }, []); return

Finishing…

; } ``` {% endtab %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% endtabs %} {% hint style="warning" %} `finishLinkOAuth()` and `finishUnlinkOAuth()` reject with an `OAuthError` if the user cancels or the flow fails. Catch the error and show the user a message before redirecting. {% endhint %} ### Related pages * [UserInfo endpoint reference](/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo): the full `identities` claim. # FAQ for Authentication # OTP Test Mode Suppress message delivery and fix OTP for testing purposes 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](/faq-for-authentication/passwordless-demo-user-for-apple-app-review). ## How to enable test mode In your portal, navigate to Advanced > Edit Config
Then add the following to the yaml: ```yaml test_mode: oob_otp: # rules defined below apply to all OOB channels (email, sms, whatsapp) enabled: true rules: - regex: .* fixed_code: "000000" sms: # channel specific rules defined here enabled: true rules: - regex: .* suppressed: true ``` 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 * `enabled` * Set to `true` to enable test mode * `false` by default. This means the OTP flow will work as expected, and fixed codes will not be accepted for the channel. ## Examples ### Case 1: Development In development, you may want to use a fixed code for testing. ```yaml test_mode: oob_otp: enabled: true rules: - regex: .* fixed_code: "000000" sms: enabled: true rules: - regex: ^\+85291231234$ # SMS not suppressed for +85291231234 - regex: .* suppressed: true whatsapp: enabled: true rules: - regex: .* suppressed: true email: enabled: true rules: - regex: .* suppressed: true ``` 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 {% hint style="info" %} Since `rules` are evaluated top to bottom, always order them from most to least specific. {% endhint %} 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 ```yaml test_mode: oob_otp: enabled: true rules: - regex: ^\+85291231234$ fixed_code: "000000" sms: enabled: true rules: - regex: ^\+85291231234$ suppressed: true whatsapp: enabled: true rules: - regex: ^\+85291231234$ suppressed: true ``` 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` # Tips for Apple App Store Review with Passwordless Login How to pass the Apple Store review process if your app uses passwordless login. When you try to publish a mobile app on the Apple AppStore, there will be an [App Review process](https://developer.apple.com/app-store/review/). 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" 1. Navigate to Advanced > Edit Config 2. paste the following to the yaml: ```yaml test_mode: oob_otp: enabled: true rules: - fixed_code: "000000" regex: (\+85291231234$|me@example\.com$) sms: enabled: true rules: - suppressed: true regex: \+85291231234$ whatsapp: enabled: true rules: - suppressed: true regex: \+85291231234$ email: enabled: true rules: - suppressed: true regex: me@example\.com$ ``` In this example, * `+85291231234` and `me@example.com` will not recieve any messages. * They can log in using the fixed OTP `000000`. * All other users will continue to receive OTPs normally. # Phone Number Validation 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](https://github.com/google/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.

Enable phone number validation with libphonenumber

{% hint style="info" %} **Note**: The phone number validation logic may become outdated due to recent changes in the numbering style in certain countries/regions. In such a case, you can **disable** the Phone Number Validation feature to enable users to register new numbers that the logic is unable to recognize. {% endhint %} # Skip Login Screen and Direct Users to Enterprise Login Learn how to take users directly to an external OAuth provider's authorization page without opening AuthUI login page. You can use Authgear's `x_oauth_provider_alias` parameter to add social/enterprise login to your application without showing any AuthUI pages. To do this, you must enable the **Social/Enterprise only** login method for your project in Authgear Portal. In this post, you'll learn how to use the `x_oauth_provider_alias` parameter to skip AuthUI and take users directly to a social/enterprise login provider's authorization page. ### Pre-requisite * An Authgear account. Create one for free [here](https://authgear.com). ### What We Will Build * In this post, we'll walk through the steps for adding only the social/enterprise login method to an Authgear application. * We'll use the Authgear SDK for React Native to set the `x_oauth_provider_alias` parameter and show how to use `x_oauth_provider_alias` without the SDK in an example Express app.
The sequence diagram above demonstrates the flow for using `x_oauth_provider_alias` to skip AuthUI. First, when the user clicks on the sign-in button, your application will call your Authgear project's `authorize` endpoint with the x\_oauth\_provider\_alias parameter appended. Next, when Authgear server receives the call, it redirects to the third-party OAuth (Social/EnterpriseLogin) provider's authorization server. The user is then shown the OAuth provider's login/authorization page for them to grant authorization. Once that is done, the OAuth provider returns an authorization code to Authgear. In the next step, Authgear exchanges the authorization code for an access token, refresh token, and ID token and then starts creating a new user or logging the existing user in. The rest of the flow from there involves the usual sending of the authorization code to the client application and the client application exchanging the authorization code for an access token, refresh token, and ID token. ### Step 1: Configure a Social/Enterprise Login Provider The first step is to add the Social/Enterprise login provider you wish to use to your Authgear project. For our example, we'll be adding Facebook. To add a new provider, log in to Authgear Portal, select your project, then navigate to **Authentication** > **Social/Enterprise Login**. Next, click on the **Edit** button, then enter the **Client ID** and **Client Secret** for the Social/Entreprise login provider then click **Save**. Also, note the value for **Alias** as you'll use it in a later step. See our guide [here](/authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook) 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: ```javascript authgear .configure({ clientID: '', endpoint: '', }) .then(() => { authgear .authenticate({ redirectURI: 'com.reactnativeauth://host/path', oauthProviderAlias: 'facebook', }) .then(({userInfo}) => { Alert.alert('Login successful, welcome ' + userInfo.email); }); }); ``` The key thing about using the above option is the presence of `oauthProviderAlias: 'facebook'` in the `authenticate()` method of the Authgear SDK. This parameter tells Authgear to redirect directly to an OAuth provider, given that the Social/Enterprise provider is configured properly as shown in [step 1](#step-1-configure-a-social-enterprise-login-provider). 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: ```javascript app.get("/login", (req, res) => { const url = new URL("/oauth2/authorize"); url.searchParams.set('client_id', config.client.id); url.searchParams.set('redirect_uri', "http://localhost:3000"); url.searchParams.set('scope', "openid offline_access"); url.searchParams.set('x_oauth_provider_alias', 'facebook') res.redirect(url); }); ``` The above code will append `&x_oauth_provider_alias=facebook` to the authorization URL. # Use the OAuth 2.0 State Parameter Reference on what the OAuth 2.0 parameter is and how to use it in Authgear SDK. The [OAuth 2.0 framework](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) includes an optional `state` parameter. The value of the `state` parameter can be any random string or number defined by a client application (e.g. a web or mobile that uses Authgear for user authentication) before making an authorization request. In fact, the `state` parameter is added to the authorization URL as a URL query. The authorization server (Authgear) will include the value of the state parameter when redirecting the user-agent back to the client application. As a result, the client application can retrieve the value of `state` returned to verify that it is the origin of the authorization request. In this post, we'll cover some possible usage of the `state` parameter and how to include the `state` parameter in an authorization request to the Authgear server. ## Use cases of the State Parameter The following are some use cases of the OAuth 2.0 state parameter. ### 1. Customize Post Login/Sign up User Experience Because the value for the state parameter passed at the beginning of an authorization request is returned unchanged after authorization, you can use this behavior to customize the post-login or sign-up user experience. For example, you can show users some custom messages after they sign up or log in, using a special link that was sent to them via email or SMS. The "special" thing in the link would be the value of a query parameter that can be passed in the `state` parameter. Then, a client application can read the value of the `state` parameter and based on that, determine when and how to display the custom message or user experience. ### 2. Analytics Another possible use of the `state` parameter is analytics and tracking user behavior. You can use the state token to include a unique key that tracks your campaigns. This way, you can know the number of users who sign up or log in to your application from a particular campaign. You can also use the value you specify in the `state` parameter in an analytic tool [Mixpanel](https://docs.mixpanel.com/docs/tracking-methods/id-management/identifying-users) (for example, as `id` in the `identify(id)` function) to track user's behavior pre-login and post-login. To learn more about using the state parameter for tracking user behavior, see our detailed guide [here](/integration/faq-for-integration/track-user-before-and-after-signup). ### 3. Security: To Prevent Cross-site Request Forgery (CSRF) Cross-site Request Forgery or short CSRF is a type of web security vulnerability where the attacker uses malicious means to trick a user into performing undesired actions on sites they use and trust. This type of attack usually targets users who are signed in and attempts to compromise access to their protected resources. In OAuth, an attacker can perform a Cross-site Request Forgery using the client application's redirect URI. The attacker can trick a user into using a redirect URI that contains their authorization code or access token. Hence the user will end up using the access token and protected resources of the attacker. When they save new data using this access token, the attacker can also view them (as they are the original owner of the protected resources). The official Authgear SDKs have mechanisms for protecting your applications from CSRF built into them. However, if you are not using the official SDK, you can secure your application by generating a random hard-to-guess value on the client application and passing it in the `state` parameter. Your application should store this value securely on the user's client-side using session cookies or some other form of local storage. Then, verify the `state` parameter in the redirect URI against the value stored locally to confirm that a user-agent is the origin of an authorization request before exchanging the authorization code for an access token. ## Examples: Including the State Parameter in Authorization Request The following URL shows an example of an authorization request URL: ``` https://your_project.authgear.cloud/login?client_id=your_authgear_app_client_id&redirect_uri=http%3A%2F%2Flocalhost%3A4000%2Fauth-redirect&state=12345678 ``` As you can see from the above URL, `state` is a query parameter in addition to other parameters like the `client_id` and `redirect_uri`. If you're constructing the authorization URL manually, you can include the state parameter by simply appending "`&state=random_state_value`" to the authorization URL. Alternatively, if you're using any of the Authgear SDKs, you can use the built-in `state` field to set a value. The following code samples show the use of the state parameter with Authgear. {% tabs %} {% tab title="JavaScript (React)" %} **Step 1: Set up a React Project to use Authgear** Create a new React project or use an existing project and configure the project to use Authgear. The following example is based on our [React example Git repository](https://github.com/authgear/authgear-example-react). First, install the Authgear web SDK by running the following command: ```sh npm install @authgear/web ``` Next, configure Authgear in your React Project's index.tsx file like this: ```typescript import authgear from "@authgear/web"; export const endpoint = "https://your_project.authgear.cloud"; // The Authgear endpoint of your project e.g. https://my-app.authgearapps.com export const clientID = ""; // Client ID can be obtained in the "Applications" page of the Portal async function init() { try { await authgear.configure({ endpoint, clientID, sessionType: "refresh_token", }); } finally { createRoot(document.getElementById("react-app-root")!).render(); } } // eslint-disable-next-line no-console init().catch((e) => console.log(e)); ``` **Step 2: Include State Parameter in Authorization Request** Set the `state` field in your call to the `startAuthentication()` method of the Authgear SDK to a random hard-to-guess value based on your use case. ```typescript const startLogin = useCallback(() => { authgear .startAuthentication({ redirectURI: "http://localhost:4000/auth-redirect", prompt: PromptOption.Login, state: "12345678" }) .then( () => { // started authorization, user should be redirected to Authgear }, (err) => { // failed to start authorization console.error(err); } ); }, []); ``` **Step 3: Read and Use the Value of State Returned After the Authorization** Implement the component that handles your OAuth 2.0 redirect like this: ```typescript const AuthRedirect: React.FC = () => { const usedToken = useRef(false); const navigate = useNavigate(); useEffect(() => { async function updateToken() { try { const u = new URL(window.location.href); const params = u.searchParams; const state = params.get("state") ?? undefined if (state !== undefined) { const initialState = "12345678"; // In a real app store the initial value on the client side using something like session cookies. //compare value of state returned in redirectURL to initial value set in startAuthentication() if (state === initialState) { //values match, do things log state to an analytic tool, set custom URL to navigate user to... console.log("state parameter match"); } else { //the value for state param return does not match, do something like stopping the authentication console.log("state parameter dont match"); return; } } await authgear.finishAuthentication(); } finally { navigate("/"); usedToken.current = true; } } if (!usedToken.current) { updateToken().catch((e) => console.error(e)); } }, [navigate]); return <>; }; ``` The above code will read the value of the state parameter returned in the redirect and compare it to the initial value. For this example, when the initial value of the `state` parameter before authorization is not the same as the value returned in the redirectURL, we halt the authentication process. {% endtab %} {% tab title="PHP" %} **Step 1: Set up PHP Project** This example uses the [League OAuth 2.0 client](https://oauth2-client.thephpleague.com/) PHP package. Install the package using the following command: ```sh composer require league/oauth2-client ``` Next, configure your PHP to use Authgear like this: ```php $clientID, // The client ID assigned to you by the provider 'clientSecret' => $clientSecret, // The client password assigned to you by the provider 'redirectUri' => $redirectUri, 'urlAuthorize' => $appUrl . '/oauth2/authorize', 'urlAccessToken' => $appUrl . '/oauth2/token', 'urlResourceOwnerDetails' => $appUrl . '/oauth2/userInfo', 'scopes' => 'openid offline_access' ]); if (!isset($_GET['code'])) { // Fetch the authorization URL from the provider; this returns the // urlAuthorize option and generates and applies any necessary parameters // (e.g. state). $authorizationUrl = $provider->getAuthorizationUrl(); // Get the state generated for you and store it to the session. $_SESSION['oauth2state'] = $provider->getState(); // Redirect the user to the authorization URL. header('Location: ' . $authorizationUrl); exit; } ``` The League OAuth 2.0 client we are using in this example helps us generate random strings for the `state` parameter. In the above code, we store the value for the state generated in session on the line with `$_SESSION['oauth2state'] = $provider->getState()`;. **Step 2: Read and Use the Value of State** Add an else block for the `if (!isset($_GET['code']))` condition with the following code: ```php else { $code = $_GET['code']; if (empty($_GET['state']) || empty($_SESSION['oauth2state']) || $_GET['state'] !== $_SESSION['oauth2state']) { if (isset($_SESSION['oauth2state'])) { unset($_SESSION['oauth2state']); } exit('Invalid state'); } else { try { $accessToken = $provider->getAccessToken('authorization_code', [ 'code' => $code ]); echo "Login successful ". $accessToken; } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) { // Failed to get the access token or user details. exit($e->getMessage()); } } } ``` The above code will prevent your PHP application from exchanging an authorization code for an access token when the value of `state` stored in the PHP session is not identical to the state returned in the redirect URI. The usage demonstrated above can prevent CSRF attacks. {% endtab %} {% endtabs %} # Local Dev Setup for Connecting to Authgear SaaS in Cookie-based Auth Setting up the local development environment for websites that use cookie-based authentication. This guide provides a simple way to bootstrap your local application that communicates with the Authgear SaaS server. {% hint style="warning" %} This guide is only for cookie-based authentication in local development setups. A typical scenario is developing websites. If you are developing mobile applications which use token-based authentication, you can just skip this guide and continue with it as usual. {% endhint %} ## Problems using localhost as a local website domain Authgear sets a cookie in the browser inside the project domain. When running your application on `localhost`, the browser will not see the cookies because the website is not in the subdomain of the domain in which the cookies are set. Therefore, the browser will not be able to authenticate itself. ## Setup a new Authgear project > For local development, it is highly recommended to create a new application on Authgear before continuing to the rest of the guide. 1. Log in and create a new project on 2. Go to the **Application** tab in your dashboard 3. Add your local application domain `{SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud` under the **Allowed Origins** list 4. Add an application, name it whatever you want. **DO NOT check the Issue JWT as access token** box because we are using cookie-based authorization. 5. Put your redirect URI for login and logout under the **Redirect URIs** list and **Post Logout Redirect URIs** list respectively. ## Map domain in `hosts` To make the cookies visible to the browser, the local website domain has to be inside the domain where the cookies are set. By adding the following line to the `/etc/hosts` file on the local machine, we can point the application domain name to localhost. ``` 127.0.0.1 {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud ``` The browser will be able to see the auth cookies if visiting the website via this domain. ## Use HTTPS Although you can see the cookies now, the cookies have the **Secure** attribute set. To include them in an HTTP request, the request has to be transmitted over a secure channel (**HTTPS** in most browsers). Therefore, we also need to establish **HTTPS** connections for our browser with the server. ### Generate certificates One quick simple way to do this is to use [mkcert](https://github.com/FiloSottile/mkcert), you may follow the installation steps [here](https://github.com/FiloSottile/mkcert#installation). After installing mkcert, generate a certificate with the following command: ``` mkcert "*.{PROJECT_NAME}.authgear.cloud" ``` A key file and a cert file will be generated. They will be used in the next part of the guide. ### Using nginx We will need an **nginx** server to serve the certificate and enable SSL. Add the following config file to your `nginx/conf.d` directory, or mount it to a volume together with the cert and key if you are using nginx in docker. The examples below show the nginx config files for nginx in host and nginx in docker. {% tabs %} {% tab title="nginx in host" %} ``` server { listen 443 ssl; server_name {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud; ssl_certificate /path/to/your/cert; ssl_certificate_key /path/to/your/key; location / { # Change it to your service endpoint proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; auth_request /_auth; auth_request_set $x_authgear_session_valid $upstream_http_x_authgear_session_valid; auth_request_set $x_authgear_user_id $upstream_http_x_authgear_user_id; auth_request_set $x_authgear_user_anonymous $upstream_http_x_authgear_user_anonymous; auth_request_set $x_authgear_user_verified $upstream_http_x_authgear_user_verified; auth_request_set $x_authgear_session_acr $upstream_http_x_authgear_session_acr; auth_request_set $x_authgear_session_amr $upstream_http_x_authgear_session_amr; auth_request_set $x_authgear_session_authenticated_at $upstream_http_x_authgear_session_authenticated_at; auth_request_set $x_authgear_user_can_reauthenticate $upstream_http_x_authgear_user_can_reauthenticate; proxy_set_header x-authgear-session-valid $x_authgear_session_valid; proxy_set_header x-authgear-user-id $x_authgear_user_id; proxy_set_header x-authgear-user-anonymous $x_authgear_user_anonymous; proxy_set_header x-authgear-user-verified $x_authgear_user_verified; proxy_set_header x-authgear-session-acr $x_authgear_session_acr; proxy_set_header x-authgear-session-amr $x_authgear_session_amr; proxy_set_header x-authgear-session-authenticated-at $x_authgear_session_authenticated_at; proxy_set_header x-authgear-user-can-reauthenticate $x_authgear_user_can_reauthenticate; } location /_auth { internal; resolver 8.8.8.8; set $resolver https://{PROJECT_NAME}.authgear.cloud/_resolver/resolve; proxy_pass $resolver; proxy_pass_request_body off; proxy_set_header Content-Length ""; } } ``` {% endtab %} {% tab title="nginx in docker" %} {% hint style="info" %} Docker `host` network driver is not supported in Docker Desktop, it has to be in a `bridge` network. If your nginx in docker needs to proxy requests to services in your host network, it needs to resolve `host.docker.internal` through `127.0.0.11`. If your services are also in the same docker bridge network (i.e. same docker-compose without specifying multiple networks), the destination domain will be the container name. {% endhint %} ``` server { listen 443 ssl; server_name {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud; ssl_certificate /path/to/your/cert; ssl_certificate_key /path/to/your/key; location / { resolver 127.0.0.11; # change {CONTAINER_NAME} to host.docker.internal if accessing host proxy_pass http://{CONTAINER_NAME}:{PORT}; proxy_set_header Host $host; auth_request /_auth; auth_request_set $x_authgear_session_valid $upstream_http_x_authgear_session_valid; auth_request_set $x_authgear_user_id $upstream_http_x_authgear_user_id; auth_request_set $x_authgear_user_anonymous $upstream_http_x_authgear_user_anonymous; auth_request_set $x_authgear_user_verified $upstream_http_x_authgear_user_verified; auth_request_set $x_authgear_session_acr $upstream_http_x_authgear_session_acr; auth_request_set $x_authgear_session_amr $upstream_http_x_authgear_session_amr; auth_request_set $x_authgear_session_authenticated_at $upstream_http_x_authgear_session_authenticated_at; auth_request_set $x_authgear_user_can_reauthenticate $upstream_http_x_authgear_user_can_reauthenticate; proxy_set_header x-authgear-session-valid $x_authgear_session_valid; proxy_set_header x-authgear-user-id $x_authgear_user_id; proxy_set_header x-authgear-user-anonymous $x_authgear_user_anonymous; proxy_set_header x-authgear-user-verified $x_authgear_user_verified; proxy_set_header x-authgear-session-acr $x_authgear_session_acr; proxy_set_header x-authgear-session-amr $x_authgear_session_amr; proxy_set_header x-authgear-session-authenticated-at $x_authgear_session_authenticated_at; proxy_set_header x-authgear-user-can-reauthenticate $x_authgear_user_can_reauthenticate; } location /_auth { internal; resolver 8.8.8.8; set $resolver https://{PROJECT_NAME}.authgear.cloud/_resolver/resolve; proxy_pass $resolver; proxy_pass_request_body off; proxy_set_header Content-Length ""; } } ``` {% endtab %} {% endtabs %} In the above examples, nginx will also authenticate requests by creating sub-requests to the Authgear internal endpoint. You can learn more [here](https://docs.authgear.com/deploy-on-your-cloud/auth-nginx#add-nginx). ## Finish Now visit the website through `https://.authgear.cloud`, and the browser will be able to send requests with the authorization cookies. For implementing login and logout logic in your website, please refer to [Web SDK](/get-started/single-page-app/website). # Add custom fields to a JWT Access Token or ID Token Learn how to add custom attributes to a JWT Access Token or ID Token using Authgear JWTs (JSON Web Tokens) are a common method for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. With Authgear, it is straightforward to add custom fields to your JWT access tokens or ID Tokens. This how-to guide will walk you through the process of **adding custom fields such as** [**User Profiles**](/integration/user-profiles) **attributes to a JWT access token/ID token** payload using Authgear and Javascript [Hooks](/customization/events-hooks). Here's an example of the [fields in the JWT Access Tokens by default](/reference/tokens/jwt-access-token) and an explanation of their values. {% hint style="info" %} You can also [add custom attributes](/integration/user-profiles) to [User Profiles](/integration/user-profiles) on the Authegear Portal. {% endhint %} ## Prerequisites * **An Authgear account:** You need an Authgear account to follow this guide. If you don't have one, you can [create it for free](https://accounts.portal.authgear.com/signup) on the Authgear website. * **A Registered App:** You need a [registered application](https://docs.authgear.com/get-started/website#setup-application-in-authgear) (client) in Authgear. ## Mutation on Access Tokens ### Enable Access Token for your App Make sure the option **Issue JWT as access token** is enabled in your **Application** settings in the Portal. 1. Log into your [Authgear account](https://portal.authgear.com/?_ga=2.25390521.563520449.1688969336-1174359617.1686657394). 2. Navigate to the **Applications** tab and choose the existing App. 3. On the **App Configuration** dashboard, locate the "**Access token**" section. 4. Make the toggle **Issue JWT as access token** switch on.
### Create a new Event Hook With the use of Hooks, Authgear provides flexibility for adding custom logic to your authentication pipeline. You can create a Hook which is triggered any of these [Events ](/customization/events-hooks)about to occur. For example, `oidc.jwt.pre_create` the event happens just before issuing the JWT access token and it can be used to put extra information into the token. 1. Navigate to your Authgear Dashboard's **Advanced**->**Hooks** section. 2. **Add** a new **Blocking Event**. 3. Choose the Block Hook **Type** as the *TypeScript* and set the Event option to `oidc.jwt.pre_create`. You will write a new Typescript function from scratch.
4. Click on **Edit Script** under the **Config** option. 5. Copy and paste the following into the editor: ```typescript import { EventOIDCJWTPreCreate, EventOIDCJWTPreCreateHookResponse } from "https://deno.land/x/authgear_deno_hook@v2.0.0/mod.ts"; export default async function(e: EventOIDCJWTPreCreate): Promise { return { mutations:{ jwt: { payload:{ ...e.payload.jwt.payload, standard_attributes: e.payload.user.standard_attributes, custom_attributes: e.payload.user.custom_attributes } } }, is_allowed: true }; } ``` 6. Click on **Finish Editing**. 7. Back to the **Hooks** page from the navigation bar and click on the **Save** button at the top of the page. In the above code, we are importing the necessary modules such as `EventOIDCJWTPreCreateHookResponse` and `EventOIDCJWTPreCreate` which are types from the Authgear [Deno](https://deno.land/) hook [Typescript library](https://deno.land/x/authgear_deno_hook). We modify the JWT payload by adding [Standard Attributes](/integration/user-profiles)(`e.payload.user.standard_attributes`) and [Custom Attributes](/integration/user-profiles)(`e.payload.user.custom_attributes`) of the user. ### Verify the Custom Field in a JWT token There are two ways to test it: * You can do this by [decoding the JWT token](/get-started/backend-api/jwt) on your application server side using a JWT decoder and inspecting the payload. * If you created the application type **OIDC Client Application,** you need to follow the steps below. Expand it to see instructions.
Verify the custom field in the JWT Token with OIDC Client Application This part explains how to retrieve an access token using **OpenID App** Endpoints and check if newly added custom attributes are in place in the JWT Access token. **Prerequisites** * Make sure that you have a registered app type of **OIDC Client Application** in Authgear Portal. **Step 1: Obtain the necessary parameters** Open your **OpenID Auth App** configuration, and find **Client ID**, **Client Secret**, and check **Authorization**, and **Token** endpoints. You will use them in the next steps. ![](/files/VRHmR9TwzHTLEfNua9pA) ![](/files/ifrIQ9Ncj42oF06E95p1) **Step 2: Construct the authorization endpoint URL** The URL for this endpoint is usually provided by the authorization server and includes parameters specifying the requested `scope`, `client_id`, and response\_type. Here's an example URL for the authorization endpoint: ``` https:///oauth2/authorize?client_id={YOUR_CLIENT_ID}&response_type=code&scope=openid ``` Replace `` with your Authgear server's domain, `YOUR_CLIENT_ID` with your application's Client ID from **OpenID App.** **Step 3: Redirect the user to the authorization endpoint** Next, you need to redirect the user to the authorization endpoint. You can just put the URL in your browser and log in with a user credential you are interested to retrieve an access token for. After successful authentication and consent, the Authgear will redirect the user back to your specified redirect URI, including an **authorization code** as a query parameter. You will need the code in the next step **Step 4: Obtain an access token** You need to make a request to the **OpenID App's Token endpoint** to exchange the authorization code we retrieved in the previous step for an access token. * The token endpoint URL is usually something like `https:///oauth2/token`. * Include parameters such as `grant_type=authorization_code`, `code=AUTHORIZATION_CODE`, `client_id=YOUR_CLIENT_ID`, `client_secret=YOUR_CLIENT_SECRET`, and `redirect_uri=YOUR_REDIRECT_URI`. * Make a POST request to the token endpoint to obtain the access token. ```bash curl --request POST \ --url 'https:///oauth2/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data code={YOUR_AUTHORIZATION_CODE} \ --data redirect_uri={YOUR_REDIRECT_URI} \ --data 'client_id={YOUR_CLIENT_ID}' \ --data client_secret={YOUR_CLIENT_SECRET} \ --data scope=openid ``` **Step 5: Verify custom attributes in the access token** Finally, we can debug the access token using the [JWT Debugger tool](https://www.authgear.com/tools/jwt-jwe-debugger) to see if the custom field and value we added previously are there inside the JWT payload. \\
## Mutation on ID Tokens With the use of Hooks, Authgear provides flexibility for adding custom logic to your authentication pipeline. You can create a Hook which is triggered any of these [Events ](/customization/events-hooks/blocking-events)about to occur. For example, `oidc.id_token.pre_create` the event happens just before issuing the JWT access token and it can be used to put extra information into the token. 1. Navigate to your Authgear Dashboard's **Advanced**->**Hooks** section. 2. **Add** a new **Blocking Event**. 3. Choose the Block Hook **Type** as the *TypeScript* and set the Event option to `oidc.id_token.pre_create`. You will write a new Typescript function from scratch.
4. Click on **Edit Script** under the **Config** option. 5. Copy and paste the following into the editor: ```typescript import { EventOIDCIDTokenPreCreate, EventOIDCIDTokenPreCreateHookResponse } from "https://deno.land/x/authgear_deno_hook@v2.0.0/mod.ts"; export default async function(e: EventOIDCIDTokenPreCreate): Promise { const customAttributes = e.payload?.user?.custom_attributes ?? null; return { is_allowed: true, mutations: { id_token: { payload: { ...e.payload.id_token.payload, custom_attributes: customAttributes } } } } } ``` 6. Click on **Finish Editing**. 7. Back to the **Hooks** page from the navigation bar and click on the **Save** button at the top of the page. In the above code, we are importing the necessary modules such as `EventOIDCIDTokenPreCreateHookResponse` and `EventOIDCIDTokenPreCreate` which are types from the Authgear [Deno](https://deno.land/) hook [Typescript library](https://deno.land/x/authgear_deno_hook). We modify the JWT payload by adding [Custom Attributes](/integration/user-profiles)(`e.payload.user.custom_attributes`) of the user. # User Profiles # What is User Profile 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](/customization/built-in-ui/user-settings) 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](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). Some of them are default hidden from the Admin Portal and end-users. Their visibility and mutability can be configured through the Admin Portal. | Attribute name | Default Visibility | Format | | -------------- | ------------------ | ------------------------------------------------------------------------------------- | | Name | Hidden | String | | Given Name | Editable | String | | Family Name | Editable | String | | Middle Name | Hidden | String | | Nickname | Hidden | String | | Profile | Hidden | URL String | | Picture | Editable | URL String | | Website | Hidden | URL String | | Gender | Editable | `male`, `female` or Custom String | | Birthdate | Editable | Date in YYYY-MM-DD | | Timezone | Editable | [tz database zone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | | Language | Editable | BCP47 language tag enabled by the project | | Address | Hidden | JSON Object | ### Standard Attributes that are coupled with Identities The following attributes are coupled with the [identities](/concepts/identity-fundamentals) owned by the end-user. They represent the email addresses, phone numbers, or usernames the end-users are using to authenticate themselves on Authgear. If the end-user uses a third-party identity provider for authentication, these attributes will be coupled with the corresponding attributes returned by the provider. The standard attributes coupled with identities are listed below: * `email` * `email_verified` * `phone_number` * `phone_number_verified` * `preferred_username` The above attributes are coupled with identities when a user specifies them during sign-up, when users verify their email address or phone number, or from **User Management** > **Users** > select a user > **Identities** in Authgear portal or via the Admin API. The Login Methods enabled for an Authgear project affect the identities available. ## Custom Attributes You can define a set of custom attributes in the user profile. They are returned as a JSON object in under the `custom_attributes` key in `userInfo`. ```json5 { ..., "custom_attributes": { "department": "example department" } } ``` ### Add new custom attributes Go to **Portal** > **User Profile** > **Custom Attributes** and click **Add New Attribute** The custom attribute name should consist of lowercase letters (a-z), digits (0-9) and underscore (\_) only. It must start with lowercase letters (a-z), and NOT end with an underscore (*\_*). The default display name will be the attribute name split with underscore and in title case. e.g. `my_string` will render as `My String` in the [AuthUI Settings page](/customization/built-in-ui/user-settings). Authgear supports the following attribute types: * String * Number * Integer * Dropdown * Phone Number * Email Address * URL * Country Code ### Modify custom attributes You can change a custom attribute name and validation settings such as min and max value. The attribute type cannot be changed once it's set. To migrate the attribute into a new type, create a new attribute, migrate the values from the old to the new one, and then change the name and access right of the old attribute to make it obsolete. ### Delete custom attributes Deleting custom attributes is not supported. You can change the name and access rights to make an attribute obsolete. ### Custom attribute order You can arrange the attribute order by drag-and-drop the handle in the custom attribute configuration in the Portal. This will control the order of how the attributes are shown to the end-users in the [AuthUI User Settings page](/customization/built-in-ui/user-settings). ## User Profile Configuration The access rights for different parties on individual attributes can be configured through the Authgear Portal. Under the hood, all the attributes are available, however, they can be configured to be `hidden` or `read-only` according to the needs of your projects to avoid confusion. These are the parties that have access to the user profile: ### The Admin API Through [the Admin API](/reference/apis/admin-api), developers **ALWAYS** have **full access** to **ALL** the standard attributes and custom attributes. The Admin API allows the developer to view or edit the standard attributes and the custom attributes. ### The Portal The admin user can view or edit the standard attributes via the Authgear Portal. ### The Session Bearer The session bearer is someone who has a valid session cookie or a valid access token. The standard attributes of the end-user whom the session represents can be viewed by accessing [the UserInfo endpoint](#userinfo-endpoint) and [the resolver endpoint](/get-started/backend-api/nginx). The session bearer can be the end-user, the client mobile app, or the client website. ### The End-user The end-user can view or edit the standard attributes through the Profile section in the [User Setting page](/customization/built-in-ui/user-settings) provided by the AuthUI. ## Profiles from Third-party Identity Providers Authgear supports various [social and enterprise identity providers](/authentication-and-access/social-enterprise-login-providers). End-users can sign up and log in to your apps via these connections. Upon signup, these providers will return a set of user attributes about the end-user. Authgear will copy those attributes and populate the profile of the end-user. More info about the population logic can be found in [the specification](https://github.com/authgear/authgear-server/blob/master/docs/specs/user-profile/design.md#standard-attributes-population). # Access User Profiles Learn how to access User Profiles To access any of the applications in your Authgear account, each user must have a profile in the account. [User Profiles](/integration/user-profiles/user-profile) contain information about your users such as name, contact information, and [standard](/integration/user-profiles/user-profile#standard-attributes) and[ custom attributes](/integration/user-profiles/user-profile#custom-attributes) you define. You can retrieve and manage user profiles in the following ways: * [From the Authgear UI portal](#id-1.-access-user-profiles-from-the-authgear-ui-portal). * [From your apps using Authgear SDKs](#id-2.-access-user-profiles-from-apps-using-authgear-sdks). * [From Admin API](#id-3.-access-user-profiles-from-admin-api). * [From the OIDC UserInfo endpoint](#id-4.-access-user-profiles-from-the-oidc-userinfo-endpoint). * [Embed User Profiles into JWT](#id-5.-embed-user-profiles-into-jwt) {% hint style="info" %} The standard attributes in UserProfile in OIDC are a standardized schema for representing the end-users identity information and you can not add or delete them. To introduce additional attributes, use custom attributes. {% endhint %} ### User Profiles Access Right Access Right defines what information can be viewed or modified when a user's profile is accessed via the Authgear Portal, User Info endpoint, or User Settings page. An Access Right can be set for each profile attribute under a specific medium of accessing user profiles. For example, in the following screenshot, the Primary Email attribute has the Editable Access Right for Portal, `Read-only` for User Info endpoint (also known as access Token Bearer), and `Editable` for User Settings page. In simpler terms, the example means an admin can modify Primary Email in Authgear Portal, while a client application can use a user's access token to view their Primary Email. Finally, users can edit their own Primary Email from the User Settings page.
#### Access Right Options The following are the available Access Right options that can be applied to each attribute for a specific medium. * **Editable:** Grants a medium access to view and modify the value of an attribute. * **Read-only:** A medium with this access for an attribute can only view the value of the attribute. * **Hidden:** If the access for an attribute is set to `Hidden` for a medium, that medium can not view or modify the attribute. By default, Authgear sets different access rights for the standard attributes on each way of accessing user profiles. You can view and configure this default access right from **User Profile** > **Standard Attributes** in the Authgear Portal. For Custom Attributes, you can define the access right for each way of accessing a user profile from **User Profile** > **Custom Attributes** in the portal. Each way of accessing user profiles belongs to one of the following Access Right Categories: * **Portal Admin Access Right:** Use this category to set the access right of an attribute in the Authgear Portal for an admin user. * **Token Bearer Access Right:** This sets the access right of an attribute for the User Info endpoint when a token bearer accesses it. It can be "Hidden" or "Read-Only". * **End-user Access Right:** Use this to set the access right of the attribute for the default User Settings UI when accessed by an end-user. ## How to Retrieve and Manage User Profiles ### Prerequisites * **An Authgear account:** You need an Authgear account to follow this guide. If you don't have one, you can[ create it for free](https://accounts.portal.authgear.com/signup) on the Authgear website. * **A Registered App:** You need a [registered application](https://docs.authgear.com/get-started/website#setup-application-in-authgear) (client) in Authgear. ### 1. Access user profiles from the Authgear UI portal It is the fastest and easiest way to view user profiles and manage them.
Expand this to see the guide To view see user profile of a specific user: 1. Go to the [Authgear Portal](https://portal.authgear.com/). 2. Navigate to **User Management.** 3. Choose a user you would like to view a profile. 4. On the **User Details** page, you will see the **Profile** tab. To manage access for standard attributes for all users: Go to **Portal** > **User Profile** > **Standard Attributes** To manage access and add new custom attributes for all users: Go to **Portal** > **User Profile** > **Custom Attributes** and click **Add New Attribute**
### 2. Access user profiles from apps using Authgear SDKs Once Authgear completes authentication and returns control to your application, it provides the user profile to the application. Most developers prefer to use the **Authgear SDKs** to get the UserInfo object using the **fetch user info** function. To start using this function read [getting started guides](/get-started/start-building) relevant to the **SDK of your choice**. Here are some code snippets that call the fetch user info function for different Authgear SDKs: {% tabs %} {% tab title="JavaScript" %} ```javascript try{ const userInfo = await authgear.fetchUserInfo() // example: output the 'sub' attribute from userInfo to console // sub is a unique identifier for each user. // You can read other attributes such as email and phoneNumber depending on your login method console.log(userInfo.sub) } catch(e) { // failed to fetch user info } ``` {% endtab %} {% tab title="iOS" %} ```swift authgear.fetchUserInfo { userInfoResult in // sessionState is now up to date // it will change to .noSession if the session is invalid let sessionState = authgear.sessionState switch userInfoResult { case let .success(userInfo): // read the userInfo if needed let userId = userInfo.sub let email = userInfo.email case let .failure(error): // failed to fetch user info // the refresh token maybe expired or revoked } ``` {% endtab %} {% tab title="Android" %} ```kotlin authgear.fetchUserInfo(new OnFetchUserInfoListener() { @Override public void onFetchedUserInfo(@NonNull UserInfo userInfo) { // sessionState is now up to date // read the userInfo if needed // example: output the 'sub' attribute from userInfo to LogCat // sub is a unique identifier for each user. // You can read other attributes such as email and phoneNumber depending on your login method Log.d("UserID:", userInfo.sub); } @Override public void onFetchingUserInfoFailed(@NonNull Throwable throwable) { // sessionState is now up to date // it will change to NO_SESSION if the session is invalid } }); ``` {% endtab %} {% tab title="Flutter" %} ```dart try { UserInfo userInfo = await authgear.getUserInfo(); // read the userInfo if needed // example: output the 'sub' attribute from userInfo to console // sub is a unique identifier for each user. // You can read other attributes such as email and phoneNumber depending on your login method print(userInfo.sub); } catch (e) { // failed to fetch user info // the refresh token maybe expired or revoked } // sessionState is now up to date SessionState state = authgear.sessionState; ``` {% endtab %} {% tab title="Xamarin" %} ```csharp try { var userInfo = await authgear.FetchUserInfoAsync() // example: output the 'sub' attribute from userInfo to console // sub is a unique identifier for each user. // You can read other attributes such as email and phoneNumber depending on your login method console.log(userInfo.sub) } catch { // failed to fetch user info // the refresh token maybe expired or revoked } ``` {% endtab %} {% endtabs %} {% hint style="info" %} See the [UserInfo page](https://docs.authgear.com/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo) for more details about the shape of user info and the available user profile attributes. {% endhint %} ### 3. Access user profiles from Admin API Authgear provides an [Admin API](/reference/apis/admin-api) GraphQL endpoint that allows applications and services to access and manipulate the User Profile object. The [API Explorer](/reference/apis/admin-api#api-explorer) lets users interactively explore the Admin API. With the API Explorer, you can search for users' profiles or update their standard or custom attributes. See the example steps of how to achieve this below:
Expand this to see the guide 1. Go to the **Portal**. 2. Navigate to the **Advanced** -> **Admin API.** 3. Find a section called **GraphiQL Explorer.** 4. Click on the **GraphiQL tool** link. The explorer will be opened in a separate browser tab. 5. Search for a user by `email`and put in your query `standardAttributes` and `customAttributes`. For example: ```json5 query { users( searchKeyword: "bobur@oursky.com" ) { edges { node { standardAttributes customAttributes } } } } ```
### 4. Access user profiles from the OIDC UserInfo endpoint The OpenID Connect (OIDC) [UseInfo](/integration/user-profiles/user-profile#userinfo-endpoint) endpoint is a protected resource that provides information about a user when a service provider presents an access token that has been issued by your **Authgear Token endpoint**. The scopes in the access token specify the user attributes that are returned in the response of the user info endpoint. It is important to note that the `openid` scope must be one of the access token claims. #### UserInfo Endpoint The UserInfo endpoint returns the Claims about the authenticated end-user, including the standard profile and custom attributes. The `userInfo` object is returned from calling **fetch user info** function which contains a unique identifier of the user. The following are some attributes that are usually in the userInfo object. Other attributes like email, phoneNumber and custom attributes will be in the userInfo object if those attributes were set for the current user. | Key | Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isAnonymous | *boolean* | Indicate if the user is anonymous, i.e. no [identity](/concepts/user-identity-and-authenticator#identity) or [authenticator](/concepts/user-identity-and-authenticator#authenticator) is provided | | isVerified | *boolean* | Indicate if the user completed the verification requirement | | sub | *string* | Unique identifier of the user in your Authgear project | To access a user's profile using the UserInfo endpoint of OpenID Connect, you need to follow these steps:
Expand this to see the guide To access a user profile endpoint, you need to have a JWT access token in the header of a request to `/oauth2/userinfo` We are going to use **cURL** commands in our API calls or you can also use [Postman](https://www.postman.com/) or similar tools. **Prerequisites** * Make sure that you have a registered app type of **OIDC Client Application** in Authgear Portal. * You have successfully configured your application to use Authgear as an OIDC provider. See your [getting started guide](/get-started/start-building) for detailed steps. **Step 1: Obtain an access token** Your client application needs a valid access token for a user in order to make request to the UserInfo endpoint. To get an access token, you need to make a request to the **OpenID App's Token endpoint** to exchange the **authorization code** that was retrieved after authorization for an access token. * The token endpoint URL is usually something like `https:///oauth2/token`. * Include parameters such as `grant_type=authorization_code`, `code=AUTHORIZATION_CODE`, `client_id=YOUR_CLIENT_ID`, `client_secret=YOUR_CLIENT_SECRET`, and `redirect_uri=YOUR_REDIRECT_URI`. * Make a POST request to the token endpoint to obtain the access token. The following is an example of a request to the token endpoint sent for a terminal using cURL: ```bash curl --request POST \ --url 'https:///oauth2/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data code={YOUR_AUTHORIZATION_CODE} \ --data redirect_uri={YOUR_REDIRECT_URI} \ --data 'client_id={YOUR_CLIENT_ID}' \ --data client_secret={YOUR_CLIENT_SECRET} \ --data scope=openid ``` **Step 2: Make a request to the Userinfo endpoint** Once you have obtained a **JWT access token**, you can use it to make a request to the Userinfo endpoint. The request to the Userinfo endpoint should include the access token in the `Authorization` header using the `Bearer` scheme. ```bash curl -X GET \ -H "Authorization: Bearer ACCESS_TOKEN" \ https:///userinfo ``` If you are using Postman, you can enable the Authorization type of OAuth2.0, provide the necessary information for getting the authorization code, obtaining an access token and use that token to request the Userinfo endpoint: ![](/files/cxbC1tt4UTYj5yLLfZQX)
See a detailed explanation of the structure and fields included in the response of the UserInfo endpoint [here](/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo). ### 5. Embed User Profiles into the JWT Access Token Authgear WebHooks makes it possible to embed the standard attributes and custom attributes for a user's profile into the OIDC JSON Web Token (JWT). Hence, you access both profile attributes in the JWT returned to your OIDC client without making another call to the UserInfo endpoint. See our post about how to [Add custom fields to a JWT Access Token](/integration/add-custom-fields-to-a-jwt-access-token) to learn more. # Update User Profiles Guide on the different ways you can modify the profiles of the users of your application. Authgear offers multiple ways for you (the admin) and your users to update user profiles. As an admin, you can modify profile attributes for any of the users of your Authgear project. End users on the other hand can modify their own profile using the Profile settings UI provided by Authgear or using a custom logic you implement in your code. In this guide, we'll walk through all the options for updating user profiles. ### Pre-requisites To follow along, you need to have the following: * An Authgear Account. You can create one for free [here](https://accounts.portal.authgear.com/signup). * 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](https://portal.authgear.com/), 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](https://docs.authgear.com/reference/apis/admin-api#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** ```graphql { "standardAttributes": { "family_name": "John", "given_name": "Doe", "gender": "male" } } ``` **Mutation** ```graphql mutation ($standardAttributes: UserStandardAttributes) { updateUser(input: {userID: "", 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](https://docs.authgear.com/reference/apis/admin-api/api-examples/update-users-standard-attributes). Also, see the [Admin API example for updating custom attributes](https://docs.authgear.com/reference/apis/admin-api/api-queries-and-mutations#id-2.20.-updateuser) 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:///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.

user settings edit profile ui

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

user settings editing attribute

# Profile Custom Attributes Learn how to add custom attributes to user profiles and manage existing custom attributes In Authgear, a user's profile includes two types of attributes. The first is the standard attributes which are basically common profile fields such as Primary Email, Primary Phone, Username, Name, Birthday, etc that are present by default. The second type is the custom attributes an Authgear user can set for their project. This allows you to add custom fields to the profiles of your users. For example, you can add a Post Code custom attribute to your Authgear so users can provide this data for their profile. All custom attributes are returned in the [UserInfo](/reference/apis/oauth-2.0-and-openid-connect-oidc/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. # Update user profile on sign-up using Hooks Learn how to update a User profile's custom attributes on sign-up using Hooks Using [Hooks](/customization/events-hooks/denohooks) you can put **extra information** into the user profile's [custom attributes](/integration/user-profiles/profile-custom-attributes) programmatically. This is useful for [Profile Enrichment](https://www.authgear.com/post/how-profile-enrichment-can-boost-your-product) 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](https://accounts.portal.authgear.com/signup) on the Authgear website. Start by logging into your [Authgear dashboard](https://portal.authgear.com/). **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. ```typescript 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](/integration/user-profiles/access-user-profiles) in Authgear. # Mobile Apps Learn how to integrate Authgear with mobile apps using SDKs and advanced configurations This section covers mobile-specific integration patterns and configurations for Authgear. {% content-ref url="/pages/-Mj8Y1oAhH7-FL0y4tol" %} [Force authentication on app launch](/integration/mobile-apps/force-authentication-on-app-launch) {% endcontent-ref %} {% content-ref url="/pages/LluSBuPDQab4Jrb3FK4I" %} [Customize the Login Pop-up / Disable the login alert box](/integration/mobile-apps/using-webview-to-open-the-authgear-ui) {% endcontent-ref %} {% content-ref url="/pages/-MbFM4jjzD5DKZzSMBE8" %} [Client SDK to make authorized API calls to backend](/get-started/backend-api/using-sdk-to-call-your-application-server) {% endcontent-ref %} # Force authentication on app launch 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. {% tabs %} {% tab title="React Native" %} ```typescript import authgear, { TransientTokenStorage } from "@authgear/react-native"; authgear.configure({ clientID: CLIENT_ID, endpoint: ENDPOINT, tokenStorage: new TransientTokenStorage(), }); ``` {% endtab %} {% tab title="Flutter" %} ```dart final authgear = Authgear( clientID: CLIENT_ID, endpoint: ENDPOINT, tokenStorage: TransientTokenStorage(), ); ``` {% endtab %} {% tab title="Xamarin" %} ```csharp var authgearOptions = new AuthgearOptions { ClientId = CLIENT_ID, AuthgearEndpoint = ENDPOINT, TokenStorage: new TransientTokenStorage(), }; #if __ANDROID__ var authgear = new AuthgearSdk(GetActivity().ApplicationContext, authgearOptions); #else #if __IOS__ var authgear = new AuthgearSdk(UIKit.UIApplication.SharedApplication, authgearOptions); #endif #endif ``` {% endtab %} {% tab title="iOS" %} ```swift Authgear( clientId: CLIENT_ID, endpoint: ENDPOINT, tokenStorage: TransientTokenStorage() ) ``` {% endtab %} {% tab title="Android" %} ```java new Authgear( application, CLIENT_ID, ENDPOINT, new TransientTokenStorage() //tokenStorage ); ``` {% endtab %} {% endtabs %} # Customize the Login Pop-up / Disable the login alert box Learn how to switch between ASWebAuthenticationSession/Custom Tabs to WebKitWebView using Authgear Mobile SDKs. The default of the Authgear Mobile SDKs is to launch AuthUI in [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) in iOS and [Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs) in Android. ASWebAuthentication is an API provided by Apple for login purpose. It will store the session cookie and share with Safari, which makes Single Sign-on (SSO) between mobile apps and web apps possible. However, it requires user consent, and will display a login alert box:
There are multiple ways you can avoid the login alert box: ## 1. Use ephemeral sessions If you do not need SSO between mobile and web apps, you can disable it by setting `isSSOEnabled = false`. {% tabs %} {% tab title="iOS (Native)" %} ```swift Authgear( clientId: "", endpoint: "", isSSOEnabled: false, ) ``` {% endtab %} {% tab title="React Native" %} ```javascript authgear .configure({ clientID: "", endpoint: "", isSSOEnabled: false, }); ``` {% endtab %} {% endtabs %} It will not share the session cookies between your app and Safari. And the login alert box will not show to prompt user consent. ## 2. Use WebKitUIImplementation The mobile SDKs include `WebKitWebViewUIImplementation`, a `UIImplementation` which makes it possible to customize more UI. Depending on the platforms, there are various alternatives: * iOS: WKWebViewUIImplementation * Other platforms / Android: WebKitWebViewUIImplementation Setting the `uiImplementation` attribute in the `configure()` method of the Authgear SDK to `WebKitWebViewUIImplementation()` will open AuthUI using [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview) on iOS and [android.webkit.WebView](https://developer.android.com/reference/android/webkit/WebView) on Android. Omitting the `uiImplementation` attribute in the `configure()` method will fall back to the default behavior (launching AuthUI in ASWebAuthenticationSession/Custom Tabs, which is `DeviceBrowserUIImplementation`). ### Example Code The following examples show how to set the `uiImplementation` attribute. {% tabs %} {% tab title="Ionic" %} ```typescript authgearCapacitor.configure({ clientID: "", endpoint: "", isSSOEnabled: true, uiImplementation: new WebKitWebViewUIImplementation(), tokenStorage: new TransientTokenStorage() }); ``` {% endtab %} {% tab title="React Native" %} ```typescript authgear .configure({ clientID: "", endpoint: "", uiImplementation: new WebKitWebViewUIImplementation() }); ``` {% endtab %} {% tab title="Android (Native)" %} ```java private Authgear authgear = new Authgear( getApplication(), "", "", tokenStorage, new WebKitWebViewUIImplementation(), isSsoEnabled, null, app2appOptions ); ``` {% endtab %} {% tab title="iOS (Native)" %} ```swift Authgear( clientId: "", endpoint: "", tokenStorage: TransientTokenStorage(), uiImplementation: WKWebViewUIImplementation(), isSSOEnabled: true, ) ``` {% endtab %} {% endtabs %} Setting `uiImplementation` to `WebKitWebViewUIImplementation` in the above example will change the behavior of your application from using **ASWebAuthenticationSession** on iOS and **Custom Tabs** on Android to using `WKWebView` and `android.webkit.WebView` respectively. To set `uiImplementation` to `WKWebView` in the native iOS SDK, use `WKWebViewUIImplementation` . ### Customizing the WebKitWebView UI `WebKitWebViewUIImplementation` allows you to customize some parts of the UI. You can do this by passing your customization options as parameters in WebKitWebViewUIImplementation(). You can customize the following parts of the UI: **Android** * `actionBarBackgroundColor`: Use this option to customize the color of the action bar on the WebView Activity screen. The value should be of type integer according to this encoding: * `actionBarButtonTintColor`: This option can be used to set the color of the icons and texts on the action bar. The value should also be of type integer and use the encoding here: . **iOS** * `navigationBarBackgroundColor`: This option can be used to customize the color of the navigation bar on iOS. The value should be of type [UIColor](https://developer.apple.com/documentation/uikit/uicolor/) or an integer (React Native or Ionic SDKs) using the following encoding: . * `navigationBarButtonTintColor`: This option sets the color of icons and texts on the navigation bar. The value should also be UIColor or an integer (React Native or Ionic SDKs) using the same encoding as `navigationBarBackgroundColor`. * `modalPresentationStyle`: Sets the type of modal to be shown. The value can be any of the following: "automatic", "fullScreen", "pageSheet". The following examples show how to set custom background color, tint color, and modal presentation style. {% tabs %} {% tab title="Ionic" %} ```typescript authgearCapacitor.configure({ clientID: "", endpoint: "", uiImplementation: new WebKitWebViewUIImplementation({ ios: { modalPresentationStyle: "fullScreen" }, android: { actionBarBackgroundColor: 0xffffff00, actionBarButtonTintColor: 0xff000000 } }), tokenStorage: new TransientTokenStorage() }); ``` {% endtab %} {% tab title="React Native" %} ```typescript authgear .configure({ clientID: "", endpoint: "", uiImplementation: new WebKitWebViewUIImplementation({ ios: { modalPresentationStyle: "fullScreen" }, android: { actionBarBackgroundColor: 0xffffff00, actionBarButtonTintColor: 0xff000000 } }) }) ``` {% endtab %} {% tab title="Android (Native)" %} ```java private int actionBarBackgroundColor = 0xffffff00; private int actionBarButtonTintColor = 0xff000000; private Authgear authgear = new Authgear( getApplication(), "", "", tokenStorage, new WebKitWebViewUIImplementation(actionBarBackgroundColor, actionBarButtonTintColor), isSsoEnabled, null, app2appOptions ); ``` {% endtab %} {% tab title="iOS (Native)" %} ```swift Authgear( clientId: "", endpoint: "", tokenStorage: TransientTokenStorage(), uiImplementation: WKWebViewUIImplementation( modalPresentationStyle: UIModalPresentationStyle.fullScreen, navigationBarBackgroundColor: UIColor.yellow, navigationBarButtonTintColor: UIColor.black ), isSSOEnabled: true ) ``` {% endtab %} {% endtabs %} ## 3. Implement Custom UIImplementation You can implement your own custom `UIImplementation` when the `WebKitWebViewUIImplementation` does not meet the requirements of your use case. The WebKitWebViewUIImplementation class itself is basically a class that implements `UIImplementation` and overrides the `openAuthorizationURL()`method. Hence your custom implementation may look like this: ```typescript class MyUIImplementation implements UIImplementation { async openAuthorizationURL(options: OpenAuthorizationURLOptions): Promise { // Call your own plugin code to implement this. } } ``` Then, you can use your custom implementation like this: ```typescript authgear.configure({ clientID: "my_client_id", endpoint: "my_endpoint", isSSOEnabled: true, uiImplementation: new MyUIImplementation(), }) ``` To get a deeper understanding of how to implement your UIImplementation, see the code for the [WebKitWebViewUIImplementation](https://github.com/authgear/authgear-sdk-android/blob/main/sdk/src/main/java/com/oursky/authgear/WebKitWebViewUIImplementation.kt) implementation. ## Unsupported Features When you drop the default DeviceBrowserUIImplementation to use your own custom UI implementation that uses WebView, it is important to note that you'll be losing the following features, due to iOS or other security limitations. 1. **Login with Google:** Google prohibits the use of `WebKitWebView` with the Google SSO. Learn more here: . As a result `WebKitWebViewUIImplementation` and Google SSO cannot be used together. 2. **Passkey:** Passkey is not supported in WebKitWebView. # Integration with other Software # Authgear and Supabase Guide on using Authgear together with Supabase database to deliver a secure and scalable application User authentication is a foundational part of any modern web application but getting it right is notoriously difficult. That’s where Authgear comes in. Authgear handles user registration, login flows, session management, and advanced security features like biometric login, 2FA, and social sign-ins out of the box. Pairing Authgear with Supabase's Postgres database and powerful Row-Level Security (RLS) gives you a secure, scalable foundation for building user-specific applications. In this guide, you’ll learn how to integrate Authgear and Supabase using React.js to build a basic CRUD application.
Simple instrument tracking app where users can manage their personal collection after logging in with Authgear

Simple instrument tracking app where users can manage their personal collection after logging in with Authgear

We will walkthrough how to **authenticate users with Authgear**, exchange tokens via a **Supabase Edge Function**, apply **RLS policies** based on Authgear-issued JWTs, and connect it all in a modern React frontend using Vite. ``` ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ Browser │ │ Authgear │ │ Supabase │ │ (React App)│◄────────►│ (Auth IdP) │ │ (Database) │ └──────┬──────┘ └──────────────┘ └──────┬───────┘ │ │ │ 1. Login with Authgear │ │ 2. Get Authgear JWT (access token) │ │ 3. Call Supabase with Authgear JWT (request data)│ └──────────────────────────────────────────────────► │ │ │ 4. Exchange JWT (Edge Function) │ │ 5. Return Supabase JWT │ │◄────────────────────────────────────────────────── │ │ │ 6. Access data with Supabase JWT (enforce RLS) │ └──────────────────────────────────────────────────► ``` ## **Full example code** The full example app source code is available on GitHub and can be used as a starting point for your own project: ## What you need * **Authgear account & project** – [Sign up for Authgear](https://portal.authgear.com/). * **Supabase account & project** – [Sign up on supabase.com](https://supabase.com/) ## Step 1: Set up an Authgear project First, configure Authgear to handle authentication for your app. 1. **Create an Authgear Application:** Log in to the Authgear Portal and create a new application. Choose **Single Page Application** as the application type. 2. **Configure OAuth Redirects:** In your Authgear app settings, set the redirect URIs: * **Redirect URI**: `http://localhost:5173/auth-redirect` – this is where Authgear will redirect the browser after a successful login (our React app will handle this route). * **Post-Logout Redirect URI:** `http://localhost:5173/` – where to navigate after users log out. 3. **Note Your Authgear Credentials:** After creation, note down: * The **Authgear Endpoint** for your app (it will look like `https://.authgear.cloud`). * The **Client ID** of your Authgear application. We will need these values when initializing Authgear in our React app and in the Supabase function. ## Step 2: Set up a Supabase project Next, prepare your Supabase backend. 1. **Create a Supabase Project:** Log in to Supabase Dashboard, create a new project (choose an organization, project name, database password, and region). 2. **Retrieve Project Keys:** In your Supabase project, go to **Project Settings → API → API keys**. Copy the **Publishable Key** and the **URL** of your project (e.g., `https://xyzcompany.supabase.co`). 3. **Get the JWT Secret:** Still in **Project settings**, navigate to **JWT Keys** and find the **Legacy JWT Secret** for your project. This is a secret key that Supabase uses to sign and verify JWTs for RLS. Copy the JWT secret value – we will use it in our Edge Function config.\\

Copy the Legacy JWT Secret from the JWT Keys page

4. *(Optional)* **Install Supabase CLI:** If you plan to use the CLI to deploy the Edge Function, install it by following [Supabase’s instructions](https://supabase.com/docs/guides/local-development/cli/getting-started). Alternatively, you can deploy the function via the Dashboard UI. ## Step 3: Create an Edge Function to exchange JWTs Now we set up the critical piece: a Supabase Edge Function that will accept Authgear’s JWT and return a new JWT signed with Supabase’s secret. 1. Navigate to "Edge Functions" -> "Secrets" and add the two secrets: 1. `AUTHGEAR_ENDPOINT` = your Authgear app endpoint (e.g. `https://myapp.authgear.cloud`). 2. `SB_JWT_SECRET` = your Supabase JWT secret (from Step 2 above). 2. Deploy the Function 1. Navigate to "Edge Functions" -> "Functions" in Supabase web UI. Copy-paste the following code and deploy it there. Name the function `exchange-jwt`. 2. Alternatively, you can use Supabase CLI to build and deploy the Edge Function from your local machine to your Supabase project. ```typescript // supabase/functions/exchange-jwt/index.ts import "jsr:@supabase/functions-js/edge-runtime.d.ts" import jwt from "npm:jsonwebtoken"; import jwks from "npm:jwks-rsa"; import * as jose from "https://deno.land/x/jose@v4.14.4/index.ts"; // CORS headers for cross-origin requests const corsHeaders = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Authorization, Content-Type", "Access-Control-Allow-Methods": "GET", "Access-Control-Max-Age": "3600" }; // Read environment variables const authgearEndpoint = Deno.env.get("AUTHGEAR_ENDPOINT"); const supabaseJwtSecret = Deno.env.get("SB_JWT_SECRET"); if (!authgearEndpoint || !supabaseJwtSecret) throw new Error("Missing env vars"); // Get JWKS URI from Authgear's OpenID configuration async function getJwksUri(): Promise { const configUrl = `${authgearEndpoint}/.well-known/openid-configuration`; const response = await fetch(configUrl); const config = await response.json(); return config.jwks_uri; } // Extract Bearer token from Authorization header function extractToken(req: Request): string | null { const authHeader = req.headers.get("Authorization"); if (!authHeader) return null; const parts = authHeader.split(" "); if (parts.length !== 2 || parts[0] !== "Bearer") return null; return parts[1]; } // Verify JWT token with Authgear's public key async function verifyToken(token: string): Promise { // Decode token to get key ID const decoded = jwt.decode(token, { complete: true }) as any; if (!decoded?.header?.kid) { throw new Error("Invalid token: missing key ID"); } // Get JWKS URI and create JWKS client const jwksUri = await getJwksUri(); const jwksClient = jwks({ jwksUri }); // Get the signing key const key = await jwksClient.getSigningKey(decoded.header.kid); const signingKey = key.getPublicKey(); // Verify the token const options = { algorithms: ["RS256"], issuer: authgearEndpoint, }; return jwt.verify(token, signingKey, options); } // Sign a new JWT with Supabase secret async function signSupabaseJwt(payload: any): Promise { payload.role = "authenticated"; // Required by Supabase // Add or modify any other claims you need for RLS policies // payload.some_claim = "some claim"; // Sign with Supabase JWT secret const supabaseSecret = new TextEncoder().encode(supabaseJwtSecret); const supabaseJwt = await new jose.SignJWT(payload) .setProtectedHeader({ alg: "HS256", typ: "JWT" }) .setIssuer("supabase") .setIssuedAt(payload.iat) .setExpirationTime(payload.exp || "") .sign(supabaseSecret); return supabaseJwt; } // Main function handler Deno.serve(async (req: Request) => { // Handle CORS preflight requests if (req.method === "OPTIONS") { return new Response("ok", { headers: corsHeaders }); } try { // Extract token from request const token = extractToken(req); if (!token) { return new Response( JSON.stringify({ error: "Missing or invalid Authorization header" }), { headers: { ...corsHeaders, "Content-Type": "application/json" }, status: 401 } ); } // Verify the token const verified = await verifyToken(token); // Sign a new JWT with Supabase secret const supabaseJwt = await signSupabaseJwt(verified); return new Response( JSON.stringify({ supabaseJwt }), { headers: { ...corsHeaders, "Content-Type": "application/json" }, status: 200, } ); } catch (error) { console.error("Token verification failed:", error.message); return new Response( JSON.stringify({ error: "Token verification failed" }), { headers: { ...corsHeaders, "Content-Type": "application/json" }, status: 401, } ); } }); ``` Once deployed, your function is accessible at: ``` ${SUPABASE_URL}/functions/v1/exchange-jwt ``` ## Step 4: Create the database table and RLS policies Now let’s set up the database table and RLS rules in Supabase. We’ll create a table (`instruments`) to store items owned by users, and use RLS to ensure each user can only manipulate their own rows. Open the SQL editor in your Supabase project and run the following SQL commands: ```sql -- 1. Helper function to get the current Authgear user ID from the JWT CREATE OR REPLACE FUNCTION current_user_id() RETURNS TEXT AS $$ SELECT auth.jwt() ->> 'sub'; $$ LANGUAGE SQL STABLE; ``` We created a SQL function `current_user_id()` that returns the JWT’s `sub` claim (subject) from the current request’s JWT. Supabase’s Postgres has an `auth.jwt()` function that exposes the JWT claims of the requester; `auth.jwt() ->> 'sub'` extracts the `sub` field as text. ```sql -- 2. Instruments table: each row has a user_id to identify the owner CREATE TABLE instruments ( id BIGSERIAL PRIMARY KEY, created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL, name TEXT NOT NULL, user_id TEXT NOT NULL -- store Authgear user’s ID (sub) ); -- 3. Enable Row Level Security on the table ALTER TABLE instruments ENABLE ROW LEVEL SECURITY; ``` * The `instruments` table has a `user_id` column which will store the Authgear user’s ID for each instrument. * We enabled RLS on the table, which means by default no rows can be accessed unless allowed by a policy. ```sql -- 4. RLS Policies: -- Allow each authenticated user to SELECT rows where user_id = their own ID CREATE POLICY "Users can read their own instruments" ON instruments FOR SELECT TO authenticated USING (user_id = current_user_id()); -- Allow INSERTs only if setting user_id to their own ID CREATE POLICY "Users can insert their own instruments" ON instruments FOR INSERT TO authenticated WITH CHECK (user_id = current_user_id()); -- Allow UPDATE on rows they own CREATE POLICY "Users can update their own instruments" ON instruments FOR UPDATE TO authenticated USING (user_id = current_user_id()) WITH CHECK (user_id = current_user_id()); -- Allow DELETE on rows they own CREATE POLICY "Users can delete their own instruments" ON instruments FOR DELETE TO authenticated USING (user_id = current_user_id()); ``` We then defined four policies, one for each CRUD operation (SELECT, INSERT, UPDATE, DELETE). Each policy is limited to the `authenticated` role and uses a condition requiring that the row’s `user_id` matches the user’s id from the JWT. ## Step 5. Build the React app with Supabase Client Now for the frontend. We will create a React app using Vite, integrate Authgear’s SDK for authentication, and configure the Supabase client to use our token exchange flow automatically. **Dependencies** 1. Scaffold a React App by `npm create vite@latest my-app -- --template react` 2. Follow the guide for build SPA in here: [React](/get-started/single-page-app/react) to setup a basic react app with Authgear authentication 3. Install the Supabase library by ``` npm install @supabase/supabase-js ``` 4. Configure the Environment Variables in `.env` and make the Supabase URL and Publishable key available. You `.env.local` should look like: ``` VITE_SUPABASE_URL=https://your-project.supabase.co VITE_SUPABASE_PUBLISHABLE_KEY=your-supabase-anon-key VITE_AUTHGEAR_ENDPOINT=https://your-app.authgear.cloud VITE_AUTHGEAR_CLIENT_ID=your-authgear-client-id VITE_AUTHGEAR_REDIRECT_URL=http://localhost:5173/auth-redirect VITE_AUTHGEAR_LOGOUT_REDIRECT_URL=http://localhost:5173/ ``` **Configure the Supabase Client** Now we can set up the Supabase JS client to use our Authgear token. Create a new file `my-app/src/lib/supabase.js` and add the following: ```javascript // my-app/src/lib/supabase.js import { createClient } from '@supabase/supabase-js'; import authgear from '@authgear/web'; const SUPABASE_URL = import.meta.env.VITE_SUPABASE_URL; const SUPABASE_ANON_KEY = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY; // Optional: caches to avoid redundant token exchanges let cachedSupabaseJwt = null; let cachedAuthgearToken = null; // Function to exchange Authgear token for Supabase token async function exchangeToken(authgearToken) { // Return cached token if the Authgear token hasn’t changed if (cachedAuthgearToken === authgearToken && cachedSupabaseJwt) { return cachedSupabaseJwt; } // Call the Supabase Edge Function const res = await fetch(`${SUPABASE_URL}/functions/v1/exchange-jwt`, { headers: { Authorization: `Bearer ${authgearToken}` } }); if (!res.ok) { throw new Error(`Token exchange failed with status ${res.status}`); } const { supabaseJwt } = await res.json(); // Update cache and return the new JWT cachedAuthgearToken = authgearToken; cachedSupabaseJwt = supabaseJwt; return supabaseJwt; } // Create Supabase client with custom auth settings export const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, { auth: { autoRefreshToken: false, // Don't use Supabase’s token refresh persistSession: false, // Don't store Supabase session (Authgear will handle session) }, accessToken: async () => { // This function runs before every Supabase request that needs auth await authgear.refreshAccessTokenIfNeeded(); const authgearToken = authgear.accessToken; if (!authgearToken) return null; // Exchange Authgear token for a Supabase token:contentReference[oaicite:12]{index=12}:contentReference[oaicite:13]{index=13} return exchangeToken(authgearToken); }, }); ``` In this configuration: * We disable `autoRefreshToken` and `persistSession` in Supabase’s client so that Authgear is the source of truth for the session. * We provide an `accessToken` async function. The Supabase Client will call this function every time it needs a JWT for an authenticated request. In our case, that is every query to our `instruments` table. * In `accessToken()`, we first ensure Authgear’s token is fresh by calling `authgear.refreshAccessTokenIfNeeded()`. * We then get `authgear.accessToken` – this is the current JWT from Authgear’s SDK. * If the token exists, we call our `exchangeToken()` helper, which calls the Edge Function’s endpoint with the Authgear token and receives a Supabase JWT in response. **Build the CRUD functions** After login, use the Supabase client to fetch and manipulate data. For example, to load the current user’s instruments, you can call: {% code overflow="wrap" %} ```javascript const { data, error } = await supabase.from('instruments').select('*'); ``` {% endcode %} To add a new instrument, call ```javascript supabase.from('instruments').insert({ name: "", user_id: userInfo.sub, }); ``` Similarly, to update or delete, similarly call `.update(...)` or `.delete(...)` in the Supabase Client with appropriate filters ## 6. Run and test the app We’re ready to test the whole system. Start the development server: ```bash npm run dev ``` Open `http://localhost:5173` in your browser and test the integration. ## That's it You’ve successfully integrated Authgear for authentication with Supabase for secure, per-user data access using Row-Level Security. With this setup, you can take full advantage of Authgear’s powerful authentication features like social logins, 2FA, and secure session management, while leveraging Supabase’s scalable database and built-in RLS to keep user data isolated and protected. This token exchange approach makes it easy to use Authgear (or any other JWT-based provider) with Supabase. # Authgear and Firebase Guide on how to use Authgear to secure Firebase services ## How to use a third-party authentication system to secure Firestore and other Firebase services. Firebase is Google's flagship solution for building serverless web and mobile applications. Some of the services Firebase offers include Firestore database, Cloud Storage, Cloud Functions, and Authentication. You can secure Firebase services like Firestore and Cloud Storage such that only authenticated users in your app have read and write access to certain parts or the entire database. This can be useful when your app allows users to generate content and you need to control who can add or view what. In this guide, you'll learn how to use Authgear as a custom authentication system to secure Firestore database. ## Why use Authgear with Firebase? Authgear is a cloud-based solution that is 100% focused on user authentication and IAM. While Firebase, on the other hand, offers other cloud services such as Cloud Storage and real-time database Firestore that enable developers to build full-stack apps without the need for implementing their own backend. Hence, you can use Authgear as an authentication provider for your app that uses Firebase to enjoy all the security and login features it offers. ## What is Firebase Custom Tokens? Custom Tokens is a feature in Firebase that allows you to authenticate users using secure JWT (JSON Web Tokens) from a third-party authentication system. Typically, to authenticate users via Custom Tokens, your authentication system (e.g., Authgear) will authenticate users using your preferred method (e.g., username and password), then return a valid JWT to your client application. The client application will pass the JWT to Firebase to create a Firebase user instance using the user's `sub` attribute from Authgear. The following flow diagram shows the complete sequence of using Firebase Custom Tokens and Authgear.

flow diagran for authgear-firebase integration

## How to integrate Authgear with Firebase using Custom Tokens In this section, we'll cover a step-by-step guide for using Authgear JWT with Firebase Custom Tokens. {% hint style="info" %} **Code Example** The example app used for this guide is based on the Authgear React example repo (clone or download the code [here](https://github.com/authgear/authgear-example-react)). Once you get the code, you'll have to set up an Authgear client application with type "Single Page Application" in the Authgear portal. More details are in the README.md file for the repo. Alternatively, you can view/download the complete code with the Firebase example from a separate GitHub repo [here](https://github.com/authgear/authgear-example-firebase). {% endhint %} As part of the guide, we'll build a demo Todo app. The app will have the following features: * Users Login/Sign up * Add to-do tasks * Delete to-do tasks * Only logged-in users can add tasks * Data is stored on the cloud, and a user can only view/delete tasks they created. ### Prerequisites In order to follow the steps in this guide, you should have the following: * Authgear account (sign up for free [here](https://portal.authgear.com/)) * Firebase project * Node.js installed on your computer ### Part 1: Configure Firebase For this part, you'll login to your Firebase console and configure your project. #### Step 1: Create Cloud Function First, we'll create a Cloud Function that will verify the access token (JWT) from Authgear and use the `uid` associated with the JWT to create a Firebase Custom Token. **Note:** this may require you to upgrade your Firebase project to at least the Blaze plan. 1. To create a Cloud Function, open and navigate to **Build** > **Functions** and enable the Cloud Function if it isn't already active for your project. 2. Next, create a `cloud_functions` folder in the root directory of the Authgear React example project you cloned earlier. 3. Change your working directory to the `cloud_functions` folder: ```sh cd cloud_functions ``` 4. Run the following command to install Firebase CLI: ```sh npm install -g firebase-tools ``` 5. After the CLI is installed, run the `firebase login` command and follow the prompt to login to your Firebase project in the CLI. 6. Run the following command to initialize Cloud Function in the cloud\_functions folder you created earlier: ```sh firebase init ``` Follow the prompt to create a v2 Cloud Function. Now you should have a `function/index.js` file in your cloud\_functions folder. This is where you'll write the code for your cloud function. #### Step 2: Enable token creator permission for cloud functions Edit the IAM settings for the service account linked to your project. To do this, go to and add `Service Account Token Creator` to `{randomNumbers}-compute@developer.gserviceaccount.com`. #### Step 3: Implement Cloud Function In this step, we'll implement a cloud function that does the following: * Accept HTTPS requests from your client application through an endpoint. * Read the value of your Authgear JWT from the HTTPS request authorization header. * Validate the JWT to ensure it is valid (not expired). * If the JWT is valid, the function will read the `uid` attribute from it and use the value to call `firebaseAdmin.auth().createCustomToken(uid)`. This will generate a new Firebase Custom Token that your client application can use to login to Firebase. To implement the above function, open `function/index.js` in your `cloud_functions` folder and replace the content with the following: ```javascript const { onRequest } = require("firebase-functions/v2/https"); const jwt = require("jsonwebtoken"); const jwks = require("jwks-rsa"); const firebaseAdmin = require("firebase-admin"); const authgearEndpoint = ""; //place your authgear app endpoint here // Get JWKs URI from Open ID Configuration documents const getJwksUri = async (authgearEndpoint) => { const config_endpoint = authgearEndpoint + "/.well-known/openid-configuration"; const response = await fetch(config_endpoint); const data = await response.json(); return data.jwks_uri; }; // Options for JWT verification const options = { algorithms: ["RS256"], issuer: authgearEndpoint, }; const checkReq = (req) => { const headerErr = ["must specify an Authorization header", null]; const formatErr = ["format is 'Authorization: Bearer '", null]; if (!req) return "server error (request was invalid)"; const { headers } = req; if (!headers) return headerErr; // missing header const { authorization } = headers; if (!authorization) return headerErr; // missing Authorization Header const parts = authorization.split(" "); if (parts.length != 2) return formatErr; // Authorization header format invalid const [scheme, credentials] = parts; if (!/^Bearer$/i.test(scheme)) return formatErr; // Authorization header is not Bearer return [false, credentials]; }; firebaseAdmin.initializeApp(); exports.getFirebaseToken = onRequest(async (req, res) => { res.set("Access-Control-Allow-Origin", "*"); if (req.method === "OPTIONS") { res.set("Access-Control-Allow-Methods", "GET"); res.set("Access-Control-Allow-Headers", "Authorization"); res.set("Access-Control-Max-Age", "3600"); return res.status(204).send(""); } const [message, token] = checkReq(req); if (message) { return res.status(500).send({ message }); // return error message if checkReq failed } else { const decodedAccessToken = jwt.decode(token, { complete: true }); // get signing key from JWKs with the "kid" in decoded access token jwksUri = await getJwksUri(authgearEndpoint); const client = jwks({ rateLimit: true, strictSsl: true, jwksUri: jwksUri, }); const signingKey = await client.getSigningKey( decodedAccessToken.header.kid ); try { const decoded = jwt.verify(token, signingKey.publicKey, options); // verify jwt const uid = decoded.sub; // if the jwt is verified, use "sub" in JWT as uid const firebaseToken = await firebaseAdmin.auth().createCustomToken(uid); // create Firebase custom token with uid return res.json({ firebaseToken }); // return Firebase custom token } catch (err) { return res.status(500).send(err); } } }); ``` Put your Authgear endpoint in `const authgearEndpoint = "";`. Run the following commands to install dependencies: ```sh npm i jwks-rsa npm i jsonwebtoken ``` Finally, run `firebase deploy` to deploy your new function. On successful deploy, Firebase CLI will output the public endpoint for your function in the terminal. Copy the endpoint as you will use it later in your React app.

firebase function URL

### Part 2: Implement React App In this part, we'll implement the client application that will use Authgear and Firebase. As mentioned in the prerequisites for this post, you can get the starter code for the application from our React example app repo. #### Step 4: Add Firebase to React App 1. Go to the Firebase Console and select your project. Next, click on **Web** as your target platform. 2. Enter the name of your app (e.g., My todo app), then click **Register app**. 3. In the Add Firebase SDK section, select **Use npm**, then run `npm install firebase` from the root directory of the Authgear React example repo (confirm that you're not running the command in the cloud\_functions folder). 4. Create a new `firebase.js` file in the root directory of your React project. 5. Copy the code that includes your Firebase config, and paste it in the `firebase.js` file.\\

Firebase app config

1. Update `firebase.js` to expose the Firebase services you'll be using: ```javascript import { initializeApp } from 'firebase/app'; import { getAuth } from 'firebase/auth'; import { getFirestore } from "firebase/firestore"; // Your web app's Firebase configuration const firebaseConfig = { apiKey: "", authDomain: "", projectId: "", storageBucket: "", messagingSenderId: "", appId: "" }; // Initialize Firebase const app = initializeApp(firebaseConfig); export const auth = getAuth(app); export const db = getFirestore(app); ``` #### Step 5: Create Todo Component Here we'll implement a to-do feature in our React app. The Todo component will contain all the code for implementing this feature. The component will do the following: * Get the current user's access token from Authgear using the Authgear SDK. * Make an HTTPS request to your Firebase function endpoint using the `fetch()` method of the Authgear SDK. The `fetch()` method includes the user's access token in the HTTPS request's authorization header. * Use the custom token that is returned by the cloud function to sign in to Firebase. * Add a new todo item to the Firestore database * Display the todo items * Delete a todo item Create a `Todo.tsx` file in the src folder of your React project, then add the following code to the file: ```javascript import React, { useEffect, useState, useContext } from "react"; import authgear from "@authgear/web"; import { UserContext } from "./context/UserProvider.js"; import { signInWithCustomToken, UserCredential } from "firebase/auth"; import { collection, getDocs, addDoc, deleteDoc, doc } from "firebase/firestore"; import { auth, db } from "../firebase.js"; interface Todo { id: string; text: string; userId: string; } const Todo: React.FC = () => { const { isLoggedIn } = useContext(UserContext); const [firebaseUser, setFirebaseUser] = useState({}); const [authError, setAuthError] = useState(false); const [todos, setTodos] = useState([]); const [newTodo, setNewTodo] = useState(""); useEffect(() => { async function getFirebaseUser() { if (isLoggedIn) { const firebaseFunctionEndpoint = ""; // place your cloud function endpoint here. try { const getCustomToken = await authgear .fetch(firebaseFunctionEndpoint) .then((response) => response.json()); if (getCustomToken.firebaseToken !== null) { const firebaseUserObj = await signInWithCustomToken( auth, getCustomToken.firebaseToken ); setFirebaseUser(firebaseUserObj); setAuthError(false); } } catch (e) { console.log(e); setAuthError(true); } } else { setAuthError(true); } } getFirebaseUser() .then(() => { fetchTodos(); }) .catch((e) => { console.error(e); }); }, [authgear]); async function fetchTodos() { try { const querySnapshot = await getDocs(collection(db, "todos")); const todoList = querySnapshot.docs.map((doc) => ({ id: doc.id, ...doc.data(), })) as Todo[]; setTodos(todoList); } catch (error) { console.error("Error fetching todos:", error); } } async function addTodo(e: React.FormEvent) { e.preventDefault(); if (!newTodo.trim() || authError) return; try { await addDoc(collection(db, "todos"), { text: newTodo, userId: (firebaseUser as UserCredential).user.uid, createdAt: new Date(), }); setNewTodo(""); fetchTodos(); } catch (error) { console.error("Error adding todo:", error); } } async function deleteTodo(id: string) { try { await deleteDoc(doc(db, 'todos', id)); fetchTodos(); } catch (error) { console.error('Error deleting todo:', error); } } if (!authError) { return (
setNewTodo(e.target.value)} placeholder="Add a new todo" />
    {todos.map((todo) => (
  • {todo.text}
    • ))}
); } else { return (

User not logged in

); } }; export default Todo; ``` Add your Cloud Function endpoint in `const firebaseFunctionEndpoint = "";` #### Step 6: Create Route for Todo Component Open `App.tsx` and add the following route in ``: ```tsx } /> ``` Make sure to import the Todo in App.tsx. ```javascript import Todo from "./Todo"; ``` Finally, add a router link to `Home.tsx` just after the **User Settings** link: ```tsx My Todos ``` You can click on the **My Todos** link to open the Todo page. #### Step 7: Update Firestore Security Rule Return to your project in Firebase console, then navigate to **Build** > **Firestore Database**. Enable Firestore if it's not active for your project.
Go to the Rules tab, then change the security rule to the following: ```javascript service cloud.firestore { match /databases/{database}/documents { match /todos/{userId} { allow read: if request.auth.uid != null; allow write: if request.auth.uid != null; } } } ``` The above rule will restrict read and write access to data in /todos/{userID} to only authenticated users. Click **Publish** to activate the new rule. #### Step 8: Run React App Follow the instructions in the `README.md` file for the Authgear React example app [here](https://github.com/authgear/authgear-example-react/blob/master/README.md) to configure the app with your Authgear project. Then run the app. You should be able to authenticate with Authgear and add items to the to-do.

UI of demo app

# Integrate with Google Tag Manager Learn how to integrate popular analytics and tracking tools into your Authgear project using Google Tag Manager Authgear allows you to add third-party user analytics tools to your project using Google Tag Manager. ### What is Google Tag Manager? Google Tag Manager (GTM) is a tag management tool from Google that makes it easy to add marketing tags to your website without modifying the site's source code. Tags can help you track traffic and user behavior on your website or application. In this guide, we will show you how to add Google Tag Manager to your Authgear project and send data to Google Analytics. You can also configure Google Tag Manager to send data from your Authgear project to other marketing tags from providers like Facebook. ### Prerequisites In order to setup Google Tag Manager and Google Analytics with Authgear, you need to have the following: 1. Authgear account 2. Google Tag Manager Account 3. Google Analytics Account ## Part 1: Connect Google Tag Manager to Authgear project The process for connecting your GTM account to Authgear is simple and can be done in these two steps. ### Step 1: Get GTM container ID Google Tag Manager lets you create containers that hold marketing tags. Each container has a unique ID and you'll need this container ID to connect your GTM container to Authgear. To get the container ID, log in to [GTM](https://tagmanager.google.com/) and navigate to the dashboard's homepage. You should find a list of all your containers and their ID. Note down the ID for the container you wish to connect to Authgear.
If you don't have a container for your Authgear project yet, click on **Create Account** to create a new container. Enter your domain name for your Authgear project as the container name and select a target platform. For this example, we'll select **Web** as the target platform.
### Step 2: Add GTM container ID to Authgear First, log in to the Authgear Portal, then select your project and navigate to **Integrations**.
Click on the **Connect** button next to the Google Tag Manager addon to open the configuration page.
Paste the GTM container ID you got from the previous step then click the Save button. And with that, you've successfully connected your GTM container to Authgear. In the next steps, we'll show you how to create tracking tags and send data to Google Analytics. ## Part 2: Track traffic and send data to Google Analytics Google Analytics is one of the marketing tags we can manage from GTM. In this part of the guide, we'll set up some tags to track page views and user events like clicking on a link or button. The tags will send these data to Google Analytics. ### Step 1: Set up Google Analytics data stream In order to create tags that send data to Google Analytics, you need to have an active data stream on Google Analytics. GTM requires the details for this stream while creating new tags for Google Analytics. To create a stream, log in to Google Analytics then navigate to the **Admin** settings page.
Create a new Google Analytics property for your Authgear project or select an existing one. Click on the Data Streams item under the property to view all streams and add a new web stream for your Authgear project. Note down the Measurement ID for your stream as we'll be using it later to create new tags.
### Step 2: Create a new user-defined variable in GTM Before we start sending data to Google Analytics, let's create a new variable in Google Tag Manager. Go back to GTM and select the correct container for your project.
Next, click on the **Variables** item on the left side navigation bar and create a new user variable with the following details: * **Variable type**: Data Layer Variable * **Data Layer Variable Name**: gtm.element.dataset.authgearEvent Once you're done save the variable as "gtm.element.dataset.authgearEvent" and continue to the next step. ### Step 3: Create a click Trigger Navigate to **Triggers** from the sidebar and create a new trigger with the following details: * **Trigger type**: Click > All Elements * **This trigger fires on**: Some Clicks Authgear's implementation of GTM is declarative. The primary button on each page has `data-authgear-event` attribute. We'll be setting a condition for the "Some Clicks" using that attribute. Configure Some "Click" as shown below:
Next, save the trigger as "Authgear-btn-click" and continue. ### Step 4: Create Page View Tag Navigate to **Tags** from the sidebar and create a new tag with the following configurations: * **Tag type**: Google Analytics > Google Tag * **Tag ID**: \ Next, expand the **Advanced Settings** section and set **Tag firing options** to **Once per page**. Now, scroll down to the Trigger section of the new tag and select **All Pages (page view)** as the trigger. Save this new tag as "Auth-gear-pageview" and continue. ### Step 5: Create Event Tag In this step, create another tag with the following configuration: * Tag type: Google Analytics > Google Analytics: GA4 Event * Measurement ID: \ * Event Name: `gtm.element.dataset.authgearEvent` Next, set the trigger for this tag to the "Authgear-btn-click" trigger we created earlier. Save the tag as "Authgear-event-tag" and continue to preview the entire setup or publish to go live. ## Conclusion After you publish your changes in Google Tag Manager when users generate hits or click buttons with the `data-authgear-event` attribute on your project you should see data on Google Analytics. The following is a list of values for the `data-authgear-event` attribute: * `authgear.button.change_password` * `authgear.button.change_additional_password` * `authgear.button.create_password` * `authgear.button.change_login_id` * `authgear.button.remove_login_id` * `authgear.button.resend_oob_otp` * `authgear.button.enter_oob_otp` * `authgear.button.enter_password` * `authgear.button.enter_recovery_code` * `authgear.button.enter_totp` * `authgear.button.send_reset_password_code` * `authgear.button.sign_in` * `authgear.button.sign_up` * `authgear.button.sign_out` * `authgear.button.oauth` * `authgear.button.reset_password` * `authgear.button.continue_with_current_account` * `authgear.button.use_another_account` * `authgear.button.remove_biometric` * `authgear.button.schedule_account_deletion` * `authgear.button.connect_oauth` * `authgear.button.disconnect_oauth` * `authgear.button.resend_verification_code` * `authgear.button.update_profile` * `authgear.button.regenerate_recovery_code` * `authgear.button.download_recovery_code` * `authgear.button.remove_totp` * `authgear.button.remove_oob_otp` * `authgear.button.setup_oob_otp` * `authgear.button.setup_totp` * `authgear.button.enter_verification_code` * `authgear.button.revoke_session` * `authgear.button.revoke_session_group` * `authgear.button.revoke_all_sessions` # FAQ for Integration # How to Track User Before and After Signup? Learn how to track a user that signs up from a particular source or campaign. In this guide, you'll learn how to track users from a particular source before and after they sign up. For example, knowing how many people sign up for your application through a signup link that you have included in a blog post or an email campaign. ### Prerequisites To follow this guide, you need to have the following: * A free Authgear account. * An application in the Authgear Portal and note down the configuration of the application. * A client application that is written in your preferred language or framework. ### What We'll Build For this guide, we'll build a demo Express application that has the following features: * Read a `source` URL parameter defined by you (the developer). * Send the value of the `source` parameter to the Authgear authorization server using the OAuth 2.0 `state` parameter. * Read the value of `state` returned after user authorization (sign up) and log the value in a database or analytics system like Mixpanel. ### What is the OAuth 2.0 State Parameter? The [OAuth 2.0 framework](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) includes an optional `state` parameter. The value of the `state` parameter can be any random string or number defined by a client application (e.g a web or mobile that uses Authgear for user authentication) before the client makes an authorization request. In simple terms, the `state` parameter is added to the authorization URL as a URL query. The authorization server (Authgear) will include the same state parameter value when redirecting the user-agent back to the client application. As a result, the client application can retrieve the value of `state` returned to verify that it is the origin of the authorization request. We will use the above behavior of the authorization process to track a user before and after they sign up. ## How to Track a User Who Signs Up from a Particular Source The following steps show the steps for building a simple application that is capable of tracking users before and after they sign up. ### Step 1: Set Up Your App to Use Authgear First, create a new project directory and open it. The demo application for this guide is a simple [Express](https://expressjs.com/) application that use Axios to make HTTP requests. Hence, install both packages using the following commands: 1\. Express: ```sh npm install express ``` 2\. Axios: ```sh npm install axios ``` Next, inside the project directory, create a new **app.js** file then add the following code to the file: ```javascript const express = require('express'); const axios = require('axios'); const app = express(); const port = process.env.PORT || 3000; const config = { client: { id: "CLIENT_ID", secret: "CLIENT_SECRET", redirect_url: "REDIRECT_URL" }, auth: { tokenHost: "AUTHGEAR_ENDPOINT", tokenPath: '/oauth2/token', authorizePath: '/oauth2/authorize', scope: 'openid offline_access' }, }; ``` You can get the correct configuration values (CLIENT\_ID, CLIENT\_SECRET, REDIRECT\_URL, and AUTHGEAR\_ENDPOINT) from the **Applications** section of the Authgear Portal. ### Step 2: Add State Parameter to Authorization Request In this step, we'll implement a `/login` route in the demo application. This route will support a `source` query parameter, for example, `/login?source=002`. Add the following code to the end of **app.js** to implement the `/login` route: ```javascript app.get("/login", (req, res) => { const url = new URL(`${config.auth.tokenHost}${config.auth.authorizePath}`); url.searchParams.set('client_id', config.client.id); url.searchParams.set('redirect_uri', config.client.redirect_url); url.searchParams.set('response_type', 'code'); url.searchParams.set('scope', config.auth.scope); if (req.query.source != null) { url.searchParams.set('state', req.query.source); } res.redirect(url); }); ``` The above code will check if the source parameter is included in the HTTP request to the `/login` route. If there is a `source` parameter, the value of the source will be added to the authorization URL's state parameter. The following is an example of a login URL that includes the source parameter: ```url http://localhost:3000/login?source=002 ``` ### Step 3: Read the Value of State After Authorization As described earlier, Authgear will return whatever value you put in the `state` parameter of the authorization URL. In the last step, we will read the value of the `source` parameter from the `/login` route and pass it to the `state` parameter. In this step, we'll read the `state` parameter that Authgear returns in the redirect URI for the initial value we passed (`source`). To do this, we'll add a `/` route to resolve our redirect URI. Add the following code to the end of **app.js** to implement the route: ```javascript app.get("/", async (req, res) => { if (req.query.code != null) { const data = { client_id: config.client.id, client_secret: config.client.secret, code: req.query.code, grant_type: 'authorization_code', response_type: 'code', redirect_uri: config.client.redirect_url, scope: config.auth.scope }; const sourceFromState = req.query.state; try { const getToken = await axios.post(` ${config.auth.tokenHost}${config.auth.tokenPath}`, data, { headers: { "Content-Type": "application/x-www-form-urlencoded" } } ); const accessToken = getToken.data.access_token; res.send(`

Access token: ${accessToken}, ${sourceFromState}

`); } catch (error) { res.send("An error occurred! Login could not complete. Error data: " + error); } } else { res.send(`

Hi there!

This demo app shows you how to add user authentication to your Express app using Authgear

Checkout docs.authgear.com to learn more about adding Authgear to your apps.

Login
`); } }); app.listen(port, () => { console.log(`server started on port ${port}!`); }); ``` The `sourceFromState` constant holds the value for the state parameter in the redirect URI. You can save this value to a database to track that the user has successfully signed up using the link with the source value in your original campaign link. You may also send this link to an analytic tool like Mixpanel to track the user and source. To run the demo app, run the following command in the terminal: ```sh node app.js ``` Then, open `http://localhost:3000/login?source=002` on a browser. You can change 002 to any random string that you wish to use for tracking a source or campaign. Also, be sure to add `http://localhost:3000` as a redirect URL for your application in the Authgear Portal. # What happens with user directly access the Authgear Endpoint? Endpoint Direct Access lets you configure what happens when users unexpectedly access your Authgear project endpoint without using OIDC/SDK/SAML. 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.

Show a link under your logo and project name

## Cookie-based Authentication If you are using [Cookie-based authentication](#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](/customization/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](/customization/built-in-ui/user-settings) page (`/settings`). {% hint style="info" %} This is only applicable for cookie-based authentication. If you integrate Authgear with the SDKs, OIDC or SAML protocols, the user should not access the endpoint URL directly in their browser. The authentication should be triggered from the flows. {% endhint %} ### **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](/customization/built-in-ui/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. --- [Next Page](/llms-full.txt/1)