Name	Name	Last commit message	Last commit date
parent directory ..
BREAKING.md	BREAKING.md
CHANGELOG.md	CHANGELOG.md
LICENSE	LICENSE
README.md	README.md

@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.
🪶 Lightweight: Just a single dependency and zero unnecessary bloat.
🤝 Compatibility: Compatible with the Secure Preferences plugin to securely store tokens.
📦 CocoaPods & SPM: Supports CocoaPods and 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

Guides

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

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.

Uh oh!

FilesExpand file tree

oauth

Directory actions

More options

Directory actions

More options

Latest commit

History

oauth

Folders and files

parent directory

README.md

@capawesome-team/capacitor-oauth

Features

Compatibility

Demo

Guides

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