Announcing the OAuth Plugin for Capacitor

Authentication is a critical part of most applications, and getting it right can be challenging. With Ionic's recent decision to discontinue new customer sales of its commercial products, including Auth Connect, many teams building Capacitor apps are now looking for a reliable alternative. That's why we built the OAuth plugin — a production-ready solution for integrating OAuth 2.0 and OpenID Connect authentication into your Capacitor applications across Android, iOS, and web. The plugin is now available for all Capawesome Insiders.

Let's explore the API and key features that make this plugin a great fit for your next project.

Installation

To install the Capacitor OAuth plugin, please refer to the Installation section in the plugin documentation.

Usage

The OAuth plugin works with any OAuth 2.0 or OpenID Connect provider, including Auth0, Azure AD, Amazon Cognito, Okta, and OneLogin. It implements the Authorization Code flow with PKCE out of the box, following current security best practices. Let's walk through the most common use cases.

Logging in

Start the OAuth flow with the login(...) method. You can either provide an issuerUrl for automatic OpenID Connect discovery, or pass the authorizationEndpoint and tokenEndpoint directly:

import { Oauth } from "@capawesome-team/capacitor-oauth";

const login = async () => {
  const result = await Oauth.login({
    issuerUrl: "https://accounts.google.com",
    clientId: "YOUR_CLIENT_ID",
    redirectUrl: "com.example.app://oauth/callback",
    scopes: ["openid", "profile", "email", "offline_access"],
  });

  console.log("Access token:", result.accessToken);
  console.log("ID token:", result.idToken);
  console.log("Refresh token:", result.refreshToken);
};

The plugin handles the entire authorization code exchange with PKCE behind the scenes. On Android and iOS, it uses the system browser for a secure authentication experience. On the web, the user is redirected to the provider's authorization page.

Handling the redirect callback

On the web platform, you need to handle the redirect callback after the user is redirected back from the provider. Call handleRedirectCallback() on page load to complete the token exchange:

import { Oauth } from "@capawesome-team/capacitor-oauth";
import { Capacitor } from "@capacitor/core";

const handleRedirectCallback = async () => {
  if (Capacitor.getPlatform() !== "web") {
    return;
  }
  const result = await Oauth.handleRedirectCallback();
  console.log("Access token:", result.accessToken);
};

This step is only required on the web. On Android and iOS, the redirect is handled natively.

Storing tokens securely

The OAuth plugin is designed to work seamlessly with the Secure Preferences plugin, so you can store tokens in encrypted storage right after login:

import { Oauth } from "@capawesome-team/capacitor-oauth";
import { SecurePreferences } from "@capawesome-team/capacitor-secure-preferences";

const login = async () => {
  const result = await Oauth.login({
    issuerUrl: "https://accounts.google.com",
    clientId: "YOUR_CLIENT_ID",
    redirectUrl: "com.example.app://oauth/callback",
    scopes: ["openid", "profile", "email", "offline_access"],
  });

  await SecurePreferences.set({
    key: "tokens",
    value: JSON.stringify(result),
  });
};

Refreshing the access token

Access tokens expire. Use the refreshToken(...) method to get a new one without requiring the user to log in again:

import { Oauth } from "@capawesome-team/capacitor-oauth";

const refreshToken = async () => {
  const result = await Oauth.refreshToken({
    issuerUrl: "https://accounts.google.com",
    clientId: "YOUR_CLIENT_ID",
    refreshToken: "YOUR_REFRESH_TOKEN",
  });

  console.log("New access token:", result.accessToken);
};

Decoding the ID token

If you need to access the user's profile information from the ID token, use the decodeIdToken(...) method:

import { Oauth } from "@capawesome-team/capacitor-oauth";

const decodeIdToken = async () => {
  const result = await Oauth.decodeIdToken({
    token: "YOUR_ID_TOKEN",
  });

  console.log("Subject:", result.payload.sub);
  console.log("Email:", result.payload.email);
  console.log("Name:", result.payload.name);
};

This decodes the JWT token locally without sending it to a server. Note that this does not verify the token signature — for server-side validation, you should verify the token on your backend.

Logging out

End the user's session with the logout(...) method, which calls the provider's end-session endpoint:

import { Oauth } from "@capawesome-team/capacitor-oauth";

const logout = async () => {
  await Oauth.logout({
    issuerUrl: "https://accounts.google.com",
    idToken: "YOUR_ID_TOKEN",
    postLogoutRedirectUrl: "com.example.app://oauth/logout",
  });
};

Checking token state

The plugin also provides utility methods to check the state of your tokens without additional logic on your side:

import { Oauth } from "@capawesome-team/capacitor-oauth";

const checkTokenState = async (
  accessToken: string,
  accessTokenExpirationDate: number,
  refreshToken: string
) => {
  const { isAvailable } = await Oauth.isAccessTokenAvailable({
    accessToken,
  });
  const { isExpired } = await Oauth.isAccessTokenExpired({
    accessTokenExpirationDate,
  });
  const { isAvailable: isRefreshAvailable } =
    await Oauth.isRefreshTokenAvailable({
      refreshToken,
    });

  console.log("Access token available:", isAvailable);
  console.log("Access token expired:", isExpired);
  console.log("Refresh token available:", isRefreshAvailable);
};

FAQ

How does this compare to Ionic Auth Connect?

The Capawesome OAuth plugin covers the core authentication functionality that most teams need: OAuth 2.0 and OpenID Connect flows with PKCE, token refresh, and multi-provider support across all platforms. With Ionic discontinuing sales of its commercial products, including Auth Connect, the Capawesome OAuth plugin provides a maintained and actively supported alternative for Capacitor applications.

Which providers are supported?

The plugin works with any OAuth 2.0 or OpenID Connect compliant provider. This includes Auth0, Azure AD (Microsoft Entra ID), Amazon Cognito, Okta, OneLogin, Google, and any other provider that follows the standard.

Is this plugin a fork of another plugin?

No. The Capawesome OAuth plugin was built from the ground up with a focus on security, reliability, and ease of use. We implemented the PKCE flow natively on Android and iOS, and designed the API to be consistent across all platforms. The web implementation uses the standard redirect flow for maximum compatibility.

Can I store tokens securely?

Yes. The plugin is designed to work with the Secure Preferences plugin, which provides encrypted key-value storage on Android and iOS. This lets you persist tokens between app sessions without exposing them in plain text.

Conclusion

The OAuth plugin gives you a straightforward way to add OAuth 2.0 and OpenID Connect authentication to your Capacitor apps. It handles the complexity of PKCE flows, provider discovery, and token management so you can focus on building your application.

Explore the complete API Reference to see all available methods and options. Have suggestions for new features? Create a feature request in our GitHub repository.

Stay connected with us on X and subscribe to our newsletter for the latest updates and announcements.