@logto/connector-apple 1.0.3 → 1.2.0

package/README.md

@@ -4,12 +4,13 @@ The official Logto connector for Apple social sign-in.
 
 **Table of contents**
 
-- [Apple connector](#apple-connector)
-  - [Get started](#get-started)
-    - [Enable Sign in with Apple for your app](#enable-sign-in-with-apple-for-your-app)
-    - [Create an identifier](#create-an-identifier)
-    - [Enable Sign in with Apple for your identifier](#enable-sign-in-with-apple-for-your-identifier)
-  - [Test Apple connector](#test-apple-connector)
+- [Get started](#get-started)
+  - [Enable Sign in with Apple for your app](#enable-sign-in-with-apple-for-your-app)
+  - [Create an identifier](#create-an-identifier)
+  - [Enable Sign in with Apple for your identifier](#enable-sign-in-with-apple-for-your-identifier)
+- [Configure scope](#configure-scope)
+  - [Pitfalls of configuring scope](#pitfalls-of-configuring-scope)
+- [Test Apple connector](#test-apple-connector)
 
 ## Get started
 
@@ -30,7 +31,7 @@ You need to enroll [Apple Developer Program](https://developer.apple.com/program
 
 You can do it via Xcode -> Project settings -> Signing & Capabilities, or visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/bundleId).
 
-![Enable Sign in with Apple](/packages/connector-apple/docs/enable-sign-in-with-apple-in-xcode.png)
+![Enable Sign in with Apple](/packages/connectors/connector-apple/docs/enable-sign-in-with-apple-in-xcode.png)
 
 See the "Enable an App ID" section in [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/configuring_your_environment_for_sign_in_with_apple) for more info.
 
@@ -45,13 +46,13 @@ See the "Enable an App ID" section in [Apple official docs](https://developer.ap
 
 Click the identifier you just created. Check "Sign in with Apple" on the details page and click "Configure".
 
-![Enable Sign in with Apple](/packages/connector-apple/docs/enable-sign-in-with-apple.png)
+![Enable Sign in with Apple](/packages/connectors/connector-apple/docs/enable-sign-in-with-apple.png)
 
 In the opening modal, select the App ID you just enabled Sign in with Apple.
 
 Enter the domain of your Logto instance without protocol and port, e.g., `your.logto.domain`; then enter the "Return URL" (i.e., Redirect URI), which is the Logto URL with `/callback/${connector_id}`, e.g., `https://your.logto.domain/callback/apple-universal`. You can get the randomly generated `connector_id` after creating Apple connector in Admin Console.
 
-![domain-and-url](/packages/connector-apple/docs/domain-and-url.png)
+![domain-and-url](/packages/connectors/connector-apple/docs/domain-and-url.png)
 
 Click "Next" then "Done" to close the modal. Click "Continue" on the top-right corner, then click "Save" to save your configuration.
 
@@ -61,11 +62,23 @@ Click "Next" then "Done" to close the modal. Click "Continue" on the top-right c
 > 
 > If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS.
 
+## Configure scope
+
+To get user's email from Apple, you need to configure the scope to include `email`. For both email and name, you can use `name email` as the scope. See [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113) for more info.
+
 > ℹ️ **Note**
 > 
-> This connector doesn't support customizing `scope` (e.g., name, email) yet since Apple requires `form_post` response mode when `scope` is not empty, which is incompatible with the current connector design.
-> 
-> We'll figure out this later.
+> The user may choose to hide their email address from your app. In this case, you will not be able to retrieve the real email address. An email address like `random@privaterelay.appleid.com` will be returned instead.
+
+### Pitfalls of configuring scope
+
+If you have configured your app to request users' email addresses after they have already signed in with Apple, you will not be able to retrieve the email addresses for those existing users, even if they sign in again using Apple ID. To address this, you need to instruct your users to visit the [Apple ID account management page](https://appleid.apple.com/account/manage) and remove your application from the "Sign in with Apple" section. This can be done by selecting "Stop using Apple Sign In" on your app's detail page.
+
+For instance, if your app requests both the users' email and name (`email name` scope), the consent page that new users see during their first sign-in should look similar to this:
+
+![Sign in with Apple consent page](/packages/connectors/connector-apple/docs/sign-in-with-apple-consent-page.png)
+
+See developer discussion [here](https://forums.developer.apple.com/forums/thread/132223).
 
 ## Test Apple connector
 

package/lib/constant.d.ts

@@ -1,8 +1,7 @@
 import type { ConnectorMetadata } from '@logto/connector-kit';
 export declare const issuer = "https://appleid.apple.com";
-export declare const authorizationEndpoint: string;
-export declare const accessTokenEndpoint: string;
-export declare const jwksUri: string;
-export declare const scope = "";
+export declare const authorizationEndpoint = "https://appleid.apple.com/auth/authorize";
+export declare const accessTokenEndpoint = "https://appleid.apple.com/auth/token";
+export declare const jwksUri = "https://appleid.apple.com/auth/keys";
 export declare const defaultMetadata: ConnectorMetadata;
 export declare const defaultTimeout = 5000;

package/lib/index.js

@@ -2,12 +2,12 @@ import { ConnectorPlatform, ConnectorConfigFormItemType, ConnectorType, validate
 import * as crypto from 'node:crypto';
 import crypto__default, { KeyObject, createPrivateKey, createPublicKey, constants, createSecretKey } from 'node:crypto';
 import { z } from 'zod';
-import * as http from 'node:http';
-import * as https from 'node:https';
-import { once } from 'node:events';
 import { Buffer as Buffer$1 } from 'node:buffer';
 import * as util from 'node:util';
 import { promisify } from 'node:util';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { once } from 'node:events';
 
 // https://github.com/facebook/jest/issues/7547
 const assert = (value, error) => {
@@ -1204,8 +1204,6 @@ function createRemoteJWKSet(url, options) {
 const issuer = 'https://appleid.apple.com';
 const authorizationEndpoint = `${issuer}/auth/authorize`;
 const jwksUri = `${issuer}/auth/keys`;
-// Note: only support fixed scope for v1.
-const scope = ''; // Note: `openid` is required when adding more scope(s)
 const defaultMetadata = {
     id: 'apple-universal',
     target: 'apple',
@@ -1230,18 +1228,50 @@ const defaultMetadata = {
             key: 'clientId',
             type: ConnectorConfigFormItemType.Text,
             required: true,
-            label: 'Client ID',
-            placeholder: '<client-id>',
+            label: 'Identifier',
+            placeholder: '<your-registered-identifier>',
+        },
+        {
+            key: 'scope',
+            type: ConnectorConfigFormItemType.Text,
+            required: false,
+            label: 'Scope',
+            placeholder: 'email name',
         },
     ],
 };
 
 const appleConfigGuard = z.object({
     clientId: z.string(),
+    scope: z.string().optional(),
+});
+const stringToJson = () => z.string().transform((value, ctx) => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return JSON.parse(value);
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
+        return z.NEVER;
+    }
 });
 // https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/configuring_your_webpage_for_sign_in_with_apple#3331292
+// https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113
 const dataGuard = z.object({
     id_token: z.string(),
+    user: stringToJson()
+        .pipe(z
+        .object({
+        name: z
+            .object({
+            firstName: z.string(),
+            lastName: z.string(),
+        })
+            .partial(),
+        email: z.string(),
+    })
+        .partial())
+        .optional(),
 });
 
 const generateNonce = () => generateStandardId();
@@ -1252,12 +1282,12 @@ const getAuthorizationUri = (getConfig) => async ({ state, redirectUri }, setSes
     const queryParameters = new URLSearchParams({
         client_id: config.clientId,
         redirect_uri: redirectUri,
-        scope,
+        scope: config.scope ?? '',
         state,
         nonce,
         // https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113
         response_type: 'code id_token',
-        response_mode: 'fragment',
+        response_mode: 'form_post',
     });
     assert(setSession, new ConnectorError(ConnectorErrorCodes.NotImplemented, {
         message: "'setSession' is not implemented.",
@@ -1266,7 +1296,7 @@ const getAuthorizationUri = (getConfig) => async ({ state, redirectUri }, setSes
     return `${authorizationEndpoint}?${queryParameters.toString()}`;
 };
 const getUserInfo = (getConfig) => async (data, getSession) => {
-    const { id_token: idToken } = await authorizationCallbackHandler(data);
+    const { id_token: idToken, user } = await authorizationCallbackHandler(data);
     if (!idToken) {
         throw new ConnectorError(ConnectorErrorCodes.SocialIdTokenInvalid);
     }
@@ -1296,6 +1326,14 @@ const getUserInfo = (getConfig) => async (data, getSession) => {
         }
         return {
             id: payload.sub,
+            // The `user` object is only available at the first sign-in. Didn't find this in Apple's
+            // docs but it seems to be the case. Fallback to the `email` field in the ID token just in
+            // case.
+            // See desperate developer discussion here:
+            // https://forums.developer.apple.com/forums/thread/132223
+            email: user?.email ??
+                (payload.email && payload.email_verified === true ? String(payload.email) : undefined),
+            name: [user?.name?.firstName, user?.name?.lastName].filter(Boolean).join(' ') || undefined,
         };
     }
     catch {

package/lib/mock.d.ts

@@ -1,4 +1,4 @@
 export declare const mockedConfig: {
     clientId: string;
-    clientSecret: string;
+    scope: string;
 };

package/lib/types.d.ts

@@ -1,16 +1,52 @@
 import { z } from 'zod';
 export declare const appleConfigGuard: z.ZodObject<{
     clientId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     clientId: string;
+    scope?: string | undefined;
 }, {
     clientId: string;
+    scope?: string | undefined;
 }>;
 export type AppleConfig = z.infer<typeof appleConfigGuard>;
 export declare const dataGuard: z.ZodObject<{
     id_token: z.ZodString;
+    user: z.ZodOptional<z.ZodPipeline<z.ZodEffects<z.ZodString, z.ZodType<JSON, z.ZodTypeDef, JSON>, string>, z.ZodObject<{
+        name: z.ZodOptional<z.ZodObject<{
+            firstName: z.ZodOptional<z.ZodString>;
+            lastName: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            firstName?: string | undefined;
+            lastName?: string | undefined;
+        }, {
+            firstName?: string | undefined;
+            lastName?: string | undefined;
+        }>>;
+        email: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: {
+            firstName?: string | undefined;
+            lastName?: string | undefined;
+        } | undefined;
+        email?: string | undefined;
+    }, {
+        name?: {
+            firstName?: string | undefined;
+            lastName?: string | undefined;
+        } | undefined;
+        email?: string | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     id_token: string;
+    user?: {
+        name?: {
+            firstName?: string | undefined;
+            lastName?: string | undefined;
+        } | undefined;
+        email?: string | undefined;
+    } | undefined;
 }, {
     id_token: string;
+    user?: string | undefined;
 }>;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@logto/connector-apple",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Apple web connector implementation.",
   "dependencies": {
-    "@logto/connector-kit": "^2.0.0",
-    "@logto/shared": "^3.0.0",
+    "@logto/connector-kit": "^2.1.0",
+    "@logto/shared": "^3.1.0",
     "jose": "^5.0.0"
   },
   "main": "./lib/index.js",
@@ -19,7 +19,7 @@
     "logo-dark.svg"
   ],
   "engines": {
-    "node": "^18.12.0"
+    "node": "^20.9.0"
   },
   "eslintConfig": {
     "extends": "@silverhand",