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와 함께 연결(자세한 내용은 연결 조회 참조) 및 새 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 기간 이후에 다시 시도하십시오. |
예시
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"]}'
keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'