passport-apple

Apple's authentication flow involves a POST request to your callback URL. Because browser SameSite policies often prevent cookies (and thus sessions) from being sent with external POST requests, you should redirect the POST request to a GET request using query parameters before passing it to Passport.

// 1. Initial login request
app.get('/apple', passport.authenticate('apple'));

// 2. Handle the POST from Apple: Redirect POST to GET to preserve session/cookies
app.post('/apple/callback', express.urlencoded({ extended: true }), (req, res) => {
  const { body } = req;
  const sp = new URLSearchParams();
  Object.entries(body).forEach(([key, value]) => sp.set(key, String(value)));
  res.redirect(`/v1/auth/apple/callback?${sp.toString()}`);
});

// 3. Handle the GET request (the actual Passport authentication)
const failureRedirect = '/failure';

app.get('/apple/callback', passport.authenticate('apple', {
  successReturnToOrRedirect: '/success',
  failureRedirect,
}), (err, _req, res, _next) => {
  // Handle specific Apple errors
  if (err instanceof Error && (err.name === 'AuthorizationError' || err.name === 'TokenError')) {
    const sp = new URLSearchParams({ error: err.name });
    if ('code' in err && typeof err.code === 'string') sp.set('code', err.code);
    res.redirect(`${failureRedirect}${sp.toString()}`);
    return;
  }

  res.redirect(failureRedirect);
});

To use the strategy, pass a configuration object to AppleStrategy.

Important Note on User Names: Apple only provides the user's name (via req.query.user) during the very first authentication attempt. You must capture and store this in your database immediately. Subsequent logins will only provide a unique ID (sub) and email.

import AppleStrategy from 'passport-apple';
import jsonwebtoken from 'jsonwebtoken';
import assert from 'node:assert';

passport.use(new AppleStrategy({
  clientID: '',
  teamID: '',
  callbackURL: 'https://redirectmeto.com/http://localhost:8080/auth/apple/callback',
  keyID: '',
  privateKeyString: '',
  passReqToCallback: true,
}, async (req, accessToken, refreshToken, idToken, profile, cb) => {
  try {
    const decodedToken = jsonwebtoken.decode(idToken, { json: true });
    assert(decodedToken != null);

    // req.query['user'] contains firstName and lastName ONLY on the first auth
    const firstTimeUser = typeof req.query['user'] === 'string' ? JSON.parse(req.query['user']) : undefined;

    const { sub, email, email_verified } = decodedToken;

    // Implement your user lookup/creation logic here
    const dbUser = await upsertUser({ sub, email, email_verified, firstTimeUser });

    return cb(null, { id: dbUser.id });
  } catch (err) {
    return cb(err);
  }
}));

The AppleStrategy constructor accepts an options object with the following configuration keys:

The AppleClientSecret class is used to generate the JSON Web Token (JWT) required for Apple authentication requests. It signs a token using your Apple Developer private key and specific configuration parameters.

Configuration Object

The constructor requires a config object with the following properties:

• client_id: Your Apple Service ID.
• team_id: Your Apple Developer Team ID.
• redirect_uri: Your configured redirect URI.
• key_id: The Key ID associated with your private key.

Private Key Loading

You can provide the private key in one of two ways:

1. File Path: Pass a string representing the path to the .p8 file as the second argument (privateKeyLocation).
2. String Content: Pass the raw private key string as the second argument (privateKeyLocation) if privateKeyLocation is falsy, or use the third argument (privateKeyString).

Usage

Call the .generate() method to receive a Promise that resolves to the signed JWT string. The token is configured to expire in 180 days (6 months).

const AppleClientSecret = require('./path/to/token');

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

// Option 1: Using a file path
const generator = new AppleClientSecret(config, './AuthKey_ABC123.p8');

// Option 2: Using a raw string
// const generator = new AppleClientSecret(config, null, '-----BEGIN PRIVATE KEY-----\n...');

generator.generate()
  .then(token => console.log('Generated Token:', token))
  .catch(err => console.error('Error:', err));

To implement 'Sign in with Apple', use the AppleStrategy constructor. You must provide configuration options for your Apple Developer credentials and a verify callback function.

Note that the idToken returned to the callback is an encoded string. To access user identity information (like sub), you should use a library like jsonwebtoken to decode it.

In the verify callback, the fourth parameter (often represented as __) is required by the Passport implementation but currently contains no data because Apple does not yet pass profile data within the access token response.

const AppleStrategy = require('passport-apple').Strategy;
const passport = require('passport');

passport.use(new AppleStrategy({
   clientID: "com.example.app", // Services ID
   teamID: "YOUR_TEAM_ID",
   callbackURL: "https://your-app.com/callback",
   keyID: "YOUR_KEY_ID",
   privateKeyLocation: "/path/to/private/key.p8",
   // OR use privateKeyString instead of privateKeyLocation
   passReqToCallback: true
}, function(req, accessToken, refreshToken, idToken, __, cb) {
   // idToken is an encoded JWT. Use jsonwebtoken to decode it.
   // Example: const decoded = jwt.decode(idToken);
   // Use decoded.sub to identify the user.
   cb(null, idToken);
}));