권한
모든 SSO 메타데이터 관리 작업은 슈퍼 관리자에게만 제한됩니다. 한 가지 예외: 팀 관리자는 자신의 팀 도메인에 대해 파일을 통해 IdP 메타데이터를 업로드할 수 있습니다.| 작업 | 필요한 역할 |
|---|---|
| SSO 메타데이터 탭 보기 | 슈퍼 관리자 |
파일을 통해 IdP 메타데이터 업로드(POST /admin/saml-metadata/upload) | 슈퍼 관리자, 또는 sso_domain이 팀의 email_domain과 일치하는 팀 관리자 |
붙여넣은 XML을 통해 IdP 메타데이터 업로드(POST /admin/saml-metadata/upload-text) | 슈퍼 관리자만 |
저장된 메타데이터 다운로드(GET /admin/saml-metadata/download) | 슈퍼 관리자 |
저장된 메타데이터 삭제(DELETE /admin/saml-metadata/delete) | 슈퍼 관리자 |
/saml/well-known/sp-metadata의 SP 메타데이터 엔드포인트는 설계상 공개입니다. 비밀은 포함되어 있지 않습니다 — SP 엔티티 ID, ACS URL, NameID 형식 및 공개 서명 인증서만 포함됩니다.빠른 참고
백엔드 호스트
<your-backend-host> (예: ek-api.corp.acme.com)모든 SAML 트래픽을 처리합니다 — SP 메타데이터, SSO 시작 및 ACS 엔드포인트. IdP가 알아야 할 유일한 호스트입니다.프론트엔드 호스트
<your-frontend-host> (예: ek.corp.acme.com)사용자가 여는 웹 UI입니다. 백엔드에서 FRONTEND_ROOT_URL을 통해 구성됩니다. IdP 구성에 나타나지 않습니다.SP 메타데이터 URL
ACS URL
SP 시작 SSO 진입점
필요한 NameID 형식
프론트엔드 SSO 모드 환경 변수
| 변수 | 설명 |
|---|---|
VITE_ALLOW_ONLY_SSO_LOGIN | 단일 클릭 SSO의 경우 true, 이메일 모달 SSO의 경우 false(기본값). |
VITE_SSO_ENTERPRISE_ID | 단일 클릭 모드에서만. SSO 메타데이터 탭에 IdP 메타데이터가 업로드된 도메인과 일치해야 합니다. |
- IdP 메타데이터를 어디에 업로드하나요? 슈퍼 관리자 대시보드 → SSO 메타데이터 탭 → 메타데이터 추가 / 업데이트
- 도메인당 하나의 문서. 다시 업로드하면 기존 메타데이터가 대체됩니다. 삭제하면 해당 도메인에 대한 SSO가 비활성화됩니다.
- 필요한 역할? 모든 작업에 슈퍼 관리자, 팀 관리자는 자신의 팀 도메인에 대해 파일 업로드 가능.
문제 해결
"유효한 도메인을 입력하세요" 오류
"유효한 도메인을 입력하세요" 오류
SSO 팀 이메일 도메인 필드는
acme.com 또는 eu.acme.co.uk와 같은 원시 도메인을 기대합니다. 제출하기 전에 모든 선두 @, https://, 경로 또는 포트 번호를 제거하세요."파일은 XML 파일이어야 합니다" 오류
"파일은 XML 파일이어야 합니다" 오류
파일 업로더는
.xml 확장자가 있는 파일만 허용합니다. IdP가 메타데이터를 .txt 파일이나 확장자 없이 제공한 경우 이름을 .xml로 바꾸거나 XML 내용 붙여넣기 옵션으로 전환하세요."내용이 유효한 XML로 보이지 않습니다" 오류
"내용이 유효한 XML로 보이지 않습니다" 오류
XML 내용 붙여넣기를 사용할 때 붙여넣은 내용은 공백을 제거한 후
<?xml 또는 <로 시작해야 합니다. 전체 메타데이터 문서를 복사했고 서문이나 설명이 포함되지 않았는지 확인하세요.IdP에서 로그인은 성공했지만 EK가 assertion을 거부함
IdP에서 로그인은 성공했지만 EK가 assertion을 거부함
이것은 거의 항상 다음 중 하나로 인해 발생합니다:
- 인증서 불일치 — 업로드된 메타데이터의 IdP 서명 인증서가 IdP가 실제로 사용하는 인증서와 더 이상 일치하지 않습니다. 이것은 일반적으로 IdP 인증서 로테이션 후에 발생합니다. IdP 관리자에게서 최신 메타데이터를 가져와 업데이트를 사용하세요.
- 잘못된 NameID 형식 — IdP가 NameID로 이메일 주소를 보내고 있지 않습니다. IdP 측에서 형식이
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress로 설정되어 있는지 확인합니다. - 엔티티 ID 불일치 — IdP에서 구성한 어드러스 또는 엔티티 ID가 EK 인스턴스의 엔티티 ID와 일치하지 않습니다. EK SP 메타데이터 XML을 다시 공유하고 IdP 관리자가 다시 가져오도록 합니다.
사용자가 성공적으로 로그인했지만 접근이 거부됨
사용자가 성공적으로 로그인했지만 접근이 거부됨
이것은 SSO 메타데이터 탭이 아닌 슈퍼 관리자 → 접근 제어에 의해 제어됩니다.
모든 새 사용자 허용 대 SAML 메타데이터로 제한 및 자동 팀/프로젝트 할당 규칙에 대한 세부 사항은 SAML 접근 제어 가이드를 참조하세요.IdP 시작 SSO가 작동하지 않음
IdP 시작 SSO가 작동하지 않음
기본적으로 EK는 자체
/sso/login 엔드포인트에서 시작된 SAML 응답만 수신합니다 — 즉 SP 시작 SSO만 지원됩니다. IdP 시작(비정상) SSO를 활성화하려면 온프레미스 운영자가 EK 백엔드에서 ALLOW_IDP_INITIATED_SSO=true를 설정하고 서비스를 재시작해야 합니다. 이것은 배포 수준 설정이며 SSO 메타데이터 탭에서 구성할 수 있는 것이 아닙니다.IdP가 프론트엔드 호스트 대신 백엔드 호스트로 구성됨
IdP가 프론트엔드 호스트 대신 백엔드 호스트로 구성됨
IdP 애플리케이션이 ACS URL 또는 엔티티 ID로 EK 프론트엔드 호스트 이름으로 구성된 경우 SAML 응답이 잘못된 서비스로 전송되어 인증이 조용히 실패합니다 — 일반적으로 IdP 로그인 화면 후 404 또는 일반 오류 페이지가 표시됩니다.IdP 관리자에게 다음을 확인하도록 요청합니다:
- ACS URL이
https://<your-backend-host>/user/generic/sso/saml/acs/admin인지. - 엔티티 ID/어드러스가
https://<your-backend-host>/saml/well-known/sp-metadata의entityID와 일치하는지.
단일 클릭 SSO 버튼이 작동하지 않음(또는 "SSO 로그인용 도메인을 결정할 수 없습니다" 표시)
단일 클릭 SSO 버튼이 작동하지 않음(또는 "SSO 로그인용 도메인을 결정할 수 없습니다" 표시)
VITE_SSO_ENTERPRISE_ID가 프론트엔드에 설정되지 않았습니다. IdP 메타데이터를 업로드한 이메일 도메인으로 설정한 다음 프론트엔드를 다시 배포하거나 재시작하여 값이 적용되도록 합니다.단일 클릭 SSO 버튼이 리다이렉션되지만 백엔드에서 SSO가 실패함
단일 클릭 SSO 버튼이 리다이렉션되지만 백엔드에서 SSO가 실패함
VITE_SSO_ENTERPRISE_ID가 설정되었지만 SSO 메타데이터 탭에 업로드된 메타데이터가 있는 도메인과 일치하지 않습니다. 다음 중 하나로 해결합니다:- 현재
VITE_SSO_ENTERPRISE_ID에 있는 도메인에 대한 IdP 메타데이터 업로드 — 프론트엔드 구성을 변경하지 않으므로 권장. VITE_SSO_ENTERPRISE_ID를 이미 메타데이터가 업로드된 도메인과 일치하도록 업데이트한 다음 프론트엔드를 다시 배포하거나 재시작.
이메일 모달 SSO가 "귀하의 조직은 SSO 로그인이 구성되지 않았습니다"를 표시
이메일 모달 SSO가 "귀하의 조직은 SSO 로그인이 구성되지 않았습니다"를 표시
사용자의 이메일 도메인에 SSO 메타데이터 탭에 IdP 메타데이터가 업로드되어 있지 않습니다. 해당 도메인에 대한 메타데이터를 업로드하거나 사용자에게 대신 이메일/비밀번호 또는 OAuth를 사용하여 로그인하도록 요청합니다.
사용자가 SSO를 완료했지만 잘못된 페이지에 도착하거나 리다이렉트 오류 발생
사용자가 SSO를 완료했지만 잘못된 페이지에 도착하거나 리다이렉트 오류 발생
성공적인 SAML 응답 후 EK는 사용자를 백엔드의
FRONTEND_ROOT_URL에 정의된 프론트엔드 URL로 리다이렉션합니다. 이 변수가 설정되지 않았거나 잘못된 호스트를 가리키거나 잘못된 스킴 또는 포트를 사용하면 사용자가 인증을 완료한 것처럼 보이지만 깨진 페이지에 도달하게 됩니다.온프레미스 운영자에게 FRONTEND_ROOT_URL이 https://<your-frontend-host>와 정확히 일치하는지 확인하도록 요청합니다 — 올바른 스킴, 올바른 포트, 후행 슬래시 문제 없음.