Article

Authenticating Users with Sign in with Apple

Securely authenticate users, and create an account in your app for users to log in to.

Overview

Sign in with Apple lets users log in to your app across all of your platforms, using their two-factor authentication Apple ID. After the user chooses to use Sign in with Apple to log in, your app receives tokens and user information that you then verify from a server.

When the user attempts to sign in using Sign in with Apple, the following sequence begins:

A sequence diagram that describes the steps required for authenticating a user.

You may group apps in your developer account for Sign in with Apple so that the same app across systems, such as iOS, macOS, and Web, only request information from the user the first time they log in. This allows you to present a simple confirmation to continue, even if the app bundle IDs are different across these systems.

Authenticate the User and Request Information

Initialize an authentication session with your app server and associate a client session with an ID token using the nonce value. You can request to receive the user’s information, such as name and email address. If the user has approved accessing this information, your authorization request then includes the requested information.

Sign in with Apple protects user accounts by using two-factor authentication. Users logged in to an Apple device can quickly sign in to your app in the following ways:

  • Face ID or Touch ID on passcode-protected devices

  • Passcode, if Touch ID or Face ID isn’t available

  • Apple ID password, if the passcode isn’t set

Native apps only allow the signed-in iCloud user to use Sign in with Apple. Web flows allow logins using any Apple ID.

Apple determines whether a user is a real person by combining on-device machine learning, account history, and hardware attestation using privacy-preserving mechanisms. There are three possible values when determining if a user is a real person:

LikelyReal

The user appears to be a real person, and you can treat this account as a valid user. You can skip any additional fraud verification checks or CAPTCHAs that your app normally uses.

Unknown

The system can’t determine whether the user is a real person. The server may return this value if status determination is taking too long. Treat this user as any other account with limited information that requires additional verification steps. Don’t block service, because the user may be a real person.

Unsupported

Real user status is only supported on iOS at this time. macOS, watchOS, tvOS, and Web all return Unsupported.

This system for detecting whether the user is real is tuned for high precision and moderate recall time. You may also use it as a feature in your own machine-learning models for detecting account fraud.

The identification servers return the user status only when the user first uses Sign in with Apple with your app. Subsequent attempts on the same device after disconnect and reconnect, or attempts on other devices, don’t return any information for this user status.

After the user logs in to your app using Sign in with Apple on one of their devices, they can sign in to your app on all of their devices. Deleting your app from a device doesn’t affect this capability. If the user reinstalls your app, they can continue to use Sign in with Apple on any of their devices to sign in with their existing account.

Retrieve the User’s Information from Apple ID Servers

The information you retrieve must include the credentials that are required to verify the user’s identity. The server returns the credentials and user information based on the initial request. The information returned can include user identity, full name, verified email address, and real user status.

After the user is successfully authenticated, the server returns an identity token, authorization code, and user identifier to your app.

The identity token is a JSON Web Token (JWT) and contains the following claims:

iss

The issuer-registered claim key, which has the value https://appleid.apple.com.

sub

The unique identifier for the user.

aud

Your client_id in your Apple Developer account.

exp

The expiry time for the token. This value is typically set to 5 minutes.

iat

The time the token was issued.

nonce

A String value used to associate a client session and an ID token. This value is used to mitigate replay attacks and is present only if passed during the authorization request.

email

The user's email address.

email_verified

A Boolean value that indicates whether the service has verified the email. The value of this claim is always true because the servers only return verified email addresses.

Use the authorization code to verify the token claims with Apple servers, and exchange them for refresh tokens.

The user identifier has the following characteristics:

  • Consists of a unique, stable string, and is intended for use as the primary identifier of the user.

  • Uses the same identifier across all of the apps in the development team associated with your Apple Developer account.

  • Different for the same user across different development teams, and can’t be used to identify a user across development teams.

  • Doesn’t change if the user stops using Sign in with Apple with your app, and later starts using it again.

  • Typically stored alongside the user’s primary key in your database. Use the user identifier instead of an email address to identify the user.

If you request the user’s full name, Sign in with Apple collects the information to pass along to your app. The name defaults to the user’s name from their Apple ID, but the user can change their name. The modified name is only shared with your app and not with Apple, and hence isn’t included in the ID token.

If you request the user’s verified email address, Sign in with Apple prompts the user for it, to share with your app. The user may choose to share their real email address or an anonymous one that uses the private email relay service. In both cases, Apple has previously verified that the email address works and is ready for use. Both email addresses enable you to quickly communicate with the user.

For more information, see Communicating Using the Private Email Relay Service.

Send Information to Your App Servers

Ensure that your app relays the credentials and user information to your app servers. The API collects this information and shares it with your app the first time the user logs in to the app using Sign in with Apple. If the user then uses Sign in with Apple on another device, the API doesn't ask for the user’s name or email again. It collects the information again only if the user stops using Sign in with Apple and later reconnects to your app.

Because the user’s information isn’t shared with your app in any subsequent API calls, your app should store it locally, immediately after you receive it from the API response. In case of subsequent failures in your process or network, you can read the information from local storage and try processing it again.

Verify Token Credentials

Your app servers verify the validity of the token credentials with Apple ID servers. For more information, see Verifying a User.

Prevent Duplicate Accounts

A user may already have an account in your system, but may attempt to use Sign in with Apple to log in to that account. Sharing the real email address that’s associated with the user’s Apple ID may not help, because it may not be the same email used to create the account with your system. There are a couple of ways you can mitigate this issue:

  • Implement the ASAuthorizationPasswordProvider class to detect and offer keychain credentials that the system already knows about. This works seamlessly to detect and use existing accounts, and prevents new accounts from being created using Sign in with Apple.

  • For new accounts created using Sign in with Apple, let the user know that they have created a new account, and ask if they have any existing accounts to link to.

See Also

Authentication and Verification of Users

Verifying a User

Check the validity and integrity of a user’s identity token.