How To

ForgeRock Identity Cloud

Integrations

Apple SSO integration with Identity Cloud for social authentication/registration

Last updated Jan 17, 2023

The purpose of this article is to provide information on configuring ForgeRock Identity Cloud to integrate with Apple® as a social identity provider using OpenID Connect (OIDC) for Single Sign-On (SSO). This integration uses Sign in with Apple (SIWA).

Overview

This article describes how to configure Identity Cloud to use Apple as a social identity provider for authentication and/or registration. Identity Cloud provides a standards-based solution for Apple social sign-on based on OIDC standards. The integration uses Sign in with Apple, which is an authentication service provided by Apple that allows users to sign in to applications with their Apple ID.

Steps involved:

Configure Sign In with Apple
Configure the Social Identity Provider in Identity Cloud
Create the end user journey
Test the end user experience

Prerequisites

You have a working Identity Cloud tenant.
You have an Apple developer account, which is a paid account. See Apple Developer Program for further information.
You have a method of encrypting a JSON Web Token (JWT) using an ES256 algorithm. One easy way to do this, and the method described in this article, is to use Ruby JWT Gem. If you don't already have Ruby, you can get it from here.

Redirect URL

Unlike other social identity providers, which use a GET redirect and values contained within the URL, Sign in with Apple requires that the redirection back to the application uses a POST request, and the POST body is what contains the important OAuth 2.0 values. See Incorporating Sign in with Apple into Other Platforms for further information from Apple.

The redirect URL will differ depending on whether or not you are using a custom domain:

If you are not using a custom domain in Identity Cloud, your redirect URL must include the Identity Cloud realm name, for example alpha, and will look similar to this: https://<tenant-env-fqdn>/am/oauth2/alpha/client/form_post/<client_name>.
If you are using a custom domain in Identity Cloud, your redirect URL will look similar to this: https://<tenant-env-fqdn>/am/oauth2/client/form_post/<client-name>.

In both cases, <client-name> is the name of the Apple social provider client you configure in Identity Cloud (see Configuring the Social Identity Provider in Identity Cloud below).

See Custom Domains for further information on custom domains in Identity Cloud.

Configuring Sign in with Apple

Disclaimer

ForgeRock assumes no responsibility for errors or omissions in the third-party software or documentation.

You configure Sign in with Apple using your Apple developer account.

Refer to the Apple developer documentation for further guidance on configuring your environment for Sign in with Apple.

Create an App ID

Although an App ID is not required for simple web app logins, you will need one if you have a native app and web app that you wish to use for a single login experience.

Go to Certificates, Identifiers & Profiles > Identifiers.
Click the Plus sign (+).
Select App IDs, then click Continue.
Click App, then click Continue.
Enter a Description and Bundle ID for the App ID. The Bundle ID should be a reverse-DNS style string, for example, com.<tenant-env-fqdn>.
Under Capabilities, select Sign in With Apple.
Click Continue, then click Register.

Create a Services ID

Go to Certificates, Identifiers & Profiles > Identifiers.
Click the Plus sign (+)
Select Services IDs, then click Continue.
Enter a Description and Identifier for the Services ID. The Identifier should be similar to your App ID to make it easy to distinguish, for example, com.<tenant-env-fqdn>.service.
Click Continue, then click Register.

Configure the Sign in with Apple Service

Go to Certificates, Identifiers & Profiles > Identifiers.
Click on the Services App that you just created.
Select Sign in With Apple, then click Configure.
Complete the following Web Authentication configuration:
- Primary App ID: Select your application's App ID (this may be the app you created in the previous steps).
- Domains and Subdomains: Enter the domain name of your app (without https://), for example, <tenant-env-fqdn>.
- Return URLs: Enter the redirect URL for your app. Sign in with Apple uses the FORM_POST response mode, so you must specify the form_post endpoint in this URL. If you are not using a custom domain for your Identity Cloud tenant, the URL must include the Identity Cloud realm name. For example, https://<tenant-env-fqdn>/am/oauth2/alpha/client/form_post/<client_name>. The client name must match the name of the social identity provider client that you will configure in Identity Cloud. See Redirect URL for further information.
Click Continue, then click Save.

Register a Private Key with Apple

Instead of using simple strings for OAuth 2.0 client secrets, Sign in with Apple uses a signed JWT containing the client ID (in this case the Services ID) combined with a private key. To register a private key with Apple:

Go to Certificates, Identifiers & Profiles > Keys.
Click the Plus sign (+)
Enter a key name.
Select Sign in With Apple and configure it for your application's Primary App ID.
Click Continue, then click Register.
Download the key and keep it in a safe place. You can only download this key once; you will not be able to download it again.
Rename the file to key.txt.

You'll use this private key to generate a client secret JWT.

Generate a Client Secret

The client secret is a JWT token that must be encrypted using the Elliptic Curve Digital Signature Algorithm (ECDSA) with the P-256 curve and the SHA-256 hash algorithm. Refer to the Apple documentation for further information on generating and validating tokens.

Important

Apple allows a maximum lifetime of 180 days (six months) for the JWT. After this time it will expire and you will need to generate a new one.

To generate the client secret JWT and encrypt the JWT using Ruby Gem:

Run the following command:$ sudo gem install jwt
Create a text file named secret_gen.rb with the following contents:require "jwt" key_file = "<Path to the private key file>" team_id = "<Your team ID>" client_id = "<Services ID>" key_id = "<Key ID of the private key>" validity_period = 180 # In days. Max 180 (6 months) according to Apple docs. private_key = OpenSSL::PKey::EC.new IO.read key_file token = JWT.encode( { iss: team_id, iat: Time.now.to_i, exp: Time.now.to_i + 86400 * validity_period, aud: "https://appleid.apple.com", sub: client_id }, private_key, "ES256", header_fields= { kid: key_id } ) puts token view raw

where:

key_file is the file that contains the format of your private key, for example, key.txt. Include the path if it's in a different location from this file.
team_id is the team ID that can be found on the Apple Developer Account > Membership page.
client_id is the Services ID (use the App ID instead if you are setting up a native iOS Sign in with Apple).
key_id is an identifier that can be found on the Keys page for the Key you generated.

Run the following command from the same location as the secret_gen.rb file:$ ruby secret_gen.rb

The client secret is returned, similar to this:eyJraWQiOiJBVFI5VTdRUk1XIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiI5UVNFNjY3NjJEIiwiaWF0IjoxNjQyNjA2MjcyLCJleHAiOjE2NTgxNTgyNzIsImF1ZCI6Imh0dHBzOi8vYXBwbGVpZC5hcHBsZS5jb20iLCJzdWIiOiJjb20uZm9yZ2VibG9ja3Muc2lnbmlud2l0aGFwcGxlc2VydmljZXMifQ.7jnQ9riFPyO76LgIYXmgvPzw3oWS1h25G7lMR-kBjeMK_MbRDgcCRZ5qoeqAW_ZK0Kyp-XdwHYNykTQDm36xUQ

You'll use this client secret when you configure the social identity provider in Identity Cloud.

Configuring the Social Identity Provider in Identity Cloud

In the Identity Cloud admin UI, go to Native Consoles > Access Management > Services > Social Identity Provider Service.
Choose Secondary Configurations, click Add a Secondary Configuration, and select Client configuration for Apple.
Complete the following configuration:
- Name: Enter a name for the social identity provider, for example, Apple.
- Client ID: Enter the client ID, which is the Services ID you set up in the previous steps.
- Redirect URL: Enter the redirect URL for your app. This must match the Return URL you configured with the Sign in with Apple Service, for example https://<tenant-env-fqdn>/am/oauth2/alpha/client/form_post/<client name>. See Redirect URL for further information on the redirect URL.
- Scope Delimiter: Enter the scope delimiter, which is usually an empty space.

Click Create.
Enter the Client Secret. This is the client secret that you generated for Sign in with Apple.
Check the rest of the default settings are correct. In particular, check the following fields:
- Enabled: Ensure the configuration is enabled.
- Transform Script: Ensure that Apple Profile Normalization is entered. This script transforms Apple credential data into a normalized form.

The configuration should look similar to this:

Click Save Changes.

Creating the end user journey

You can create custom end user journeys for social registration and sign in. These journeys will include all your enabled social identity providers, so you won't need to create different journeys for different providers.

See How do I create end user journeys for social registration and login in Identity Cloud? for information on how to create end user journeys for SSO with social providers.

Testing the end user experience

In the Identity Cloud admin UI, go to Journeys.
Click the journey that you want to test.
Copy the Preview URL.
Paste the preview URL into a browser using Incognito or Browsing mode.
Follow the sign in and/or registration steps to test your journey.

For example, if Apple is configured as a social identity provider for social login, end users are asked if they want to authenticate with Apple, similar to the screenshot below.