# Accesso degli utenti di test con keenauth test login

`keenauth test login` accede a un ambiente `development` come utente di test e stampa i token, così puoi chiamare la tua API o testare il tuo backend senza passare dalla pagina di accesso. Passa per il vero login ospitato, nello stesso modo in cui lo farebbe un browser, e usa il codice fisso di sviluppo `424242` (vedi [Utenti e messaggi di test negli ambienti non di produzione](/docs/guides/test-environments)).

Il comando non richiede né una chiave API né una sessione `keenauth login`: accede come utente di test, non come te.

## Prima di iniziare

- **Un utente di test.** L'indirizzo deve contenere il tag `+test` nella parte locale, per esempio `ada+test@example.com` o `ada+test_1@example.com`. Crea prima l'utente, per esempio con `keenauth users create --email ada+test@example.com`. Il comando rifiuta qualsiasi altro indirizzo prima di inviare una richiesta, ed esce con codice 2.
- **Un'applicazione pubblica.** Passa l'ID di un'applicazione nativa o single-page dell'ambiente con `--client-id`. L'applicazione deve consentire l'accesso con un codice email (senza password, `email_otp`).
- **Un URI di reindirizzamento.** Per impostazione predefinita il comando usa `http://127.0.0.1:<porta casuale>/callback`. Registra `http://127.0.0.1/callback` per l'applicazione: un URI di reindirizzamento loopback accetta qualsiasi porta (RFC 8252). Nessuno ascolta su quell'indirizzo; il comando legge il reindirizzamento da solo. Per usare un altro URI di reindirizzamento registrato, passa `--redirect-uri`.
- **L'issuer dell'ambiente.** Passalo con `--issuer` oppure imposta `KEENAUTH_ISSUER`, per esempio `https://acme-dev.keenauth.app`.

## Utilizzo

```sh
export KEENAUTH_ISSUER=https://acme-dev.keenauth.app
keenauth test login --user ada+test@example.com --client-id app_01j9z3k4m5n6p7q8r9s0t1v2w3
```

| Flag | Descrizione |
|---|---|
| `--user` | Indirizzo email dell'utente di test (obbligatorio). |
| `--client-id` | ID di un'applicazione pubblica dell'ambiente (obbligatorio). |
| `--issuer` | URL dell'issuer dell'ambiente. Predefinito: la variabile d'ambiente `KEENAUTH_ISSUER`. |
| `--scope` | Scope da richiedere, separati da spazi. Predefinito: `openid profile email`. Aggiungi `offline_access` per ricevere un refresh token. |
| `--resource` | Indicatore della risorsa dell'API per cui è destinato l'access token (RFC 8707). |
| `--redirect-uri` | Un URI di reindirizzamento registrato per l'applicazione. |
| `--output`, `-o` | `json`, `yaml` o `table`. Senza il flag la CLI stampa una tabella su un terminale e JSON altrimenti. |

L'output contiene `token_type`, `access_token`, `id_token` (quando è richiesto `openid`), `refresh_token` (solo quando è richiesto `offline_access`), `expires_in` e `scope`. Tratta i token come password: agiscono come utente di test finché non scadono. Il comando li scrive su stdout e da nessun'altra parte, e non stampa mai il codice.

```sh
ACCESS_TOKEN=$(keenauth test login --user ada+test@example.com --client-id app_01j9z3k4m5n6p7q8r9s0t1v2w3 -o json | jq -r .access_token)
curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/orders
```

## Cosa fa il comando

1. Legge il documento di discovery dell'ambiente e apre una richiesta di autorizzazione con PKCE (`S256`), `state` e `nonce`.
2. Nel login ospitato inserisce l'indirizzo, chiede un codice email e invia `424242`. Se l'ambiente chiede poi un codice email come secondo fattore, chiede quel codice e invia di nuovo `424242`.
3. Segue il reindirizzamento verso l'URI di reindirizzamento, verifica `state` e `iss`, e scambia il codice di autorizzazione all'endpoint dei token.
4. Verifica che l'ID token sia stato emesso dall'issuer per la tua applicazione con il `nonce` della richiesta, e stampa i token.

Il comando si interrompe con un errore quando l'accesso richiede altro, per esempio una password, una passkey, un'app autenticatore, il Single Sign-On aziendale per il dominio dell'indirizzo, una pagina di consenso o la scelta di un'organizzazione.

## Ambienti

Solo gli ambienti `development` accettano il codice fisso. Usa il comando solo con un ambiente di sviluppo:

- In `staging` non viene inviato nulla agli indirizzi di test, ma il codice fisso viene rifiutato (`401 invalid_credentials`).
- In `production` un indirizzo `+test` è un indirizzo normale: il codice email viene davvero inviato, e il codice fisso viene rifiutato.

Quando il server rifiuta un passaggio, la CLI stampa la sua risposta di problema senza modifiche (`error`, `code`, `status`, `detail`, `request_id`), per esempio `code: test_feature_not_in_production`.

## Codici di uscita

| Codice | Significato |
|---|---|
| `0` | L'utente di test ha effettuato l'accesso; i token vengono stampati. |
| `1` | L'accesso non è riuscito: un errore OAuth, una mancata corrispondenza di `state`, `iss` o `nonce`, oppure un passaggio che il comando non può completare. |
| `2` | Errore di utilizzo: l'indirizzo non ha il tag `+test`, manca un flag obbligatorio o l'issuer, oppure un valore non è valido. Nessuna richiesta è stata inviata. |
| `3` | Il server ha risposto `401` o `403`, per esempio `invalid_credentials` o `test_feature_not_in_production`. |