Apple SSO integration with Identity Cloud for social authentication/registration
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.
Sign in with Apple uses the FORM_POST response mode, so you must specify the form_post
endpoint in the redirect URL.
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.
See Also
See Also
How do I create end user journeys for social registration and login in Identity Cloud?
Does the ForgeRock solution support social authentication?
Single Sign-On Integrations for Identity Cloud
Identity Cloud documentation:
- Social authentication
- Journeys
- Creating an Apple Client (ForgeRock SDKs)
Other social integrations:
- Amazon SSO integration with Identity Cloud for social authentication/registration
- Facebook SSO integration with Identity Cloud for social authentication/registration
- Google SSO integration with Identity Cloud for social authentication/registration
- LinkedIn SSO integration with Identity Cloud for social authentication/registration
- Microsoft SSO integration with Identity Cloud for social authentication/registration
- Salesforce SSO integration with Identity Cloud for social authentication/registration
- WordPress SSO integration with Identity Cloud for social authentication/registration
- Yahoo SSO integration with Identity Cloud for social authentication/registration