apple-auth

Data Persistence Requirement

Apple provides the user's name only once: during the very first time the user taps "Sign in with Apple" in your application.

You must store the name in your database immediately during this first interaction.

For all subsequent logins, Apple will only provide a unique ID and the user's email. You should use these to look up the existing user in your database.

To use this library, you must configure several identifiers in your Apple Developer account. This involves three main steps:

1. Create an App ID: Even if you do not have a native iOS or Mac app, you must create an App ID. Ensure that the "Sign in with Apple" capability is checked under the "Capabilities" section.
2. Create a Services ID: This acts as your client_id. During setup, click "configure" on "Sign in with Apple", add your domain in the "Domains" section, and specify your allowed redirect URL. You must verify your domain using the download and verify buttons provided in the Service ID configuration.
3. Create a Key: Go to the "Keys" section and create a new key. Configure it to assign "Sign in with Apple" to your specific App ID. Important: Download the private key file immediately and store it securely; you cannot download it again once it is gone.

The library requires a config directory containing your downloaded private key file and a config.json file. The config.json file must contain the following fields:

• client_id: The "Service ID" created in the Apple Identifiers section.
• team_id: The 10-character code found at the top left of your Apple Developer page.
• redirect_uri: The return URL you registered in the Apple Developer portal.
• key_id: The identifier for the private key you generated.
• scope: The information requested from the user (e.g., email and/or name).

Note: Providing email or name in the scope ensures your app is ready for when Apple fully releases these features, preventing the need for users to re-authorize later.

{
    "client_id": "",
    "team_id": "",
    "redirect_uri": "",
    "key_id": "",
    "scope": ""
}

To get started with Sign in with Apple in your Node.js project, install the apple-auth package using npm:

npm install apple-auth

To troubleshoot failed requests, you can enable a debugging mode. When this mode is active, all failed requests are logged to the console, and error messages will contain more specific details. To enable it, pass an options object with the debug key set to true as the fourth argument when initializing the AppleAuth class.

let auth = new AppleAuth(
  config,
  SECRET_KEY,
  TEXT_METHOD,
  {
    debug: true
  }
);

The AppleAuth instance provides three primary methods to handle the Sign in with Apple flow:

• auth.loginURL(): Generates the Login URL that users must visit to authenticate.
• auth.accessToken(grantCode): Exchanges a received grantCode for an access token.
• auth.refreshToken(refreshToken): Uses a refreshToken to obtain a new access token.

To use the library, instantiate the AppleAuth class. You need to provide a configuration object (loaded from a file) and the path to your .p8 authentication key file.

const fs = require('fs');
const AppleAuth = require('apple-auth');

// Load your configuration file
const config = fs.readFileSync("./config/config");

// Initialize the auth instance with config and the path to your AuthKey.p8
const auth = new AppleAuth(config, './config/AuthKey.p8');

Use the refreshToken(refreshToken) method to obtain a new access token using a previously issued refresh token. This is useful for maintaining a user's session without requiring them to re-authenticate manually.

try {
  const newTokenData = await appleAuth.refreshToken(oldRefreshToken);
  console.log('New Token Data:', newTokenData);
} catch (error) {
  console.error(error);
}

To use the library, instantiate the AppleAuth class. The constructor requires the AppleAuthConfig object, the file path to your private key (privateKeyLocation), the method to read the key (privateKeyMethod), and an optional CustomConfig object.

import AppleAuth from 'apple-auth';

const config = {
  client_id: 'com.example.service',
  team_id: 'TEAMID123',
  redirect_uri: 'https://example.com/callback',
  key_id: 'KEYID123',
  scope: 'name email'
};

const appleAuth = new AppleAuth(
  config, 
  './path/to/private_key.p8', 
  'file', 
  { debug: true }
);

Call loginURL() to generate the authorization URL used to redirect the user to Apple's sign-in page. This method also generates and stores a unique state value to prevent CSRF attacks. You should retrieve this state value using the state getter and verify it when the user is redirected back to your application.

const url = appleAuth.loginURL();
const state = appleAuth.state;

// Redirect the user to 'url' and verify 'state' on callback