# Importa i metadati IdP SAML in una connessione

`POST /v1/connections/{connection_id}:import-metadata` · autorizzazione `connections:write`

Applica al connessione SAML enterprise un documento di metadati SAML 2.0 caricato dal provider di identità.

- La parte del provider di identità della connessione (entity ID, URL di single sign-on con HTTP-Redirect, URL di single logout) viene sostituita con i valori del documento.
- I certificati di firma nel documento che non sono ancora scaduti e non sono ancora registrati vengono aggiunti (`source` è `manual`). I certificati già presenti nella connessione restano attivi; eliminali con [Elimina un certificato](../connection-certificates/delete.md).
- La connessione ora segue il documento caricato: un URL dei metadati memorizzato e il pinning dei certificati vengono cancellati.
- La modifica invalida l'ultimo [test della connessione](test.md) superato; per attivare la connessione serve un nuovo test superato.

Su una connessione **attiva**, un documento che modifica l'entity ID o l'URL SSO del provider di identità, oppure che rimuove un pin di firma, non viene applicato. L'intera importazione diventa una [bozza di revisione](revisions.md): la risposta mostra la parte del provider di identità attiva, invariata, `added_certificate_fingerprints` è vuoto e `revision` è valorizzato. Testa la bozza con [Testa una connessione](test.md) e `revision_id`, poi [pubblicala](publish-revision.md). Le altre importazioni (nuovi certificati, URL SLO, valori MFA) vengono applicate direttamente.

Il documento viene analizzato con limiti rigidi (massimo 1 MiB, nessun `DOCTYPE`). Quando il documento non è valido la risposta non indica il motivo e né il motivo né il contenuto del documento vengono registrati nei log. Un documento con più elementi `EntityDescriptor` richiede `entity_id`. La richiesta non accetta l'header `If-Match` perché il materiale SAML non ha una versione. Le scritture vengono registrate in audit come `connection.idp_metadata_imported`, più `connection.idp_certificate_added` per ogni nuovo certificato.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | path | sì | ID della connessione SAML enterprise (`conn_…`). |
| `metadata_xml` | string | sì | Il documento di metadati (`EntityDescriptor` o `EntitiesDescriptor`), massimo 1 MiB. |
| `entity_id` | string | per più entità | L'entity ID del provider di identità da prendere da un documento con più entità. Con una sola entità deve corrispondere. |
| `mfa_authn_context_values` | array \| null | no | Valori `AuthnContextClassRef` di SAML che il provider di identità considera autenticazione a più fattori (massimo 10). Quando sono indicati (anche una lista vuota) vengono memorizzati; quando sono omessi o `null` vengono mantenuti quelli memorizzati. |

## Risposta

`200 OK`:

```json
{
  "idp_entity_id": "https://idp.example.com/entity",
  "idp_sso_url": "https://idp.example.com/sso/redirect",
  "idp_slo_url": null,
  "certificates": [
    {"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
  ],
  "added_certificate_fingerprints": ["3b0c…"]
}
```

| Campo | Descrizione |
|---|---|
| `idp_entity_id`, `idp_sso_url`, `idp_slo_url` | La parte del provider di identità dopo l'importazione; `idp_slo_url` è `null` quando il documento non ha un servizio di single logout. |
| `certificates` | I certificati di firma attivi della connessione (vedi [Elenca i certificati](../connection-certificates/list.md)). |
| `added_certificate_fingerprints` | Impronte SHA-256 dei certificati aggiunti da questa importazione; i certificati già registrati non sono elencati. |
| `revision` | Solo quando l'importazione è diventata una bozza di revisione: la bozza (vedi [Elenca le revisioni](revisions.md)). |

## Errori

| HTTP | code | Quando |
|---|---|---|
| 404 | `not_found` | La connessione non esiste in questo ambiente o non è una connessione enterprise. |
| 409 | `conflict` | La connessione non è una connessione SAML, non ha ancora una configurazione SAML oppure l'importazione supererebbe 3 certificati attivi (non viene modificato nulla). |
| 422 | `validation_failed` | Il documento o un campo non è valido; `errors[]` indica il campo (`/metadata_xml`, `/entity_id`, `/mfa_authn_context_values`). Negli ambienti di staging e produzione viene rifiutato anche un provider di identità di test su `/metadata_xml`: un entity ID nel dominio riservato `.invalid`, oppure la chiave pubblica di test del [server mock locale](/docs/cli/mock-server). |
| 413 | `payload_too_large` | Il corpo della richiesta supera 4 MiB. |
| 400 | `unknown_field` | Il corpo contiene un campo sconosciuto. |
| 401 | `unauthenticated` | La credenziale è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha l'autorizzazione richiesta. |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

```bash
jq -Rs '{metadata_xml: .}' idp-metadata.xml > import.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:import-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @import.json
```

```bash
keenauth connections import-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --metadata-file idp-metadata.xml
```