capacitor-auth-manager 2.4.2 → 2.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -1
- package/README.md +505 -0
- package/package.json +12 -24
- package/Readme.md +0 -203
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,32 @@ All notable changes to `capacitor-auth-manager` are documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [2.4.3] — 2026-07-25
|
|
9
|
+
|
|
10
|
+
**Documentation and metadata only — no runtime changes.** Brings the package to the house README
|
|
11
|
+
standard and, importantly, **documents two High-severity defects that have been shipping since before
|
|
12
|
+
this release**. They are stated plainly in the README's Limitations section rather than left for a
|
|
13
|
+
consumer to discover at runtime:
|
|
14
|
+
|
|
15
|
+
- **The published ESM build does not resolve under bare Node.** `moduleResolution: "bundler"` emits 133
|
|
16
|
+
extensionless relative specifiers across 33 files. Bundlers resolve them; Node's ESM resolver does
|
|
17
|
+
not, so SSR, Node-resolution test runners and `node --import` all fail.
|
|
18
|
+
- **Importing the package throws `window is not defined`.** A module-scope singleton in
|
|
19
|
+
`src/core/auth-manager.ts` constructs a `WebStorage` that reads `window.localStorage` unguarded. This
|
|
20
|
+
also makes `sideEffects: false` untrue.
|
|
21
|
+
|
|
22
|
+
Neither is fixed here — both need a code change and a version bump beyond a documentation patch. Every
|
|
23
|
+
conventional gate passes while they ship: typecheck, lint, build, the exports-map walk and even an
|
|
24
|
+
esbuild bundle are all green. Only installing the tarball and importing it under bare Node catches them.
|
|
25
|
+
Tracked in `docs/REPORTED-ISSUES.md` as ISSUE-001 and ISSUE-002.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- README rewritten to the canonical package pattern; `Readme.md` renamed to `README.md`.
|
|
30
|
+
- `homepage` moved off the npmjs.com page onto the documentation site.
|
|
31
|
+
- `funding` added; `keywords` reduced from 24 to 9 honest terms.
|
|
32
|
+
- `files` allowlist corrected to include the `bin` script explicitly; inert `.npmignore` removed.
|
|
33
|
+
|
|
8
34
|
## [2.4.2] — 2026-06-30
|
|
9
35
|
|
|
10
36
|
**Native now actually compiles — Google-only native (verified).** `2.4.1` shipped native sources that
|
|
@@ -177,4 +203,10 @@ as each is hardened and verified on device; until then they report a clear `PROV
|
|
|
177
203
|
|
|
178
204
|
- `npm run build` succeeds; `npm run test:run` — 79 tests pass; `npm run lint` — 0 errors.
|
|
179
205
|
|
|
180
|
-
|
|
206
|
+
## Earlier releases
|
|
207
|
+
|
|
208
|
+
`0.0.1`, `0.0.2`, `1.0.0`, `1.1.0` and `2.1.0` were published before this changelog was started, and no
|
|
209
|
+
per-version record of them was kept. They are listed here so the gap is visible rather than silent; the
|
|
210
|
+
published artefacts remain on
|
|
211
|
+
[npm](https://www.npmjs.com/package/capacitor-auth-manager?activeTab=versions). Treat `2.2.0` as the first
|
|
212
|
+
release with a documented history.
|
package/README.md
ADDED
|
@@ -0,0 +1,505 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="https://capacitor-auth-manager-docs.aoneahsan.com/img/logo.svg" alt="Capacitor Auth Manager logo" width="120" />
|
|
4
|
+
|
|
5
|
+
<h1>capacitor-auth-manager</h1>
|
|
6
|
+
|
|
7
|
+
<p><strong>Firebase-agnostic Google sign-in for Capacitor and the web — one call, same result on every platform.</strong></p>
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/capacitor-auth-manager)
|
|
10
|
+
[](https://www.npmjs.com/package/capacitor-auth-manager)
|
|
11
|
+
[](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/LICENSE)
|
|
12
|
+
[](https://www.npmjs.com/package/capacitor-auth-manager)
|
|
13
|
+
[](https://bundlephobia.com/package/capacitor-auth-manager)
|
|
14
|
+
[](https://nodejs.org)
|
|
15
|
+
|
|
16
|
+
[Docs](https://capacitor-auth-manager-docs.aoneahsan.com) · [npm](https://www.npmjs.com/package/capacitor-auth-manager) · [GitHub](https://github.com/aoneahsan/capacitor-auth-manager) · [Changelog](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md) · [Support](https://github.com/aoneahsan/capacitor-auth-manager/issues)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
> [!IMPORTANT]
|
|
21
|
+
> - **Google is the only enabled provider in `2.4.x`.** The other fourteen are present in the source but
|
|
22
|
+
> un-registered — calling one throws `AuthErrorCode.PROVIDER_NOT_ENABLED`. They are re-enabled one at a
|
|
23
|
+
> time, each verified on a device first.
|
|
24
|
+
> - **Import it from a bundler, not from bare Node.** The published ESM build resolves under Vite, webpack,
|
|
25
|
+
> Metro and esbuild, but not under Node's own ESM resolver, and importing the package in a server or SSR
|
|
26
|
+
> context throws `window is not defined`. See [Limitations](#limitations).
|
|
27
|
+
|
|
28
|
+
Capacitor Auth Manager gives a Capacitor app one Google sign-in call that behaves the same on web, iOS and
|
|
29
|
+
Android, and hands back a raw `idToken` to use as you like. It pulls in no `firebase` dependency, so it fits
|
|
30
|
+
apps built on Firebase Auth and apps built on their own backend equally well. Typed React, Vue and Angular
|
|
31
|
+
adapters ship with it, so the sign-in button is a few lines in whichever framework you already use.
|
|
32
|
+
|
|
33
|
+
| | |
|
|
34
|
+
|---|---|
|
|
35
|
+
| **Version** | `2.4.2` |
|
|
36
|
+
| **License** | MIT |
|
|
37
|
+
| **Node** | `>=18.0.0` |
|
|
38
|
+
| **Platforms** | Web · iOS · Android |
|
|
39
|
+
| **Install size** | 264 kB tarball · ~17.4 kB min+gzip for the root entry |
|
|
40
|
+
| **Types** | Bundled `.d.ts` (ESM + CJS) |
|
|
41
|
+
| **Status** | Google provider in production use · remaining providers staged |
|
|
42
|
+
|
|
43
|
+
<a id="table-of-contents"></a>
|
|
44
|
+
## 🧭 Table of Contents [#](#table-of-contents)
|
|
45
|
+
|
|
46
|
+
- [💡 Why capacitor-auth-manager](#why-capacitor-auth-manager)
|
|
47
|
+
- [✨ Features](#features)
|
|
48
|
+
- [📱 Platform Support](#platform-support)
|
|
49
|
+
- [📋 Requirements](#requirements)
|
|
50
|
+
- [📦 Installation](#installation)
|
|
51
|
+
- [🚀 Quick Start](#quick-start)
|
|
52
|
+
- [🛠️ Usage](#usage)
|
|
53
|
+
- [⚙️ Configuration](#configuration)
|
|
54
|
+
- [🔧 API Reference](#api-reference)
|
|
55
|
+
- [🧩 Types](#types)
|
|
56
|
+
- [💻 Command Line](#command-line)
|
|
57
|
+
- [🎛️ Advanced Features](#advanced-features)
|
|
58
|
+
- [🚑 Recovery & Troubleshooting](#recovery-troubleshooting)
|
|
59
|
+
- [🚧 Limitations](#limitations)
|
|
60
|
+
- [❓ FAQ](#faq)
|
|
61
|
+
- [📚 Documentation](#documentation)
|
|
62
|
+
- [🔄 Changelog](#changelog)
|
|
63
|
+
- [🗺️ Roadmap](#roadmap)
|
|
64
|
+
- [🤝 Contributing](#contributing)
|
|
65
|
+
- [💬 Support](#support)
|
|
66
|
+
- [📄 License](#license)
|
|
67
|
+
- [👤 Author](#author)
|
|
68
|
+
- [🔗 Links](#links)
|
|
69
|
+
- [🏷️ Keywords](#keywords)
|
|
70
|
+
|
|
71
|
+
<a id="why-capacitor-auth-manager"></a>
|
|
72
|
+
## 💡 Why capacitor-auth-manager [#](#why-capacitor-auth-manager)
|
|
73
|
+
|
|
74
|
+
Google sign-in in a Capacitor app is normally two implementations wearing one button. On the web you open a
|
|
75
|
+
Firebase popup; inside the native webview that popup is unreliable, so you add a native plugin and a second
|
|
76
|
+
code path with a different result shape. The branch then leaks into your UI, your tests and your error
|
|
77
|
+
handling.
|
|
78
|
+
|
|
79
|
+
This package collapses that into `auth.signIn(AuthProvider.GOOGLE)`. It routes to Google Identity Services on
|
|
80
|
+
the web, the GoogleSignIn SDK on iOS and Credential Manager on Android, and returns the same
|
|
81
|
+
`{ user, credential }` shape from all three. What you do with the `idToken` afterwards — hand it to Firebase,
|
|
82
|
+
or verify it on your own server — stays your decision.
|
|
83
|
+
|
|
84
|
+
| | `capacitor-auth-manager` | Firebase popup + a separate native plugin |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| Call sites for one button | one | two, behind a platform branch |
|
|
87
|
+
| Result shape | identical on all three platforms | differs per path |
|
|
88
|
+
| `firebase` dependency | none | required on web |
|
|
89
|
+
| Framework adapters | React, Vue, Angular included | write your own |
|
|
90
|
+
| Providers available today | Google | whatever each piece supports |
|
|
91
|
+
|
|
92
|
+
**Not the right tool when** — you need a provider other than Google today; you need a Google **access token**
|
|
93
|
+
in the browser to call Google APIs (the web flow is id-token only); you import packages in bare Node or render
|
|
94
|
+
on a server (see [Limitations](#limitations)); or you already have a Firebase-popup web flow that works and no
|
|
95
|
+
native build to support.
|
|
96
|
+
|
|
97
|
+
<a id="features"></a>
|
|
98
|
+
## ✨ Features [#](#features)
|
|
99
|
+
|
|
100
|
+
- **One call per platform** — the same `signIn` on web, iOS and Android, returning the same shape.
|
|
101
|
+
- **Firebase-agnostic** — returns a raw `idToken`, and pulls no `firebase` package into your tree.
|
|
102
|
+
- **Modern native SDKs** — Android Credential Manager and iOS GoogleSignIn rather than deprecated APIs.
|
|
103
|
+
- **Typed framework adapters** — a `useAuth` hook for React, composables for Vue, an injectable
|
|
104
|
+
`AuthService` and route guards for Angular.
|
|
105
|
+
- **Observable auth state** — subscribe once with `onAuthStateChange` and let the UI follow.
|
|
106
|
+
- **Pluggable storage** — web and Capacitor Preferences backends ship with it, and it accepts your own
|
|
107
|
+
`StorageInterface` when you need Keychain or Keystore.
|
|
108
|
+
- **No token persistence by default** — sessions restore through the Google SDK rather than through
|
|
109
|
+
`localStorage`.
|
|
110
|
+
|
|
111
|
+
<a id="platform-support"></a>
|
|
112
|
+
## 📱 Platform Support [#](#platform-support)
|
|
113
|
+
|
|
114
|
+
| Platform | Supported | Notes |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| Web | ✅ | Google Identity Services id-token flow. Returns `idToken` only — no `accessToken`. |
|
|
117
|
+
| Android | ✅ | Credential Manager. `serverClientId` is required to receive an `idToken`. |
|
|
118
|
+
| iOS | ✅ | GoogleSignIn 7.x. Returns `idToken`, `accessToken`, and `serverAuthCode` when configured. |
|
|
119
|
+
| Node / SSR | ❌ | Importing the package on a server throws `window is not defined`. See [Limitations](#limitations). |
|
|
120
|
+
|
|
121
|
+
Native sources for both platforms compile in a clean Capacitor 8 app, verified with Gradle `assembleDebug`
|
|
122
|
+
and `pod lib lint`. A successful compile is not a runtime test — sign in once on a real device before rolling
|
|
123
|
+
a new version across several apps.
|
|
124
|
+
|
|
125
|
+
<a id="requirements"></a>
|
|
126
|
+
## 📋 Requirements [#](#requirements)
|
|
127
|
+
|
|
128
|
+
| Requirement | Version | Why |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| Node | `>=18.0.0` | build and install only; the package itself runs in a browser or a webview |
|
|
131
|
+
| `@capacitor/core` | `^7.4.2 \|\| ^8.0.0` | peer — imported by the published bundle, so install it even for a web-only build |
|
|
132
|
+
| `@capacitor/preferences` | `^6 \|\| ^7 \|\| ^8` | optional peer — only for `CapacitorPreferencesStorage` |
|
|
133
|
+
| `react` | `^16.8 \|\| ^17 \|\| ^18 \|\| ^19` | optional peer — only for `capacitor-auth-manager/react` |
|
|
134
|
+
| `vue` | `^3.0.0` | optional peer — only for `capacitor-auth-manager/vue` |
|
|
135
|
+
| `@angular/core` | `^12` – `^22` | optional peer — only for `capacitor-auth-manager/angular` |
|
|
136
|
+
|
|
137
|
+
You also need Google OAuth client IDs: a **Web** client for every platform, plus an **Android** client
|
|
138
|
+
registered with your signing fingerprints and an **iOS** client if you ship those platforms.
|
|
139
|
+
|
|
140
|
+
<a id="installation"></a>
|
|
141
|
+
## 📦 Installation [#](#installation)
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
yarn add capacitor-auth-manager @capacitor/core
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
For the native plugin, sync it into the platform projects. Without this step iOS and Android never load it:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
npx cap sync
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Then finish the per-platform OAuth setup, which cannot be done from JavaScript:
|
|
154
|
+
|
|
155
|
+
- **Android** — add your `google-services.json`, register the app's SHA-1 and SHA-256 fingerprints against an
|
|
156
|
+
Android OAuth client, and pass your **Web** client ID as `serverClientId`. Credential Manager will not
|
|
157
|
+
return an `idToken` without it. The plugin adds no manifest permissions of its own.
|
|
158
|
+
- **iOS** — add `GIDClientID` to `Info.plist` (or pass `iosClientId`), and add the reversed client ID as a URL
|
|
159
|
+
scheme under `CFBundleURLTypes`.
|
|
160
|
+
|
|
161
|
+
The bundled [command-line helper](#command-line) can write most of this for you.
|
|
162
|
+
|
|
163
|
+
<a id="quick-start"></a>
|
|
164
|
+
## 🚀 Quick Start [#](#quick-start)
|
|
165
|
+
|
|
166
|
+
Configure once at startup, then sign in from anywhere.
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
import { auth, AuthProvider } from 'capacitor-auth-manager';
|
|
170
|
+
|
|
171
|
+
auth.configure({
|
|
172
|
+
providers: {
|
|
173
|
+
[AuthProvider.GOOGLE]: {
|
|
174
|
+
clientId: 'YOUR_WEB_OAUTH_CLIENT_ID',
|
|
175
|
+
serverClientId: 'YOUR_WEB_OAUTH_CLIENT_ID', // required on Android for an idToken
|
|
176
|
+
iosClientId: 'YOUR_IOS_OAUTH_CLIENT_ID',
|
|
177
|
+
},
|
|
178
|
+
},
|
|
179
|
+
persistence: 'local',
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
const result = await auth.signIn(AuthProvider.GOOGLE);
|
|
183
|
+
console.log(result.user.email, result.credential.idToken);
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`AuthProvider.GOOGLE` is the typo-safe form of the string `'google'`; either works.
|
|
187
|
+
|
|
188
|
+
<a id="usage"></a>
|
|
189
|
+
## 🛠️ Usage [#](#usage)
|
|
190
|
+
|
|
191
|
+
### Hand the credential to Firebase
|
|
192
|
+
|
|
193
|
+
Identical on web, iOS and Android — the `idToken` is all Firebase needs.
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
|
|
197
|
+
|
|
198
|
+
const result = await auth.signIn(AuthProvider.GOOGLE);
|
|
199
|
+
await signInWithCredential(getAuth(), GoogleAuthProvider.credential(result.credential.idToken));
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Verify on your own backend instead
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
const { credential } = await auth.signIn(AuthProvider.GOOGLE);
|
|
206
|
+
await fetch('/api/session', {
|
|
207
|
+
method: 'POST',
|
|
208
|
+
headers: { 'Content-Type': 'application/json' },
|
|
209
|
+
body: JSON.stringify({ idToken: credential.idToken }),
|
|
210
|
+
});
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Always verify the token's signature server-side. This package does not verify it in the browser.
|
|
214
|
+
|
|
215
|
+
### React
|
|
216
|
+
|
|
217
|
+
```tsx
|
|
218
|
+
import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
|
|
219
|
+
|
|
220
|
+
function LoginButton() {
|
|
221
|
+
const { user, signIn, signOut, isLoading } = useAuth();
|
|
222
|
+
if (isLoading) return <span>Checking…</span>;
|
|
223
|
+
if (user) return <button onClick={() => signOut()}>Sign out {user.email}</button>;
|
|
224
|
+
return <button onClick={() => signIn(AuthProvider.GOOGLE)}>Sign in with Google</button>;
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Vue exposes the same surface as composables from `capacitor-auth-manager/vue`, and Angular as an injectable
|
|
229
|
+
`AuthService` plus `AuthGuard` from `capacitor-auth-manager/angular`.
|
|
230
|
+
|
|
231
|
+
### React to auth state anywhere
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
const unsubscribe = auth.onAuthStateChange((state) => {
|
|
235
|
+
console.log(state.user ? `signed in as ${state.user.email}` : 'signed out');
|
|
236
|
+
});
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Migrating from `@codetrix-studio/capacitor-google-auth`
|
|
240
|
+
|
|
241
|
+
The token moves from `result.authentication.idToken` to `result.credential.idToken`; the native account
|
|
242
|
+
chooser and the Firebase handoff behave as before.
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
// before
|
|
246
|
+
await GoogleAuth.initialize({ clientId });
|
|
247
|
+
const u = await GoogleAuth.signIn();
|
|
248
|
+
const token = u.authentication.idToken;
|
|
249
|
+
|
|
250
|
+
// after
|
|
251
|
+
auth.configure({ providers: { [AuthProvider.GOOGLE]: { clientId, serverClientId, iosClientId } } });
|
|
252
|
+
const res = await auth.signIn(AuthProvider.GOOGLE);
|
|
253
|
+
const token = res.credential.idToken;
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
<a id="configuration"></a>
|
|
257
|
+
## ⚙️ Configuration [#](#configuration)
|
|
258
|
+
|
|
259
|
+
`auth.configure()` takes the manager options; each provider takes its own block.
|
|
260
|
+
|
|
261
|
+
| Option | Type | Default | What it does |
|
|
262
|
+
|---|---|---|---|
|
|
263
|
+
| `providers` | `Record<AuthProvider, ProviderOptions>` | `{}` | Per-provider configuration. |
|
|
264
|
+
| `persistence` | `'local' \| 'session' \| 'none'` | `'local'` | Where auth state is kept between loads. |
|
|
265
|
+
| `storage` | `StorageInterface` | web storage | Custom backend — pass `CapacitorPreferencesStorage` or your own. |
|
|
266
|
+
|
|
267
|
+
Google provider options:
|
|
268
|
+
|
|
269
|
+
| Option | Platform | What it does |
|
|
270
|
+
|---|---|---|
|
|
271
|
+
| `clientId` | web (required), Android fallback | Web OAuth client ID; becomes the id token's `aud`. |
|
|
272
|
+
| `serverClientId` | Android (required), iOS | Web OAuth client ID. Credential Manager needs it to return an `idToken`. |
|
|
273
|
+
| `iosClientId` | iOS | iOS OAuth client ID, if not set as `GIDClientID` in `Info.plist`. |
|
|
274
|
+
| `scopes` | all | Extra OAuth scopes. Defaults to `openid email profile`. |
|
|
275
|
+
| `hostedDomain` | all | Restrict sign-in to one Google Workspace domain. |
|
|
276
|
+
| `loginHint` | all | Pre-fill an account. |
|
|
277
|
+
| `filterByAuthorizedAccounts` | Android | Show only previously authorised accounts. |
|
|
278
|
+
| `autoSelectEnabled` | Android | Allow one-tap auto-select for returning users. |
|
|
279
|
+
| `nonce` | web | Bind the request to an id-token `nonce` claim, which the package validates. |
|
|
280
|
+
|
|
281
|
+
The same Google options can live in `capacitor.config` under the plugin block instead of in application code.
|
|
282
|
+
Full reference: [Configuration](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/configuration).
|
|
283
|
+
|
|
284
|
+
<a id="api-reference"></a>
|
|
285
|
+
## 🔧 API Reference [#](#api-reference)
|
|
286
|
+
|
|
287
|
+
A signature index. Full documentation is on the
|
|
288
|
+
[docs site](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton).
|
|
289
|
+
|
|
290
|
+
| Export | Signature | Docs |
|
|
291
|
+
|---|---|---|
|
|
292
|
+
| `auth.configure` | `(config: AuthManagerConfig) => void` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
293
|
+
| `auth.signIn` | `(provider: AuthProvider, options?: SignInOptions) => Promise<AuthResult>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
294
|
+
| `auth.signOut` | `(options?: SignOutOptions) => Promise<void>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
295
|
+
| `auth.getCurrentUser` | `() => AuthUser \| null` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
296
|
+
| `auth.isAuthenticated` | `() => boolean` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
297
|
+
| `auth.onAuthStateChange` | `(cb: AuthStateChangeCallback) => () => void` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
298
|
+
| `auth.getIdToken` | `(options?: GetIdTokenOptions) => Promise<string \| null>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
299
|
+
| `auth.refreshToken` | `(options?: RefreshTokenOptions) => Promise<AuthResult>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
300
|
+
| `auth.revokeAccess` | `() => Promise<void>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
301
|
+
| `auth.deleteAccount` | `() => Promise<void>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
|
|
302
|
+
| `AuthError` · `isAuthError` | error class and type guard | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/errors) |
|
|
303
|
+
| `WebStorage` · `CapacitorPreferencesStorage` | `StorageInterface` implementations | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/storage) |
|
|
304
|
+
|
|
305
|
+
Subpath exports: `capacitor-auth-manager`, `/react`, `/vue`, `/angular`, `/core`, `/providers/web`.
|
|
306
|
+
|
|
307
|
+
<a id="types"></a>
|
|
308
|
+
## 🧩 Types [#](#types)
|
|
309
|
+
|
|
310
|
+
The shapes you actually touch. Every export is typed; see
|
|
311
|
+
[Types](https://capacitor-auth-manager-docs.aoneahsan.com/api/types) for the full set.
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
interface AuthResult {
|
|
315
|
+
user: AuthUser;
|
|
316
|
+
credential: AuthCredential;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
interface AuthCredential {
|
|
320
|
+
providerId: string; // 'google.com'
|
|
321
|
+
signInMethod: string;
|
|
322
|
+
idToken?: string; // web, iOS, Android
|
|
323
|
+
accessToken?: string; // iOS only for Google
|
|
324
|
+
serverAuthCode?: string; // iOS, when serverClientId is set — exchange it on your server
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
interface AuthUser {
|
|
328
|
+
uid: string;
|
|
329
|
+
email: string | null;
|
|
330
|
+
emailVerified: boolean;
|
|
331
|
+
displayName: string | null;
|
|
332
|
+
photoURL: string | null;
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
interface StorageInterface {
|
|
336
|
+
get<T>(key: string): Promise<T | null>;
|
|
337
|
+
set<T>(key: string, value: T): Promise<void>;
|
|
338
|
+
remove(key: string): Promise<void>;
|
|
339
|
+
clear(): Promise<void>;
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
<a id="command-line"></a>
|
|
344
|
+
## 💻 Command Line [#](#command-line)
|
|
345
|
+
|
|
346
|
+
An interactive helper that writes the platform OAuth wiring described in [Installation](#installation).
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
npx capacitor-auth-configure
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
It asks which platforms you target and which client IDs you hold, then updates `capacitor.config`,
|
|
353
|
+
`Info.plist` and the Android configuration accordingly. It takes no flags and prompts for every answer, so
|
|
354
|
+
run it in a real terminal rather than in CI.
|
|
355
|
+
|
|
356
|
+
<a id="advanced-features"></a>
|
|
357
|
+
## 🎛️ Advanced Features [#](#advanced-features)
|
|
358
|
+
|
|
359
|
+
- **Custom secure storage** — implement `StorageInterface` over Keychain or Keystore and pass it as
|
|
360
|
+
`storage` instead of the default web storage.
|
|
361
|
+
- **Nonce validation** — supply `nonce` on web and the package checks the returned id token's claim against it.
|
|
362
|
+
- **Google's own button** — when One-Tap is inside its cooldown window, the web provider exposes a
|
|
363
|
+
`renderButton(element)` escape hatch that draws Google's official button.
|
|
364
|
+
- **Log level control** — `defaultLogger.setLevel('debug')`, or the `VITE_LOG_LEVEL` / `LOG_LEVEL` build
|
|
365
|
+
variables, without touching `console` directly.
|
|
366
|
+
- **Config in `capacitor.config`** — keep the Google block in native config instead of application code.
|
|
367
|
+
|
|
368
|
+
<a id="recovery-troubleshooting"></a>
|
|
369
|
+
## 🚑 Recovery & Troubleshooting [#](#recovery-troubleshooting)
|
|
370
|
+
|
|
371
|
+
| Symptom | Cause | Fix |
|
|
372
|
+
|---|---|---|
|
|
373
|
+
| `idToken` is `null` on Android | `serverClientId` missing, or the SHA fingerprint is not registered | Pass your **Web** client ID as `serverClientId` and register the app's SHA-1/SHA-256 on the Android OAuth client |
|
|
374
|
+
| `PROVIDER_NOT_ENABLED` | that provider is not enabled in `2.4.x` | Only Google is available today — see [Roadmap](#roadmap) |
|
|
375
|
+
| `window is not defined` on the server | the package reads browser storage when imported | Import it only in client code, or behind a dynamic import — see [Limitations](#limitations) |
|
|
376
|
+
| `Cannot find module '…/core/auth-manager'` under Node | Node's ESM resolver rejects the published extensionless paths | Import through a bundler; bare Node ESM is unsupported today |
|
|
377
|
+
| Nothing happens on web sign-in | One-Tap is inside its cooldown window | Render Google's official button via `renderButton(element)` |
|
|
378
|
+
| `Cannot find module '@capacitor/core'` | the peer is not installed | `yarn add @capacitor/core` — it is needed even for a web-only build |
|
|
379
|
+
| Native plugin never runs | `npx cap sync` was not run after install | Run it, then rebuild the native project |
|
|
380
|
+
|
|
381
|
+
<a id="limitations"></a>
|
|
382
|
+
## 🚧 Limitations [#](#limitations)
|
|
383
|
+
|
|
384
|
+
Stated as plainly as the features, because each one otherwise costs an afternoon.
|
|
385
|
+
|
|
386
|
+
- **Google is the only working provider.** Fourteen others exist in the source and throw
|
|
387
|
+
`PROVIDER_NOT_ENABLED` when called.
|
|
388
|
+
- **Bare Node ESM does not resolve.** The published `dist/esm` uses extensionless relative paths, which
|
|
389
|
+
bundlers accept and Node's ESM resolver rejects. Vite, webpack, Metro and esbuild are fine; `node --import`
|
|
390
|
+
and Node-resolution test runners are not.
|
|
391
|
+
- **No server-side rendering.** Importing the package evaluates a singleton that reads browser storage, so it
|
|
392
|
+
throws `window is not defined` in Node. Load it in client code or behind a dynamic import.
|
|
393
|
+
- **`@capacitor/core` is effectively required**, despite being declared an optional peer — the published
|
|
394
|
+
bundle imports it even in a web-only build.
|
|
395
|
+
- **No `accessToken` on web or Android.** The web flow is id-token only; Android's Credential Manager returns
|
|
396
|
+
an `idToken` and leaves access tokens to the separate Google Authorization API. Only iOS returns both.
|
|
397
|
+
- **No id-token verification in the browser.** Signature and claim checks belong to your server, or Firebase.
|
|
398
|
+
- **Native runtime is not covered by CI.** Both platforms are verified to compile, not to sign in. Test a new
|
|
399
|
+
version on one real device before rolling it out widely.
|
|
400
|
+
- **`serverAuthCode` must never be exchanged client-side.** It is returned on iOS for your backend to use.
|
|
401
|
+
|
|
402
|
+
<a id="faq"></a>
|
|
403
|
+
## ❓ FAQ [#](#faq)
|
|
404
|
+
|
|
405
|
+
**Do I need Firebase to use this?**
|
|
406
|
+
No. It returns a raw `idToken` and never imports `firebase`. Handing that token to Firebase is one supported
|
|
407
|
+
option among several.
|
|
408
|
+
|
|
409
|
+
**Can I use it on the web only, without a native build?**
|
|
410
|
+
Yes — skip `npx cap sync`. You still need `@capacitor/core` installed, because the published bundle imports it.
|
|
411
|
+
|
|
412
|
+
**Why is there no `accessToken` on web?**
|
|
413
|
+
The web path uses the Google Identity Services id-token flow, which is what lets it work with no client secret
|
|
414
|
+
and no backend. To call Google APIs from the browser, use the GIS token client alongside this package.
|
|
415
|
+
|
|
416
|
+
**Which client ID goes where?**
|
|
417
|
+
The **Web** client ID is used as `clientId` on web and as `serverClientId` on Android. The iOS client ID is
|
|
418
|
+
separate. This catches nearly everyone once.
|
|
419
|
+
|
|
420
|
+
**When will the other providers land?**
|
|
421
|
+
One at a time, each verified on a device first. See [Roadmap](#roadmap).
|
|
422
|
+
|
|
423
|
+
**Is it safe to use in a Next.js or Nuxt app?**
|
|
424
|
+
Only in client components, or behind a dynamic import. A top-level server import throws — see
|
|
425
|
+
[Limitations](#limitations).
|
|
426
|
+
|
|
427
|
+
<a id="documentation"></a>
|
|
428
|
+
## 📚 Documentation [#](#documentation)
|
|
429
|
+
|
|
430
|
+
| Document | Read it when |
|
|
431
|
+
|---|---|
|
|
432
|
+
| [Introduction](https://capacitor-auth-manager-docs.aoneahsan.com/intro) | deciding whether this fits your app |
|
|
433
|
+
| [Installation](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/installation) | setting it up the first time |
|
|
434
|
+
| [Quick start](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/quick-start) | you want a working button in five minutes |
|
|
435
|
+
| [Configuration](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/configuration) | tuning manager or provider options |
|
|
436
|
+
| [Google provider](https://capacitor-auth-manager-docs.aoneahsan.com/providers/google) | wiring client IDs and scopes correctly |
|
|
437
|
+
| [Android](https://capacitor-auth-manager-docs.aoneahsan.com/platforms/android) · [iOS](https://capacitor-auth-manager-docs.aoneahsan.com/platforms/ios) · [Web](https://capacitor-auth-manager-docs.aoneahsan.com/platforms/web) | one platform behaves differently from the others |
|
|
438
|
+
| [React](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/react) · [Vue](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/vue) · [Angular](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/angular) · [Vanilla JS](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/vanilla-js) | integrating with your framework |
|
|
439
|
+
| [API reference](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) | you need an exact signature |
|
|
440
|
+
| [FAQ](https://capacitor-auth-manager-docs.aoneahsan.com/faq) | something surprised you |
|
|
441
|
+
|
|
442
|
+
<a id="changelog"></a>
|
|
443
|
+
## 🔄 Changelog [#](#changelog)
|
|
444
|
+
|
|
445
|
+
Latest release: **`2.4.2`** — native sources now compile in a real Capacitor 8 app, and the heavy Facebook and
|
|
446
|
+
Microsoft native SDKs were dropped so the plugin no longer drags them into every consumer build.
|
|
447
|
+
|
|
448
|
+
Full history: [CHANGELOG.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md).
|
|
449
|
+
|
|
450
|
+
<a id="roadmap"></a>
|
|
451
|
+
## 🗺️ Roadmap [#](#roadmap)
|
|
452
|
+
|
|
453
|
+
- Resolve the bare-Node ESM and server-side import limitations above.
|
|
454
|
+
- Re-enable the remaining providers one at a time, each hardened and then verified on a device.
|
|
455
|
+
- Android access-token and `serverAuthCode` support through the Google Authorization API.
|
|
456
|
+
- A `3.0.0` once every provider works again.
|
|
457
|
+
|
|
458
|
+
Dates are deliberately absent; each item ships when it is verified rather than when it is scheduled.
|
|
459
|
+
|
|
460
|
+
<a id="contributing"></a>
|
|
461
|
+
## 🤝 Contributing [#](#contributing)
|
|
462
|
+
|
|
463
|
+
Fork and open a pull request — see
|
|
464
|
+
[CONTRIBUTING.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/.github/CONTRIBUTING.md) for
|
|
465
|
+
setup, standards, and how to request collaborator access. `main` is protected: every change lands through a
|
|
466
|
+
reviewed pull request. Security issues follow
|
|
467
|
+
[SECURITY.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/.github/SECURITY.md) rather than
|
|
468
|
+
the public tracker.
|
|
469
|
+
|
|
470
|
+
<a id="support"></a>
|
|
471
|
+
## 💬 Support [#](#support)
|
|
472
|
+
|
|
473
|
+
Questions and bugs: [open an issue](https://github.com/aoneahsan/capacitor-auth-manager/issues).
|
|
474
|
+
|
|
475
|
+
If this package saves you time, you can support its maintenance at
|
|
476
|
+
[aoneahsan.com/payment](https://aoneahsan.com/payment?project-id=capacitor-auth-manager&project-identifier=capacitor-auth-manager).
|
|
477
|
+
|
|
478
|
+
<a id="license"></a>
|
|
479
|
+
## 📄 License [#](#license)
|
|
480
|
+
|
|
481
|
+
MIT © Ahsan Mahmood — see
|
|
482
|
+
[LICENSE](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/LICENSE).
|
|
483
|
+
|
|
484
|
+
<a id="author"></a>
|
|
485
|
+
## 👤 Author [#](#author)
|
|
486
|
+
|
|
487
|
+
**Ahsan Mahmood** — [aoneahsan.com](https://aoneahsan.com) · [GitHub](https://github.com/aoneahsan) ·
|
|
488
|
+
[LinkedIn](https://linkedin.com/in/aoneahsan) · [aoneahsan@gmail.com](mailto:aoneahsan@gmail.com)
|
|
489
|
+
|
|
490
|
+
<a id="links"></a>
|
|
491
|
+
## 🔗 Links [#](#links)
|
|
492
|
+
|
|
493
|
+
| | |
|
|
494
|
+
|---|---|
|
|
495
|
+
| Documentation | https://capacitor-auth-manager-docs.aoneahsan.com |
|
|
496
|
+
| npm | https://www.npmjs.com/package/capacitor-auth-manager |
|
|
497
|
+
| Repository | https://github.com/aoneahsan/capacitor-auth-manager |
|
|
498
|
+
| Issues | https://github.com/aoneahsan/capacitor-auth-manager/issues |
|
|
499
|
+
| Changelog | https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md |
|
|
500
|
+
| Support the project | https://aoneahsan.com/payment |
|
|
501
|
+
|
|
502
|
+
<a id="keywords"></a>
|
|
503
|
+
## 🏷️ Keywords [#](#keywords)
|
|
504
|
+
|
|
505
|
+
*capacitor · authentication · google-sign-in · oauth · id-token · capacitor-plugin · react · vue · angular*
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "capacitor-auth-manager",
|
|
3
|
-
"version": "2.4.
|
|
3
|
+
"version": "2.4.3",
|
|
4
4
|
"description": "Capacitor + web authentication. Firebase-agnostic native & web Google sign-in (idToken/accessToken) for React, Vue, Angular and vanilla JS — a drop-in alternative to @codetrix-studio/capacitor-google-auth. More providers shipping one at a time.",
|
|
5
5
|
"main": "dist/plugin.cjs.js",
|
|
6
6
|
"module": "dist/esm/index.js",
|
|
@@ -48,10 +48,11 @@
|
|
|
48
48
|
"android/proguard-rules.pro",
|
|
49
49
|
"dist/",
|
|
50
50
|
"ios/Plugin/",
|
|
51
|
+
"scripts/configure.js",
|
|
51
52
|
"CapacitorAuthManager.podspec",
|
|
53
|
+
"README.md",
|
|
52
54
|
"CHANGELOG.md",
|
|
53
|
-
"
|
|
54
|
-
"!**/AGENTS.md"
|
|
55
|
+
"LICENSE"
|
|
55
56
|
],
|
|
56
57
|
"author": {
|
|
57
58
|
"email": "aoneahsan@gmail.com",
|
|
@@ -66,37 +67,24 @@
|
|
|
66
67
|
"bugs": {
|
|
67
68
|
"url": "https://github.com/aoneahsan/capacitor-auth-manager/issues"
|
|
68
69
|
},
|
|
69
|
-
"homepage": "https://
|
|
70
|
+
"homepage": "https://capacitor-auth-manager-docs.aoneahsan.com",
|
|
71
|
+
"funding": "https://aoneahsan.com/payment?project-id=capacitor-auth-manager&project-identifier=capacitor-auth-manager",
|
|
70
72
|
"keywords": [
|
|
71
|
-
"
|
|
73
|
+
"capacitor",
|
|
72
74
|
"authentication",
|
|
75
|
+
"google-sign-in",
|
|
73
76
|
"oauth",
|
|
74
|
-
"
|
|
75
|
-
"
|
|
76
|
-
"microsoft",
|
|
77
|
-
"facebook",
|
|
78
|
-
"github",
|
|
79
|
-
"slack",
|
|
80
|
-
"linkedin",
|
|
81
|
-
"firebase",
|
|
82
|
-
"email-magic-link",
|
|
83
|
-
"sms",
|
|
84
|
-
"email-code",
|
|
85
|
-
"biometric",
|
|
77
|
+
"id-token",
|
|
78
|
+
"capacitor-plugin",
|
|
86
79
|
"react",
|
|
87
80
|
"vue",
|
|
88
|
-
"angular"
|
|
89
|
-
"capacitor",
|
|
90
|
-
"plugin",
|
|
91
|
-
"native",
|
|
92
|
-
"web",
|
|
93
|
-
"pwa",
|
|
94
|
-
"universal"
|
|
81
|
+
"angular"
|
|
95
82
|
],
|
|
96
83
|
"scripts": {
|
|
97
84
|
"build": "npm run clean && npm run tsc && rollup -c rollup.config.mjs",
|
|
98
85
|
"clean": "rimraf ./dist",
|
|
99
86
|
"tsc": "tsc -p tsconfig.build.json",
|
|
87
|
+
"typecheck": "tsc -p tsconfig.build.json --noEmit",
|
|
100
88
|
"watch": "tsc --watch",
|
|
101
89
|
"lint": "eslint .",
|
|
102
90
|
"prettier": "prettier --write .",
|
package/Readme.md
DELETED
|
@@ -1,203 +0,0 @@
|
|
|
1
|
-
# Capacitor Auth Manager
|
|
2
|
-
|
|
3
|
-
Firebase-agnostic **Google authentication** for Capacitor + web — a drop-in alternative to
|
|
4
|
-
`@codetrix-studio/capacitor-google-auth`. One API (`signIn(AuthProvider.GOOGLE)`) returns a Google
|
|
5
|
-
credential `{ idToken, accessToken?, serverAuthCode?, user }` on **web, iOS and Android**; your app feeds
|
|
6
|
-
the `idToken` into Firebase (or anything else). Works with React, Vue, Angular, and vanilla JS.
|
|
7
|
-
|
|
8
|
-
> **Status (2.4.x): Google-first.** The package is being brought to production **one provider at a time**.
|
|
9
|
-
> Right now **Google is enabled** (web + iOS + Android). The other 14 providers' code lives in the repo but
|
|
10
|
-
> is un-registered — calling them throws `AuthErrorCode.PROVIDER_NOT_ENABLED` — and each is re-enabled and
|
|
11
|
-
> verified on device one at a time. See the [changelog](./CHANGELOG.md).
|
|
12
|
-
|
|
13
|
-
## Why this exists
|
|
14
|
-
|
|
15
|
-
For native Google sign-in in a Capacitor app you normally reach for `@codetrix-studio/capacitor-google-auth`.
|
|
16
|
-
This package does the same job (native Google ID token → your Firebase `signInWithCredential`) but is yours
|
|
17
|
-
to maintain, uses the modern **Android Credential Manager** and **GoogleSignIn** SDKs, keeps the **same call
|
|
18
|
-
on every platform**, and stays **Firebase-agnostic** (no `firebase` dependency pulled in).
|
|
19
|
-
|
|
20
|
-
## Install
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npm install capacitor-auth-manager
|
|
24
|
-
# then, for the native plugin:
|
|
25
|
-
npx cap sync
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
`@capacitor/core` is an optional peer — needed only for the native (iOS/Android) plugin. Framework adapters
|
|
29
|
-
(`react` / `vue` / `@angular/core`) are optional peers too; install only what you use.
|
|
30
|
-
|
|
31
|
-
## Provider support
|
|
32
|
-
|
|
33
|
-
| Provider | Web | iOS | Android | Status |
|
|
34
|
-
|---|---|---|---|---|
|
|
35
|
-
| **Google** | ✅ GIS id-token | ✅ GoogleSignIn | ✅ Credential Manager | **Enabled** |
|
|
36
|
-
| Apple, Microsoft, Facebook, GitHub, Slack, LinkedIn, Firebase, Magic-link, SMS, Email/Phone/Username+password, Email-code, Biometric | — | — | — | ⏳ coming, one at a time (`PROVIDER_NOT_ENABLED`) |
|
|
37
|
-
|
|
38
|
-
## Quick start
|
|
39
|
-
|
|
40
|
-
Configure once, then sign in. Use the exported **`AuthProvider` enum** (recommended — typo-safe; the plain
|
|
41
|
-
string `'google'` also works).
|
|
42
|
-
|
|
43
|
-
```ts
|
|
44
|
-
import { auth, AuthProvider } from 'capacitor-auth-manager';
|
|
45
|
-
|
|
46
|
-
auth.configure({
|
|
47
|
-
providers: {
|
|
48
|
-
[AuthProvider.GOOGLE]: {
|
|
49
|
-
clientId: 'YOUR_WEB_OAUTH_CLIENT_ID', // web + Android serverClientId fallback
|
|
50
|
-
serverClientId: 'YOUR_WEB_OAUTH_CLIENT_ID', // REQUIRED on Android to receive an idToken
|
|
51
|
-
iosClientId: 'YOUR_IOS_OAUTH_CLIENT_ID', // iOS (or set GIDClientID in Info.plist)
|
|
52
|
-
},
|
|
53
|
-
},
|
|
54
|
-
persistence: 'local',
|
|
55
|
-
});
|
|
56
|
-
|
|
57
|
-
const result = await auth.signIn(AuthProvider.GOOGLE);
|
|
58
|
-
// The same field is populated on web, iOS and Android:
|
|
59
|
-
const idToken = result.credential.idToken;
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
### Hand the credential to Firebase (identical on every platform)
|
|
63
|
-
|
|
64
|
-
```ts
|
|
65
|
-
import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
|
|
66
|
-
|
|
67
|
-
const result = await auth.signIn(AuthProvider.GOOGLE);
|
|
68
|
-
await signInWithCredential(
|
|
69
|
-
getAuth(),
|
|
70
|
-
GoogleAuthProvider.credential(result.credential.idToken),
|
|
71
|
-
);
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### React
|
|
75
|
-
|
|
76
|
-
```tsx
|
|
77
|
-
import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
|
|
78
|
-
|
|
79
|
-
function LoginButton() {
|
|
80
|
-
const { user, signIn, signOut } = useAuth();
|
|
81
|
-
if (user) return <button onClick={() => signOut()}>Sign out</button>;
|
|
82
|
-
return <button onClick={() => signIn(AuthProvider.GOOGLE)}>Sign in with Google</button>;
|
|
83
|
-
}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
`useAuth()` also returns `isLoading`, `isAuthenticated`, `error`, `refreshToken`, `getIdToken`, and
|
|
87
|
-
`revokeAccess`. Vue (`capacitor-auth-manager/vue`) and Angular (`capacitor-auth-manager/angular`) expose the
|
|
88
|
-
same surface as composables / an injectable `AuthService`; both re-export `AuthProvider`.
|
|
89
|
-
|
|
90
|
-
## What you get back
|
|
91
|
-
|
|
92
|
-
`signIn` resolves to an `AuthResult`:
|
|
93
|
-
|
|
94
|
-
```ts
|
|
95
|
-
{
|
|
96
|
-
user: { uid, email, emailVerified, displayName, photoURL, providerData: [...], metadata: {...} },
|
|
97
|
-
credential: {
|
|
98
|
-
providerId: 'google.com',
|
|
99
|
-
signInMethod: 'google.com',
|
|
100
|
-
idToken?: string, // present on web, iOS, Android
|
|
101
|
-
accessToken?: string, // iOS; web/Android: see notes below
|
|
102
|
-
serverAuthCode?: string, // iOS when serverClientId + offline access; exchange on YOUR server only
|
|
103
|
-
},
|
|
104
|
-
}
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
Per-platform token availability (honest):
|
|
108
|
-
|
|
109
|
-
- **Web** (Google Identity Services id-token flow): returns **`idToken`** only — no `accessToken`. If you
|
|
110
|
-
need to call Google APIs from the browser, use the GIS token client separately.
|
|
111
|
-
- **iOS** (GoogleSignIn): `idToken` + `accessToken` (+ `serverAuthCode` when `serverClientId` is set).
|
|
112
|
-
- **Android** (Credential Manager): returns **`idToken`** reliably. `accessToken` / `serverAuthCode` require
|
|
113
|
-
the separate Google Authorization API and are not returned by the sign-in call (planned).
|
|
114
|
-
|
|
115
|
-
For the Firebase `signInWithCredential` handoff, the **`idToken` is all you need** on every platform.
|
|
116
|
-
|
|
117
|
-
## Native setup
|
|
118
|
-
|
|
119
|
-
### Android
|
|
120
|
-
|
|
121
|
-
1. In Google Cloud / Firebase, create an **Android** OAuth client and add your app's **SHA-1/SHA-256**
|
|
122
|
-
signing fingerprints; create (or reuse) a **Web** OAuth client.
|
|
123
|
-
2. Pass that **Web** client id as `serverClientId` (Credential Manager needs it to return an idToken).
|
|
124
|
-
3. Add your app's `google-services.json` to the Android project as usual.
|
|
125
|
-
4. The device must have a Google account signed in (Credential Manager shows that account chooser).
|
|
126
|
-
|
|
127
|
-
No extra AndroidManifest permissions are required by this plugin.
|
|
128
|
-
|
|
129
|
-
### iOS
|
|
130
|
-
|
|
131
|
-
1. Create an **iOS** OAuth client in Google Cloud.
|
|
132
|
-
2. Add `GIDClientID` (your iOS client id) to `Info.plist`, or pass it as `iosClientId`.
|
|
133
|
-
3. Add the **reversed client id** as a URL scheme in `Info.plist` → `CFBundleURLTypes`
|
|
134
|
-
(e.g. `com.googleusercontent.apps.XXXX`).
|
|
135
|
-
4. For a `serverAuthCode`, also set `serverClientId` (your Web client id).
|
|
136
|
-
|
|
137
|
-
### Capacitor config
|
|
138
|
-
|
|
139
|
-
You can also set the Google options in `capacitor.config` under the plugin block instead of `auth.configure`.
|
|
140
|
-
|
|
141
|
-
## Migrating from `@codetrix-studio/capacitor-google-auth`
|
|
142
|
-
|
|
143
|
-
```ts
|
|
144
|
-
// before
|
|
145
|
-
await GoogleAuth.initialize({ clientId });
|
|
146
|
-
const u = await GoogleAuth.signIn();
|
|
147
|
-
await signInWithCredential(getAuth(), GoogleAuthProvider.credential(u.authentication.idToken));
|
|
148
|
-
|
|
149
|
-
// after
|
|
150
|
-
import { auth, AuthProvider } from 'capacitor-auth-manager';
|
|
151
|
-
auth.configure({ providers: { [AuthProvider.GOOGLE]: { clientId, serverClientId, iosClientId } } });
|
|
152
|
-
const res = await auth.signIn(AuthProvider.GOOGLE);
|
|
153
|
-
await signInWithCredential(getAuth(), GoogleAuthProvider.credential(res.credential.idToken));
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
The id token moves from `result.authentication.idToken` to `result.credential.idToken`. Everything else
|
|
157
|
-
(the native account chooser, the Firebase handoff) behaves the same.
|
|
158
|
-
|
|
159
|
-
## Configuration (`GoogleAuthOptions`)
|
|
160
|
-
|
|
161
|
-
| Option | Where | Purpose |
|
|
162
|
-
|---|---|---|
|
|
163
|
-
| `clientId` | web (required), Android fallback | Web OAuth client id; the id token's `aud`. |
|
|
164
|
-
| `serverClientId` | Android (required for idToken), iOS | Web OAuth client id for Credential Manager / `serverAuthCode`. |
|
|
165
|
-
| `iosClientId` | iOS | iOS OAuth client id (or set `GIDClientID` in Info.plist). |
|
|
166
|
-
| `scopes` | all | Extra OAuth scopes (default `openid email profile`). |
|
|
167
|
-
| `hostedDomain` / `loginHint` | all | Restrict to a Workspace domain / prefill an account. |
|
|
168
|
-
| `filterByAuthorizedAccounts`, `autoSelectEnabled` | Android | Credential Manager UX (returning-user / one-tap auto-select). |
|
|
169
|
-
| `nonce` | web | Bind the request to an id-token `nonce` claim (validated). |
|
|
170
|
-
|
|
171
|
-
## Security & storage
|
|
172
|
-
|
|
173
|
-
- **No secrets are persisted by default.** Short-lived id tokens are re-derived from the Google SDK's silent
|
|
174
|
-
restore rather than written to `localStorage` / `@capacitor/preferences`. Inject a `StorageInterface`
|
|
175
|
-
(ideally Keychain/Keystore-backed) if you need token persistence at rest.
|
|
176
|
-
- The web flow uses the GIS **id-token** flow specifically so **no client secret and no backend** are
|
|
177
|
-
required. A `serverAuthCode` (iOS) must be exchanged on **your** server, never in the browser.
|
|
178
|
-
- The package does not verify id-token signatures in the browser — validate the id token server-side (or via
|
|
179
|
-
Firebase) before trusting its claims.
|
|
180
|
-
|
|
181
|
-
## Caveats
|
|
182
|
-
|
|
183
|
-
- The iOS (Swift) and Android (Java) sources are written to the official SDK contracts but are **not compiled
|
|
184
|
-
in CI**. Validate a new version in **one** app (web + one Android device + one iOS device) before rolling
|
|
185
|
-
out to many apps.
|
|
186
|
-
- Web Google sign-in uses One-Tap / FedCM `prompt()`; if One-Tap is suppressed (cooldown), render Google's
|
|
187
|
-
official button via the provider's `renderButton(element)` escape hatch, or use your own Firebase popup on web.
|
|
188
|
-
|
|
189
|
-
## Contributing & support
|
|
190
|
-
|
|
191
|
-
- [Contributing](./.github/CONTRIBUTING.md) · [Security policy](./.github/SECURITY.md) ·
|
|
192
|
-
[Support](./.github/SUPPORT.md) · [Changelog](./CHANGELOG.md)
|
|
193
|
-
- Docs: https://github.com/aoneahsan/capacitor-auth-manager-docs
|
|
194
|
-
- Author: Ahsan Mahmood — aoneahsan@gmail.com — https://aoneahsan.com
|
|
195
|
-
|
|
196
|
-
## License
|
|
197
|
-
|
|
198
|
-
[MIT](./LICENSE) © 2024–2026 Ahsan Mahmood
|
|
199
|
-
|
|
200
|
-
## Links
|
|
201
|
-
|
|
202
|
-
- npm: https://www.npmjs.com/package/capacitor-auth-manager
|
|
203
|
-
- Repository: https://github.com/aoneahsan/capacitor-auth-manager
|