Apple
To add Apple as a social sign-in provider, you need an Apple Developer account. Go to Enrolling and Verifying Your Identity with the Apple Developer App to create one.
Webbrowser
- Ory Console
- Ory CLI
Follow these steps to add Apple as a social sign-in provider to your project using the Ory Console:
-
Sign in to Ory Console and select Social Sign-in.
-
Click the switch next to the Apple logo to start the configuration.
-
Copy the Redirect URI and save it for later use.
-
Using an Apple Developer Account, create an app, a service, and a private key:
- To set up an application, navigate to the Apple Developer Dashboard and go to Certs, Identifiers, and Profiles then Identifiers.
- Create a new App IDs identifier. When prompted for a type select App.
- Enter a description and bundle ID of your liking.
- Scroll down and select Sign in with Apple.
- Click Continue, then Register.
- Go back to the Identifiers overview.
- Next to the search icon open the dropdown and select "Services IDs".
- Create a new Services ID.
- Choose a description of your liking. The identifier must match the App ID value.
- Click Continue, then Register.
- Click on the newly created service identifier and click the "Sign in with Apple" checkbox.
- Click the Configure button and set the domains and subdomain to match your Ory Network domain (or custom hostname).
- Add the Redirect URI you received earlier and set it here as the return URL and click Next.
- Click Continue, then Save.
- Next, go to Keys and register a new key.
- Set a key name and enable Sign in with Apple. Next to Sign in with Apple, click Configure.
- Use the App ID you created earlier as the primary AppID.
- Click Continue, then Register.
- Download the key and click Done.
-
Copy the correct identifiers to the Ory Console Apple configuration:
- Client ID: Add the identifier of the Services ID (not the Bundle ID) you created in Apple. Not the ID of the App ID. Not the Team ID. Not the Name.
- Client Secret Signing Key: Paste the contents of your key file downloaded from Apple. Paste the entire key, including the BEGIN/END PRIVATE KEY lines.
- Apple Team ID: Add your Apple Team ID. In the Apple Developer Console top right menu, navigate to View Membership > Membership > Team ID.
- Key ID: Paste the key ID of your Apple key. To find this, navigate to your Apple Keys in the Apple Developer Console and open your key. Copy the Key ID.
- Private Key: Paste the contents of the downloaded files into the field in the Ory Console.
-
In the Scopes field of the form in the Ory Console, add the following scope:
email
-
Copy the following details from your registered application in Apple to the corresponding fields in the Ory Console form:
- Apple Team Id
- Apple Private Key Id
- Apple Private Key
-
In the Data Mapping field of the form in the Ory Console, add the following Jsonnet code snippet, which maps the desired claims to the Ory Identity schema:
local claims = {
email_verified: false,
} + std.extVar('claims');
{
identity: {
traits: {
// Allowing unverified email addresses enables account
// enumeration attacks, if the value is used for
// verification or as a password login identifier.
//
// Therefore we only return the email if it (a) exists and (b) is marked verified
// by Apple.
[if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
},
},
}<JsonnetWarning format="Jsonnet code snippets" use="data mapping" />
-
Click Save Configuration.
Follow these steps to add Apple as a social sign-in provider to your project using the Ory CLI:
-
Using an Apple Developer Account, create an app, a service, and a private key. Check the Ory Console guide for the concrete steps.
-
In the created app, set the redirect URI to:
https://{project.slug}.projects.oryapis.com/self-service/methods/oidc/callback/apple
-
Create a Jsonnet code snippet to map the desired claims to the Ory Identity schema.
local claims = {
email_verified: false,
} + std.extVar('claims');
{
identity: {
traits: {
// Allowing unverified email addresses enables account
// enumeration attacks, if the value is used for
// verification or as a password login identifier.
//
// Therefore we only return the email if it (a) exists and (b) is marked verified
// by Apple.
[if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
},
},
}<JsonnetWarning format="Jsonnet code snippets" use="data mapping" />
-
Encode the Jsonnet snippet with Base64 or host it under an URL accessible to Ory Network.
cat your-data-mapping.jsonnet | base64
-
Download the Ory Identities config from your project and save it to a file:
## List all available projects
ory list projects
## Get config
ory get identity-config {project-id} --format yaml > identity-config.yaml -
Add the social sign-in provider configuration to the downloaded config. Add the Jsonnet snippet with mappings as a Base64 string or provide an URL to the file.
selfservice:
methods:
oidc:
config:
providers:
- id: apple # this is `<provider-id>` in the Authorization callback URL. It should be "apple"
provider: apple
client_id: .... # Replace this with the Services ID provided by Apple
apple_team_id: .... # Replace this with the Team ID provided by Apple
apple_private_key_id: .... # Replace this with the private key identifier generated by Apple
apple_private_key: |
-----BEGIN PRIVATE KEY-----
.... # Replace this with the content of the private key downloaded from Apple
-----END PRIVATE KEY-----
issuer_url: https://appleid.apple.com
mapper_url: "base64://{YOUR_BASE64_ENCODED_JSONNET_HERE}"
# Alternatively, use an URL:
# mapper_url: https://storage.googleapis.com/abc-cde-prd/9cac9717f007808bf17f22ce7f4295c739604b183f05ac4afb4
scope:
- email
enabled: true -
Update the Ory Identities configuration using the file you worked with:
ory update identity-config {project-id} --file identity-config.yaml
Using the Apple SDK on native apps
Apple provides a more integrated UX for native apps using the
Apple SDK.
This flow uses the native Apple SDK and does not require a browser. This results in a signed id_token
on the client side
(typically your app) which is exchanged at Ory for a session token.
The following steps are required to integrate the Apple SDK with Ory:
- Configure an Apple social sign-in provider in Ory using the same
client_id
as in your native app. - Optional: iOS apps generate different token audiences per distribution (debug, release, etc.). You can add the ID of your
current distribution to the
additional_id_token_audiences
field. Example:sh.ory.network-example-ios.debug
. - Generate a random value that you can use as a
nonce
. - Obtain an
id_token
from Apple using the Apple SDK. Make sure to also submit thenonce
. - Submit the
id_token
andnonce
(as theid_token_nonce
) as part of theupdateRegistrationFlow
orupdateLoginFlow
request to Ory. - Ory will validate the
id_token
and create an identity and optionally a session (if configured).
The id_token
is verified using Apple's publicly available signing keys, available under https://appleid.apple.com/auth/keys.
The id_token
issued by Apple only contains the user's email address. You can submit additional claims to Ory as part of the
updateRegistrationFlow
request, as traits
.
As Ory does not communicate directly with Apple during this flow, it does not have access to the Access & Refresh Tokens. This
means that Ory cannot return these in the admin APIs or SDK. If you need these tokens, you can exchange the authorization_code
returned by Apple on the device manually.
import { FrontendApi } from "@ory/client"
import * as AppleAuthentication from "expo-apple-authentication"
import * as Crypto from "expo-crypto"
async function signInWithApplePayload(): Promise<{
id_token: string
id_token_nonce: string
traits: Record<string, unknown>
}> {
const digest = await Crypto.digestStringAsync(
Crypto.CryptoDigestAlgorithm.SHA256,
Crypto.getRandomBytes(16).toString(),
)
let credential: AppleAuthentication.AppleAuthenticationCredential
try {
credential = await AppleAuthentication.signInAsync({
requestedScopes: [
AppleAuthentication.AppleAuthenticationScope.EMAIL,
AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
],
nonce: digest,
})
} catch (e) {
console.error("Couldn't sign in with Apple: ", e)
throw e
}
return {
id_token: credential.identityToken || "",
id_token_nonce: digest,
traits: {
name: {
first: credential.fullName?.givenName || "given name",
last: credential.fullName?.familyName || "last name",
},
},
}
}
export async function signInWithApple(sdk: FrontendApi, flowId: string) {
const payload = await signInWithApplePayload()
return sdk.updateLoginFlow({
flow: flowId,
updateLoginFlowBody: {
method: "oidc",
provider: "apple",
...payload,
},
})
}
export async function registerWithApple(sdk: FrontendApi, flowId: string) {
const payload = await signInWithApplePayload()
return sdk.updateRegistrationFlow({
flow: flowId,
updateRegistrationFlowBody: {
method: "oidc",
provider: "apple",
...payload,
},
})
}
Troubleshooting
When you add a social sign-in provider, you can encounter common problems such as:
- Redirect URI mismatch
- Redirect loops during registration
- Domain verification issues
To troubleshoot those issues, read Social sign-in troubleshooting.
Error: token audience didn't match allowed audiences
Make sure to either add your apps current identifier to the additional_id_token_audiences
field or set it as the Client ID of
the provider in the Ory Console.