# Définir la connexion initiée par le fournisseur d'identité pour une connexion SAML

`PUT /v1/connections/{connection_id}/idp-initiated` · autorisation `connections:write`

Autorise ou désactive la connexion initiée par le fournisseur d'identité (une réponse SAML non sollicitée envoyée depuis le portail d'applications du fournisseur d'identité) pour une connexion SAML d'entreprise, et définit les applications dans lesquelles l'utilisateur peut arriver. Elle est désactivée par défaut.

- **Remplacement complet :** chaque requête écrit les trois champs. Un `idp_initiated_default_application_id` omis et un `idp_initiated_allowed_application_ids` vide sont effacés.
- **Cibles :** chaque application doit exister dans cet environnement, authentifier les utilisateurs via un navigateur (et non en machine à machine, de gestion ou via un document de métadonnées de client ID) et disposer d'un `initiate_login_uri`. Après la connexion, le navigateur est redirigé vers cette adresse avec `iss`, et l'application lance sa propre requête d'autorisation avec `state` et PKCE.
- **RelayState :** lorsque le fournisseur d'identité envoie un RelayState, celui-ci ne sélectionne une application que s'il est identique octet par octet au `client_id` de cette application, et si l'application est celle par défaut ou figure dans la liste autorisée. Le RelayState n'est jamais traité comme une URL.
- **Sécurité :** ce paramètre accepte des réponses que vos utilisateurs n'ont pas initiées ; un utilisateur du tableau de bord doit donc effectuer une authentification renforcée récente et avoir le rôle `owner` ou `admin`. Le portail d'administration ne permet pas de le modifier.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `connection_id` | path | oui | Identifiant de la connexion SAML d'entreprise (`conn_…`). |
| `If-Match` | header | non | L'`ETag` de la connexion. Une valeur périmée échoue avec `412`. |
| `allow_idp_initiated` | boolean | oui | Accepter les réponses SAML non sollicitées. `true` exige `idp_initiated_default_application_id`. |
| `idp_initiated_default_application_id` | string \| null | si activé | Application (`app_…`) utilisée lorsque le RelayState est vide. |
| `idp_initiated_allowed_application_ids` | array | non | Applications (`app_…`) qu'un RelayState peut sélectionner ; valeurs uniques, 20 au maximum. |

## Réponse

`200 OK` avec la connexion (voir [Obtenir une connexion](../connections/get.md)) et son nouvel `ETag`. La connexion affiche les valeurs enregistrées dans `allow_idp_initiated`, `idp_initiated_default_application_id` et `idp_initiated_allowed_application_ids`.

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 404 | `not_found` | La connexion n'existe pas dans cet environnement. |
| 412 | `precondition_failed` | `If-Match` ne correspond pas à la version actuelle. |
| 422 | `validation_failed` | La connexion n'est pas une connexion SAML d'entreprise, l'application par défaut est absente alors que la fonctionnalité est activée, ou une application ne respecte pas les règles de cible ; `errors[]` indique le champ concerné. |
| 400 | `unknown_field` | Le corps de la requête contient un champ inconnu. |
| 401 | `unauthenticated` | L'identifiant est absent, invalide ou révoqué. |
| 403 | `insufficient_permissions` | L'identifiant ne dispose pas de l'autorisation requise. |
| 403 | `step_up_required` | Un utilisateur du tableau de bord n'a pas effectué d'authentification renforcée récente. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la période indiquée par `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez après la période indiquée par `Retry-After`. |

## Exemple

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/idp-initiated" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_idp_initiated":true,"idp_initiated_default_application_id":"app_01j9xp6q0r1s5t7v9w1x3y5z7c","idp_initiated_allowed_application_ids":["app_01j9xp6q0r1s5t7v9w1x3y5z7c"]}'
```

```bash
keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'
```