Add Apple as a social connection

Enable Apple as a social connection

To get started, you must enable Apple as a social connection in the Clerk Dashboard.

1. In the Clerk Dashboard, navigate to the SSO connections⁠ page.
2. Select the Add connection button, and select For all users.
3. In the Choose provider dropdown, select Apple.
4. Ensure that both Enable for sign-up and sign-in and Use custom credentials are toggled on.
5. (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.

Get your Apple Team ID

The Apple Team ID is required for web based OAuth 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⁠.
2. Under Certificates, IDs and Profiles, select Identifiers.
3. In the dropdown near the top-right of the page, select the App IDs option from the list.
4. Next to Identifiers at the top of the page, select the plus icon (+) to register a new identifier.
5. On the Register a new identifier page, select App IDs, then select Continue.
6. 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.
7. 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.
8. 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.
9. 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.

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.
2. In the dropdown near the top-right of the page, select the Services IDs option from the list.
3. Next to Identifiers at the top of the page, select the plus icon (+) to register a new identifier.
4. On the Register new identifier page, select Services IDs, then select Continue. You'll be redirected to the Register a Services ID page.
5. 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.
6. In the confirmation view, select Register.
7. After the registration is finished, select the newly-created Services ID. Ensure the Sign In with Apple box is enabled and select Configure.
8. Under Primary App ID, select the App ID you created in the previous step.
9. 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.
10. Select Next. You'll be redirect to the Confirm your web authentication configuration screen.
11. Select Done. You'll be taken back to the Edit your Services ID Configuration page.
12. Select Continue. You'll be taken to the confirmation page.
13. 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.

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.
2. In the sidebar, select Keys.
3. Next to Keys at the top of the page, select the plus icon (+) to register a new key.
4. 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.
5. 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.
6. 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.
7. Save the Key ID value as you'll need to supply it to Clerk later.
8. 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).
9. Select Done.

Configure Email Source for Apple Private Relay

This step is required for web based OAuth flows only.

Apple provides a privacy feature called Hide My Email⁠, 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.

To be able to send emails properly to users with hidden addresses, you must configure an additional setting in the Apple Developer portal.

1. Return to the Certificates, Identifiers & Profiles page.
2. In the sidebar, select Services.
3. 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.
4. Next to Email sources at the top of the page, select the plus icon (+) to add a new Email Source.
5. 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.
6. Select Next. You'll be taken to the confirmation page.
7. Select Register.
8. 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.

For more info about Apple's Private Relay service, refer to the following documentation:

• https://support.apple.com/en-us/HT210425#hideemail⁠
• https://help.apple.com/developer-account/?lang=en#/devf822fb8fc⁠

Get your Apple Bundle ID

The Apple Bundle ID is required for native OAuth flows (iOS, macOS, watchOS, tvOS).

You can find your Apple Bundle ID in the list of app IDs or manually set it up.

1. Navigate to the Apple Developer portal⁠.
2. Under Certificates, IDs and Profiles, select Identifiers.
3. In the dropdown near the top-right of the page, select the App IDs option from the list.
4. 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.
5. Next to Identifiers at the top of the page, select the plus icon (+) to register a new identifier.
6. On the Register a new identifier page, select App IDs, then select Continue.
7. 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.
8. 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.
9. 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.
10. Finally, select Register.

Connect your Apple app to your Clerk app

By now, you should have the following values saved from the Apple Developer portal:

• Apple Team ID
• Apple Services ID
• Apple Key ID
• Apple Private Key file
• Apple Bundle ID (for native flows)

Connect your Apple app to your Clerk app by adding these values to the Clerk Dashboard.

1. Navigate back to the tab where the Clerk Dashboard and your Apple configuration modal is open.
2. Add all the corresponding fields depending on your desired flow. For the Apple Private Key file, open it with a text editor and just copy/paste the contents.
3. Select Add connection.

Test your OAuth

The simplest way to test your OAuth is to visit your Clerk application's Account Portal, which is available for all Clerk applications out-of-the-box.

1. In the Clerk Dashboard, navigate to the Account Portal⁠ page.
2. Next to the Sign-in URL, select Visit. The URL should resemble:
   • For development – https://your-domain.accounts.dev/sign-in
   • For production – https://accounts.your-domain.com/sign-in
3. On the sign-in page, you should see Apple as an option. Use it to sign in with your Apple account.