# Sign in with Apple strategy for Passport

[![Build Status](https://travis-ci.org/growlot/passport-apple-token.svg?branch=master)](https://travis-ci.org/passport-apple-token)
[![NPM version](https://badge.fury.io/js/%40growlot%2Fpassport-apple-token.svg)](https://www.npmjs.com/package/passport-apple-token)
[![Dependencies](https://david-dm.org/growlot/passport-apple-token.svg)](https://david-dm.org/passport-apple-token)

[Passport](http://www.passportjs.org/) strategy for authenticating with [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/).

## Install

    $ npm install passport-apple-token

## Usage

### Create a Service

Before using this module, you must register a service with Apple. You need an Apple Developer Account for this.

- Register a new **App ID**, e.g. `com.example.test`, and enable the "Sign in with Apple" capability.
- Register a new **Services ID**, e.g. `com.example.account`. This is the `clientID` for the module configuration. Configure "Sign in with Apple" for this service and set the **Return URLs**.
- You might need to verify the ownership of the Domain by following the instructions.
- Register a new **Key**, enable "Sign in with Apple" for this key and download it. Its ID is the `keyID`.

### Configure Strategy

The Sign in with Apple authentication strategy authenticates users using an Apple ID and OAuth 2.0 tokens. The strategy options are supplied in the step above. The strategy also requires a `verify` callback, which receives an access token and profile, and calls `cb` providing a user.

```js
passport.use(new AppleStrategy({
    clientID: 'com.example.account', // Services ID
    teamID: '1234567890', // Team ID of your Apple Developer Account
    keyID: 'ABCDEFGHIJ', // Key ID, received from https://developer.apple.com/account/resources/authkeys/list
    key: fs.readFileSync(path.join('path', 'to', 'AuthKey_XYZ1234567.p8')), // Private key, downloaded from https://developer.apple.com/account/resources/authkeys/list
    scope: ['name', 'email'],
    callbackURL: 'https://example.com/auth/apple/callback'
  },
  (accessToken, refreshToken, profile, cb) => {
    User.findOrCreate({ exampleId: profile.id }, (err, user) => {
      return cb(err, user);
    });
  }
));
```

### Authenticate Requests

Use `passport.authenticate()`, specifying the `'apple'` strategy, to authenticate requests. The authorization code is passed via the `code` POST parameter, so your endpoint callback needs to support HTTPS POST and provide the `req.body` property.

For example, as route middleware in an [Express](http://expressjs.com/) application, using `express.urlencoded` to provide `req.body`:

```js
app.get('/auth/apple',
  passport.authenticate('apple'));

app.post('/auth/apple/callback',
  express.urlencoded(),
  passport.authenticate('apple', { failureRedirect: '/login' }),
  (req, res) => {
    // Successful authentication, redirect home.
    res.redirect('/');
  });
```

You can find a complete example at [examples/server.js](examples/server.js).

## FAQ

#### Which fields are provided in the user profile?

Apple currently returns a User ID that is tied to you Team ID. That means, the same Apple ID will result in the same User ID returned for authentication requests done with your Team ID. Other Teams will get a different ID for this User.

Also, if the User wants to, their name and email address is returned:

```js
{ id, name: { firstName, lastName }, email } = profile;
```

*Note that the `name` and `email` properties are only returned on the first login the user*.

## License

[The MIT License](http://opensource.org/licenses/MIT)