@capawesome/capacitor-apple-sign-in¶

Unofficial Capacitor plugin to sign-in with Apple.¹

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Features¶

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

🖥️ Cross-platform: Supports Android, iOS, and Web.
🍎 Native Sign-In: Uses native AuthenticationServices on iOS.
🌐 WebView OAuth: Implements Apple OAuth flow on Android without external dependencies.
📧 Scope support: Request email and full name on all platforms.
🔐 Nonce & state: Supports nonce for replay protection and state for CSRF protection.
🪶 Lightweight: Just a single dependency and zero unnecessary bloat.
🤝 Compatibility: Compatible with the Google Sign-In and OAuth plugins.
📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.

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

Compatibility¶

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

Guides¶

How to Sign In with Apple using Capacitor

Installation¶

npm install @capawesome/capacitor-apple-sign-in
npx cap sync

iOS¶

Add the Sign in with Apple capability to your app in Xcode:

Open your app target in Xcode.
Go to the Signing & Capabilities tab.
Click + Capability and add Sign in with Apple.

Web¶

The plugin loads the Apple JS SDK automatically. Make sure you have configured your Apple Service ID with the correct redirect URL and web domain in the Apple Developer Portal.

Configuration¶

No configuration required for this plugin.

Usage¶

import { AppleSignIn, SignInScope } from '@capawesome/capacitor-apple-sign-in';

const initialize = async () => {
  await AppleSignIn.initialize({
    clientId: 'com.example.app.signin',
  });
};

const signIn = async () => {
  const result = await AppleSignIn.signIn({
    scopes: [SignInScope.Email, SignInScope.FullName],
    redirectUrl: 'https://example.com/callback',
    nonce: 'random-nonce',
    state: 'random-state',
  });
  return result;
};

initialize(...)¶

initialize(options: InitializeOptions) => Promise<void>

Initialize the plugin.

This method must be called before signIn() on Android and Web.

Only available on Android and Web.

Param	Type
`options`	`InitializeOptions`

Since: 0.1.0

signIn(options?: SignInOptions | undefined) => Promise<SignInResult>

Sign in with Apple.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

Since: 0.1.0

Interfaces¶

InitializeOptions¶

Prop	Type	Description	Since
`clientId`	`string`	The Apple Service ID to use for sign-in.	0.1.0

SignInResult¶

Prop	Type	Description	Since
`authorizationCode`	`string`	The authorization code.	0.1.0
`idToken`	`string`	The ID token (JWT).	0.1.0
`user`	`string`	The stable Apple user identifier. On Android and Web, this is decoded from the JWT `sub` claim.	0.1.0
`email`	`string \| null`	The user's email address. On iOS, this is only provided on the first sign-in.	0.1.0
`givenName`	`string \| null`	The user's given name. On iOS, this is only provided on the first sign-in.	0.1.0
`familyName`	`string \| null`	The user's family name. On iOS, this is only provided on the first sign-in.	0.1.0
`state`	`string`	The state value from the sign-in request. Only available on Android and Web.	0.1.0
`realUserStatus`	`RealUserStatus`	The real user status. Only available on iOS.	0.1.0

SignInOptions¶

Prop	Type	Description	Since
`redirectUrl`	`string`	The OAuth redirect URL to use for sign-in. Only available on Android and Web.	0.1.0
`scopes`	`SignInScope[]`	The scopes to request during sign-in.	0.1.0
`nonce`	`string`	A nonce for replay protection.	0.1.0
`state`	`string`	A state value for CSRF protection. Only available on Android and Web.	0.1.0

Enums¶

RealUserStatus¶

Members	Value	Description	Since
`LikelyReal`	`'LIKELY_REAL'`	The user appears to be a real person.	0.1.0
`Unknown`	`'UNKNOWN'`	The system can't determine whether the user is a real person.	0.1.0
`Unsupported`	`'UNSUPPORTED'`	The real user status is not supported on this platform.	0.1.0

SignInScope¶

Members	Value	Description	Since
`Email`	`'EMAIL'`	Request the user's email address.	0.1.0
`FullName`	`'FULL_NAME'`	Request the user's full name.	0.1.0

Security¶

This plugin handles the OAuth flow and returns tokens to your app. To keep your integration secure, be aware of the following:

Server-side token verification is required. The idToken (JWT) is not verified client-side. Your backend must verify the JWT signature using Apple's public keys before trusting any claims (e.g. user, email). Never use client-side token data for authorization decisions without server-side verification.
Validate the state parameter. The plugin passes the state value through to the result but does not validate it. Your app must compare the returned state against the value it originally sent to protect against CSRF attacks.
Android uses a WebView-based OAuth flow. Unlike iOS (which uses native AuthenticationServices), the Android implementation renders Apple's sign-in page in a WebView. Unlike a system browser flow, the WebView is controlled by the app and has access to page content. Ensure your redirectUrl uses HTTPS and points to a domain you control.

FAQ¶

This plugin is purpose-built for Apple Sign-In and focuses on providing a clean and modern API with the latest platform features. Here are some of the key differences:

Cross-platform: Supports Android, iOS, and Web.
Lightweight: No unnecessary dependencies. Just Apple Sign-In, nothing else.
No deprecated APIs: Uses the latest platform APIs (AuthenticationServices on iOS).
Scope support: Request email and full name on all platforms.
Error codes: Provides typed error codes for proper error handling.

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by Apple Inc. or any of their affiliates or subsidiaries. ↩