> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Guida all'integrazione dell'autenticazione: architettura e go-live

> Come funziona un'integrazione Didit Authentication in produzione: schermate ospitate o proprie, token, controlli backend, sessioni, app native e go-live.

Questa guida spiega come si compone un'integrazione di Didit Authentication nell'ambiente di produzione, dal primo reindirizzamento fino alla checklist per la messa in produzione.
Inizia con la [guida rapida](https://docs.didit.me/it/authentication/quickstart.md) se non hai ancora autenticato un utente, e usa le guide rapide delle piattaforme per il codice di ciascun SDK.

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Sono coinvolte quattro parti:

| Componente | Di sua competenza |
| - | - |
| La tua app | Avvio dell'accesso, conservazione del verificatore PKCE e di `state`, gestione dei token e invio del token di accesso al tuo backend. Gli SDK si occupano di tutto. |
| La tua origine di accesso | `https://<slug>.auth.didit.me` (oppure il tuo [dominio personalizzato](https://docs.didit.me/it/authentication/branding-and-custom-domain.md#dominio-personalizzato)): le pagine ospitate, l'endpoint dei token, la sessione, il discovery e le chiavi di firma. |
| Il tuo backend | Verifica del token di accesso a ogni richiesta protetta, controllo della sessione prima di azioni sensibili e decisione su cosa la persona può fare. |
| Console Didit e webhook | Configurazione, persone e relative sessioni, eventi di accesso e i webhook `auth.*` a cui il tuo server è iscritto. |

Nella tua app non deve mai trovarsi alcuna chiave API Didit né alcun segreto: la chiave pubblicabile è pubblica, e lo scambio del codice è protetto da PKCE invece che da un segreto del client.

## Pagine ospitate o schermate proprie

Scegli dove le persone digitano la propria email, password o codice.
L'impostazione è `sign_in_ui` (`hosted` per impostazione predefinita, oppure `own`), e puoi modificarla in seguito.

| | Pagine ospitate (consigliato) | Schermate proprie |
| - | - | - |
| Cosa sviluppi | Un pulsante di accesso e una pagina di callback. | Ogni schermata e ogni passaggio intermedio. |
| Metodi | Tutti, inclusi i link magici, l'SSO aziendale e le passkey. | Password, codice via email, codice via telefono, MFA e challenge di protezione tramite i metodi headless degli SDK. I link magici funzionano solo sulle pagine ospitate. |
| Passaggi successivi | Gestiti per te: MFA, configurazione MFA, challenge di protezione e verifica in fase di registrazione. | Le tue schermate gestiscono `mfa_required`, `mfa_enrollment_required`, `protection_required` e `verification_required`. Vedi [metodi di accesso](https://docs.didit.me/it/authentication/sign-in-methods.md). |
| Marchio | Il tuo logo, i tuoi colori e i tuoi testi da [personalizzazione del brand](https://docs.didit.me/it/authentication/branding-and-custom-domain.md). | Completamente tuo. |
| Configurazione | URL di reindirizzamento. | URL di reindirizzamento, più la tua origine web in **Allowed origins**. |

Le passkey appartengono all'origine di accesso della tua applicazione.
I metodi passkey degli SDK funzionano solo sulle pagine servite da quell'origine, quindi, nelle tue schermate proprie su un altro dominio, indirizza le persone alla pagina ospitata per le passkey.

## Scegli il tuo SDK

| La tua app | Pacchetto | Dove vengono conservati i token |
| - | - | - |
| App web a pagina singola | [`@didit-protocol/auth`](https://docs.didit.me/it/authentication/quickstarts/javascript) o [`@didit-protocol/auth-react`](https://docs.didit.me/it/authentication/quickstarts/react) | Archiviazione web o memoria nel browser. Mantieni una Content Security Policy rigorosa. |
| App web renderizzata lato server | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/it/authentication/quickstarts/nextjs) | Cookie HttpOnly impostati dal tuo server. La pagina non vede mai i token. |
| iOS | [`DiditAuth`](https://docs.didit.me/it/authentication/quickstarts/ios) | Il Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/it/authentication/quickstarts/android) | Archiviazione protetta dall'Android Keystore. |
| React Native o Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/it/authentication/quickstarts/react-native) o [`didit_auth`](https://docs.didit.me/it/authentication/quickstarts/flutter) | L'archiviazione protetta della piattaforma, tramite i moduli nativi. |
| Qualsiasi backend | [SDK per server](https://docs.didit.me/it/integration/server-sdks/overview.md), `verifyToken` da `@didit-protocol/auth/server`, oppure qualsiasi libreria JWT | Nulla da conservare: verifica il token che riceve. |

Senza un SDK, implementa tu stesso il flusso del codice di autorizzazione con PKCE: la [guida rapida JavaScript](https://docs.didit.me/it/authentication/quickstarts/javascript.md#senza-l’sdk) mostra l'intero contratto.

## Proteggi il tuo backend

Un controllo della sessione lato frontend regola solo ciò che mostri.
Il tuo backend prende ogni decisione a partire da un token verificato.

1. **Verifica il token di accesso a ogni richiesta.** Controlla la firma ES256 rispetto al JWKS dell'emittente, poi `iss`, `aud`, `exp` e `typ: at+jwt`, e rifiuta un token il cui `act` non sia `null`, a meno che l'endpoint non accetti [agenti AI](https://docs.didit.me/it/authentication/agent-access.md). Vedi [come verificare un token sul tuo server](https://docs.didit.me/it/authentication/tokens-and-jwks.md#verifica-un-token-sul-tuo-server).
2. **Controlla la sessione attiva prima di un'azione sensibile.** Un token di accesso resta valido fino alla scadenza, entro 5 minuti. `GET /session/` fallisce subito quando la sessione è stata revocata, è rimasta inattiva o è scaduta, quando la persona è stata bloccata, o quando la sessione non rispetta più la tua policy MFA. Vedi [controllo della sessione](https://docs.didit.me/it/authentication/tokens-and-jwks.md#controlla-la-sessione).
3. **Richiedi uno step-up quando l'azione è rischiosa.** Prima di un'erogazione o di un pagamento in uscita, di un nuovo conto bancario o di una modifica dell'email o del telefono, chiedi a Didit se la persona deve verificarsi di nuovo, e agisci solo su uno step-up `approved` che il tuo backend ha letto direttamente. Vedi [step-up prima delle azioni sensibili](https://docs.didit.me/it/authentication/verified-identity.md#step-up-prima-delle-azioni-sensibili).
4. **Prendi `vendor_data` dal token verificato**, mai da un campo inviato dal browser, e usalo per le verifiche e le transazioni della persona.

## Sessioni

| Evento | Cosa succede |
| - | - |
| Accesso | Viene avviata una sessione. La sua durata è definita da `session_lifetime` (30 giorni per impostazione predefinita) e termina prima dopo un periodo di inattività pari a `idle_timeout` (1 giorno per impostazione predefinita). |
| Ogni pochi minuti | L'SDK aggiorna il token di accesso, che dura al massimo 5 minuti. Il token di aggiornamento viene ruotato: ognuno funziona una sola volta. |
| Un token di aggiornamento già usato viene inviato di nuovo | Didit lo considera un furto e termina la sessione. Esegui un solo aggiornamento alla volta per sessione. |
| Accesso da un altro dispositivo | Con `multiple_sessions: false`, le altre sessioni della persona terminano. |
| Reimpostazione della password | Tutte le sessioni terminano quando `revoke_on_password_change` è attivo (impostazione predefinita). |
| Disconnessione | `DELETE /session/` termina la sessione e la tua app reindirizza la persona a `post_logout_redirect_uri`. |
| Il tuo team interviene | La console può revocare una singola sessione, disconnettere una persona da tutte le sessioni oppure bloccarla. Consulta la [guida alla console](https://docs.didit.me/it/authentication/console.md#accessi-e-sessioni). |

Puoi modificare le durate in **Authentication > Security and sessions** oppure tramite API nelle [impostazioni dell'applicazione](https://docs.didit.me/it/authentication/overview.md#impostazioni-dell’applicazione).

![La vista Active sessions nella Didit Business Console, che elenca le sessioni attive con dispositivo, posizione, inizio, ultima attività, fine e un pulsante Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, con Revoke su ogni sessione.

## App native

Didit reindirizza le persone verso un'app nativa solo tramite reindirizzamento HTTPS: non accetta schemi URL personalizzati.

* **iOS:** configura il reindirizzamento come dominio associato, con `webcredentials` nel tuo `apple-app-site-association`.
* **Android:** configura il reindirizzamento come App Link, con il tuo `assetlinks.json`.
* Registra ogni URL di reindirizzamento in **Authentication > Security and sessions**, come un callback web.

Per le passkey nella tua app, registra le app che condividono le passkey della tua applicazione con `PUT native-apps/` tramite la [API di gestione dell'autenticazione](https://docs.didit.me/it/authentication/set-up-by-api.md).
Didit include poi queste app nell'`apple-app-site-association` e nell'`assetlinks.json` che pubblica sulla tua origine di accesso.
`MANAGEMENT_BASE` è l'indirizzo dell'API di gestione della tua applicazione, e una chiave API con lo scope `authentication` in scrittura può effettuare la chiamata.
La chiamata sostituisce entrambi gli elenchi, quindi inviali entrambi:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Campo | Regola |
| - | - |
| `ios_app_ids` | Fino a 10 voci, composte dal tuo Team ID e dall'identificatore del bundle, per esempio `ABCDE12345.com.example.app`. |
| `android_apps` | Fino a 10 app, ognuna con il proprio `package_name` e da 1 a 5 impronte digitali SHA-256 del certificato di firma. |

Le guide rapide per [iOS](https://docs.didit.me/it/authentication/quickstarts/ios.md) e [Android](https://docs.didit.me/it/authentication/quickstarts/android.md) mostrano il lato app.

## Collega la verifica dell'identità e il monitoraggio delle transazioni

Ogni persona ha un unico valore `vendor_data`, nei suoi token e nella sua sessione.
Usalo come `vendor_data` quando [crei una sessione di verifica](https://docs.didit.me/it/sessions-api/create-session.md) o [invii una transazione](https://docs.didit.me/it/transaction-monitoring/transactions.md), e la console mostra accessi, verifiche e transazioni riferiti alla stessa persona.

* Per verificare le persone in fase di registrazione o di nuovo prima di un pagamento, senza costruire un flusso di verifica, usa [identità verificata](https://docs.didit.me/it/authentication/verified-identity.md).
* Gli eventi di accesso arrivano automaticamente alle [regole sugli eventi](https://docs.didit.me/it/transaction-monitoring/event-rules.md) e alle viste antifrode. Non inviare i tuoi eventi `auth.login` per gli stessi accessi.
* Un accesso riuscito non approva mai una verifica o una transazione: gestisci separatamente la decisione di ciascun prodotto.

Vedi [mantieni la stessa persona tra i prodotti](https://docs.didit.me/it/authentication/overview.md#mantieni-la-stessa-persona-tra-i-prodotti).

## Ricevere gli eventi di accesso

Sottoscrivi una [destinazione webhook](https://docs.didit.me/it/integration/webhooks.md) ai tipi `auth.*` di cui hai bisogno, come `auth.new_device` o `auth.account_locked`.
Deduplica in base a `auth_event.event_id` e verifica la firma come per ogni webhook di Didit.
Consulta [eventi e webhook](https://docs.didit.me/it/authentication/events-and-webhooks.md) per ogni tipo e il relativo payload.

## Sposta gli utenti esistenti

Se i tuoi utenti hanno già un account su un'altra piattaforma di identità o nel tuo database, [importali](https://docs.didit.me/it/authentication/migration.md) prima di passare all'accesso con Didit.
Importa gli hash delle password dove la fonte li fornisce, mantieni i collegamenti social e conserva i tuoi ID utente come `external_id`, che diventa il loro `vendor_data`.
Per gli utenti non cambia nulla finché non passi la tua app a Didit.

## Checklist per il go-live

1. L'autenticazione è attiva per la tua applicazione Live nella pagina **Products**.
2. Gli URL di reindirizzamento `https://` di produzione e le origini consentite sono registrati nell'applicazione Live. Un'applicazione Live non accetta indirizzi `http://`.
3. Ogni metodo di accesso social usa il client ID e il secret della tua app: le credenziali di test di Didit funzionano solo in sandbox.
4. La configurazione di produzione contiene la chiave pubblicabile Live (`pk_live_`) e il tuo issuer Live.
5. La policy MFA, la durata della sessione, il timeout di inattività, la lunghezza della password e la policy di registrazione sono quelle che desideri. Vedi [impostazioni dell'applicazione](https://docs.didit.me/it/authentication/overview.md#impostazioni-dell’applicazione).
6. La [protezione dai bot](https://docs.didit.me/it/authentication/bot-protection.md) è attiva, con il controllo delle password compromesse.
7. Il tuo backend verifica ogni access token e chiama `GET /session/` prima delle azioni sensibili.
8. Il branding, i testi delle pagine e i link ai termini e all'informativa sulla privacy sono configurati. Se prevedi di usare un [dominio personalizzato](https://docs.didit.me/it/authentication/branding-and-custom-domain.md#dominio-personalizzato), attivalo prima che le persone inizino ad aggiungere passkey.
9. La tua destinazione webhook è iscritta ai tipi `auth.*` che gestisci.
10. Hai testato sull'applicazione Live la registrazione, l'accesso di chi è già registrato, l'annullamento, il recupero della password, MFA, la scadenza della sessione, il logout e una sessione revocata.

## Risoluzione dei problemi

| Sintomo | Causa e soluzione |
| - | - |
| Ogni route di runtime risponde `404` | L'autenticazione è disattivata per l'applicazione, oppure l'indirizzo combina un'origine sandbox e un'origine di produzione. Attivala dalla pagina **Products** e usa l'origine indicata dalla tua chiave pubblicabile. |
| La pagina di accesso risponde `400` e chiede di registrare un indirizzo, oppure `POST /authorize/` risponde `invalid_redirect_uri` | Il `redirect_uri` non è registrato esattamente: schema, host, porta, percorso e query devono corrispondere carattere per carattere. Vedi [URL di reindirizzamento](https://docs.didit.me/it/authentication/overview.md#url-di-reindirizzamento). |
| Una chiamata del browser alla tua origine di accesso risponde `403` con `origin_not_allowed` | La tua origine web non è in **Allowed origins**. Aggiungila senza percorso e senza barra finale. |
| `POST /token/` risponde `invalid_grant` | Il codice è già stato usato, ha più di 60 secondi, oppure è stato inviato con un altro verificatore PKCE o un altro `redirect_uri`. In caso di aggiornamento, il refresh token è già stato usato, il che termina la sessione. Avvia di nuovo l'accesso. |
| Un accesso con password risponde `invalid_credentials` anche con la password corretta | L'email non è verificata, oppure l'account è bloccato o sospeso. Didit fornisce deliberatamente la stessa risposta. Controlla la persona in **Users**. |
| `GET /session/` risponde `401` | La sessione è stata revocata, è diventata inattiva o è scaduta, la persona è stata bloccata, il token è stato sostituito durante un refresh, oppure la sessione non soddisfa più la tua policy MFA. Aggiorna il token oppure fai di nuovo l'accesso della persona. |
| L'aggiunta di una passkey o di un autenticatore risponde `403 reauthentication_required` | Queste operazioni richiedono una sessione creata negli ultimi 5 minuti. Prima fai di nuovo l'accesso della persona. |
| Un codice via telefono risponde `503 delivery_unavailable` | Il codice non è stato consegnato. Lascia che la persona riprovi oppure proponi un altro metodo. |
| Una chiamata risponde `429` | Hai raggiunto un limite di frequenza. Riprova dopo il tempo indicato in `Retry-After`. Vedi [limiti di frequenza](https://docs.didit.me/it/authentication/bot-protection.md#limiti-di-frequenza). |
| Una chiamata di configurazione con una chiave API risponde `409 product_disabled` | L'autenticazione è disattivata per l'applicazione. Una persona la attiva dalla console. |
| Una chiamata risponde `403 plan_required` | La funzionalità, come i ruoli personalizzati o i link di configurazione SSO aziendale, richiede il piano Scale o Enterprise. Le applicazioni sandbox la includono in qualsiasi piano. |
| I token non funzionano dopo che hai attivato un dominio personalizzato | L'emittente e la chiave pubblicabile sono cambiati. Copia la nuova chiave nella tua app e aggiorna l'emittente che il tuo backend verifica. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.