> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Aggiungi l'accesso con Apple

Registra un App ID, un Services ID e una chiave Sign in with Apple nel portale Apple Developer, poi collega la coppia client all'app.

## Procedura dettagliata per principianti

Prerequisiti: l'app web in esecuzione in locale (Online in 5 minuti), un database migrato per account reali (Configura il database) e un'iscrizione all'Apple Developer Program — lo stesso account da 99 $ all'anno che la guida agli account mobile fa aprire, quindi completa prima quel passaggio se non l'hai già fatto. Tutto ciò che sta nel portale sviluppatori qui sotto non costa nulla in più.

Perché è importante: la revisione dell'App Store richiede Sign in with Apple ogni volta che un'app iOS offre l'accesso social di terze parti come Google o GitHub — ed è anche un pulsante solido a basso attrito sul web: gli utenti Apple accedono con l'account già presente sui loro dispositivi.

Terminologia rapida: un App ID è l'identificativo registrato della tua app (`com.yourcompany.yourapp`). Un Services ID è un secondo identificativo che Apple emette per l'accesso web e server — quello diventa il tuo client ID. Una return URL è l'indirizzo esatto a cui Apple può rimandare un utente che ha effettuato l'accesso — il callback Better Auth del kit. Una secret key è il file `.p8` che Apple ti dà una sola volta; lo trasformi tu stesso nel client secret.

1. Registra un App ID con la capacità Sign in with Apple. 2. Registra un Services ID che punta a esso e che contiene il tuo dominio più la return URL. 3. Crea una chiave Sign in with Apple e scarica il file `.p8`. 4. Trasforma la chiave in un JWT di client secret e imposta i tre valori env.

Un limite onesto: le return URL di Apple devono essere indirizzi `https://` assoluti su un dominio registrato — `localhost` e il semplice `http` vengono rifiutati, quindi il pulsante non si può provare del tutto su un server locale nudo. Verifica sul tuo URL distribuito, oppure esponi il server locale tramite un tunnel https (per esempio `cloudflared tunnel` o `ngrok`) e registra il dominio del tunnel più il suo callback durante i test.

[Crea l'account Apple Developer](https://supastack.dev/it/docs/mobile/external-accounts.md)

[Configura il database](https://supastack.dev/it/docs/web/setup-database.md)


## Registrare l'App ID

1. Apri [developer.apple.com/account](https://developer.apple.com/account) e accedi con l'account che detiene l'iscrizione al Developer Program.

2. Apri Certificates, Identifiers & Profiles → Identifiers e fai clic sul pulsante blu +.

3. Seleziona App IDs → Continue, lascia il tipo su App → Continue.

4. Description: il nome del tuo prodotto. Bundle ID: scegli Explicit e inserisci la forma a dominio inverso `com.yourcompany.yourapp` — se distribuisci l'app iOS, usa esattamente l'`ios.bundleIdentifier` di `apps/mobile/app.json` così entrambe le piattaforme condividono un unico App ID.

5. Nell'elenco delle capacità spunta Sign in with Apple → Continue → Register.

Atteso: l'identificativo appare nell'elenco Identifiers con la capacità Sign in with Apple attivata. Riutilizza questo unico App ID — il Services ID e la chiave si agganciano entrambi a esso come app primaria.


## Registrare il Services ID e la return URL

1. Di nuovo in Identifiers fai clic ancora su +, scegli Services IDs → Continue.

2. Description: qualcosa come `yourapp web sign-in`. Identifier: un altro nome a dominio inverso — la convenzione è `com.yourcompany.yourapp.web` — volutamente diverso dall'App ID. Questo Services ID è il client ID che il server usa per l'accesso web; copialo esattamente, poi Continue → Register.

3. Seleziona il nuovo Services ID nell'elenco, spunta Sign in with Apple e fai clic su Configure.

4. Nella finestra imposta Primary App ID sull'App ID della sezione precedente. In Website URLs aggiungi il tuo dominio (per esempio `yourdomain.com`), e in Return URLs aggiungi `https://yourdomain.com/api/auth/callback/apple` — quel percorso è il callback Better Auth del kit, `{APP_URL}/api/auth/callback/apple`. Save → Continue → Save.

Ogni return URL deve essere un indirizzo `https://` assoluto su un dominio registrato: `localhost`, gli indirizzi IP nudi e `http` vengono rifiutati. Per lo sviluppo in locale esegui l'app dietro un tunnel https, aggiungi il dominio del tunnel al Services ID, registra `https://<tunnel-domain>/api/auth/callback/apple` e imposta `APP_URL` sull'URL del tunnel durante i test.

Atteso: il Services ID mostra Sign in with Apple → Enabled. Se il portale rifiuta il tuo dominio, completa prima la verifica di proprietà del dominio nella pagina dell'account.


## Creare la chiave Sign in with Apple

1. Apri Keys nella barra laterale sinistra → +. Dai un nome alla chiave (per esempio `yourapp sign-in key`), spunta Sign in with Apple, fai clic su Configure, scegli l'App ID come Primary App ID → Save → Continue → Register.

2. Nella schermata di conferma annota il Key ID, poi fai clic su Download — il file `.p8` viene offerto una sola volta. Se lo perdi, revoca la chiave e creane un'altra; Apple non ne conserva copia.

3. Annota anche il tuo Team ID — è stampato nell'angolo in alto a destra delle pagine dell'account sviluppatore, accanto al nome del tuo account.

Atteso: ora hai tre valori — il file `.p8`, un Key ID e il tuo Team ID. Tieni il file `.p8` fuori da Git: firma come il tuo account sviluppatore.


## Aggiungere i valori all'app

Il kit si aspetta esattamente le tre righe qui sotto — la stessa coppia `clientId`/`clientSecret` che usa ogni provider social. `APPLE_CLIENT_ID` è il Services ID (`com.yourcompany.yourapp.web`), non l'App ID.

Apple non emette un client secret statico, quindi `APPLE_CLIENT_SECRET` è un JWT che firmi tu stesso a partire da Team ID, Key ID e la chiave privata `.p8` — la documentazione di Better Auth include il piccolo script generatore per farlo. Un secret firmato resta valido al massimo sei mesi: metti un promemoria per rigenerarlo e aggiornare il valore env, perché l'accesso fallisce nel momento in cui scade. Non incollare mai il contenuto del file `.p8` né il Key ID grezzo nell'env — solo il JWT generato ci appartiene.

Il client secret e il file `.p8` restano lato server: mai in variabili `NEXT_PUBLIC_`/`EXPO_PUBLIC_` e mai committati — in produzione impostali tramite il secret store del tuo hosting. Riavvia il server di sviluppo dopo le modifiche; i cambiamenti env si leggono solo all'avvio.

```
# apps/web/.env.local
AUTH_APPLE_ENABLED=true
APPLE_CLIENT_ID=com.yourcompany.yourapp.web   # the Services ID, not the App ID
APPLE_CLIENT_SECRET=<JWT signed with Team ID + Key ID + .p8>
```


## Verificare e risolvere i problemi

Apri il tuo `APP_URL` — un URL distribuito o il tunnel https — su `/auth`, fai clic sul pulsante Apple, accedi con qualsiasi Apple ID (non deve essere l'account sviluppatore) e conferma di tornare con l'accesso effettuato.

La maggior parte dei fallimenti è una di tre confusioni: Services ID vs App ID — il client ID deve essere il Services ID per l'accesso web; una return URL che non corrisponde — il callback deve essere esattamente uguale a una Return URL registrata, protocollo, dominio e percorso inclusi; o un client secret scaduto/non valido — rigenera il JWT, che è solo un token firmato, non il contenuto del `.p8`.

Finché `AUTH_APPLE_ENABLED=true` non è impostato, l'opzione Apple su `/auth` resta disattivata — controlla i nomi env e riavvia. Attivare il flag senza `APPLE_CLIENT_ID` e `APPLE_CLIENT_SECRET` fa fallire l'avvio e nomina la variabile mancante.

L'app iOS raggiunge questo stesso backend — distribuisci Sign in with Apple anche al suo interno così la revisione dell'App Store accetta gli altri pulsanti social. La guida agli account mobile spiega cosa cerca la revisione.

[Crea gli account mobile](https://supastack.dev/it/docs/mobile/external-accounts.md)

[Aggiungi poi i pagamenti con Stripe](https://supastack.dev/it/docs/web/stripe-payments.md)

[Panoramica dei provider OAuth](https://supastack.dev/it/docs/web/setup-oauth.md)


Per continuare la configurazione, leggi [Aggiungi i pagamenti con Stripe](https://supastack.dev/it/docs/web/stripe-payments.md).


## Successivo

[Aggiungi i pagamenti con Stripe](https://supastack.dev/it/docs/web/stripe-payments.md)