# Imposta l'accesso avviato dall'IdP per una connessione SAML

`PUT /v1/connections/{connection_id}/idp-initiated` · autorizzazione `connections:write`

Consente o disattiva l'accesso avviato dall'IdP (una risposta SAML non richiesta inviata dal portale delle applicazioni del provider di identità) per una connessione SAML enterprise, e imposta le applicazioni in cui l'utente può atterrare. È disattivato per impostazione predefinita.

- **Sostituzione completa:** ogni richiesta scrive tutti e tre i campi. Un `idp_initiated_default_application_id` omesso e un `idp_initiated_allowed_application_ids` vuoto vengono cancellati.
- **Destinazioni:** ogni applicazione deve esistere in questo ambiente, far accedere gli utenti tramite browser (non client machine-to-machine, di gestione o client con documento di metadati di ID client) e avere un `initiate_login_uri`. Dopo l'accesso il browser viene inviato a quell'indirizzo con `iss`, e l'applicazione avvia la propria richiesta di autorizzazione con `state` e PKCE.
- **RelayState:** quando il provider di identità invia un RelayState, seleziona un'applicazione solo se è uguale byte per byte al `client_id` di quell'applicazione e l'applicazione è quella predefinita o è nell'elenco consentito. Il RelayState non viene mai trattato come URL.
- **Sicurezza:** questa impostazione accetta risposte che i tuoi utenti non hanno avviato, quindi un utente della dashboard ha bisogno di un'autenticazione di step-up recente e del ruolo `owner` o `admin`. L'Admin Portal non può modificarla.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | path | sì | ID della connessione SAML enterprise (`conn_…`). |
| `If-Match` | header | no | L'`ETag` della connessione. Un valore obsoleto fallisce con `412`. |
| `allow_idp_initiated` | boolean | sì | Accetta risposte SAML non richieste. `true` richiede `idp_initiated_default_application_id`. |
| `idp_initiated_default_application_id` | string \| null | quando abilitato | Applicazione (`app_…`) usata quando il RelayState è vuoto. |
| `idp_initiated_allowed_application_ids` | array | no | Applicazioni (`app_…`) che un RelayState può selezionare; univoche, al massimo 20. |

## Risposta

`200 OK` con la connessione (vedi [Ottieni una connessione](../connections/get.md)) e il nuovo `ETag`. La connessione mostra i valori memorizzati in `allow_idp_initiated`, `idp_initiated_default_application_id` e `idp_initiated_allowed_application_ids`.

## Errori

| HTTP | code | Quando |
|---|---|---|
| 404 | `not_found` | La connessione non esiste in questo ambiente. |
| 412 | `precondition_failed` | `If-Match` non corrisponde alla versione corrente. |
| 422 | `validation_failed` | La connessione non è una connessione SAML enterprise, l'applicazione predefinita manca quando è abilitato, oppure un'applicazione non rispetta le regole di destinazione; `errors[]` indica il campo. |
| 400 | `unknown_field` | Il corpo contiene un campo sconosciuto. |
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha l'autorizzazione richiesta. |
| 403 | `step_up_required` | Un utente della dashboard non ha completato un'autenticazione di step-up recente. |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza non è disponibile temporaneamente; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/idp-initiated" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_idp_initiated":true,"idp_initiated_default_application_id":"app_01j9xp6q0r1s5t7v9w1x3y5z7c","idp_initiated_allowed_application_ids":["app_01j9xp6q0r1s5t7v9w1x3y5z7c"]}'
```

```bash
keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'
```