Docs

You are viewing an archived version of the docs.Go to latest version

Apple

How to set up social connection with Apple

Overview

To make development flow as smooth as possible, Clerk uses pre-configured configuration profiles - steps are needed to your part (other than enabling the provider from Dashboard). For production instances, the process for Apple is a bit more complicated compared to other providers, but don't worry - Clerk provides step-by-step instructions to help guide you.

The purpose of this guide is to help you create an Apple App that can be used with Clerk's OAuth implementation, for the purpose of integrating your application with Sign in with Apple. If you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the Social connection (OAuth) guide.

Before you start

Configuring Apple social connection

To configure Apple SSO in your Clerk instance, you will need to retrieve (4) configuration values from the Apple Developer portal and enter them into your instance settings in Clerk Dashboard:

  1. the Apple Team ID
  2. the Apple Services ID
  3. the Apple Key ID
  4. the generated private key

Also, you'll need to retrieve (2) configuration values from Clerk Dashboard and enter them into the Apple Developer portal:

  1. the return URL (aka. OAuth redirect URI)
  2. the Email Source for Apple's Private Email Relay service

First, sign in to the Apple Developer portal and from the sidebar, click on Certificates, Identifiers and Profiles.

Navigating to Certificates, Identifiers and Profiles

Retrieving the Apple Team ID

The first thing you have to do is create an App ID. You can think of it like a top-level container that logically groups all of the resources you'll have to create for your application (keypairs, services etc.)

From the sidebar on the left, click on Identifiers and make sure that from the dropdown at the top-right corner, the App IDs option is selected. Then, click on the blue plus icon.

Creating a new identifier

You'll be taken to a Register a new identifier page with several choices. Select the App IDs option and click Continue.

Selecting App IDs

On the next page, you'll be prompted to select a type for your application. Choose App and click Continue.

Selecting App

In the next screen, you'll have to fill in a description for your App ID and a Bundle ID. None of these matter for the purposes of this guide, but it's good to pick something descriptive.

Adding description

Also, from the list of Capabilities displayed right below, make sure that Sign In with Apple is checked. Then click Continue and in the confirmation screen.

From the confirmation screen, write down the value displayed in the App ID Prefix - this is the Team ID that you'll use later on when configuring your Clerk instance.

Finally, click Register to complete the creation of your App ID.

Completing the creation of App ID

Retrieving the Apple Services ID

Now that you have created an App ID, you can create a Services ID.

Navigate back to the Certificates, Identifiers & Profiles screen and from the sidebar, click on Identifiers.

On the next screen, select Services ID from the dropdown at the top-right corner and click on the blue plus icon to create a new Services ID.

Creating a new identifier

You'll be taken to the same Register new identifier screen as in the previous section. This time, you'll choose Services IDs from the various options presented and then click Continue.

Selecting Services IDs

In the next screen, fill in a description and an Identifier. This identifier is important, since it is your Services ID value you'll need later on to configure your instance, so make sure to note it down.

Adding description

After the registration is finished, go back to configure the newly-created Services ID. Make sure the Sign In with Apple box is enabled and click Configure.

Navigating to the configuration page

This configuration screen is where you tell Apple what domain and redirect URIs your application will use. Choose the App ID you created before, and in the domain enter clerk.<your-domain>.

Next, in your Clerk Dashboard, go to User & Authentication > Social Connections. Click the gear icon next to the Apple provider and copy the Authorized redirect URI value. Paste the value into the Return URLs in Apple Developer Portal and click Next.

Adding the values from the Clerk dashboard into the configuration

Retrieving the Apple Key ID and private key

Apple differs a bit from most other providers, in that it does not use a shared Client Secret, but rather public/private keypairs.

The general concept is that a keypair is generated in the Apple Developer portal, and during an OAuth flow, your application is expected to mint a JWT that's signed with that private key. The private key essentially replaces the commonly used "Client Secret" that you see in other OAuth vendors.

Let's see how to generate a keypair and how to retrieve the Key ID and the private key values that you'll need to configure Apple SSO in Clerk.

Once again, navigate to the Certificates, Identifiers & Profiles page and choose Keys from the sidebar. In the next screen, click the blue plus icon.

Fill in a descriptive name (it doesn't matter much) and make sure you've ticked the Sign In with Apple checkbox from the list below. Then, click the corresponding Configure on the right column.

Registering a new key

You'll be taken to a page where you'll have to associate the key you're about to create, with an App ID.

From the Primary App ID dropdown, select the App ID you created in the first step of this guide and click Save.

Associating an App ID to the newly created key

You'll be taken back to the previous Register a New Key page. Click Continue and you'll be presented with the final confirmation screen. Verify that Sign in with Apple is checked and click Register.

Finalizing the creation of the newly created key

You'll be taken to a page titled Download Your Key. From here, you want to note down the displayed Key ID. You will also download the private key as a file (as the instructions point out, be sure to backup the key in a secure place). Click on Download to retrieve the private key.

Downloading the newly created key

With the Key ID and your private key at hand, you have everything you need to configure Apple SSO in your Clerk Dashboard. Click Done.

Configuring Email Source for Apple Private Relay users

This section concerns only production instances. Development and staging instances are handled for you automatically.

Apple provides a privacy feature called Hide My Email, in which users can choose to Sign In with Apple to your instance, but 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 email properly to users with private addresses, you must configure an additional setting in the Apple Developer portal.

First, navigate to Clerk Dashboard, to your production instance's Social Connections settings page. Click to enable Apple, and in the configuration modal, you'll see a read-only setting named Email Source for Apple Private Email Relay.

This setting is only available after you have deployed your instance.

Finding the Email Source for Apple Private Email Relay value on the Clerk dashboard

The value of the setting is essentially an email address; copy it, go to your Apple Developer portal, and go to the Certificates, Identifiers & Profiles page. Click on More from the sidebar on the left and then Configure.

Accessing the configuration page for Certificates, Identifiers & Profiles

On the next screen, click on the blue plus icon to add a new Email Source.

Creating a new Email Source

Paste the value you copied from the Clerk Dashboard to the Email Addresses field and click Next. Then click Register to confirm the changes.

Adding the value from the Clerk dashboard into the email addresses list

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.

Certificates, Identifiers & Profiles showing the verified email source

If it does not appear as Verified yet, don't worry, DNS propagation may take some time to complete. Wait a few minutes (it could even be hours) and click on Reverify SPF button from that list.

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

Configuring the settings in your instance

If you completed the previous steps of this guide, by now you should have the following information available, all provided by the Apple Developer portal:

  1. the Apple Team ID
  2. the Apple Services ID
  3. the Apple Key ID
  4. the private key file

Don't worry, the hard part is over. Now you can go to your instance's settings in the Dashboard, and navigate to the Social Connections settings under User & Authentication. Find the Apple provider from the list, toggle it on and click on the gear icon.

In the modal, you'll see all the corresponding fields that you should paste the aforementioned values into. For the private key file, open it with a text editor and just copy/paste the contents.

After filling in the settings, you'll end up with something roughly like this:

Adding the values into the Clerk dashboard

Click Save and you should be good to go. Congratulations! Social connection with Apple is now configured for your instance.

References

Feedback

What did you think of this content?

Last updated on