Authgear
Start BuildingHomePortalCommunity
  • Authgear Overview
  • Get Started
    • 5-Minute Guide
    • Start Building
    • Single-Page App
      • JavaScript (Web)
      • React
      • Angular
      • Vue
    • Native/Mobile App
      • iOS SDK
      • Android SDK
        • Android Kotlin coroutine support
        • Android OKHttp Interceptor Extension (Optional)
      • Flutter SDK
      • React Native SDK
      • Ionic SDK
      • Xamarin SDK
      • Using Authgear without SDK (Client side)
    • Regular Web App
      • Express
      • Next.js
      • Python Flask App
      • Java Spring Boot
      • ASP.NET Core MVC
      • Laravel
      • PHP
    • Backend/API Integration
      • Client SDK to make authorized API calls to backend
      • Validate JWT in your backend
      • Forward Authentication to Authgear Resolver Endpoint
    • AI Coding tools
      • Cursor/Windsurf
    • Integration by OIDC
    • Integration by SAML
      • Use Authgear as SAML Identity Provider for Salesforce
      • Use Authgear as SAML Identity Provider for Dropbox
      • SAML Attribute Mapping
  • Authentication and Access
    • Authentication
      • Add Passkeys Login
      • Add WhatsApp OTP Login
      • Add Email Magic Link Login
      • Add Biometric Login
      • Add Anonymous Users
      • Enable Two-Factor Authentication (2FA)
      • Re-authentication
      • Set Password Expiry
      • Change Forgot/Reset Password settings
      • Add authentication to any web page
    • Single Sign-on Overview
      • App2App Login
      • App2Web (Pre-authenticated URLs)
      • Web2App (From Mobile Apps to Browsers)
      • Force Authgear to Show Login Page
      • Single Sign-on with OIDC
      • Single Sign-on with SAML
    • Social/Enterprise Login Providers Overview
      • Social Login Providers
        • Connect Apps to Apple
        • Connect Apps to Google
        • Connect Apps to Facebook
        • Connect Apps to GitHub
        • Connect Apps to LinkedIn
        • Connect Apps to WeChat
      • Enterprise Login Providers
        • Connect Apps to Azure Active Directory
        • Connect Apps to Microsoft AD FS
        • Connect Apps to Azure AD B2C
      • Force Social/Enterprise Login Providers to Show Login Screen
  • FAQ for Authentication
    • Tips for Apple App Store Review with Passwordless Login
    • Phone Number Validation
    • Skip Login Screen and Direct Users to Enterprise Login
    • Use the OAuth 2.0 State Parameter
    • Local Dev Setup for Connecting to Authgear SaaS in Cookie-based Auth
  • Integration
    • Add custom fields to a JWT Access Token
    • User Profiles
      • What is User Profile
      • Access User Profiles
      • Update User Profiles
      • Profile Custom Attributes
      • Update user profile on sign-up using Hooks
    • Mobile Apps
      • Force authentication on app launch
      • Customize the Login Pop-up / Disable the login alert box
    • Integration with other Software
      • Integrate Authgear with Firebase
      • Integrate with Google Tag Manager
    • FAQ for Integration
      • How to Track User Before and After Signup?
      • What happens with user directly access the Authgear Endpoint?
  • Customization
    • Built-in UI
      • Branding in Auth UI
      • User Settings
      • Privacy Policy & Terms of Service Links
      • Customer Support Link
      • Custom Text
      • Languages and Localization
    • Custom UI
      • Authentication Flow API
      • Implement Authentication Flow API using Express
      • Implement Authentication Flow API using PHP
      • Add Custom Login/Signup UI to Native Apps
      • Manually Link OAuth Provider using Account Management API
      • Implement a custom account recovery UI using Authentication Flow API
    • Custom Domain
    • Custom Email and SMS Templates
    • Custom Email Provider
    • Custom SMS Provider
      • Twilio
      • Webhook/Custom Script
    • Events and Hooks
      • Event List
      • Webhooks
      • JavaScript / TypeScript Hooks
      • Example: Only Allow Signups from Inside the Corporate Network using Hooks
  • Admin & Operations
    • Monitor
      • Audit Log For Users Activities
      • Audit Log for Admin API and Portal
      • Analytics
    • User Management
      • Account Deletion
      • Import Users using User Import API
      • Export Users using the User Export API
      • Manage Users Roles and Groups
      • How to Handle Password While Creating Accounts for Users
    • Migration
      • Bulk migration
      • Rolling migration
      • Zero-downtime migration
  • Security
    • Brute-force Protection
    • Bot Protection
    • Non-HTTP scheme redirect URI
    • Password Strength
  • Reference
    • APIs
      • Admin API
        • Authentication and Security
        • API Schema
        • API Queries and Mutations
        • Using global node IDs
        • Retrieving users using Admin API
        • API Examples
          • Generate OTP code
          • Search for users
          • Update user's picture
          • Update user's standard attributes
      • Authentication Flow API
      • OAuth 2.0 and OpenID Connect (OIDC)
        • Supported Scopes
        • UserInfo
      • User Import API
      • User Export API
    • Tokens
      • JWT Access Token
      • Refresh Token
    • Rate Limits
      • Account Lockout
    • Glossary
    • Billing FAQ
  • Authgear ONCE
    • What is Authgear ONCE
    • Install Authgear ONCE on a VM
    • Install Authgear ONCE on Amazon Web Services (AWS)
    • Install Authgear ONCE on Vultr
  • Concepts
    • Identity Fundamentals
    • Authgear use cases
    • User, Identity and Authenticator
  • Client App SDKs
    • Javascript SDK Reference
    • iOS SDK Reference
    • Android SDK Reference
    • Flutter SDK Reference
    • Xamarin SDK Reference
  • Deployment
    • Run with Docker
    • Deploy with Helm chart
    • Authenticating HTTP request with Nginx
    • Configuration
      • Environment Variables
      • authgear.yaml
      • authgear.secrets.yaml
    • Architecture Guides
      • AWS Reference Architecture
      • Azure Reference Architecture
      • Google Cloud Reference Architecture
      • Throughput Scaling Reference
  • Troubleshooting
    • How to Fix SubtleCrypto: digest() undefined Error in Authgear SDK
    • How to Fix CORS Error
Powered by GitBook
On this page
  • Setup Application in Authgear
  • Step 1: Create an application in the Portal
  • Step 2: Configure the application
  • Add Authgear to any web page using JavaScript
  • Step 1: Create a Basic Single Page Web Application
  • Step 2: Create Web Server
  • Step 3: Create Web Page
  • Step 4: Install Authgear Web JavaScript SDK
  • Step 5: Initialize Authgear SDK
  • Step 6: Start the authentication flow
  • Step 7: Handling auth result in the redirectURI
  • Step 8: Open User Settings Page
  • Step 9: Additional Actions
  • Next steps
  • JavaScript SDK Reference

Was this helpful?

Edit on GitHub
Export as PDF
  1. Get Started
  2. Single-Page App

JavaScript (Web)

Integrate Authgear to your website with the Web SDK

PreviousSingle-Page AppNextReact

Last updated 5 days ago

Was this helpful?

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.

See and clone the full code for the demo app for this tutorial in the Github Repo here.

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 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 the application type Single Page Application. Click the Save button to proceed.

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/

Note that the trailing "/" in the above URLs must be included.

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:

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:

npm init -y

Install the Express npm package:

npm install express

Install Nodemon (used for adding hot road to JavaScript development):

npm install -D nodemon

Now create a server.js file in the root folder of your project. Add the following code to server.js:

const express = require("express");
const { join } = 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("/*", (_, res) => {
  res.sendFile(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:

"start": "node server.js",
"dev": "nodemon server.js"

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.

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:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Authgear SPA SDK Sample</title>
    <link rel="stylesheet" type="text/css" href="/css/main.css" />
  </head>

  <body>
    <h2>SPA Authentication Sample</h2>
    <p>Welcome to our page!</p>
    <button id="btn-login" disabled="true" onclick="login()">Log in</button>
    <button id="btn-logout" disabled="true" onclick="logout()">Log out</button>
  </body>
</html>

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:

<script src="https://unpkg.com/@authgear/web@2.2.0/dist/authgear-web.iife.js"></script>

The Web JS SDK is also available as an npm package. That can be installed using any of the following commands:

NPM

npm install --save --save-exact @authgear/web

Yarn

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 <script> tag to index.html on a new line just before the </body> . Your index.html should look like this at this point:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Authgear SPA SDK Sample</title>
    <link rel="stylesheet" type="text/css" href="/css/main.css" />
  </head>

  <body>
    <h2>SPA Authentication Sample</h2>
    <p>Welcome to our page!</p>
    <button id="btn-login" disabled="true" onclick="login()">Log in</button>
    <button id="btn-logout" disabled="true" onclick="logout()">Log out</button>
    <script src="https://unpkg.com/@authgear/web@2.2.0/dist/authgear-web.iife.js"></script>
  </body>
</html>

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:

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:

let authgearClient = null;

const configureClient = async () => {
    authgearClient = window.authgear.default;

    await authgearClient.configure({
        endpoint: "<YOUR_AUTHGEAR_PROJECT_DOMAIN>",
        clientID: "<YOUR_AUTHGEAR_APP_CLIENT_ID>",
        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 <script src="js/app.js"></script> just above the line with the Authgear CDN <script> tag as shown below:

<body>
  <h2>SPA Authentication Sample</h2>
  <p>Welcome to our page!</p>
  <button id="btn-login" disabled="true" onclick="login()">Log in</button>
  <button id="btn-logout" disabled="true" onclick="logout()">Log out</button>
  <script src="js/app.js"></script>
  <script src="https://unpkg.com/@authgear/web@2.2.0/dist/authgear-web.iife.js"></script>
</body>

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:

const login = async () => {
    await authgearClient
        .startAuthentication({
            redirectURI: "http://localhost:3000/",
            prompt: "login",
        })
        .then(
            () => {
                console.log("Logged in!");
            },
            (err) => {
                console.log("Log in failed", err);
            }
        );
};

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.

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:

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:

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:

let authgearClient = null;

const configureClient = async () => {
    authgearClient = window.authgear.default;

    await authgearClient.configure({
        endpoint: "<YOUR_AUTHGEAR_PROJECT_DOMAIN>",
        clientID: "<YOUR_AUTHGEAR_CLIENT_APP_ID>",
        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:

<button id="btn-settings" disabled="true" onclick="openUserSettings()">User Settings</button>

Next, add the following code to app.js: just below the logout() function:

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:

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

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

authgearClient.fetchUserInfo();

See more user info examples.

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.


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.

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.

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.

JavaScript SDK Reference

For detailed documentation on the JavaScript Web SDK, visit @authgear/web Reference

Backend/API Integration
create spa application authgear portal
Edit an application
spa demo web app page