Apple
Learn how to set up Sign in with Apple.
To configure your global Apple integration you’ll need two pieces of information from WorkOS: a Redirect URI and an outbound email domain for Apple’s Private Relay email service.
You’ll also need four pieces of information from an active Apple Developer Account: an Apple Team ID, Apple Service ID, Apple Private Key and Private Key ID.
WorkOS provides a default set of Apple credentials, which allow you to quickly enable and test Sign in with Apple. WorkOS will automatically use the default credentials until you add your own Apple Team ID, Apple Service ID, and Apple Private Key to the configuration in the WorkOS dashboard.
The default credentials are only intended for testing and therefore only available in the Staging environment. For your production environment, please follow the steps below to create and specify your own Apple Team ID, Apple Service ID, and Apple Private Key.
Please note that when you are using WorkOS default credentials, Apple’s authentication flow will display the WorkOS name, logo, and other information to users. Once you register your own application and use its credentials for the authentication flow, you will have the opportunity to customize the app.
Navigate to the Authentication section of the WorkOS dashboard. Scroll down to the Apple OAuth section and find the following values in the configuration:
- Redirect URI
- outbound email domains
After the authentication process has completed and a authorization code is granted, the user will be sent to the Redirect URI.
Outbound email domains are registered with Apple’s Private Relay email service. Apple requires outbound email domains and/or email addresses to be registered with Private Relay to deliver email to those users. For more information, see Apple’s documentation on Private Relay.
These values will be used later in the guide.
In order to integrate you’ll need an active Apple Developer account. From that Apple Developer account you’ll need:
- A Team ID
- A Service ID
- A private key ID
- The private key contents
Follow these steps to retrieve these values and configure your integration with Apple.
Sign in to the certificates, identifiers, and profiles section of your Apple Developer account. The landing page will have your name, company name, and your Team ID. Note the Team ID value for later.
The Team ID is sensitive and will only be used by the server to communicate with Apple. It should not be shared with the client.
Skip this step if you already have an App ID.
Click on Identifiers on the sidebar, then click on the + button to create a new identifier.
On the next page, select App IDs and click Continue.
Next, select App and click Continue.
On the next page, fill in a description and a bundle ID. The bundle ID should be unique and in reverse domain notation, e.g., com.example.myapp.
Also, check the Sign in with Apple box in the Capabilities section. There is no need to update anything in the Edit modal.
Then click Continue. Review your selections and click Register.
Next we need to create a linked Service ID. Click on Identifiers on the sidebar, then click on the + button.
On the next page, select Services IDs and click Continue.
Enter a description and a Service ID. The Service ID should be unique and in reverse domain notation, e.g. com.example.myapp.
Click Continue. Note the Service ID for later and click Register to create the service.
Now we will configure our new service for Sign in with Apple. First select the new service from the list of Service IDs.
Check the Sign in with Apple box and click Configure.
Ensure the App ID we created earlier is selected in the dropdown. Then enter api.workos.com in the Domains and Subdomains field and paste the Return URI from the WorkOS dashboard in the Return URLs field.
Click Done and then Continue. Review your changes and click Save.
Click on Keys on the sidebar, then click on the + button to create a new key.
On the next page, enter a human-readable Key Name. Then check the Sign in with Apple box and click Configure.
In the Configure dialog, select the App ID we created earlier and click Save.
Click Continue. Review your changes and click Register to create your key.
Make sure to download your new private key. Also note the Key ID for later.
Navigate back to the Authentication section in the WorkOS dashboard, and click on Edit under Sign in with Apple.
Toggle Enabled on and provide the credentials from Apple that you generated in the previous steps.
Sign in with Apple users can opt to hide their email address when signing in. In order for emails to be sent to those users, we need to configure Private Email Relay.
On the Sign in with Apple modal, copy the list of outbound email domains.
Then open your Apple Developer account and click on Services on the sidebar. Then click on Configure under Sign in with Apple for Email Communication.
Click the + button next to Email Sources and enter the outbound email domains from the WorkOS dashboard in the Domains and Subdomains text box. Then click Next and Register.
You are now ready to start authenticating with Sign in with Apple. Your users will see the option to Sign in with Apple when visiting your AuthKit domain. Alternatively if you’re using the standalone SSO API, you can initiate Sign in with Apple by passing AppleOAuth as the provider.