Skip to content

apple-sign-in

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

apple-sign-in

README.md

Capacitor Apple Sign-In Plugin

Unofficial Capacitor plugin to sign-in with Apple.1

Features

The Capacitor Apple Sign-In plugin is one of the most complete Apple authentication solutions for Capacitor apps. 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!

Use Cases

The Apple Sign-In plugin is typically used to let users authenticate with their Apple ID, for example:

  • User authentication: Offer Sign in with Apple as a login option in your app on Android, iOS, and Web.
  • Account creation: Request the user's email address and full name during sign-up using the email and full name scopes.
  • Backend integration: Send the authorization code and ID token to your backend to verify the sign-in and create a user session.
  • Secure sign-in flows: Pass a nonce for replay protection and a state value for CSRF protection.

Compatibility

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

Guides

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-apple-sign-in` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

The following examples show how to initialize the plugin and sign in with Apple.

Initialize the plugin

On Android and Web, you must initialize the plugin with your Apple Service ID before calling signIn(...). This method is only available on Android and Web:

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

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

Sign in with Apple

Start the sign-in flow and receive the authorization code and ID token. Use the scopes option to request the user's email address and full name, and pass a nonce for replay protection. The redirectUrl and state options are only available on Android and Web:

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

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

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.

Do I need to call initialize on iOS?

No, the initialize(...) method is only available on Android and Web, where it must be called before signIn(...) to set the Apple Service ID. On iOS, the plugin uses the native AuthenticationServices framework and no initialization is required.

Why are the email and name only returned on the first sign-in on iOS?

On iOS, Apple only provides the user's email address, given name, and family name on the first sign-in; on subsequent sign-ins, these values are null. Make sure to persist this information, for example on your backend, when you receive it for the first time.

Can I use this plugin with Ionic, React, Vue or Angular?

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.

Related Plugins

  • Facebook Sign-In: Sign in with Facebook.
  • Google Sign-In: Sign in with Google.
  • OAuth: Communicate with OAuth 2.0 and OpenID Connect providers.
  • Passkeys: Create and authenticate with passkeys based on the WebAuthn standard.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

Footnotes

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