Amazon Cognito user pools enables you to add user sign-in and sign-up to your mobile and web applications using a secure and scalable user directory. With Amazon Cognito user pools, your end users can sign in using a user name or password, or with a third-party identity service, such as Facebook or Google. The process of using a third-party identity service is called federation. With federation, you can build applications that retrieve information about your end users that they have provided to another service and have consented to give to your applications.
Amazon Cognito user pools now supports Sign in with Apple as an identity provider (IdP). You can now federate users using the Sign in with Apple service, map these users to a user directory, and retrieve standard authentication tokens from a user pool after the user authenticates with Apple using their Apple ID credentials.
Much like login with Facebook or Google, Sign in with Apple acts as an authorization server and verifies an end user with their Apple ID credentials. Sign in with Apple is built on the OpenID Connect (OIDC) protocol. As of writing this post, there are a few notable differences about Sign in with Apple compared to other OpenID Providers.
- Using Sign in with Apple, an end user can choose whether to share the email linked to their Apple ID or use a generated one provided by Apple. The generated email will be of the form “<randomstring>@privaterelay.appleid.com”.
- Unlike other identity providers, Sign in with Apple only honors the scopes requested for an end user on their first authentication through the service for the app configured on Apple’s developer portal. In other words, if you start requesting name after an end user has authenticated, for example, that information will not be returned.
- Sign in with Apple returns the requested scopes in the initial return from their authorization endpoint for the first user authentication; however, only the email associated with the Apple ID is returned in a trusted form via the ID token.
How to set up Sign in with Apple and associate it with an Amazon Cognito user pool
The prerequisites for setting up the IdP end-to-end are:
- An Amazon Cognito user pool with an application client
- A domain that is associated with the user pool
- An Apple ID with two-factor authentication enabled
Step 1: Set up Sign in with Apple service in Apple’s Developer portal
- Enroll in the Apple Developer Program with an Apple ID and then sign in using it.
- On the main developer portal page, select Certificates, IDs, & Profiles.
- On the left navigation bar, select Identifiers.
- On the Identifiers page, select the + icon.
- On the Register a New Identifier page, select App IDs.
- On the Register an App ID page, under App ID Prefix, take note of the Team ID value.
- Select the operating system the app will be run on (choose macOS for web-based apps).
- Provide a description in the Description text box.
- Provide a string for identifying the app under Bundle ID.
- Under Capabilities, select Sign in with Apple, and then select either Enable as a primary App ID (default) for use in a single Apple app or Group with an existing primary App ID for use in multiple Apple apps.
- Select Continue, review the configuration, and then select Register.
- On the Identifiers page, on the right, select App IDs, and then select Services ID.
- Select the + icon and, on the Register a New Identifier page, select Services IDs.
- On the Register a Services ID page, select the Sign in with Apple checkbox to enable the service, and then select Configure.
- Select the App ID that you created in step 1.1.
- Under Web Domain, put the domain associated with your user pool.
NOTE: You do not have to verify the domain because the verification is required for a transaction method that Amazon Cognito does not use.
- Under Return URLs, type https://<your domain>/oauth2/idpresponse, select Add, and then select Save.
- Provide a description in the Description text box.
- Provide an identifier in the Identifier text box.
Important: Make a note of this identifier because you will need it later.
- Select Continue, review the information, and then select Register.
- On the left navigation bar, select Keys, and on the new page, select the + icon.
- On the Register a New Key page, select the check box next to Sign in with Apple.
- Select the App ID you created in 1.1 and then select Save.
- Provide a key name (can be anything).
- Click Continue, review the information, then select Register.
- On the page you are redirected to take note of the Key ID and download the .p8 file containing the private key.
Step 2: Set up the Sign in with Apple IdP in Amazon Cognito user pools console
- Sign in to the Amazon Cognito console, select Manage User Pools, and then select the user pool that you will be using with Sign in with Apple.
- Under Federation, under the Identity providers tab, select Sign in with Apple.
- Provide the Apple Services ID, Team ID, Key ID, and private key for the Sign in with Apple application along with the desired scopes.
Note: The private key is provided in the .p8 file; the contents are plain text. You can provide either the file or the contents within the file for the private key.
- Select the Attribute mapping tab, and then select the Apple tab.
- Select the checkboxes under Capture next to the Apple attributes, and select the user pool attribute under User pool attribute that will receive the value from the Apple attribute and that you would like to receive in the tokens from Amazon Cognito.
- To enable your app client to allow federation through the Sign in with Apple IdP, under the App client settings tab under App Integration, find the App client that you want to allow Sign in with Apple and select the Sign in with Apple check box.
Step 3: Get started with your application
- To test that you have everything configured correctly, under the configured app client, select the Launch Hosted UI link to bring you to a sample Login page.Your configured Sign in with Apple provider will be displayed on this page through a button labelled Continue with Apple.
- (Optional) Perform a test authentication to ensure you have everything configured correctly on Apple’s and the Amazon Cognito side.
When a user federates using Sign in with Apple, the interactions between the end user, Amazon Cognito App Client, and Sign in with Apple looks like this:
- New user goes to app and selects Sign in with Apple
- App redirects to Apple authentication web page
- Apple requests Apple ID credentials
- User provides credentials
- Apple requests consent for information
- User chooses share/don’t share email (if requested)
- Redirect back to Cognito app with Authorization code
- Requests ID token using Authorization code, client ID, and generated client secret
- ID token response containing requested scopes
Tips for using Sign in with Apple in your application
- If you want to revoke the private key associated with the Sign in with Apple service, create a new private key in the Apple developer portal and provide it to Amazon Cognito prior to revoking the old key. Doing so will ensure that you do not invalidate any ongoing end-user authentication on Apple’s side.
- If you decide to increase the requested scopes and want the additional information from existing users, those users will have to go to appleid.apple.com and, under Apps & Websites Using Apple ID, select the application, select Stop using Apple ID, and then federate again using Sign in with Apple.
- The name provided by Sign in with Apple is not verified in any manner and should only be used for non-essential features; for example, a welcome message on the landing UI of your app after an end user logs in.
- If you get an “invalid redirect_url” error message on Apple’s authentication page and the redirect URL in the request is correct, check that you’ve provided the Service Identifier and not the Application Identifier for the Sign in with Apple IdP settings in Amazon Cognito user pools.
For more information, see Adding Social Identity Providers to a User Pool in the Amazon Cognito Developer Guide. You can reach us by posting to the Amazon Cognito forums. If you have feedback about this blog post, submit comments in the Comments section below.
Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.