# Descargar los metadatos SAML del SP de una conexión

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

Descarga el documento de metadatos firmado del proveedor de servicios (SP) SAML 2.0 de una conexión empresarial SAML: el archivo que el administrador del proveedor de identidad carga en dicho proveedor. Es el mismo documento que sirve la dirección pública de metadatos de la conexión (`https://<host del SP>/saml/<conn_…>/metadata`):

- `entityID`, `validUntil` (7 días a partir de ahora) y `cacheDuration` (`PT24H`);
- los certificados de firma y de cifrado (dos de cada uno durante una ventana anual de rotación de claves);
- los formatos de NameID admitidos, el servicio de consumo de aserciones (HTTP-POST) y los puntos de cierre de sesión único;
- una firma XML envolvente creada con la clave de firma activa del SP de la conexión.

Las claves del SP se crean en el primer uso si aún no existen. El documento no contiene ningún secreto. Las lecturas no se auditan.

Con `revision_id` obtiene en su lugar el documento de una [revisión en borrador](revisions.md). En el caso de una [migración del host del SP](migrate-sp-host.md), incluye los endpoints del nuevo host: entréguelo al administrador del proveedor de identidad antes de publicar la revisión.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `connection_id` | ruta | sí | ID de la conexión empresarial (`conn_…`). |
| `revision_id` | consulta | no | Una revisión en borrador de la conexión (`connrev_…`). |

## Respuesta

`200 OK` con el documento XML como cuerpo:

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

```xml
<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>
```

## Errores

| HTTP | code | Cuándo |
|---|---|---|
| 404 | `not_found` | La conexión no existe en este entorno o no es una conexión empresarial. |
| 409 | `conflict` | La conexión no es una conexión SAML o todavía no tiene configuración SAML. |
| 422 | `validation_failed` | `revision_id` está mal formado o se repite (`invalid_value`, `repeated`), o no es una revisión en borrador de esta conexión (`not_found`); `errors[]` apunta a `/revision_id`. |
| 401 | `unauthenticated` | La credencial falta, no es válida o ha sido revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene el permiso necesario. |
| 429 | `rate_limited` | Se superó el límite de tasa; reintente después del período indicado en `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del período indicado en `Retry-After`. |

## Ejemplo

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

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

Sin `--file`, la CLI escribe el XML en la salida estándar. Un archivo existente nunca se sobrescribe.