This guide uses the Authgear Web SDK for integrating Authgear with a 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

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.

Install the Authgear Web SDK

NPM

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

Yarn

yarn add @authgear/web --exact

Initialize the Authgear SDK

The SDK must be properly configured before use. Call the configure method every time your page loads up.

import authgear from "@authgear/web";

authgear
  .configure({
    // custom domain endpoint or default endpoint
    // default domain should be something like: https://<yourapp>.authgear.cloud
    endpoint: "<your_app_endpoint>",
    // Client ID of your application
    clientID: "<your_client_id>",
    // sessionType can be "refresh_token" or "cookie", default "refresh_token"
    sessionType: "refresh_token",
  })
  .then(
    () => {
      // configure successfully.
    },
    (err) => {
      // failed to configure.
    }
  );
  

• Token-based authentication

  • sessionType should be set to refresh_token

• Cookie-based authentication

  • endpoint must be a custom domain endpoint

  • sessionType should be set to cookie

Login to the application

Step 1: Start the auth flow

When the user clicks login/signup on your website, make a start authorization call to redirect them to the login/signup page.

import authgear from "@authgear/web";

authgear
  .startAuthentication({
    // configure redirectURI which users will be redirected to
    // after they have authenticated with Authgear
    // you can use any path in your website
    // make sure it is in the "Redirect URIs" list of the Application
    redirectURI: "https://yourdomain.com/auth-redirect",
    prompt: "login",
  })
  .then(
    () => {
      // started authorization, user should be redirected to Authgear
    },
    (err) => {
      // failed to start authorization
    }
  );
  

By default, Authgear will not ask user to login again if user has already logged in. You can optionally set prompt to login if you want the user always reach the login page and login again.

Step 2: 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 succeed, the application should navigate the user to other URL such as the user's home page and remove the code query parameters.

import authgear from "@authgear/web";

authgear.finishAuthentication().then(
  (userInfo) => {
    // authorized successfully
    // you should navigate the user to another path
  },
  (err) => {
    // failed to finish authorization
  },
);

Now, your user is logged in!

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 authgear.configure, it only reflect SDK local state.
// value can be NO_SESSION or AUTHENTICATED
let sessionState = authgear.sessionState;

if (sessionState === "AUTHENTICATED") {
    authgear
        .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 authgear.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

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.

import authgear from "@authgear/web";

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

Token-based authentication

To include the access token to the HTTP requests to your application server, there are two ways to achieve this.

Option 1: Using fetch function provided by Authgear SDK

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.

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

Next steps

JavaScript SDK Reference

Single Page Application

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

Native/Mobile Apps

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

Regular Web App

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

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

Get the Extension

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

Usage

Configure OkHttpClient to use AuthgearInterceptor as follows:

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

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

Authgear is an authentication & user management solution which makes it very easy for developers to integrate and customize their consumer applications, it includes these features out of the box:

• Easy-to-use interfaces for user registration and login, including email, phone, username as login ID, and password, OTP, magic links, etc for authentication.

• Support biometric login on mobile, Passkeys, and Multi-Factor Authentication (MFA) such as SMS/email-based verification and authenticator apps with TOTP.

• A user management portal, like password resets, account locking, scheduled deletion or anonymization, and user profile management.

• Single Sign-On (SSO) provides a single unified experience for your customers to log into multiple web/mobile apps, including Web2Web, Web2App, and App2App SSO.

• Session management with Authgear Portals, and a pre-built setting page for users to control concurrent sessions.

• Customizable UI with a user-friendly low-code dashboard.

• Various security features such as audit logs, brute force protection, smart account lockout, password policy, etc.

Learn about Authgear

Authgear contains the following high-level components:

Authenticate on the Web/Mobile App

• Auth UI - is the default batteries included UI for login, signup and setting page. You can customize the style via the Portal, including the CSS and HTML of each page.

Backend Authentication and Integrations

Management Portal

Security

Login Methods

Customize User Interface (UI)

User Management

Features for managing your users via Authgear Portal.

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

Video Guide

1. Create Authgear account

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

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

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

4. User Settings Page

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

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

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

• Password: users can change their password from here.

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

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

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.

6. View and Manage Your Users

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

• Authgear Portal

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

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

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

7. Continue Exploring Authgear

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

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

Authgear helps you add user logins to your Angular apps. It provides prebuilt login page and user settings page that accelerate the development.

Table of Content

Setup Application in Authgear

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.

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 in the next section.

Install the Angular CLI

To install the Angular CLI, open a terminal window and run the following command:

npm install -g @angular/cli

Create initial workspace

Run the following cli command to create a new workspace and initial app called my-app with a routing module generated.

# Create a workspace called my-app
ng new my-app --routing --defaults
# Move into the project directory
cd my-app

Edit script for launching the app

In the package.json file, edit the start script in the script section

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

<div>Hello world</div>

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

npm install --save-exact @authgear/web

In src/app/app.component.ts , import authgear and call the configure function to initialize an Authgear instance on application loads.

// src/app/app.component.ts
import { Component, OnInit } from '@angular/core';
import authgear from '@authgear/web';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent implements OnInit {
  // configure Authgear container instance
  initAuthgear(): Promise<void> {
    return authgear.configure({
      endpoint: '<your_app_endpoint>',
      clientID: '<your_client_id>',
      sessionType: 'refresh_token',
    });
  }

  ngOnInit(): void {
    this.initAuthgear().catch((e) => {
      // Error handling
      console.log(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.

It is recommend to render the app after configure() resolves. So by the time the app is rendered, Authgear is ready to use.

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 a isLoggedIn boolean variable. The isLoggedIn boolean variable can be auto updated using the onSessionStateChange callback. This callback can be stored in delegate which is in the local SDK container.

// src/app/services/user.service.ts
import { Injectable } from '@angular/core';
import authgear from '@authgear/web';

@Injectable({
  providedIn: 'root',
})
export class UserService {
  // By default the user is not logged in
  isLoggedIn: boolean = 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;
        if (sessionState === 'AUTHENTICATED') {
          this.isLoggedIn = true;
        } else {
          this.isLoggedIn = false;
        }
      },
    };
  }
}

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:

ng generate component auth-redirect

We will inject the router and the UserService to get the use of navigation and the isLoggedIn state.

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

// src/app/auth-redirect/auth-redirect.component.ts
import { Component, OnInit } from '@angular/core';
import { UserService } from '../services/user.service';
import authgear from '@authgear/web';
import { Router } from '@angular/router';

@Component({
  selector: 'app-auth-redirect',
  templateUrl: './auth-redirect.component.html',
  styleUrls: ['./auth-redirect.component.css'],
})
export class AuthRedirectComponent implements OnInit {
  constructor(private router: Router, private user: UserService) {}

  ngOnInit(): void {
    authgear
      .finishAuthentication()
      .catch((e) => console.error(e))
      .then(() => {
        this.router.navigate(['']);
      });
  }
}

Step 5: Add Routes and Context Provider to the App

Next, we will add a "Home" page . Create a home component using the following command:

ng generate component home

Then import HomeComponent and AuthRedirectComponent as routes. We can add those routes in the app-routing.module.ts file:

// src/app/app-routing.module.ts
import { NgModule } from '@angular/core';
import { RouterModule, Routes } from '@angular/router';
import { AuthRedirectComponent } from './auth-redirect/auth-redirect.component';
import { HomeComponent } from './home/home.component';

const routes: Routes = [
  { path: '', component: HomeComponent },
  { path: 'auth-redirect', component: AuthRedirectComponent },
];

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule],
})
export class AppRoutingModule {}

You can apply those routes in src/app/app.component.html by replace the lines with the following:

<router-outlet></router-outlet>

The file structure should now look like

src
├── (...)
└── app
    ├── app-routing.module.ts
    ├── app.component.ts
    ├── app.component.html
    ├── app.module.ts
    ├── (...)
    ├── 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(ConfigureOptions). This will redirect the user to the login page.

// src/app/home/home.component.ts
import { Component, OnInit } from '@angular/core';
import { UserService } from '../services/user.service';
import authgear from '@authgear/web';

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.css'],
})
export class HomeComponent implements OnInit {
  constructor(public user: UserService) {}

  ngOnInit(): void {}

  startLogin(): void {
    authgear
      .startAuthentication({
        redirectURI: 'http://localhost:4000/auth-redirect',
        prompt: 'login',
      })
      .then(
        () => {
          // started authorization, user should be redirected to Authgear
        },
        (err) => {
          // failed to start authorization
          console.error(err);
        }
      );
  }
}

Then you can add a button which will trigger the startLogin method in home.component.html:

<h1>Home Page</h1>
<button type="button" (click)="startLogin()">Login</button>

You can now run npm start and you will be redirected to the Authgear Login page when you click the Login button.

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 fetchInfo() and access its sub property.

// src/app/home/home.component.ts
import { Component, OnInit } from '@angular/core';
import { UserService } from '../services/user.service';
import authgear from '@authgear/web';

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.css'],
})
export class HomeComponent implements OnInit {
  isLoading: boolean = false;
  greetingMessage: string = '';

  constructor(public user: UserService) {}

  async updateGreetingMessage() {
    this.isLoading = true;
    try {
      if (this.user.isLoggedIn) {
        const userInfo = await authgear.fetchUserInfo();
        this.greetingMessage = 'The current User sub: ' + userInfo.sub;
      }
    } finally {
      this.isLoading = false;
    }
  }

  ngOnInit(): void {
    this.updateGreetingMessage().catch((e) => {
      console.error(e);
    });
  }

  startLogin(): void {
    authgear
      .startAuthentication({
        redirectURI: 'http://localhost:4000/auth-redirect',
        prompt: 'login',
      })
      .then(
        () => {
          // started authorization, user should be redirected to Authgear
        },
        (err) => {
          // failed to start authorization
          console.error(err);
        }
      );
  }
}

In the home.component.html:

<h1>Home Page</h1>
<span *ngIf="isLoading">Loading</span>
<span *ngIf="greetingMessage">{{ greetingMessage }}</span>
<div *ngIf="!user.isLoggedIn">
  <button type="button" (click)="startLogin()">Login</button>
</div>

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:

<div *ngIf="user.isLoggedIn">
  <button type="button" (click)="logout()">Logout</button>
</div>

And add the logout method:

logout(): void {
  authgear
    .logout({
      redirectURI: 'http://localhost:4000/',
    })
    .then(
      () => {
        this.greetingMessage = '';
      },
      (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 <your_app_endpoint>/settings

In home.component.html append a conditional link to the logout button section.

<div *ngIf="user.isLoggedIn">
  <button type="button" (click)="logout()">Logout</button>
  <br />
  <a target="_blank" rel="noreferrer" (click)="userSetting($event)" href="#">
    User Setting
  </a>
</div>

And add the userSetting method:

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

async userSetting(event: MouseEvent) {
  event.preventDefault();
  event.stopPropagation();
  await authgear.open(Page.Settings);
}

This the resulting home.component.ts:

// src/app/home/home.component.ts
import { Component, OnInit } from '@angular/core';
import { UserService } from '../services/user.service';
import authgear, { Page } from '@authgear/web';

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.css'],
})
export class HomeComponent implements OnInit {
  isLoading: boolean = false;
  greetingMessage: string = '';

  constructor(public user: UserService) {}

  async updateGreetingMessage() {
    this.isLoading = true;
    try {
      if (this.user.isLoggedIn) {
        const userInfo = await authgear.fetchUserInfo();
        this.greetingMessage = 'The current User sub: ' + userInfo.sub;
      }
    } finally {
      this.isLoading = false;
    }
  }

  ngOnInit(): void {
    this.updateGreetingMessage().catch((e) => {
      console.error(e);
    });
  }

  startLogin(): void {
    authgear
      .startAuthentication({
        redirectURI: 'http://localhost:4000/auth-redirect',
        prompt: '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 = '';
        },
        (err) => {
          console.error(err);
        }
      );
  }

  async userSetting(event: MouseEvent) {
    event.preventDefault();
    event.stopPropagation();
    await authgear.open(Page.Settings);
  }
}

This is the resulting home.component.html:

<h1>Home Page</h1>
<span *ngIf="isLoading">Loading</span>
<span *ngIf="greetingMessage">{{ greetingMessage }}</span>
<div *ngIf="!user.isLoggedIn">
  <button type="button" (click)="startLogin()">Login</button>
</div>
<div *ngIf="user.isLoggedIn">
  <button type="button" (click)="logout()">Logout</button>
  <br />
  <a target="_blank" rel="noreferrer" (click)="userSetting($event)" href="#">
    User Setting
  </a>
</div>

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

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

Authgear helps you add user logins to your Vue apps. It provides prebuilt login page and user settings page that accelerate the development.

Table of Content

Setup Application in Authgear

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.

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 in the next section.

Install basic project dependencies

Create the project folder and install the dependencies. We will use vite as the build tool and the vue-router package. Also, we will use TypeScript in this tutorial.

# Create a brand new project using vite
npm create vite@latest my-app -- --template vue-ts
# Move into the project directory
cd my-app
# Install dependencies
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:

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

// src/components/Home.vue
<script setup lang="ts"></script>

<template><div>Hello World</div></template>

Edit the App.vue file

The App.vue file is generated by Vite already but some sections might not being needed for this tutorial.

// src/components/App.vue
<script setup lang="ts">
import Home from "./components/Home.vue";
</script>

<template>
  <Home />
</template>

Delete unnecessary files

Some of the files might not being used and thus can be deleted. You can perform the following script to delete these files:

rm -rf src/assets src/components/HelloWorld.vue

File structure

The file structure in your project is now:

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 default page with the title Vite + Vue and a count button 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:

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

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.

// 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: "<your_app_endpoint>",
      clientID: "<your_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.

It is recommend to render the app after configure() resolves. So by the time the app is rendered, Authgear is ready to use.

Step 4: Implement the Context Provider

Since we want to reference the logged in state in anywhere of the app, let's put the state in a context provider with UserProvider.vue in the /src/contexts folder.

In UserProvider.vue, it 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.

// src/context/UserProvider.vue
<script lang="ts">
import {
  defineComponent,
  InjectionKey,
  provide,
  readonly,
  ref,
  Ref,
  toRefs,
} from "vue";
import authgear from "@authgear/web";

export interface UserContextValue {
  isLoggedIn: Ref<boolean>;
}

export const UserStateSymbol: InjectionKey<UserContextValue> =
  Symbol("UserState");

export default defineComponent({
  setup() {
    const isLoggedIn = ref(false);

    const state: UserContextValue = {
      isLoggedIn,
    };

    authgear.delegate = {
      onSessionStateChange: (container) => {
        const sessionState = container.sessionState;
        if (sessionState === "AUTHENTICATED") {
          isLoggedIn.value = true;
        } else {
          isLoggedIn.value = false;
        }
      },
    };

    provide<UserContextValue>(UserStateSymbol, toRefs(readonly(state)));

    return { state };
  },
});
</script>

<template>
  <slot />
</template>

Step 5: Implement the Auth Redirect

Next, we will add an "AuthRedirect" page for handling the authentication result after the user have 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 automatic set to true. Finally, navigate back to root (/) which is our Home page.

The final AuthRedirect.vue will look like this

// src/components/AuthRedirect.vue
<script setup lang="ts">
import { onMounted } from "vue";
import authgear from "@authgear/web";
import { router } from "../router";

onMounted(() => {
  async function updateToken() {
    try {
      await authgear.finishAuthentication();
    } finally {
      router.replace({ path: "/" });
    }
  }
  updateToken().catch((e) => console.error(e));
});
</script>

<template></template>

Step 6: Apply Routes and Context Provider to the App

As we have already configure the routes in the previous section, we can simply add <router-view /> 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:

// src/App.vue
<script setup lang="ts">
import UserProvider from "./contexts/UserProvider.vue";
</script>

<template>
  <UserProvider>
    <router-view />
  </UserProvider>
</template>

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.

// src/components/Home.vue
<script setup lang="ts">
import authgear from "@authgear/web";

const startLogin = () => {
  authgear
    .startAuthentication({
      redirectURI: "http://localhost:4000/auth-redirect",
      prompt: "login",
    })
    .then(
      () => {
        // started authorization, user should be redirected to Authgear
      },
      (err) => {
        // failed to start authorization
        console.error(err);
      }
    );
};
</script>

<template>
  <h1>Home Page</h1>
  <button @click="startLogin">Login</button>
</template>

You can now run npm run dev and you will be redirected to the Authgear Login page when you click the Login button.

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 fetchInfo() and access its sub property.

The Login button can be also rendered conditionally which only visible if the user is not logged in.

// src/components/Home.vue  
<script setup lang="ts">
import authgear from "@authgear/web";
import { inject, onMounted, ref } from "vue";
import { UserStateSymbol } from "../contexts/UserProvider.vue";

const { isLoggedIn } = inject(UserStateSymbol)!;
const isLoading = ref(false);
const greetingMessage = ref("");

onMounted(() => {
  async function updateGreetingMessage() {
    isLoading.value = true;
    try {
      if (isLoggedIn.value) {
        const userInfo = await authgear.fetchUserInfo();
        greetingMessage.value = "The current User sub: " + userInfo.sub;
      }
    } finally {
      isLoading.value = false;
    }
  }

  updateGreetingMessage().catch((e) => {
    console.error(e);
  });
});

const startLogin = () => {
  authgear
    .startAuthentication({
      redirectURI: "http://localhost:4000/auth-redirect",
      prompt: "login",
    })
    .then(
      () => {
        // started authorization, user should be redirected to Authgear
      },
      (err) => {
        // failed to start authorization
        console.error(err);
      }
    );
};
</script>

<template>
  <h1>Home Page</h1>
  <span v-if="isLoading">Loading...</span>
  <span v-if="greetingMessage">{{ greetingMessage }}</span>
  <div v-if="!isLoggedIn">
    <button @click="startLogin">Login</button>
  </div>
</template>

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 an Logout button when user is logged in.

In Home.vue, we will add a conditional elements in the template:

<div v-if="isLoggedIn">
  <button @click="logout">Logout</button>
</div>

And add the logout callback:

const logout = () => {
  authgear
    .logout({
      redirectURI: "http://localhost:4000/",
    })
    .then(
      () => {
        greetingMessage.value = "";
      },
      (err) => {
        console.error(err);
      }
    );
};

Run the app again, we can now logout by clicking the logout button.

Step 10: 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 <your_app_endpoint>/settings

In Home.vue append a conditional link to the logout button section.

<div v-if="isLoggedIn">
  <button @click="logout()">Logout</button>
  <br />
  <a
    target="_blank"
    rel="noreferrer"
    @click.stop.prevent="userSetting"
    href="#"
  >
    User Setting
  </a>
</div>

And add the userSetting callback:

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

const userSetting = async () => {
  await authgear.open(Page.Settings);
};

This the the resulting Home.vue:

// src/components/Home.vue
<script setup lang="ts">
import authgear, { Page } from "@authgear/web";
import { inject, onMounted, ref } from "vue";
import { UserStateSymbol } from "../contexts/UserProvider.vue";

const { isLoggedIn } = inject(UserStateSymbol)!;
const isLoading = ref(false);
const greetingMessage = ref("");

onMounted(() => {
  async function updateGreetingMessage() {
    isLoading.value = true;
    try {
      if (isLoggedIn.value) {
        const userInfo = await authgear.fetchUserInfo();
        greetingMessage.value = "The current User sub: " + userInfo.sub;
      }
    } finally {
      isLoading.value = false;
    }
  }

  updateGreetingMessage().catch((e) => {
    console.error(e);
  });
});

const startLogin = () => {
  authgear
    .startAuthentication({
      redirectURI: "http://localhost:4000/auth-redirect",
      prompt: "login",
    })
    .then(
      () => {
        // started authorization, user should be redirected to Authgear
      },
      (err) => {
        // failed to start authorization
        console.error(err);
      }
    );
};

const logout = () => {
  authgear
    .logout({
      redirectURI: "http://localhost:4000/",
    })
    .then(
      () => {
        greetingMessage.value = "";
      },
      (err) => {
        console.error(err);
      }
    );
};

const userSetting = async () => {
  await authgear.open(Page.Settings);
};
</script>

<template>
  <h1>Home Page</h1>
  <span v-if="isLoading">Loading...</span>
  <span v-if="greetingMessage">{{ greetingMessage }}</span>
  <div v-if="!isLoggedIn">
    <button @click="startLogin">Login</button>
  </div>
  <div v-if="isLoggedIn">
    <button @click="logout">Logout</button>
    <br />
    <a
      target="_blank"
      rel="noreferrer"
      @click.stop.prevent="userSetting"
      href="#"
    >
      User Setting
    </a>
  </div>
</template>

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

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

This guide provides instructions on integrating Authgear with a React Native app. Supported platforms include:

• React Native 0.60.0 or higher

Video Guide for React Native

Setup Application in 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.

oauth:
  clients:
    - name: your_app_name
      client_id: a_random_generated_string
      redirect_uris:
        - "com.myapp://host/path"
      grant_types:
        - authorization_code
        - refresh_token
      response_types:
        - code
        - none

Create a React Native app

Follow the documentation of React Native to see how you can create a new React Native app.

npx react-native init myapp
cd myapp

Install the SDK

yarn add --exact @authgear/react-native
(cd ios && pod install)

Platform Integration

To finish the integration, setup the app to handle the redirectURI specified in the application. This part requires platform specific integration.

Android

Add the following activity entry to the AndroidManifest.xml of your app. The intent system would dispatch the redirect URI to OAuthRedirectActivity and the sdk would handle the rest.

<!-- Your application configuration. Omitted here for brevity -->
<application>
  <!-- Other activities or entries -->

  <!-- Add the following activity -->
  <!-- android:exported="true" is required -->
  <!-- See https://developer.android.com/about/versions/12/behavior-changes-12#exported -->
  <activity android:name="com.authgear.reactnative.OAuthRedirectActivity"
            android:exported="true"
            android:launchMode="singleTask">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <!-- Configure data to be the exact redirect URI your app uses. -->
                <!-- Here, we are using com.authgear.example://host/path as configured in authgear.yaml. -->
                <!-- NOTE: The redirectURI supplied in AuthenticateOptions *has* to match as well -->
                <data android:scheme="com.myapp.example"
                    android:host="host"
                    android:pathPrefix="/path"/>
            </intent-filter>
  </activity>
</application>

Targeting API level 30 or above (Android 11 or above)

If your Android app is targeting API level 30 or above (Android 11 or above), you need to add a queries section to AndroidManifest.xml.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <!-- Other elements such <application> -->
  <queries>
    <intent>
      <action android:name="android.support.customtabs.action.CustomTabsService" />
    </intent>
  </queries>
</manifest>

iOS

Declare URL Handling in Info.plist

In Info.plist, add the matching redirect URI.

<?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>CFBundleURLSchemes</key>
                      <array>
                              <string>com.myapp.example</string>
                      </array>
              </dict>
      </array>
</dict>
</plist>

Insert the SDK Integration Code

In AppDelegate.m, add the following code snippet.

// Other imports...
#import <authgear-react-native/AGAuthgearReactNative.h>

// Other methods...

// For handling deeplink
- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:
                (NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    return [AGAuthgearReactNative application:app openURL:url options:options];
}

// For handling deeplink
// deprecated, for supporting older devices (iOS < 9.0)
- (BOOL)application:(UIApplication *)application
              openURL:(NSURL *)url
    sourceApplication:(NSString *)sourceApplication
          annotation:(id)annotation {
    return [AGAuthgearReactNative application:application
                                      openURL:url
                            sourceApplication:sourceApplication
                                  annotation:annotation];
}

// for handling universal link
- (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
      restorationHandler:
          (void (^)(NSArray<id<UIUserActivityRestoring>> *_Nullable))
              restorationHandler {
    return [AGAuthgearReactNative application:application
                        continueUserActivity:userActivity
                          restorationHandler:restorationHandler];
}

Try authenticate

Add this code to your react native app. This snippet configures authgear to connect to an authgear server deployed at endpoint with the client you have just setup via clientID, opens a browser for authentication, and then upon success redirects to the app via the redirectURI specified.

import React, { useCallback } from "react";
import { View, Button } from "react-native";
import authgear 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://<myapp>.authgear.cloud",
      })
      .then(() => {
        authgear
          .authenticate({
            redirectURI: "com.myapp.example://host/path",
          })
          .then(({ userInfo }) => {
            console.log(userInfo);
          });
      });
  }, []);

  return (
    <View>
      <Button onPress={onPress} title="Authenticate" />
    </View>
  );
}

Now, your user is logged in!

Get the Logged In State

When you start launching the application. You may want to know if the user has logged in. (e.g. Show users the login page 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.

// After authgear.configure, it only reflect SDK local state.
// value can be NO_SESSION or AUTHENTICATED
let sessionState = authgear.sessionState;

if (sessionState === "AUTHENTICATED") {
    authgear
        .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 authgear.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

Using the Access Token in HTTP Requests

To include the access token to the HTTP requests to your application server, there are two ways to achieve this.

Option 1: Using fetch function provided by Authgear SDK

authgear
    .fetch("YOUR_SERVER_URL")
    .then(response => response.json())
    .then(data => console.log(data));

Option 2: Add the access token to your HTTP

You can access 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 your application request.

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

Logout

To log out the user from the current app session, you need to invoke the logout function.

authgear
  .logout()
  .then(() => {
    // logout successfully
  });

Next steps

To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.

JavaScript SDK Reference

Authgear helps you add user logins to your React apps. It provides prebuilt login page and user settings page that accelerate the development.

Table of Content

Setup Application in Authgear

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.

Step 1: Create a simple React project

Install basic project dependencies

Create the project folder and install the dependencies. We will use parcel as the build tool and the react-router-dom, react , and react-dom packages. Also, we will use TypeScript in this tutorial.

Add script for launching the app

In the package.json file, add these two lines to the script section

The start script run the app in development mode on port 4000. The build script build the app for production to the dist/ folder.

Create the index.html file

In src/, create a new file called index.html for parcel to bundle the app:

src/index.html:

Create the App.tsx file

Create a new file called App.tsx with simply showing Hello World in the screen:

Create the index.tsx file

Create a new file called index.tsx as the entry point of the application.

The file structure in your project is now:

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 React project directory to install the Authgear Web SDK

In src/index.tsx , import authgear and call the configure function to initialize an Authgear instance on application loads.

It is recommend to render the app after configure() resolves. So by the time the app is rendered, Authgear is ready to use.

Step 3: Implement the Context Provider

Since we want to reference the logged in state in anywhere of the app, let's put the state in a context provider with UserProvider.tsx in the /src/context folder.

In UserProvider.tsx, it will have a isLoggedIn boolean and a setIsLoggedIn function. The is LoggedIn boolean state can be auto updated using the onSessionStateChange callback. This callback can be stored in delegate which is in the local SDK container.

Step 4: Implement the Auth Redirect

Next, we will add an "AuthRedirect" page for handling the authentication result after the user have been authenticated by Authgear.

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 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 automatic set to true. Finally, navigate back to root (/) which is our Home page.

The final AuthRedirect.tsx will look like this

Step 5: Add Routes and Context Provider to the App

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

The file structure should now look like

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 startLogin callback on click. This will redirect the user to the login page.

You can now run npm start and you will be redirected to the Authgear Login page when you click the Login button.

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.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 fetchInfo() and access its sub property.

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.tsx, we will add a conditional elements in the elements:

And add the logout callback:

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 openURL function to open the setting page at <your_app_endpoint>/settings

In Home.tsx Add a conditional link to the elements.

And add the userSetting callback:

This the the resulting Home.tsx:

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

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.

The Authgear Android SDK comes with kotlin support out of the box. In fact, the SDK is written in kotlin!

If you are using kotlin, you can benefit from the suspend function APIs authgear provides. For example, the above authorize example can be written as follows:

This guide provides instructions on integrating Authgear with an iOS app. Supported platforms include:

• iOS 11.0 or higher

Setup Application in 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.

Install the SDK

CocoaPods

Swift Package Manager

Register URL Scheme for Redirect URI

In your application's Info.plist , register your custom URL scheme, (e.g. com.myapp).

Configuration Authgear SDK

SDK must be properly configured before use.

Trigger authenticate

When the user clicks login/signup on your app, you can use the following code to start authorization.

Your user is now logged in!

Get the Logged In State

When you start launching the application. You may want to know if the user has logged in. (e.g. Show users the login page 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.

The value of sessionState can be .unknown, .noSession or .authenticated. Initially, the sessionState is .unknown. After a call to authgear.configure, the session state would become .authenticated if a previous session was found, or .noSession if such session was not found.

Fetching User Info

Using the Access Token in HTTP Requests

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.

Logout

To log out the user from the current app session, you need to invoke thelogoutfunction.

Next steps

To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.

iOS SDK Reference

Footnote

Learning objectives

You will learn the following throughout the article:

• How to add user login, sign-up, and logout to Next.js Applications.

• How to create a middleware to protect Next.js application pages.

Implementing authentication in a Next.js web app

Prerequisites

Before you begin, you'll need the following:

Part 1: Configure Authgear

Step 1: Configure an application