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.
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 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: 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 e revision_id, poi pubblicala. 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:

{
  "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).
`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).

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.
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

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

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