diff --git a/docs/authentication/social-connections/apple.mdx b/docs/authentication/social-connections/apple.mdx index e7f69e4475..2d30fdc337 100644 --- a/docs/authentication/social-connections/apple.mdx +++ b/docs/authentication/social-connections/apple.mdx @@ -1,6 +1,6 @@ --- title: Add Apple as a social connection -description: Learn how to allow users to sign into your Clerk app with their Apple ID using OAuth. +description: Learn how to allow users to sign up and sign in to your Clerk app with their Apple ID using OAuth. --- - - Use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) to authenticate users with OAuth in your apps and websites. + - Use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) to authenticate users with OAuth -Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) allows your users to sign in and sign up to your Clerk application with their Apple ID. +Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) allows your users to sign in and sign up to your Clerk app with their Apple ID. ## Configure for your development instance @@ -28,55 +28,53 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a To configure your development instance, follow these steps: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the **Add connection** button, and select **For all users**. +1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Apple**. 1. Then, - - For **web based flows**, select **Add connection**. + - For **web-based flows**, select **Add connection**. - For **native sign-in flows**, enable **Use custom credentials** and provide the **Apple Bundle ID**. If you're unsure about how to find this value, see the [Get your Apple Bundle ID](#get-your-apple-bundle-id) section. ## Configure for your production instance -In _production instances_, you must provide custom credentials. +For _production instances_, you must provide custom credentials. -For **web based browser originated flows**, you need to generate and provide your own **Apple Services ID**, **Apple Private Key**, **Apple Team ID**, and **Apple Key ID** using your Apple Developer account. +For **web based browser originated flows**, you must generate and provide your own **Apple Services ID**, **Apple Private Key**, **Apple Team ID**, and **Apple Key ID** using your Apple Developer account. For **native sign in flows** (iOS, macOS, watchOS, tvOS), you must _at least_ provide your app's **Apple Bundle ID**. For better results, it's recommended to also provide the web based flow fields. -To configure your production instance, follow these steps: +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Apple Developer dashboard](https://developer.apple.com/account). ### Enable Apple as a social connection To get started, you must enable Apple as a social connection in your Clerk Dashboard. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For all users**. + 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Apple**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. (For web based flows) Save the **Email Source for Apple Private Email Relay** and **Return URL** values somewhere secure, as you'll need to supply them to Apple later. Leave this page and modal open. + 1. (For web-based flows) Save the **Email Source for Apple Private Email Relay** and **Return URL** values somewhere secure, as you'll supply them to Apple later. Keep this page and modal open. ### Get your Apple Team ID - The **Apple Team ID** is _required_ for web based OAuth flows and _recommended_ for native app flows. + The **Apple Team ID** is _required_ for web-based flows and _recommended_ for native app flows. To get your **Apple Team ID**, you must create a new **App ID** in the Apple Developer portal. - 1. In another tab, navigate to the [Apple Developer portal](https://developer.apple.com/account). - 1. Under **Certificates, IDs and Profiles**, select **Identifiers**. - 1. In the dropdown near the top-right of the page, select the **App IDs** option from the list. + 1. On a separate page, navigate to the [Apple Developer dashboard](https://developer.apple.com/account). + 1. Under **Certificates, IDs and Profiles**, select [**Identifiers**](https://developer.apple.com/account/resources/identifiers/list). + 1. In the top-right, select the dropdown and select **App IDs**. 1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. 1. On the **Register a new identifier** page, select **App IDs**, then select **Continue**. - 1. On the next page, you'll be prompted to **Select a type** for your application. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page. - 1. Fill in a description for your **App ID** and a **Bundle ID**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page. - 1. At the top of the page, you'll see your **App ID Prefix**. Save this value somewhere secure, as you'll need it to configure your Clerk app. This is your **App Team ID** in Clerk. + 1. On the next page, you'll be prompted to **Select a type** for your app. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page. + 1. Fill in a description for your **App ID** and a **Bundle ID**. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page. + 1. At the top of the page, you'll see your **App ID Prefix**. Save this value somewhere secure. This is your **App Team ID** in Clerk. 1. Finally, select **Register**. ### Get your Apple Services ID - The **Apple Services ID** is _required_ for web based OAuth flows and _recommended_ for native app flows. + The **Apple Services ID** is _required_ for web-based flows and _recommended_ for native app flows. To get your **Apple Services ID**, you must create a new **Services ID** in the Apple Developer portal. @@ -84,19 +82,19 @@ To configure your production instance, follow these steps: 1. In the dropdown near the top-right of the page, select the **Services IDs** option from the list. 1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. 1. On the **Register new identifier** page, select **Services IDs**, then select **Continue**. You'll be redirected to the **Register a Services ID** page. - 1. Add a description for your **Services ID**, and set an **Identifier**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Save the **Identifier** value somewhere secure, as you'll need it to configure your Clerk app. This is your **Services ID** in Clerk. Finally, select **Continue**. + 1. Add a description for your **Services ID**, and set an **Identifier**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Save the **Identifier** value somewhere secure. This is your **Services ID** in Clerk. Finally, select **Continue**. 1. In the confirmation view, select **Register**. 1. After the registration is finished, select the newly-created **Services ID**. Ensure the **Sign In with Apple** box is enabled and select **Configure**. 1. Under **Primary App ID**, select the **App ID** you created in the previous step. 1. Under **Domains and subdomains**, add your `clerk..com` domain. Under **Return URLS**, add the **Return URL** value you saved from the Clerk Dashboard. For example, if your domain is `myapp.com`, then you would add `clerk.myapp.com` to **Domains and subdomains** and `https://clerk.myapp.com/v1/oauth_callback` to **Return URLS**. - 1. Select **Next**. You'll be redirect to the **Confirm your web authentication configuration** screen. - 1. Select **Done**. You'll be taken back to the **Edit your Services ID Configuration** page. - 1. Select **Continue**. You'll be taken to the confirmation page. + 1. Select **Next**. You'll be redirected to the **Confirm your web authentication configuration** screen. + 1. Select **Done**. You'll be redirected to the **Edit your Services ID Configuration** page. + 1. Select **Continue**. You'll be redirected to the confirmation page. 1. Select **Save**. ### Get your Apple Private Key and Key ID - The **Apple Private Key** and **Key ID** are _required_ for web based OAuth flows and _recommended_ for native app flows. + The **Apple Private Key** and **Key ID** are _required_ for web-based flows and _recommended_ for native app flows. To get your **Apple Private Key** and **Key ID**, you must create a new **Key** in the Apple Developer portal. @@ -104,15 +102,15 @@ To configure your production instance, follow these steps: 1. In the sidebar, select **Keys**. 1. Next to **Keys** at the top of the page, select the plus icon (+) to register a new key. 1. On the **Register a New Key** page, add a **Key Name** and ensure the **Sign In with Apple** box is enabled and select **Configure**. You'll be redirected to the **Configure Key** page. - 1. Under **Primary App ID**, select the **App ID** you created in the first step of this guide. Then select **Save**. You'll be taken back to the previous **Register a New Key** page. + 1. Under **Primary App ID**, select the **App ID** you created in the first step of this guide. Then select **Save**. You'll be redirected to the previous **Register a New Key** page. 1. Select **Continue** and you'll be presented with the final confirmation screen. Verify that **Sign in with Apple** is checked and select **Register**. You'll be redirected to the **Download Your Key** page. - 1. Save the **Key ID** value as you'll need to supply it to Clerk later. + 1. Save the **Key ID** value somewhere secure as you'll supply it to Clerk later. 1. Download the private key as a file (as the instructions point out, be sure to backup the key in a secure place as it cannot be redownloaded later). 1. Select **Done**. ### Configure Email Source for Apple Private Relay - This step is _required_ for web based OAuth flows only. + This step is _required_ for web-based flows only. Apple provides a privacy feature called [Hide My Email](https://support.apple.com/en-us/HT210425#hideemail), in which users can sign in to your app with Apple without revealing their real email addresses. Instead, your instance will receive an app-specific email address that will nevertheless forward any emails to the real user's address. @@ -123,11 +121,11 @@ To configure your production instance, follow these steps: 1. Under **Sign in with Apple for Email Communication**, select **Configure**. You'll be redirected to the **Configure Sign in with Apple for Email Communication** page. 1. Next to **Email sources** at the top of the page, select the plus icon (+) to add a new **Email Source**. 1. In the **Register your email sources** modal that opened, under **Email Addresses**, add the **Email Source for Apple Private Email Relay** value that you saved from the Clerk Dashboard. It should look something like this: `bounces+00000000@clkmail.myapp.com`. - 1. Select **Next**. You'll be taken to the confirmation page. + 1. Select **Next**. You'll be redirected to the confirmation page. 1. Select **Register**. 1. On the completion page, select **Done**. - After this, you should now see the email address added to the list, and it should be marked as verified with a green check icon. If it does not appear as verified yet, DNS propagation may take some time to complete so wait before trying to select the **Reverify SPF** button. + After this, you should now see the email address added to the list, and it should be marked as verified with a green check icon. If it does not appear as verified yet, DNS propagation may take some time to complete so wait before trying to select **Reverify SPF**. For more info about Apple's Private Relay service, refer to the following documentation: @@ -146,9 +144,9 @@ To configure your production instance, follow these steps: 1. If you've already set up your project in XCode, your Bundle ID should be already registered. Otherwise, follow the steps below to create a new identifier. 1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. 1. On the **Register a new identifier** page, select **App IDs**, then select **Continue**. - 1. On the next page, you'll be prompted to **Select a type** for your application. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page. + 1. On the next page, you'll be prompted to **Select a type** for your app. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page. 1. Fill in a description for your **App ID** and a **Bundle ID**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page. - 1. At the top of the page, you'll see your **Bundle ID**. Save this value somewhere secure, as you'll need it to configure your Clerk app. This is your **Apple Bundle ID** in Clerk. + 1. At the top of the page, you'll see your **Bundle ID**. Save this value somewhere secure. This is your **Apple Bundle ID** in Clerk. 1. Finally, select **Register**. ### Connect your Apple app to your Clerk app @@ -169,7 +167,7 @@ To configure your production instance, follow these steps: ### Test your OAuth - The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. + The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box. 1. In the top navigation of the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal), select **Configure.** Then in the sidebar, select **Account Portal** 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: