# SAML 연결에 대해 IdP 시작 로그인 설정

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

엔터프라이즈 SAML 연결에 대해 IdP 시작 로그인(ID 공급자의 앱 포털에서 보낸 요청되지 않은 SAML 응답)을 허용하거나 끕니다. 또한 사용자가 이동할 수 있는 애플리케이션을 설정합니다. 기본값은 꺼짐입니다.

- **전체 교체:** 모든 요청은 세 필드를 모두 기록합니다. `idp_initiated_default_application_id`를 생략하거나 `idp_initiated_allowed_application_ids`를 빈 배열로 보내면 해당 값이 지워집니다.
- **대상:** 각 애플리케이션은 이 환경에 존재해야 하고, 브라우저를 통해 로그인해야 하며(머신 간 통신, 관리 또는 클라이언트 ID 메타데이터 문서 클라이언트는 제외), `initiate_login_uri`가 있어야 합니다. 로그인 후 브라우저는 `iss`와 함께 해당 주소로 이동하며, 애플리케이션은 `state`와 PKCE를 사용해 자체 인가 요청을 시작합니다.
- **RelayState:** ID 공급자가 RelayState를 보내는 경우, 해당 값이 애플리케이션의 `client_id`와 바이트 단위로 일치하고 그 애플리케이션이 기본값이거나 허용 목록에 있을 때만 애플리케이션을 선택합니다. RelayState는 URL로 취급하지 않습니다.
- **보안:** 이 설정은 사용자가 시작하지 않은 응답을 허용하므로, 대시보드 사용자에게는 최근의 추가 인증(step-up)과 `owner` 또는 `admin` 역할이 필요합니다. Admin Portal에서는 이 설정을 변경할 수 없습니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `connection_id` | path | 예 | 엔터프라이즈 SAML 연결 ID(`conn_…`)입니다. |
| `If-Match` | header | 아니요 | 연결의 `ETag`입니다. 오래된 값이면 `412`로 실패합니다. |
| `allow_idp_initiated` | boolean | 예 | 요청되지 않은 SAML 응답을 허용합니다. `true`이면 `idp_initiated_default_application_id`가 필요합니다. |
| `idp_initiated_default_application_id` | string \| null | 활성화 시 | RelayState가 비어 있을 때 사용되는 애플리케이션(`app_…`)입니다. |
| `idp_initiated_allowed_application_ids` | array | 아니요 | RelayState가 선택할 수 있는 애플리케이션(`app_…`)입니다. 고유해야 하며 최대 20개입니다. |

## 응답

`200 OK`와 함께 연결(자세한 내용은 [연결 조회](../connections/get.md) 참조) 및 새 `ETag`를 반환합니다. 연결에는 `allow_idp_initiated`, `idp_initiated_default_application_id`, `idp_initiated_allowed_application_ids`에 저장된 값이 표시됩니다.

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 404 | `not_found` | 이 환경에 연결이 없습니다. |
| 412 | `precondition_failed` | `If-Match`가 현재 버전과 일치하지 않습니다. |
| 422 | `validation_failed` | 연결이 엔터프라이즈 SAML 연결이 아니거나, 활성화된 상태에서 기본 애플리케이션이 없거나, 애플리케이션이 대상 규칙을 충족하지 않습니다. `errors[]`에 해당 필드가 표시됩니다. |
| 400 | `unknown_field` | 본문에 알 수 없는 필드가 있습니다. |
| 401 | `unauthenticated` | 자격 증명이 없거나 유효하지 않거나 취소되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 403 | `step_up_required` | 대시보드 사용자가 최근의 추가 인증을 완료하지 않았습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |

## 예시

```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}'
```