Apple

Overview

Adding a “Sign in with Apple” button to FusionAuth is straightforward and this guide will walk you through the steps necessary to collect the configuration details from your Apple Developer account to enable this social login.

Once you have completed this configuration, you will be able to enable the “Sign in with Apple” login button for one or more FusionAuth applications. Below is an example login page with the Apple Identity Provider enabled.

Here's a diagram of the login flow between:

• the user
• your application
• FusionAuth and
• a remote identity provider such as Apple

Logging In Using Apple

Although this looks complex, the user only sees a few screens, such as the FusionAuth login screen, the Apple login screen, and your application.

Create an Apple Developer Account

Ensure you have an Apple Developer account and then navigate to your Apple Developer account.

• https://developer.apple.com/

If you do not yet have an Apple Developer account, please do this now. Once you have logged in to Apple and obtained access to your Apple Developer account, continue to the next step.

Configure your Apple Developer Account

If you already have an App ID, Services ID, and key configured for Sign in with Apple, you can use these existing values. If you have yet to configure your Apple developer account for Sign in with Apple, complete the following steps.

Register a New App ID

From your Apple Developer account, navigate to Certificates, Identifiers & Profiles and select Identifiers from the left column. Click on the plus icon to add a new identifier.

Select App IDs and click “Continue”. On the next panel, select type as App and click “Continue”. On the next panel, fill in the Description field, specify the Bundle ID, and select Sign in with Apple from the list of capabilities. Click “Continue”. On the next panel confirm your selection, make a note of the App ID Prefix (Team ID), and click “Register”. Select App IDs and click “Continue”. On the next panel, select type as App and click “Continue”. On the next panel, fill in the Description field, specify the Bundle ID and select Sign in with Apple from the list of capabilities. Click “Continue”. On the next panel confirm your selection, make a note of the App ID Prefix (Team ID), and click “Register”.

Register a New Services ID

From your Apple Developer account, navigate to Certificates, Identifiers & Profiles and select Identifiers from the left column. Click on the plus icon to add a new identifier.

Select Services IDs and click “Continue”. On the next panel, fill in the Description and Identifier fields and click “Continue”. Complete this step by clicking “Register” on the following panel.

Edit your newly created Services ID, then enable and configure Sign In with Apple. Clicking the “Configure” button will open a Web Authentication Configuration panel. In this step, you will need to configure the application domain and Return URL of your FusionAuth service.

If you do not see the Domains and Subdomains and the Return URLs text input fields, click the plus icon next to Website URLs.

Next, enter your application domain and Return URL.

For example, if the FusionAuth URL is https://login.piedpiper.com then the origin would be login.piedpiper.com. The Return URL is the FusionAuth URL with a path of /oauth2/callback, so in this example, the return URL would be https://login.piedpiper.com/oauth2/callback. Note that Apple expects a secure (https) URL, so an http endpoint won’t work, even in development or test environments.

Additional domains and return URLs may be added at a later time too. Once you have completed this configuration, save your changes and click “Continue”. Confirm your changes to the Services ID by clicking “Save”.

Register a New Key

From your Apple Developer account, navigate to Certificates, Identifiers & Profiles and select Keys from the left column. Click on the plus icon to add a new key.

Enter a name for your key.

Enable the Sign in with Apple checkbox, and then click the “Configure” button.

On the next panel select the previously created App ID and click “Save”. Click “Continue” and then confirm key registration by clicking “Register”. When prompted to download the key, do so and make a note of the Key ID.

Import the Private Key

Now that we have completed the Apple application configuration, we can import the private key we collected in the previous step. Unless otherwise directed by Apple, you can assume the provided private key is using the Elliptic curve. To import the private key, navigate to Settings -> Key Master and select Import Elliptic Private Key from the actions in the top right.

Enter the Key ID from the previous step into the Key identifier field. Using a text editor, open the key file you downloaded in the previous step and copy the value into the Private key field.

Create an Apple Identity Provider in FusionAuth

The next step is creating an Apple Identity Provider in FusionAuth. Switch to your FusionAuth portal and navigate to Settings -> Identity Providers and click Add Apple from the top right selection button.

This will take you to the Add Apple panel. Fill out the required fields using the values from your Apple Developer account. The button text is also required but it will be defaulted to “Sign in with Apple”. You may optionally modify this default value.

To enable this identity provider for an application, find your application name in the Applications configuration section at the bottom of this panel. You will always see the FusionAuth application, this application represents the FusionAuth administrative user interface. If you wish to be able to log into FusionAuth with this provider, you may enable this application.

In the following screenshot you will see that we have enabled this login provider for the Pied Piper application and enabled Create registration. Enabling create registration means that a user does not need to be manually registered for the application prior to using this login provider.

For example, when a new user attempts to log into Pied Piper using Apple, if their user does not exist in FusionAuth it will be created dynamically, and if the Create registration toggle has been enabled, the user will also be registered for Pied Piper and assigned any default roles assigned by the application.

If you do not wish to automatically provision a user for this application when logging in with Apple, leave Create registration off. You will need to manually register a user for this application before they may Sign in with Apple.

That's it, now the Sign in with Apple button will show up on the login page for the Pied Piper application.

Form Fields

Apple Private Mail Relay Configuration

When a user logs in with Apple, they will be provided an option to send their actual email address or an anonymous email address back to FusionAuth.

For example, if the user selects to use an anonymous email address, FusionAuth will receive an email address for that user that ends in @privaterelay.appleid.com. This email address may be used to communicate with the user, however it means that the email will be routed through Apple’s Private Email Relay service. To ensure your email is delivered, you will need to register your email domain and perform any necessary configuration with your SMTP service provider.

• Apple - Communicating Using the Private Email Relay Service

Some email service providers may provide documentation to assist you in making the necessary configuration changes. For example, the following article is provided by SendGrid to help you send email through Apple’s Private Email Relay.

• SendGrid - Configuring Sign in with Apple

CORS Configuration

To complete the login request, Apple will make an HTTP POST request to the callback URL in FusionAuth. For this request to be allowed through the CORS filter you will need to navigate to Settings -> System -> CORS and add https://appleid.apple.com as an Allowed Origin in the CORS configuration.

Once you complete your Apple Identity Provider configuration, if your CORS configuration is not yet configured to allow the Apple login request to complete, you will be shown the following warning prompting you to complete the CORS configuration. See the CORS Filter reference for additional details on modifying the CORS configuration.

Troubleshooting CORS

If you receive a 403 status code in the browser console during login when using Safari, additional configuration is required. The redirect flow is slightly different between the browsers.

To resolve this issue, navigate to Settings -> System -> CORS and add the GET method to the Allowed methods .

Building Your Own Integration

If you are building your own login experience, you'll want to start the identity provider flow yourself and then complete the login.

You might do this if you are using the Login API rather than using the hosted FusionAuth login pages. Here's a diagram illustrating this login flow.

An Integration With An Identity Provider Using The API

Completing the login is documented further in the API.

If you require a refresh token after completing the login, ensure Enable JWT Refresh is true in the application configuration. This is found in the administrative user interface by navigating to Applications -> Your Application -> Security -> Login API settings.

Supporting Web and Mobile

If you are using version 1.43.0 or later, follow the directions in Using Bundle Id . For versions prior to 1.43.0, follow the directions in Using Services Id with Application Overrides .

Using Bundle Id

Supporting Sign in with Apple from both web and mobile applications in version 1.43.0 or later no longer requires multiple applications.

• Services Id is the Apple Services ID used for web applications
• Bundle Id is the Apple Bundle ID used for native applications

Configure one or both of the Services Id and Bundle Id fields as needed. If you are only supporting a native app, use Bundle Id and leave Services Id blank. If only a webapp, use Services Id and leave Bundle Id blank. If your application is both a native and a web application, configure both the Bundle Id and Services Id fields.

You can still override the configuration for either field on a per-application basis.

The login API request from a native application needs to include data.isNativeApp with a string value of "true". This configuration will use the Bundle Id from the Apple IdP configuration rather than Services Id .

Using Services Id with Application Overrides

If you are supporting Sign in with Apple from both web and mobile applications prior to version 1.43.0, two configurations are required, with slightly different values.

• For web applications, the Services Id is the Apple Services ID.
• For mobile applications, the Services Id is the Apple Bundle ID.

However, you can’t have more than one Apple Identity Provider for a single application configuration.

To support both mobile and web users, create two applications in FusionAuth. Enable the Apple Identity Provider for each application. Finally, use the “Overrides” section to set the Services Id to the correct value.

You’ll typically register a user for both applications whenever a user signs in with Apple, which you can do using a User Registration Complete webhook.

Troubleshooting

Key Import Error

If you see the following error in the UI:

A request to the Apple Token API has failed. Unable to complete this login request.

And this error is logged in the Event Log:

Status code [400] Error response is { "error" : "invalid_client" }

Ensure that you have imported the private key provided by Apple into FusionAuth using the Key ID specified in the Apple Developer Account dashboard.

If you import with the default behavior, FusionAuth will generate an identifier. The generated key identifier will not match the value expected by Apple and the integration will fail with the above error.

If you encounter this error, re-import the private key with the correct Id to ensure the key identifier is set correctly.

Scope Error When Using The Link on Email Strategy

If you choose Link on email for a linking strategy and see this UI error:

"An email address was not provided for the user. This account cannot be used to login, unable to complete this login request."

Please confirm that you have requested the email scope. See configuration reference here.

Note that if you specify the email scope, but a subsequent configuration error causes a full login / user creation to fail, you may still see the above error. This is because Apple only sends the user’s email address on the first login, and only the user ID on subsequent authentication requests. To solve this, reset access to your app on your Apple device. You can do this by navigating to Phone Settings -> Apple Id -> Password & Security -> Apple ID logins -> [YOUR APP] -> Stop using Apple ID. If you are using macOS, navigate to Preferences -> Apple Id -> Password & Security -> Apple ID logins -> [YOUR APP] -> Stop using Apple ID. Then try to log in again and the email address should be sent.