Apple OIDC

Setup#

Sign in with Apple requires an Apple Developer account and a publicly reachable HTTPS callback. Apple does not accept localhost, an IP address, or an http:// Return URL for a web Services ID. Use a staging domain or HTTPS development tunnel; keep its hostname stable while you configure the provider.

1. In Apple Developer Portal, register a Services ID
2. Enable Sign in with Apple and configure:
   • Domain: auth.example.com
   • Return URL: https://auth.example.com/sqlos/auth/oidc/callback
3. Create a Sign in with Apple key and download its .p8 private key. Record the Apple Team ID and Key ID; Apple does not let you download the key twice.
4. Create the connection in the dashboard, or use the authenticated admin API. SqlOS generates Apple's client-secret JWT from the Team ID, Key ID, and private key; do not paste a static clientSecret.

jq -n --rawfile privateKey ./AuthKey_YOUR_KEY_ID.p8 '{
  providerType: "apple",
  displayName: "Apple",
  clientId: "YOUR_APPLE_SERVICES_ID",
  allowedCallbackUris: [
    "https://auth.example.com/sqlos/auth/oidc/callback"
  ],
  appleTeamId: "YOUR_APPLE_TEAM_ID",
  appleKeyId: "YOUR_APPLE_KEY_ID",
  applePrivateKeyPem: $privateKey
}' | curl --fail --silent --show-error \
  -X POST http://localhost:5062/sqlos/admin/auth/api/oidc-connections \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H 'Content-Type: application/json' \
  --data-binary @-

5. The create operation enables the connection. Use this endpoint only to re-enable a connection that an operator disabled:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/oidc-connections/{id}/enable \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR"

Callback claim handling#

Apple can include a user form field only on the first authorization. SqlOS treats that browser-posted object as an optional display-name hint, never as identity evidence:

• sub, email, and email_verified come from the signed, validated Apple ID token;
• any email or subject in the callback user JSON is ignored;
• only bounded, sanitized name.firstName and name.lastName values can fill a missing display name.

Persist the display name after first login if your application needs it later. Apple may not send the callback user object again, while the signed identity remains stable through the ID token.

See OIDC Social Login for the complete auth flow.

The .p8 file and the dashboard cookie jar both contain sensitive material. Keep them out of source control and shell history, and delete temporary copies after use. See Authenticate operator API calls, Apple's web authorization documentation, and OIDC Social Login.