Scarica i metadati SAML SP di una connessione

GET /v1/connections/{connection_id}/sp-metadata · autorizzazione connections:read

Scarica il documento firmato dei metadati SAML 2.0 del service provider (SP) di una connessione SAML enterprise: il file che l'amministratore del provider di identità carica nel provider di identità. È lo stesso documento che serve l'indirizzo pubblico dei metadati della connessione (https://<host SP>/saml/<conn_…>/metadata):

entityID, validUntil (7 giorni in avanti) e cacheDuration (PT24H);
i certificati di firma e di cifratura (due per ciascuno durante la finestra annuale di rotazione delle chiavi);
i NameID format supportati, l'assertion consumer service (HTTP-POST) e gli endpoint di single logout;
una firma XML enveloped creata con la chiave di firma SP attiva della connessione.

Le chiavi SP vengono create al primo utilizzo se non esistono ancora. Il documento non contiene segreti. Le letture non vengono registrate nel log di audit.

Con revision_id ottieni invece il documento di una revisione in bozza. Per una migrazione dell'host SP contiene gli endpoint sul nuovo host: consegnalo all'amministratore del provider di identità prima di pubblicare la revisione.

Richiesta

Campo	Tipo	Obbligatorio	Descrizione
`connection_id`	path	sì	ID della connessione enterprise (`conn_…`).
`revision_id`	query	no	Una revisione in bozza della connessione (`connrev_…`).

Risposta

200 OK con il documento XML nel corpo:

Header	Valore
`Content-Type`	`application/samlmetadata+xml`
`Content-Disposition`	`attachment; filename="<conn_…>-sp-metadata.xml"`
`Cache-Control`	`no-store`

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    ID="_…" entityID="https://acme.eu.keenauth.app/saml/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/metadata"
    validUntil="2026-11-02T10:00:00Z" cacheDuration="PT24H">
  <ds:Signature>…</ds:Signature>
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    …
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Errori

HTTP	code	Quando
404	`not_found`	La connessione non esiste in questo ambiente oppure non è una connessione enterprise.
409	`conflict`	La connessione non è una connessione SAML, oppure non ha ancora una configurazione SAML.
422	`validation_failed`	`revision_id` è malformato o ripetuto (`invalid_value`, `repeated`), oppure non è una revisione in bozza di questa connessione (`not_found`); `errors[]` punta a `/revision_id`.
401	`unauthenticated`	La credenziale manca, non è valida o è stata 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 non è disponibile temporaneamente; riprova dopo il periodo indicato in `Retry-After`.

Esempio

curl -o sp-metadata.xml "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/sp-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

keenauth connections sp-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --file sp-metadata.xml

Senza --file la CLI scrive l'XML sullo standard output. Un file esistente non viene mai sovrascritto.