Aggiungi un certificato di firma IdP a una connessione

POST /v1/connections/{connection_id}/certificates · permesso connections:write

Aggiunge a una connessione SAML enterprise un certificato di firma del provider di identità. Usala per caricare il certificato a mano o per ruotare i certificati: aggiungi prima il nuovo certificato, passa il provider di identità a quello nuovo, poi elimina il vecchio. La rotazione ha effetto immediato, anche su una connessione attiva.

Il certificato è un unico blocco PEM CERTIFICATE (al massimo 8 KiB). Non deve essere scaduto e deve avere una chiave RSA di almeno 2048 bit oppure una chiave ECDSA P-256, P-384 o P-521. Quando viene rifiutato, la risposta non indica il motivo e né il motivo né il contenuto del certificato vengono registrati. Una connessione ha al massimo 3 certificati attivi. Un certificato eliminato dalla connessione non può essere aggiunto di nuovo. La richiesta non accetta l'header If-Match. Le scritture vengono registrate come connection.idp_certificate_added.

Richiesta

Campo Tipo Obbligatorio Descrizione
connection_id percorso sì ID della connessione SAML enterprise (conn_…).
certificate stringa sì Un certificato PEM (-----BEGIN CERTIFICATE----- …), al massimo 8 KiB.

Risposta

201 Created con il nuovo certificato (vedi Elenca i certificati). Quando lo stesso certificato è già presente sulla connessione, la risposta è 200 OK con il certificato registrato; non viene scritto né tracciato nulla.

{"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}

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, ha già 3 certificati attivi, oppure il certificato è stato eliminato da essa in precedenza.
422 validation_failed Il certificato manca, è troppo grande o non viene accettato; errors[] indica /certificate. Gli ambienti di staging e produzione rifiutano anche un certificato uguale alla chiave pubblica di prova del server mock locale.
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 il permesso richiesto.
429 rate_limited È stato superato il limite di frequenza; riprova dopo il periodo indicato da Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato da Retry-After.

Esempio

jq -Rs '{certificate: .}' idp-signing.pem > cert.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/certificates" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @cert.json

keenauth connections certificates add conn_01j9xp6q0r1s5t7v9w1x3y5z7b --certificate-file idp-signing.pem