> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO 문제 해결 및 참고

> 온프레미스 EK 인스턴스의 SAML SSO에 대한 권한, 빠른 참고 URL 및 문제 해결 가이드.

이 문서는 권한, 빠른 참고 값 및 일반적인 SSO 문제에 대한 솔루션을 다룹니다. 설정 지침은 [SSO 메타데이터 설정 가이드](/super-admin/sso/saml-sso-metadata-setup-guide)를 참조하세요.

## 권한

모든 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`)                  | 슈퍼 관리자                                                 |

<Note>
  `/saml/well-known/sp-metadata`의 SP 메타데이터 엔드포인트는 설계상 공개입니다. 비밀은 포함되어 있지 않습니다 — SP 엔티티 ID, ACS URL, NameID 형식 및 공개 서명 인증서만 포함됩니다.
</Note>

## 빠른 참고

<CardGroup cols={2}>
  <Card title="백엔드 호스트" icon="server">
    `<your-backend-host>` (예: `ek-api.corp.acme.com`)

    모든 SAML 트래픽을 처리합니다 — SP 메타데이터, SSO 시작 및 ACS 엔드포인트. **IdP가 알아야 할 유일한 호스트입니다.**
  </Card>

  <Card title="프론트엔드 호스트" icon="globe">
    `<your-frontend-host>` (예: `ek.corp.acme.com`)

    사용자가 여는 웹 UI입니다. 백엔드에서 `FRONTEND_ROOT_URL`을 통해 구성됩니다. **IdP 구성에 나타나지 않습니다.**
  </Card>

  <Card title="SP 메타데이터 URL" icon="link">
    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    이를 IdP 관리자와 공유하여 EK를 SAML 애플리케이션으로 등록합니다.
  </Card>

  <Card title="ACS URL" icon="arrow-right-to-bracket">
    ```
    https://<your-backend-host>/user/generic/sso/saml/acs/admin
    ```

    IdP가 SAML 응답을 POST하는 위치. 항상 백엔드 호스트 — 프론트엔드가 아님.
  </Card>

  <Card title="SP 시작 SSO 진입점" icon="right-to-bracket">
    ```
    https://<your-backend-host>/sso/login?enterprise_id=<email-domain>
    ```

    사용자가 SSO를 시작할 때 프론트엔드가 리다이렉션되는 백엔드 엔드포인트.
  </Card>

  <Card title="필요한 NameID 형식" icon="id-card">
    ```
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    ```

    IdP는 이 형식으로 사용자의 이메일 주소를 보내야 합니다.
  </Card>
</CardGroup>

### 프론트엔드 SSO 모드 환경 변수

| 변수                          | 설명                                                       |
| --------------------------- | -------------------------------------------------------- |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | 단일 클릭 SSO의 경우 `true`, 이메일 모달 SSO의 경우 `false`(기본값).       |
| `VITE_SSO_ENTERPRISE_ID`    | 단일 클릭 모드에서만. SSO 메타데이터 탭에 IdP 메타데이터가 업로드된 도메인과 일치해야 합니다. |

* **IdP 메타데이터를 어디에 업로드하나요?** 슈퍼 관리자 대시보드 → **SSO 메타데이터** 탭 → **메타데이터 추가** / **업데이트**
* **도메인당 하나의 문서.** 다시 업로드하면 기존 메타데이터가 대체됩니다. 삭제하면 해당 도메인에 대한 SSO가 비활성화됩니다.
* **필요한 역할?** 모든 작업에 슈퍼 관리자, 팀 관리자는 자신의 팀 도메인에 대해 파일 업로드 가능.

## 문제 해결

<AccordionGroup>
  <Accordion title="&#x22;유효한 도메인을 입력하세요&#x22; 오류">
    **SSO 팀 이메일 도메인** 필드는 `acme.com` 또는 `eu.acme.co.uk`와 같은 원시 도메인을 기대합니다. 제출하기 전에 모든 선두 `@`, `https://`, 경로 또는 포트 번호를 제거하세요.
  </Accordion>

  <Accordion title="&#x22;파일은 XML 파일이어야 합니다&#x22; 오류">
    파일 업로더는 `.xml` 확장자가 있는 파일만 허용합니다. IdP가 메타데이터를 `.txt` 파일이나 확장자 없이 제공한 경우 이름을 `.xml`로 바꾸거나 **XML 내용 붙여넣기** 옵션으로 전환하세요.
  </Accordion>

  <Accordion title="&#x22;내용이 유효한 XML로 보이지 않습니다&#x22; 오류">
    **XML 내용 붙여넣기**를 사용할 때 붙여넣은 내용은 공백을 제거한 후 `<?xml` 또는 `<`로 시작해야 합니다. 전체 메타데이터 문서를 복사했고 서문이나 설명이 포함되지 않았는지 확인하세요.
  </Accordion>

  <Accordion title="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 관리자가 다시 가져오도록 합니다.
  </Accordion>

  <Accordion title="사용자가 성공적으로 로그인했지만 접근이 거부됨">
    이것은 SSO 메타데이터 탭이 아닌 **슈퍼 관리자 → 접근 제어**에 의해 제어됩니다. `모든 새 사용자 허용` 대 `SAML 메타데이터로 제한` 및 [자동 팀/프로젝트 할당 규칙](/super-admin/sa-automated-management)에 대한 세부 사항은 [**SAML 접근 제어**](/super-admin/sa-access-controls) 가이드를 참조하세요.
  </Accordion>

  <Accordion title="IdP 시작 SSO가 작동하지 않음">
    기본적으로 EK는 자체 `/sso/login` 엔드포인트에서 시작된 SAML 응답만 수신합니다 — 즉 SP 시작 SSO만 지원됩니다. IdP 시작(비정상) SSO를 활성화하려면 온프레미스 운영자가 EK 백엔드에서 `ALLOW_IDP_INITIATED_SSO=true`를 설정하고 서비스를 재시작해야 합니다. 이것은 배포 수준 설정이며 SSO 메타데이터 탭에서 구성할 수 있는 것이 아닙니다.
  </Accordion>

  <Accordion title="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`와 일치하는지.

    프론트엔드 호스트는 IdP의 SAML 애플리케이션 구성에 나타나지 않아야 합니다.
  </Accordion>

  <Accordion title="단일 클릭 SSO 버튼이 작동하지 않음(또는 &#x22;SSO 로그인용 도메인을 결정할 수 없습니다&#x22; 표시)">
    `VITE_SSO_ENTERPRISE_ID`가 프론트엔드에 설정되지 않았습니다. IdP 메타데이터를 업로드한 이메일 도메인으로 설정한 다음 프론트엔드를 다시 배포하거나 재시작하여 값이 적용되도록 합니다.
  </Accordion>

  <Accordion title="단일 클릭 SSO 버튼이 리다이렉션되지만 백엔드에서 SSO가 실패함">
    `VITE_SSO_ENTERPRISE_ID`가 설정되었지만 SSO 메타데이터 탭에 업로드된 메타데이터가 있는 도메인과 일치하지 않습니다. 다음 중 하나로 해결합니다:

    * 현재 `VITE_SSO_ENTERPRISE_ID`에 있는 도메인에 대한 IdP 메타데이터 업로드 — 프론트엔드 구성을 변경하지 않으므로 권장.
    * `VITE_SSO_ENTERPRISE_ID`를 이미 메타데이터가 업로드된 도메인과 일치하도록 업데이트한 다음 프론트엔드를 다시 배포하거나 재시작.

    두 값은 정확히 일치해야 합니다(대소문자 구분 없음).
  </Accordion>

  <Accordion title="이메일 모달 SSO가 &#x22;귀하의 조직은 SSO 로그인이 구성되지 않았습니다&#x22;를 표시">
    사용자의 이메일 도메인에 SSO 메타데이터 탭에 IdP 메타데이터가 업로드되어 있지 않습니다. 해당 도메인에 대한 메타데이터를 업로드하거나 사용자에게 대신 이메일/비밀번호 또는 OAuth를 사용하여 로그인하도록 요청합니다.
  </Accordion>

  <Accordion title="사용자가 SSO를 완료했지만 잘못된 페이지에 도착하거나 리다이렉트 오류 발생">
    성공적인 SAML 응답 후 EK는 사용자를 백엔드의 `FRONTEND_ROOT_URL`에 정의된 프론트엔드 URL로 리다이렉션합니다. 이 변수가 설정되지 않았거나 잘못된 호스트를 가리키거나 잘못된 스킴 또는 포트를 사용하면 사용자가 인증을 완료한 것처럼 보이지만 깨진 페이지에 도달하게 됩니다.

    온프레미스 운영자에게 `FRONTEND_ROOT_URL`이 `https://<your-frontend-host>`와 정확히 일치하는지 확인하도록 요청합니다 — 올바른 스킴, 올바른 포트, 후행 슬래시 문제 없음.
  </Accordion>
</AccordionGroup>