Add Apple as a social connection

Enable Apple as a social connection

1. In the Clerk Dashboard, navigate to the SSO Connections⁠ page.
2. Select Add connection 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 provide them to Apple later. Keep this page and modal open.

Get your Apple Team ID

The Apple Team ID is required for web-based flows and recommended for native app flows.

To get your Apple Team ID, create a new App ID in the Apple Developer portal by following these steps:

1. On a separate page, navigate to the Apple Developer dashboard⁠.
2. Under Certificates, IDs and Profiles, select Identifiers⁠.
3. In the top-right, select the dropdown and select App IDs.
4. Next to Identifiers at the top of the page, select the plus icon (+) to register a new identifier. You'll be redirected to the Register a new identifier page.
5. Select App IDs, then select Continue.
6. 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.
7. 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.
8. At the top of the page, you'll see your App ID Prefix. Save this value somewhere secure. This is your Apple Team ID in Clerk.
9. Finally, select Register. You'll be redirected to the Identifiers page.

Get your Apple Services ID

The Apple Services ID is required for web-based flows and recommended for native app flows.

To get your Apple Services ID, create a new Services ID in the Apple Developer portal.

1. On the Identifiers page, in the dropdown near the top-right of the page, select the Services IDs option from the list.
2. Next to Identifiers at the top of the page, select the plus icon (+) to register a new identifier. You'll be redirected to the Register a new identifier page.
3. Select Services IDs, then select Continue. You'll be redirected to the Register a Services ID page.
4. Add a description for your Services ID, and set an Identifier. Save the Identifier value somewhere secure. This is your Apple Services ID in Clerk. Finally, select Continue.
5. In the confirmation view, select Register.
6. After the registration is finished, select the newly-created Services ID. Ensure the Sign In with Apple box is enabled and select Configure.
7. Under Primary App ID, select the App ID you created in the previous step.
8. Under Domains and Subdomains, add your Clerk Frontend API URL without the protocol. For example, if your domain is https://myapp.com, then your Frontend API URL is https://clerk.myapp.com, and you would add clerk.myapp.com to Domains and Subdomains.
9. Under Return URLS, add the Return URL value you saved from the Clerk Dashboard.
10. Select Next. You'll be redirected to the Confirm your web authentication configuration screen.
11. Select Done. You'll be redirected to the Edit your Services ID Configuration page.
12. Select Continue. You'll be redirected to the confirmation page.
13. Select Save. You'll be redirected to the Identifiers page.

Get your Apple Private Key and Key ID

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, create a new Key in the Apple Developer portal.

1. On the Identifiers page, in the sidebar, select Keys.
2. Next to Keys at the top of the page, select the plus icon (+) to register a new key. You'll be redirected to the Register a New Key page.
3. 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.
4. 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.
5. Select Continue and you'll be presented with the final confirmation screen. Verify that Sign in with Apple is checked. Select Register. You'll be redirected to the Download Your Key page.
6. Save the Key ID value somewhere secure. This is your Apple Key ID in Clerk.
7. Download the private key file. This is your Apple Private Key in Clerk. Ensure you back up the key in a secure location, as it cannot be downloaded again later.
8. Select Done. You'll be redirected to the Keys page.

Configure Email Source for Apple Private Relay

This step is required for web-based flows only.

Apple provides a privacy feature called Hide My Email⁠, allowing users to sign in to your app with Apple without disclosing their actual email addresses. Instead, your instance receives an app-specific email address that forwards any emails to the user real'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. In the sidebar, select Services.
2. 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.
3. Next to Email Sources at the top of the page, select the plus icon (+) to add a new Email Source.
4. In the Register your email sources modal that opens, 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.
5. Select Next. The modal will redirect to the Confirm your email sources screen.
6. Select Register. The modal will redirect to the Email Source Registration Complete screen.
7. Select Done.

After this step, the email address should appear in the list and display a green check icon, indicating it has been verified. If it's not marked as verified yet, DNS propagation may still be in progress. Wait for the propagation to complete before attempting to select Reverify SPF.

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

• https://support.apple.com/en-us/HT210425#hideemail⁠
• https://developer.apple.com/help/account/configure-app-capabilities/configure-private-email-relay-service⁠

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. You'll be redirected to the Register a new identifier page.
6. Select App IDs, then select Continue.
7. On the next page, you'll be prompted to Select a type for your app. Choose App and select Continue. You'll be redirected to the Register an App ID page.
8. 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.
9. 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.
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 Clerk Dashboard where the configuration modal should still be 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 copy/paste the contents.
3. Select Add connection.

Test your connection

The simplest way to test your connection is to visit your Clerk app's Account Portal, which is available for all Clerk apps 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

1. Sign in with your connection's credentials.