@capawesome-team/capacitor-oauth¶

Capacitor plugin for communicating with OAuth 2.0 and OpenID Connect providers.

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Features¶

We are proud to offer one of the most complete and feature-rich Capacitor plugins for OAuth. Here are some of the key features:

🖥️ Cross-platform: Supports Android, iOS and Web.
🌐 Providers: Works with any OAuth 2.0 / OpenID Connect provider, including Auth0, Azure AD, Amazon Cognito, Okta and OneLogin.
🔐 PKCE: Implements the Authorization Code flow with Proof Key for Code Exchange (PKCE).
🔍 Auto-discovery: Automatically fetches endpoints via OpenID Connect discovery.
🔄 Token Refresh: Refresh access tokens using a refresh token.
🪪 JWT Decoding: Decode JWT ID tokens without verification.
🤝 Compatibility: Compatible with the Secure Preferences plugin to securely store tokens.
📦 SPM: Supports Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.
⭐️ Support: Priority support from the Capawesome Team.
✨ Handcrafted: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just open an issue and we'll take a look!

Compatibility¶

Plugin Version	Capacitor Version	Status
0.1.x	>=8.x.x	Active support

Demo¶

Android	iOS	Web

Installation¶

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, install the package:

npm install @capawesome-team/capacitor-oauth
npx cap sync

Android¶

Variables¶

This plugin will use the following project variables (defined in your app's variables.gradle file):

$appAuthVersion version of net.openid:appauth (default: 0.11.1)

Redirect Scheme¶

Add the following to your app's build.gradle file to configure the redirect scheme used by AppAuth:

android {
    defaultConfig {
        manifestPlaceholders = [appAuthRedirectScheme: "com.example.app"]
    }
}

Replace com.example.app with the scheme of your redirect URI.

Proguard¶

If you are using Proguard, you need to add the following rules to your proguard-rules.pro file:

-keep class io.capawesome.capacitorjs.plugins.** { *; }

Usage¶

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

const login = async () => {
  // Sign in the user
  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);
  // Store the tokens securely
  await SecurePreferences.set({
    key: 'tokens',
    value: JSON.stringify(result),
  });
};

const handleRedirectCallback = async () => {
  if (Capacitor.getPlatform() !== 'web') {
    return;
  }
  // Handle the redirect callback on web
  const result = await Oauth.handleRedirectCallback();
  console.log('Access token:', result.accessToken);
};

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

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

const decodeIdToken = async () => {
  const result = await Oauth.decodeIdToken({
    token: 'YOUR_ID_TOKEN',
  });
  console.log('Payload:', result.payload);
};

decodeIdToken(...)¶

decodeIdToken(options: DecodeIdTokenOptions) => Promise<DecodeIdTokenResult>

Decode a JWT ID token without verification.

Param	Type
`options`	`DecodeIdTokenOptions`

Returns: Promise<DecodeIdTokenResult>

Since: 0.1.0

getAccessTokenExpirationDate(...)¶

getAccessTokenExpirationDate(options: GetAccessTokenExpirationDateOptions) => Promise<GetAccessTokenExpirationDateResult>

Get the access token expiration date as an ISO 8601 string.

Param	Type
`options`	`GetAccessTokenExpirationDateOptions`

Returns: Promise<GetAccessTokenExpirationDateResult>

Since: 0.1.0

isAccessTokenAvailable(...)¶

isAccessTokenAvailable(options: IsAccessTokenAvailableOptions) => Promise<IsAccessTokenAvailableResult>

Check if an access token is available (non-null and non-empty).

Param	Type
`options`	`IsAccessTokenAvailableOptions`

Returns: Promise<IsAccessTokenAvailableResult>

Since: 0.1.0

isAccessTokenExpired(...)¶

isAccessTokenExpired(options: IsAccessTokenExpiredOptions) => Promise<IsAccessTokenExpiredResult>

Check if the access token has expired.

Param	Type
`options`	`IsAccessTokenExpiredOptions`

Returns: Promise<IsAccessTokenExpiredResult>

Since: 0.1.0

isRefreshTokenAvailable(...)¶

isRefreshTokenAvailable(options: IsRefreshTokenAvailableOptions) => Promise<IsRefreshTokenAvailableResult>

Check if a refresh token is available (non-null and non-empty).

Param	Type
`options`	`IsRefreshTokenAvailableOptions`

Returns: Promise<IsRefreshTokenAvailableResult>

Since: 0.1.0

handleRedirectCallback()¶

handleRedirectCallback() => Promise<HandleRedirectCallbackResult>

Handle the redirect callback after a login or logout redirect on the web.

Call this method on page load when the URL contains authorization response parameters.

Only available on Web.

Returns: Promise<LoginResult>

Since: 0.1.0

login(options: LoginOptions) => Promise<LoginResult>

Start an OAuth 2.0 authorization code flow with PKCE.

Param	Type
`options`	`LoginOptions`

Returns: Promise<LoginResult>

Since: 0.1.0

logout(...)¶

logout(options: LogoutOptions) => Promise<void>

End the OAuth session by calling the end-session endpoint.

Note that some providers (e.g. Microsoft Entra ID) may not redirect back to the app after logout and instead show a "You have signed out" page. In this case, the user has to close the browser manually which results in a USER_CANCELED error even though the logout was successful.

Param	Type
`options`	`LogoutOptions`

Since: 0.1.0

refreshToken(...)¶

refreshToken(options: RefreshTokenOptions) => Promise<RefreshTokenResult>

Refresh the access token using a refresh token.

Param	Type
`options`	`RefreshTokenOptions`

Returns: Promise<LoginResult>

Since: 0.1.0

Interfaces¶

DecodeIdTokenResult¶

Prop	Type	Description	Since
`header`	`Record<string, unknown>`	The decoded JWT header.	0.1.0
`payload`	`Record<string, unknown>`	The decoded JWT payload containing the claims.	0.1.0

DecodeIdTokenOptions¶

Prop	Type	Description	Since
`token`	`string`	The JWT ID token string to decode.	0.1.0

GetAccessTokenExpirationDateResult¶

Prop	Type	Description	Since
`date`	`string`	The access token expiration date as an ISO 8601 string.	0.1.0

GetAccessTokenExpirationDateOptions¶

Prop	Type	Description	Since
`accessTokenExpirationDate`	`number`	The access token expiration date in epoch milliseconds.	0.1.0

IsAccessTokenAvailableResult¶

Prop	Type	Description	Since
`isAvailable`	`boolean`	Whether the access token is non-null and non-empty.	0.1.0

IsAccessTokenAvailableOptions¶

Prop	Type	Description	Since
`accessToken`	`string`	The access token to check.	0.1.0

IsAccessTokenExpiredResult¶

Prop	Type	Description	Since
`isExpired`	`boolean`	Whether the access token has expired.	0.1.0

IsAccessTokenExpiredOptions¶

Prop	Type	Description	Since
`accessTokenExpirationDate`	`number`	The access token expiration date in epoch milliseconds.	0.1.0

IsRefreshTokenAvailableResult¶

Prop	Type	Description	Since
`isAvailable`	`boolean`	Whether the refresh token is non-null and non-empty.	0.1.0

IsRefreshTokenAvailableOptions¶

Prop	Type	Description	Since
`refreshToken`	`string`	The refresh token to check.	0.1.0

LoginResult¶

Prop	Type	Description	Since
`accessToken`	`string`	The access token.	0.1.0
`accessTokenExpirationDate`	`number`	The access token expiration date in epoch milliseconds.	0.1.0
`idToken`	`string`	The JWT ID token (OpenID Connect).	0.1.0
`refreshToken`	`string`	The refresh token.	0.1.0
`scope`	`string`	The granted scopes as a space-delimited string.	0.1.0
`tokenType`	`string`	The token type.	0.1.0

LoginOptions¶

Prop	Type	Description	Since
`issuerUrl`	`string`	The OpenID Connect issuer URL for auto-discovery. The plugin will fetch the OpenID Connect discovery document from `{issuerUrl}/.well-known/openid-configuration` to obtain the authorization and token endpoint URLs. Either `issuerUrl` or both `authorizationEndpoint` and `tokenEndpoint` must be provided.	0.1.0
`authorizationEndpoint`	`string`	The authorization endpoint URL. Either `issuerUrl` or both `authorizationEndpoint` and `tokenEndpoint` must be provided.	0.1.0
`tokenEndpoint`	`string`	The token endpoint URL. Either `issuerUrl` or both `authorizationEndpoint` and `tokenEndpoint` must be provided.	0.1.0
`clientId`	`string`	The OAuth client ID.	0.1.0
`redirectUrl`	`string`	The redirect URI to use after authentication.	0.1.0
`scopes`	`string[]`	The OAuth scopes to request.	0.1.0
`loginHint`	`string`	A hint to the authorization server about the user's identifier to pre-fill the login form.	0.1.0
`prompt`	`string`	The prompt parameter to control the authorization server UI behavior.	0.1.0
`additionalParameters`	`Record<string, string>`	Additional parameters to include in the authorization request.	0.1.0

LogoutOptions¶

Prop	Type	Description	Since
`issuerUrl`	`string`	The OpenID Connect issuer URL used to fetch the discovery document at `{issuerUrl}/.well-known/openid-configuration`. Either `issuerUrl` or `endSessionEndpoint` must be provided.	0.1.0
`endSessionEndpoint`	`string`	The end-session endpoint URL. Either `issuerUrl` or `endSessionEndpoint` must be provided.	0.1.0
`idToken`	`string`	The ID token hint for session identification.	0.1.0
`postLogoutRedirectUrl`	`string`	The redirect URI to use after logout.	0.1.0
`additionalParameters`	`Record<string, string>`	Additional parameters to include in the end-session request.	0.1.0

RefreshTokenOptions¶

Prop	Type	Description	Since
`issuerUrl`	`string`	The OpenID Connect issuer URL used to fetch the discovery document at `{issuerUrl}/.well-known/openid-configuration`. Either `issuerUrl` or `tokenEndpoint` must be provided.	0.1.0
`tokenEndpoint`	`string`	The token endpoint URL. Either `issuerUrl` or `tokenEndpoint` must be provided.	0.1.0
`clientId`	`string`	The OAuth client ID.	0.1.0
`refreshToken`	`string`	The refresh token obtained from login.	0.1.0
`additionalParameters`	`Record<string, string>`	Additional parameters to include in the token refresh request.	0.1.0

Type Aliases¶

HandleRedirectCallbackResult¶

LoginResult

RefreshTokenResult¶

LoginResult

Changelog¶

See CHANGELOG.md.

Breaking Changes¶

See BREAKING.md.

License¶

See LICENSE.

@capawesome-team/capacitor-oauth¶

Features¶

Compatibility¶

Demo¶

Installation¶

Android¶

Variables¶

Redirect Scheme¶

Proguard¶

Usage¶

API¶

decodeIdToken(...)¶

getAccessTokenExpirationDate(...)¶

isAccessTokenAvailable(...)¶

isAccessTokenExpired(...)¶

isRefreshTokenAvailable(...)¶

handleRedirectCallback()¶

login(...)¶

logout(...)¶

refreshToken(...)¶

Interfaces¶

DecodeIdTokenResult¶

DecodeIdTokenOptions¶

GetAccessTokenExpirationDateResult¶

GetAccessTokenExpirationDateOptions¶

IsAccessTokenAvailableResult¶

IsAccessTokenAvailableOptions¶

IsAccessTokenExpiredResult¶

IsAccessTokenExpiredOptions¶

IsRefreshTokenAvailableResult¶

IsRefreshTokenAvailableOptions¶

LoginResult¶

LoginOptions¶

LogoutOptions¶

RefreshTokenOptions¶

Type Aliases¶

HandleRedirectCallbackResult¶

RefreshTokenResult¶

Changelog¶

Breaking Changes¶

License¶