@capawesome/capacitor-apple-sign-in

Unofficial Capacitor plugin to sign-in with Apple.[^1]

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:

1. Open your app target in Xcode.
2. Go to the Signing & Capabilities tab.
3. 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;
};

API

• initialize(...)
• signIn(...)
• Interfaces
• Enums

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

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

What's the difference between this plugin and other Apple Sign-In plugins?

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.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Apple Inc. or any of their affiliates or subsidiaries.