Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(/social-connections/apple) update guide #1619

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

(/social-connections/apple) update guide #1619

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
400fbb1
WIP
alexisintech Oct 9, 2024
0586a58
wip
alexisintech Oct 28, 2024
a09aa1f
wip
alexisintech Oct 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 33 additions & 35 deletions docs/authentication/social-connections/apple.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
---

<TutorialHero
Expand All @@ -17,102 +17,100 @@ description: Learn how to allow users to sign into your Clerk app with their App
}
]}
>
- 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
</TutorialHero>

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

For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs. For **web based flows**, no other configuration is needed. For **native sign-in flows**, you must provide your app's [Bundle ID](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).

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).

<Steps>
### 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.

1. You should be back at the **Identifiers** page.
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.<INSERT-YOUR-DOMAIN>.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.

1. You should be back at the **Identifiers** page.
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.

Expand All @@ -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: `[email protected]`.
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:

Expand All @@ -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
Expand All @@ -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:
Expand Down
Loading