--- description: Capacitor plugin for OAuth 2.0 and OpenID Connect with PKCE, token refresh, and provider discovery on Android, iOS, Web. An Ionic Auth Connect alternative. title: Capacitor OAuth Plugin for Android, iOS & Web - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/oauth.png --- [Skip to content ](#capacitor-oauth-plugin) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * OAuth [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Troubleshooting ](#troubleshooting) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Next steps ](#next-steps) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Troubleshooting ](#troubleshooting) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Next steps ](#next-steps) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # Capacitor OAuth Plugin[ΒΆ](#capacitor-oauth-plugin "Permanent link") Capacitor plugin for communicating with OAuth 2.0 and OpenID Connect providers.[1](#fn:1)[2](#fn:2) [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1) ](https://capawesome.io/) ## Features[ΒΆ](#features "Permanent link") The Capacitor OAuth plugin is one of the most complete authentication solutions for Capacitor apps. 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](https://capawesome.io/docs/sdks/capacitor/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](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[ΒΆ](#use-cases "Permanent link") The OAuth plugin is typically used whenever an app needs to authenticate users against an OAuth 2.0 or OpenID Connect provider, for example: * **Enterprise sign-in**: Authenticate users against identity providers such as Auth0, Azure AD, Amazon Cognito, Okta or OneLogin using the Authorization Code flow with PKCE. * **Social login**: Sign in users with providers like Google that support OpenID Connect discovery. * **Session management**: Keep users signed in by refreshing access tokens with a refresh token and checking token expiration. * **User profiles**: Decode the JWT ID token to access the user's claims. * **Auth Connect migration**: Replace the discontinued Ionic Auth Connect plugin with an actively maintained alternative. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.1.x | \>=8.x.x | Active support | ## Demo[ΒΆ](#demo "Permanent link") | Android | iOS | Web | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | ![Android Demo](../../../assets/external/github.com/user-attachments/assets/95ec6fe8-ba1d-4be0-898d-6b63a9170347.gif) | ![iOS Demo](../../../assets/external/github.com/user-attachments/assets/0f06193f-15c5-4c72-a3dd-ada5163ce3eb.gif) | ![Web Demo](../../../assets/external/github.com/user-attachments/assets/267c8536-2c83-455a-ab8f-76ed99011ba1.gif) | ## Guides[ΒΆ](#guides "Permanent link") * [Announcing the Capacitor OAuth Plugin](https://capawesome.io/blog/announcing-the-capacitor-oauth-plugin/) * [How to Use Better Auth in Capacitor Apps](https://capawesome.io/blog/how-to-use-better-auth-in-capacitor-apps/) * [How to Sign in with Okta using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-okta-using-capacitor/) * [How to Sign in with Auth0 using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-auth0-using-capacitor/) * [How to Sign in with Azure Entra ID using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-azure-entra-id-using-capacitor/) * [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/) * [Alternative to the Ionic Auth Connect Plugin](https://capawesome.io/blog/alternative-to-ionic-auth-connect-plugin/) ## Installation[ΒΆ](#installation "Permanent link") This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)npm config set //npm.registry.capawesome.io/:_authToken ` **Attention**: Replace `` 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](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-oauth` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: `[](#%5F%5Fcodelineno-3-1)npm install @capawesome-team/capacitor-oauth [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") #### Variables[ΒΆ](#variables "Permanent link") 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[ΒΆ](#redirect-scheme "Permanent link") Add the following to your app's `build.gradle` file to configure the redirect scheme used by AppAuth: `[](#%5F%5Fcodelineno-4-1)android { [](#%5F%5Fcodelineno-4-2) defaultConfig { [](#%5F%5Fcodelineno-4-3) manifestPlaceholders = [appAuthRedirectScheme: "com.example.app"] [](#%5F%5Fcodelineno-4-4) } [](#%5F%5Fcodelineno-4-5)} ` Replace `com.example.app` with the scheme of your redirect URI. #### Proguard[ΒΆ](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-5-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } ` ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to sign in a user, handle the redirect callback on the Web, refresh the access token, sign out a user, and decode an ID token, using the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin to securely store the tokens. ### Sign in a user[ΒΆ](#sign-in-a-user "Permanent link") Start an OAuth 2.0 authorization code flow with PKCE using the `login(...)` method. When you provide the `issuerUrl`, the plugin automatically fetches the authorization and token endpoints via OpenID Connect discovery: `[](#%5F%5Fcodelineno-6-1)import { Oauth } from '@capawesome-team/capacitor-oauth'; [](#%5F%5Fcodelineno-6-2)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-6-3) [](#%5F%5Fcodelineno-6-4)const login = async () => { [](#%5F%5Fcodelineno-6-5) // Sign in the user [](#%5F%5Fcodelineno-6-6) const result = await Oauth.login({ [](#%5F%5Fcodelineno-6-7) issuerUrl: 'https://accounts.google.com', [](#%5F%5Fcodelineno-6-8) clientId: 'YOUR_CLIENT_ID', [](#%5F%5Fcodelineno-6-9) redirectUrl: 'com.example.app://oauth/callback', [](#%5F%5Fcodelineno-6-10) scopes: ['openid', 'profile', 'email', 'offline_access'], [](#%5F%5Fcodelineno-6-11) }); [](#%5F%5Fcodelineno-6-12) console.log('Access token:', result.accessToken); [](#%5F%5Fcodelineno-6-13) console.log('ID token:', result.idToken); [](#%5F%5Fcodelineno-6-14) console.log('Refresh token:', result.refreshToken); [](#%5F%5Fcodelineno-6-15) // Store the tokens securely [](#%5F%5Fcodelineno-6-16) await SecurePreferences.set({ [](#%5F%5Fcodelineno-6-17) key: 'tokens', [](#%5F%5Fcodelineno-6-18) value: JSON.stringify(result), [](#%5F%5Fcodelineno-6-19) }); [](#%5F%5Fcodelineno-6-20)}; ` ### Handle the redirect callback on the Web[ΒΆ](#handle-the-redirect-callback-on-the-web "Permanent link") On the Web, call the `handleRedirectCallback()` method on page load when the URL contains authorization response parameters. This method is only available on Web: `[](#%5F%5Fcodelineno-7-1)import { Oauth } from '@capawesome-team/capacitor-oauth'; [](#%5F%5Fcodelineno-7-2)import { Capacitor } from '@capacitor/core'; [](#%5F%5Fcodelineno-7-3) [](#%5F%5Fcodelineno-7-4)const handleRedirectCallback = async () => { [](#%5F%5Fcodelineno-7-5) if (Capacitor.getPlatform() !== 'web') { [](#%5F%5Fcodelineno-7-6) return; [](#%5F%5Fcodelineno-7-7) } [](#%5F%5Fcodelineno-7-8) // Handle the redirect callback on web [](#%5F%5Fcodelineno-7-9) const result = await Oauth.handleRedirectCallback(); [](#%5F%5Fcodelineno-7-10) console.log('Access token:', result.accessToken); [](#%5F%5Fcodelineno-7-11)}; ` ### Refresh the access token[ΒΆ](#refresh-the-access-token "Permanent link") Use the `refreshToken(...)` method to obtain a new access token using the refresh token from the login: `[](#%5F%5Fcodelineno-8-1)import { Oauth } from '@capawesome-team/capacitor-oauth'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const refreshToken = async () => { [](#%5F%5Fcodelineno-8-4) const result = await Oauth.refreshToken({ [](#%5F%5Fcodelineno-8-5) issuerUrl: 'https://accounts.google.com', [](#%5F%5Fcodelineno-8-6) clientId: 'YOUR_CLIENT_ID', [](#%5F%5Fcodelineno-8-7) refreshToken: 'YOUR_REFRESH_TOKEN', [](#%5F%5Fcodelineno-8-8) }); [](#%5F%5Fcodelineno-8-9) console.log('New access token:', result.accessToken); [](#%5F%5Fcodelineno-8-10)}; ` ### Sign out a user[ΒΆ](#sign-out-a-user "Permanent link") End the OAuth session by calling the provider's end-session endpoint using the `logout(...)` method: `[](#%5F%5Fcodelineno-9-1)import { Oauth } from '@capawesome-team/capacitor-oauth'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const logout = async () => { [](#%5F%5Fcodelineno-9-4) await Oauth.logout({ [](#%5F%5Fcodelineno-9-5) issuerUrl: 'https://accounts.google.com', [](#%5F%5Fcodelineno-9-6) idToken: 'YOUR_ID_TOKEN', [](#%5F%5Fcodelineno-9-7) postLogoutRedirectUrl: 'com.example.app://oauth/logout', [](#%5F%5Fcodelineno-9-8) }); [](#%5F%5Fcodelineno-9-9)}; ` ### Decode an ID token[ΒΆ](#decode-an-id-token "Permanent link") Use the `decodeIdToken(...)` method to decode a JWT ID token without verification and access its claims: `[](#%5F%5Fcodelineno-10-1)import { Oauth } from '@capawesome-team/capacitor-oauth'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const decodeIdToken = async () => { [](#%5F%5Fcodelineno-10-4) const result = await Oauth.decodeIdToken({ [](#%5F%5Fcodelineno-10-5) token: 'YOUR_ID_TOKEN', [](#%5F%5Fcodelineno-10-6) }); [](#%5F%5Fcodelineno-10-7) console.log('Payload:', result.payload); [](#%5F%5Fcodelineno-10-8)}; ` ## API[ΒΆ](#api "Permanent link") * [decodeIdToken(...)](#decodeidtoken) * [getAccessTokenExpirationDate(...)](#getaccesstokenexpirationdate) * [isAccessTokenAvailable(...)](#isaccesstokenavailable) * [isAccessTokenExpired(...)](#isaccesstokenexpired) * [isRefreshTokenAvailable(...)](#isrefreshtokenavailable) * [handleRedirectCallback()](#handleredirectcallback) * [login(...)](#login) * [logout(...)](#logout) * [refreshToken(...)](#refreshtoken) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### decodeIdToken(...)[ΒΆ](#decodeidtoken "Permanent link") `[](#%5F%5Fcodelineno-11-1)decodeIdToken(options: DecodeIdTokenOptions) => Promise ` Decode a JWT ID token without verification. | Param | Type | | ----------- | --------------------------------------------- | | **options** | [DecodeIdTokenOptions](#decodeidtokenoptions) | **Returns:** `Promise<[DecodeIdTokenResult](#decodeidtokenresult)>` **Since:** 0.1.0 --- ### getAccessTokenExpirationDate(...)[ΒΆ](#getaccesstokenexpirationdate "Permanent link") `[](#%5F%5Fcodelineno-12-1)getAccessTokenExpirationDate(options: GetAccessTokenExpirationDateOptions) => Promise ` Get the access token expiration date as an ISO 8601 string. | Param | Type | | ----------- | --------------------------------------------------------------------------- | | **options** | [GetAccessTokenExpirationDateOptions](#getaccesstokenexpirationdateoptions) | **Returns:** `Promise<[GetAccessTokenExpirationDateResult](#getaccesstokenexpirationdateresult)>` **Since:** 0.1.0 --- ### isAccessTokenAvailable(...)[ΒΆ](#isaccesstokenavailable "Permanent link") `[](#%5F%5Fcodelineno-13-1)isAccessTokenAvailable(options: IsAccessTokenAvailableOptions) => Promise ` Check if an access token is available (non-null and non-empty). | Param | Type | | ----------- | --------------------------------------------------------------- | | **options** | [IsAccessTokenAvailableOptions](#isaccesstokenavailableoptions) | **Returns:** `Promise<[IsAccessTokenAvailableResult](#isaccesstokenavailableresult)>` **Since:** 0.1.0 --- ### isAccessTokenExpired(...)[ΒΆ](#isaccesstokenexpired "Permanent link") `[](#%5F%5Fcodelineno-14-1)isAccessTokenExpired(options: IsAccessTokenExpiredOptions) => Promise ` Check if the access token has expired. | Param | Type | | ----------- | ----------------------------------------------------------- | | **options** | [IsAccessTokenExpiredOptions](#isaccesstokenexpiredoptions) | **Returns:** `Promise<[IsAccessTokenExpiredResult](#isaccesstokenexpiredresult)>` **Since:** 0.1.0 --- ### isRefreshTokenAvailable(...)[ΒΆ](#isrefreshtokenavailable "Permanent link") `[](#%5F%5Fcodelineno-15-1)isRefreshTokenAvailable(options: IsRefreshTokenAvailableOptions) => Promise ` Check if a refresh token is available (non-null and non-empty). | Param | Type | | ----------- | ----------------------------------------------------------------- | | **options** | [IsRefreshTokenAvailableOptions](#isrefreshtokenavailableoptions) | **Returns:** `Promise<[IsRefreshTokenAvailableResult](#isrefreshtokenavailableresult)>` **Since:** 0.1.0 --- ### handleRedirectCallback()[ΒΆ](#handleredirectcallback "Permanent link") `[](#%5F%5Fcodelineno-16-1)handleRedirectCallback() => Promise ` 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](#loginresult)>` **Since:** 0.1.0 --- ### login(...)[ΒΆ](#login "Permanent link") `[](#%5F%5Fcodelineno-17-1)login(options: LoginOptions) => Promise ` Start an OAuth 2.0 authorization code flow with PKCE. | Param | Type | | ----------- | ----------------------------- | | **options** | [LoginOptions](#loginoptions) | **Returns:** `Promise<[LoginResult](#loginresult)>` **Since:** 0.1.0 --- ### logout(...)[ΒΆ](#logout "Permanent link") `[](#%5F%5Fcodelineno-18-1)logout(options: LogoutOptions) => Promise ` 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](#logoutoptions) | **Since:** 0.1.0 --- ### refreshToken(...)[ΒΆ](#refreshtoken "Permanent link") `[](#%5F%5Fcodelineno-19-1)refreshToken(options: RefreshTokenOptions) => Promise ` Refresh the access token using a refresh token. | Param | Type | | ----------- | ------------------------------------------- | | **options** | [RefreshTokenOptions](#refreshtokenoptions) | **Returns:** `Promise<[LoginResult](#loginresult)>` **Since:** 0.1.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### DecodeIdTokenResult[ΒΆ](#decodeidtokenresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ----------------------- | ---------------------------------------------- | ----- | | **header** | Record | The decoded JWT header. | 0.1.0 | | **payload** | Record | The decoded JWT payload containing the claims. | 0.1.0 | #### DecodeIdTokenOptions[ΒΆ](#decodeidtokenoptions "Permanent link") | Prop | Type | Description | Since | | --------- | ------ | ---------------------------------- | ----- | | **token** | string | The JWT ID token string to decode. | 0.1.0 | #### GetAccessTokenExpirationDateResult[ΒΆ](#getaccesstokenexpirationdateresult "Permanent link") | Prop | Type | Description | Since | | -------- | ------ | ------------------------------------------------------- | ----- | | **date** | string | The access token expiration date as an ISO 8601 string. | 0.1.0 | #### GetAccessTokenExpirationDateOptions[ΒΆ](#getaccesstokenexpirationdateoptions "Permanent link") | Prop | Type | Description | Since | | ----------------------------- | ------ | ------------------------------------------------------- | ----- | | **accessTokenExpirationDate** | number | The access token expiration date in epoch milliseconds. | 0.1.0 | #### IsAccessTokenAvailableResult[ΒΆ](#isaccesstokenavailableresult "Permanent link") | Prop | Type | Description | Since | | --------------- | ------- | --------------------------------------------------- | ----- | | **isAvailable** | boolean | Whether the access token is non-null and non-empty. | 0.1.0 | #### IsAccessTokenAvailableOptions[ΒΆ](#isaccesstokenavailableoptions "Permanent link") | Prop | Type | Description | Since | | --------------- | ------ | -------------------------- | ----- | | **accessToken** | string | The access token to check. | 0.1.0 | #### IsAccessTokenExpiredResult[ΒΆ](#isaccesstokenexpiredresult "Permanent link") | Prop | Type | Description | Since | | ------------- | ------- | ------------------------------------- | ----- | | **isExpired** | boolean | Whether the access token has expired. | 0.1.0 | #### IsAccessTokenExpiredOptions[ΒΆ](#isaccesstokenexpiredoptions "Permanent link") | Prop | Type | Description | Since | | ----------------------------- | ------ | ------------------------------------------------------- | ----- | | **accessTokenExpirationDate** | number | The access token expiration date in epoch milliseconds. | 0.1.0 | #### IsRefreshTokenAvailableResult[ΒΆ](#isrefreshtokenavailableresult "Permanent link") | Prop | Type | Description | Since | | --------------- | ------- | ---------------------------------------------------- | ----- | | **isAvailable** | boolean | Whether the refresh token is non-null and non-empty. | 0.1.0 | #### IsRefreshTokenAvailableOptions[ΒΆ](#isrefreshtokenavailableoptions "Permanent link") | Prop | Type | Description | Since | | ---------------- | ------ | --------------------------- | ----- | | **refreshToken** | string | The refresh token to check. | 0.1.0 | #### LoginResult[ΒΆ](#loginresult "Permanent link") | 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 | | **additionalParameters** | Record | Additional non-standard parameters returned by the token endpoint. All values are returned as strings. | 0.1.8 | | **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[ΒΆ](#loginoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **additionalParameters** | Record | Additional parameters to include in the authorization request. | | 0.1.0 | | **authorizationEndpoint** | string | The authorization endpoint URL. Either issuerUrl or both authorizationEndpoint and tokenEndpoint must be provided. | | 0.1.0 | | **clientId** | string | The OAuth client ID. | | 0.1.0 | | **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 | | **loginHint** | string | A hint to the authorization server about the user's identifier to pre-fill the login form. | | 0.1.0 | | **prefersEphemeralWebBrowserSession** | boolean | Whether the authentication session should use an ephemeral web browser session. If true, the session will not share cookies or other browsing data with the user's regular browser session. As a side effect, the system consent dialog (e.g. "...wants to use 'example.com' to Sign In") is not shown. Only available on iOS. | false | 0.1.5 | | **prompt** | string | The prompt parameter to control the authorization server UI behavior. | | 0.1.0 | | **redirectUrl** | string | The redirect URI to use after authentication. **Attention**: On iOS, the redirect URI returned by the provider must exactly match this value (including any trailing slash), otherwise login(...) will never resolve. See the [Troubleshooting](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/oauth#troubleshooting) section for details. | | 0.1.0 | | **scopes** | string\[\] | The OAuth scopes to request. | | 0.1.0 | | **tokenEndpoint** | string | The token endpoint URL. Either issuerUrl or both authorizationEndpoint and tokenEndpoint must be provided. | | 0.1.0 | | **uiLocales** | string\[\] | The end-user's preferred languages for the authorization server UI, as an ordered list of BCP47 language tags. | | 0.1.4 | #### LogoutOptions[ΒΆ](#logoutoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **additionalParameters** | Record | Additional parameters to include in the end-session request. | | 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 | | **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 | | **postLogoutRedirectUrl** | string | The redirect URI to use after logout. | | 0.1.0 | | **prefersEphemeralWebBrowserSession** | boolean | Whether the authentication session should use an ephemeral web browser session. If true, the session will not share cookies or other browsing data with the user's regular browser session. As a side effect, the system consent dialog (e.g. "...wants to use 'example.com' to Sign Out") is not shown. Only available on iOS. | false | 0.1.5 | #### RefreshTokenOptions[ΒΆ](#refreshtokenoptions "Permanent link") | 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 | Additional parameters to include in the token refresh request. | 0.1.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### HandleRedirectCallbackResult[ΒΆ](#handleredirectcallbackresult "Permanent link") `[LoginResult](#loginresult)` #### RefreshTokenResult[ΒΆ](#refreshtokenresult "Permanent link") `[LoginResult](#loginresult)` ## Troubleshooting[ΒΆ](#troubleshooting "Permanent link") ##### `login(...)` never resolves on iOS[ΒΆ](#login-never-resolves-on-ios "Permanent link") On iOS, `login(...)` may hang forever (while working on Android and Web) if the redirect URI returned by your provider does not exactly match the `redirectUrl` you passed. The plugin compares scheme, host and path and silently ignores any mismatch, so the promise never settles. The usual culprit is a **trailing slash** added by the provider or its infrastructure (`com.example.app://callback` vs `com.example.app://callback/`). Compare the returned redirect URI (e.g. via a network proxy such as [Proxyman](https://proxyman.io/)) byte-for-byte with your `redirectUrl` and make them match exactly. ## FAQ[ΒΆ](#faq "Permanent link") ### Is this plugin an alternative to Ionic Auth Connect?[ΒΆ](#is-this-plugin-an-alternative-to-ionic-auth-connect "Permanent link") Yes. This plugin was built as an actively maintained alternative to [Ionic Auth Connect](https://ionic.io/products/auth-connect), which has been discontinued and reaches end of life on December 31, 2027\. It offers a similar feature set: * OAuth 2.0 and OpenID Connect support for any provider, including Auth0, Azure AD, Amazon Cognito, Okta and OneLogin * Authorization Code flow with Proof Key for Code Exchange (PKCE) * Automatic endpoint discovery via OpenID Connect discovery * Access token refresh using a refresh token * Logout via the provider's end-session endpoint ### How do I migrate from Ionic Auth Connect?[ΒΆ](#how-do-i-migrate-from-ionic-auth-connect "Permanent link") For an AI-assisted migration of your code, add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool and instruct it to use the `ionic-enterprise-sdk-migration` skill to migrate your project from Ionic Auth Connect to `@capawesome-team/capacitor-oauth`. Alternatively, if you want to perform the migration manually, you can follow the instructions in this blog post: [Alternative to the Ionic Auth Connect plugin](https://capawesome.io/blog/alternative-to-ionic-auth-connect-plugin/). ### Why does `login(...)` never resolve on iOS?[ΒΆ](#why-does-login-never-resolve-on-ios "Permanent link") This usually happens when the redirect URI returned by your provider does not exactly match the `redirectUrl` you passed, for example because of a trailing slash added by the provider. The plugin compares scheme, host and path and silently ignores any mismatch. See the [Troubleshooting](#troubleshooting) section for details on how to diagnose and fix this. ### Where should I store the tokens?[ΒΆ](#where-should-i-store-the-tokens "Permanent link") Tokens are sensitive data and should not be stored in plain text. The plugin is compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin, which securely stores key/value pairs such as tokens, as shown in the [usage examples](#usage) above. ### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ### How does OAuth compare to Apple, Google, or Facebook Sign-In?[ΒΆ](#how-does-oauth-compare-to-apple-google-or-facebook-sign-in "Permanent link") This plugin talks to any OAuth 2.0 / OpenID Connect provider directly, which is the right fit for a custom identity provider or one without a dedicated Capacitor plugin. If you're specifically integrating Apple, Google, or Facebook, their dedicated [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/), [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/), and [Facebook Sign-In](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/) plugins use each provider's native SDK and are usually simpler to set up than configuring them through generic OAuth. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face recognition or fingerprint recognition. * [In-App Browser](https://capawesome.io/docs/sdks/capacitor/in-app-browser/): Open the OAuth authorization page in an embedded browser instead of the system browser. * [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard. * [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information. ## Next steps[ΒΆ](#next-steps "Permanent link") Here are a few resources to help you continue: * Read [Alternative to the Ionic Auth Connect plugin](https://capawesome.io/blog/alternative-to-ionic-auth-connect-plugin/) if you are migrating from Ionic Auth Connect. * Store tokens and other sensitive data with the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/). * Check out [Getting Started with Insiders](https://capawesome.io/docs/insiders/getting-started/) to learn how to install the plugin. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/oauth/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/oauth/BREAKING.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/oauth/LICENSE). --- 1. This project is not affiliated with, endorsed by, sponsored by, or approved by the OpenID Foundation or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text") 2. `OpenID` is a registered trademark of the OpenID Foundation. [↩](#fnref:2 "Jump back to footnote 2 in the text") July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/oauth/#article", "headline": "Capacitor OAuth Plugin for Android, iOS & Web", "name": "Capacitor OAuth Plugin for Android, iOS & Web", "description": "Capacitor plugin for OAuth 2.0 and OpenID Connect with PKCE, token refresh, and provider discovery on Android, iOS, Web. An Ionic Auth Connect alternative.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/oauth/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/oauth/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/oauth/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/oauth/#software", "name": "Capacitor OAuth Plugin for Android, iOS & Web", "description": "Capacitor plugin for OAuth 2.0 and OpenID Connect with PKCE, token refresh, and provider discovery on Android, iOS, Web. An Ionic Auth Connect alternative.", "url": "https://capawesome.io/docs/sdks/capacitor/oauth/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Is this plugin an alternative to Ionic Auth Connect?", "acceptedAnswer": {"@type": "Answer", "text": "Yes. This plugin was built as an actively maintained alternative to Ionic Auth Connect, which has been discontinued and reaches end of life on December 31, 2027. It offers a similar feature set: OAuth 2.0 and OpenID Connect support for any provider, including Auth0, Azure AD, Amazon Cognito, Okta and OneLogin Authorization Code flow with Proof Key for Code Exchange (PKCE) Automatic endpoint discovery via OpenID Connect discovery Access token refresh using a refresh token Logout via the provider's end-session endpoint"}}, {"@type": "Question", "name": "How do I migrate from Ionic Auth Connect?", "acceptedAnswer": {"@type": "Answer", "text": "For an AI-assisted migration of your code, add the Capawesome Skills to your AI tool and instruct it to use the ionic-enterprise-sdk-migration skill to migrate your project from Ionic Auth Connect to @capawesome-team/capacitor-oauth. Alternatively, if you want to perform the migration manually, you can follow the instructions in this blog post: Alternative to the Ionic Auth Connect plugin."}}, {"@type": "Question", "name": "Why does login(...) never resolve on iOS?", "acceptedAnswer": {"@type": "Answer", "text": "This usually happens when the redirect URI returned by your provider does not exactly match the redirectUrl you passed, for example because of a trailing slash added by the provider. The plugin compares scheme, host and path and silently ignores any mismatch. See the Troubleshooting section for details on how to diagnose and fix this."}}, {"@type": "Question", "name": "Where should I store the tokens?", "acceptedAnswer": {"@type": "Answer", "text": "Tokens are sensitive data and should not be stored in plain text. The plugin is compatible with the Secure Preferences plugin, which securely stores key/value pairs such as tokens, as shown in the usage examples above."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}, {"@type": "Question", "name": "How does OAuth compare to Apple, Google, or Facebook Sign-In?", "acceptedAnswer": {"@type": "Answer", "text": "This plugin talks to any OAuth 2.0 / OpenID Connect provider directly, which is the right fit for a custom identity provider or one without a dedicated Capacitor plugin. If you're specifically integrating Apple, Google, or Facebook, their dedicated Apple Sign-In, Google Sign-In, and Facebook Sign-In plugins use each provider's native SDK and are usually simpler to set up than configuring them through generic OAuth."}}], "url": "https://capawesome.io/docs/sdks/capacitor/oauth/"} ```