> ## 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 메타데이터 설정 가이드

> IdP를 등록하고 메타데이터를 업로드하여 온프레미스 EK 인스턴스에서 SAML 2.0 SSO를 활성화하는 단계별 지침.

<Note>
  이 가이드는 온프레미스 EK 인스턴스를 관리하는 IT 및 ID 관리자를 위해 작성되었습니다. "귀하의 IdP", "귀하의 IdP 관리자" 또는 "귀하의 이메일 도메인"에 대한 모든 참조는 Automation Anywhere가 관리하는 것이 아닌 귀하 조직의 자체 인프라를 가리킵니다.
</Note>

이 가이드는 슈퍼 관리자가 이메일 도메인에 대해 SAML SSO를 활성화하는 두 부분 과정을 안내합니다: EK의 SP 메타데이터를 IdP와 공유한 다음 IdP의 메타데이터를 다시 EK에 업로드합니다.

EK의 SAML SSO가 내부적으로 어떻게 작동하는지 잘 모르시나요? 먼저 [SAML SSO 개요](/super-admin/sso/saml-sso-how-it-works)를 시작하세요.

## 전제 조건

시작하기 전에 다음을 확인하세요:

* **온프레미스 EK 배포**가 사용자 브라우저에서 접근할 수 있는 백엔드(`<your-backend-host>`)와 프론트엔드(`<your-frontend-host>`)와 함께 실행 중입니다. IdP는 `<your-backend-host>/user/generic/sso/saml/acs/admin`에서 HTTP-POST SAML 응답만 수신하면 됩니다 — SP 메타데이터를 다운로드 파일로 제공하는 경우 백엔드에 대한 직접적인 아웃바운드 연결이 **필요하지 않습니다**.
* **슈퍼 관리자**로서 EK에 로그인했습니다. SMO 메타데이터 탭과 모든 하위 엔드포인트는 슈퍼 관리자에게만 제한됩니다.
* IdP가 SAML 2.0 호환이고 SP 메타데이터 XML/URL을 사용할 수 있거나 SP 엔티티 ID와 ACS URL로 수동 구성할 수 있습니다.
* IdP가 `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` 형식을 사용하여 SAML `NameID`로 사용자의 이메일 주소를 보내도록 구성되었습니다. EK는 NameID를 사용하여 사용자 계정을 조회하거나 프로비저닝합니다.
* SSO를 활성화하려는 **이메일 도메인**을 알고 있습니다(예: `acme.com`). SSO는 도메인을 기준으로 하므로 해당 도메인을 공유하는 모든 사용자 — `alice@acme.com`, `bob@acme.com` 등 — 가 동일한 IdP로 라우팅됩니다.
* 배포가 어떤 **프론트엔드 SSO 모드**에서 작동하는지 알고 있습니다. 이는 프론트엔드의 `VITE_ALLOW_ONLY_SSO_LOGIN` 환경 변수에 의해 제어됩니다:
  * `true` — 단일 클릭 SSO. 도메인이 `VITE_SSO_ENTERPRISE_ID`를 통해 하드 코딩되어 메타데이터를 업로드하는 도메인과 정확히 일치해야 합니다.
  * `false` *(기본값)* — 이메일 모달 SSO. 도메인이 로그인 시 사용자의 이메일에서 파생됩니다. 여러 도메인이 각각 고유한 업로드된 메타데이터를 가질 수 있습니다.

## 1부 — IdP에 SP 메타데이터 제공

IdP 메타데이터를 업로드하기 전에 IdP 관리자가 IdP에서 EK를 SAML 애플리케이션으로 등록해야 합니다. EK는 공개적이고 잘 알려진 엔드포인트를 통해 SP 메타데이터를 게시하여 이 작업을 간소화합니다 — 수동 필드 복사가 필요하지 않습니다.

### SP 메타데이터 엔드포인트

EK 백엔드는 SP 메타데이터를 다음에 게시합니다:

```
https://<your-backend-host>/saml/well-known/sp-metadata
```

응답은 인스턴스의 엔티티 ID, ACS URL, 필요한 NameID 형식 및 SP 서명 인증서(구성된 경우)를 포함하는 표준 호환 SAML 2.0 `EntityDescriptor`입니다. 이 엔드포인트는 설계상 인증되지 않으므로 IdP가 직접 가져올 수 있습니다.

<Tip>
  전체 참고 — 엔드포인트 동작, 샘플 XML, 보장 대 선택적 구성 요소 및 온프레미스 운영자가 배포 시 조정할 수 있는 백엔드 환경 변수(`CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`, `SAML_SP_CERT_FILE`, `SAML_SP_KEY_FILE`)는 [SP 메타데이터 엔드포인트](/super-admin/sso/sp-metadata-endpoint)를 참조하세요.
</Tip>

### SP 메타데이터를 공유하는 방법

<AccordionGroup>
  <Accordion title="옵션 A — URL 제공">
    IdP가 EK 백엔드 호스트에 접근할 수 있는 경우 IdP 관리자에게 잘 알려진 URL을 직접 제공합니다:

    ```
    https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    대부분의 최신 IdP(Okta, Entra ID, Ping, OneLogin, Auth0 등)는 URL에서 SP 메타데이터를 가져올 수 있으며 SP 구성 — 엔티티 ID, ACS URL, NameID 형식 및 서명 인증서 — 을 자동으로 채웁니다.
  </Accordion>

  <Accordion title="옵션 B — 파일을 다운로드하여 전달">
    IdP가 백엔드 호스트에 직접 접근할 수 없는 경우 — 세그멘테이션된 네트워크, 에어갭 환경 또는 IdP가 기업 경계 외부의 SaaS인 경우 — XML을 다운로드하여 비대면으로 IdP 관리자에게 전달합니다:

    ```bash theme={null}
    curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata
    ```

    IdP 관리자는 IdP의 SAML 애플리케이션 구성 화면에서 `ek_sp_metadata.xml`을 업로드합니다. SP 구성이 변경될 때만 다시 내보내고 다시 업로드하면 됩니다 — 일반적으로 백엔드 호스트 이름 변경, SP 서명 인증서 로테이션 또는 엔티티 ID 재정의 변경 시.
  </Accordion>
</AccordionGroup>

### 수동 구성(IdP가 메타데이터를 사용할 수 없는 경우)

IdP에 필드를 수동으로 입력해야 하는 경우 SP 메타데이터 XML의 값을 사용합니다. 가장 자주 요구되는 필드는 다음과 같습니다:

| 필드                                | 값                                                                                                                      |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **엔티티 ID / 어드러스**                 | SP 메타데이터 응답의 `<md:EntityDescriptor>`의 `entityID` 속성. 기본값은 ACS URL; 배포 시 `CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`를 통해 재정의 가능. |
| **ACS URL / 답장 URL / 싱글 사인온 URL** | `https://<your-backend-host>/user/generic/sso/saml/acs/admin` — 항상 백엔드 호스트, 프론트엔드가 아님.                                 |
| **바인딩**                           | HTTP-POST                                                                                                              |
| **NameID 형식**                     | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`                                                               |
| **AuthnRequest 서명**               | EK 배포에 SP 인증서가 구성된 경우 `true`(메타데이터에서 `AuthnRequestsSigned`로 광고됨); 그렇지 않으면 `false`.                                     |
| **Assertion 서명 요구**               | `true` — 항상. EK는 서명된 assertion을 요구합니다.                                                                                 |

<Warning>
  IdP는 사용자의 이메일 주소를 SAML `NameID`로 보내야 합니다. IdP가 대신 불투명한 내부 ID를 보내면 로그인이 실패하거나 잘못된 키의 계정이 생성됩니다.
</Warning>

### IdP 관리자가 반환해야 할 것

IdP에서 SAML 애플리케이션이 생성되면 IdP 관리자에게 **IdP SAML 메타데이터 XML**을 요청합니다. 이것은 2부에서 업로드할 파일입니다.

거의 모든 IdP가 이 파일을 생성할 수 있습니다. IdP UI에서의 일반적인 이름:

| IdP                                           | 찾는 위치                                                       |
| --------------------------------------------- | ----------------------------------------------------------- |
| **Okta**                                      | 애플리케이션의 *로그인* 탭의 *"ID 제공자 메타데이터"* 링크                        |
| **Entra ID / Azure AD**                       | SSO 블레이드 아래의 *"연합 메타데이터 XML"* 다운로드                          |
| **Ping / OneLogin / Auth0 / ADFS / Keycloak** | 일반적으로 *"메타데이터"* 또는 \*"SAML 메타데이터"\*로 레이블이 지정됨, XML로 다운로드 가능 |

XML은 IdP의 `entityID`, `SingleSignOnService` 위치 및 바인딩, 그리고 assertion을 확인하기 위한 IdP의 서명 인증서를 포함하는 유효한 SAML 2.0 `EntityDescriptor`여야 합니다.

## 2부 — IdP 메타데이터 업로드

IdP 메타데이터 XML을 확보했으므로 이제 EK 인스턴스의 이메일 도메인에 등록할 수 있습니다.

### SSO 메타데이터 탭 열기

<Steps>
  <Step title="EK에 로그인">
    슈퍼 관리자로서 EK에 로그인합니다.
  </Step>

  <Step title="슈퍼 관리자 대시보드 열기">
    오른쪽 상단의 계정 메뉴로 이동하여 **슈퍼 관리자 대시보드**를 클릭합니다.
  </Step>

  <Step title="SSO 메타데이터 탭으로 이동">
    **SSO 메타데이터** 탭으로 전환합니다. 세 개의 열을 가진 기존 도메인 → 메타데이터 매핑 테이블이 표시됩니다:

    * **SSO 도메인** — 메타데이터가 등록된 이메일 도메인(예: `acme.com`).
    * **수정일** — 해당 도메인에 대한 메타데이터가 마지막으로 업로드되거나 교체된 시간.
    * **작업** — 해당 행의 저장된 메타데이터를 다운로드, 업데이트 또는 삭제하는 컨트롤.

    오른쪽 상단의 검색 상자를 사용하여 도메인별로 필터링합니다. 테이블은 **SSO 도메인** 또는 **수정일**별로 정렬 가능합니다.
  </Step>
</Steps>

### 새 도메인에 메타데이터 추가

<Steps>
  <Step title="메타데이터 추가 대화 상자 열기">
    SSO 메타데이터 탭의 오른쪽 상단에서 **메타데이터 추가**를 클릭합니다. 아직 도메인이 구성되지 않은 경우 빈 상태 카드에서도 클릭할 수 있습니다.<br /><img src="https://mintcdn.com/automationanywhere/GwZtgh73O0-NsEVq/img/sa/sso/add-metadata-dialog.png?fit=max&auto=format&n=GwZtgh73O0-NsEVq&q=85&s=59176f248d196eb7d6ea959a50732843" alt="메타데이터 추가 대화 상자" width="700" height="438" data-path="img/sa/sso/add-metadata-dialog.png" />
  </Step>

  <Step title="이메일 도메인 입력">
    **SSO 팀 이메일 도메인** 필드에 SSO가 적용되어야 하는 도메인을 입력합니다 — 예를 들어 `acme.com`. 이메일 주소의 도메인 부분만 사용합니다: `@` 없음, 경로 없음, 스킴 없음. 값은 저장 시 소문자로 정규화됩니다.

    <Warning>
      배포가 단일 클릭 SSO 모드(`VITE_ALLOW_ONLY_SSO_LOGIN=true`)에서 작동하면 이 값이 `VITE_SSO_ENTERPRISE_ID`와 정확히 일치해야 합니다. 불일치는 SSO 버튼이 업로드된 메타데이터가 없는 도메인으로 사용자를 리다이렉션하여 백엔드에서 인증이 실패함을 의미합니다.
    </Warning>
  </Step>

  <Step title="업로드 방법을 선택하고 XML 제공">
    <Tabs>
      <Tab title="파일 업로드">
        IdP 관리자가 제공한 `.xml` 파일을 선택합니다. `.xml` 확장자가 있는 파일만 허용됩니다.
      </Tab>

      <Tab title="XML 내용 붙여넣기">
        전체 IdP 메타데이터 XML을 텍스트 영역에 직접 붙여넣습니다. 내용은 `<?xml ...?>` 또는 `<EntityDescriptor ...>`로 시작해야 합니다.
      </Tab>
    </Tabs>
  </Step>

  <Step title="제출">
    **메타데이터 업로드**를 클릭합니다. 대화 상자가 닫히고 토스트 알림이 업로드를 확인하며 새 도메인이 테이블에 나타납니다.
  </Step>
</Steps>

<Note>
  각 도메인은 한 번에 하나의 활성 IdP 메타데이터 문서만 가질 수 있습니다. 동일한 도메인에 다시 업로드하면 기존 메타데이터가 대체됩니다 — 아래의 *기존 도메인에 대한 메타데이터 업데이트*를 참조하세요.
</Note>

### 기존 도메인의 메타데이터 업데이트

IdP는 서명 인증서를 로테이션하고 가끔 엔드포인트를 변경합니다. 이 일이 발생하면 IdP 관리자와 협력하여 IdP가 새 키로 assertion에 서명하기 **전에** 새 XML이 EK에 업로드되도록 합니다.

<Steps>
  <Step title="도메인 행 찾기">
    SSO 메타데이터 테이블에서 도메인을 찾습니다.
  </Step>

  <Step title="업데이트 클릭">
    행의 작업 열에서 **업데이트**를 클릭합니다.
  </Step>

  <Step title="새 XML 제공">
    **SSO 메타데이터 업데이트** 대화 상자가 도메인이 미리 채워져 있고 잠긴 상태로 열립니다. 업데이트 시 도메인을 변경할 수 없습니다 — 항목을 재사용하려면 삭제하고 다시 추가하세요. 업로드 방법을 선택하고 새 도메인과 마찬가지로 새 XML을 제공합니다.
  </Step>

  <Step title="제출">
    **메타데이터 업데이트**를 클릭합니다. 교체는 즉시 적용됩니다 — 해당 도메인의 다음 SSO 로그인이 새 메타데이터를 사용합니다.
  </Step>
</Steps>

### 현재 저장된 메타데이터 다운로드

행의 작업 열에서 **다운로드 아이콘**을 클릭합니다. 파일은 `<도메인>_saml_metadata.xml`로 저장됩니다.

유용한 경우:

* 현재 이 EK 인스턴스에서 어떤 IdP 메타데이터가 활성화되어 있는지 확인.
* 감사를 위해 보안 또는 규정 준수 팀에 사본 제공.
* 업데이트 수행 전 백업.

### 도메인의 메타데이터 삭제

<Steps>
  <Step title="삭제 클릭">
    행의 작업 열에서 **삭제**를 클릭합니다.
  </Step>

  <Step title="확인">
    확인 대화 상자에서 경고를 읽고 확인란을 선택합니다 — *"이 도메인의 모든 사용자에 대한 SSO가 비활성화됨을 이해합니다"* — 그리고 **삭제**를 클릭합니다.
  </Step>
</Steps>

<Danger>
  삭제는 되돌릴 수 없습니다. 삭제 후:

  * EK는 해당 도메인에 대한 IdP 메타데이터를 더 이상 보유하지 않습니다.
  * `@<도메인>` 사용자의 모든 새 SSO 로그인 시도가 실패합니다.
  * 기존 계정 — 이메일/비밀번호, Google OAuth 또는 이전 SSO 로그인에 의해 프로비저닝된 계정 — 은 **삭제되지 않지만** 해당 사용자는 더 이상 SSO를 통해 로그인할 수 없습니다.

  도메인에 대한 SSO를 복원하려면 IdP 메타데이터 XML을 다시 업로드해야 합니다.
</Danger>

## 끝에서 끝 체크리스트

온프레미스 EK 인스턴스에서 새 이메일 도메인에 대해 SAML SSO를 활성화할 때 런북으로 사용하세요.

<Steps>
  <Step title="EK SP 메타데이터를 IdP 관리자와 공유">
    IdP 관리자에게 EK 백엔드의 SP 메타데이터를 제공합니다 — 프론트엔드 호스트가 아닙니다.

    * IdP가 백엔드에 직접 접근할 수 있는 경우 다음을 알려주세요:
      ```
      https://<your-backend-host>/saml/well-known/sp-metadata
      ```
    * 그렇지 않으면 XML을 다운로드하여 비대면으로 전달합니다:
      ```bash theme={null}
      curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata
      ```
  </Step>

  <Step title="IdP 관리자가 SAML 애플리케이션을 만듦">
    SP 메타데이터를 확보하면 IdP 관리자가 IdP에서 EK를 SAML 애플리케이션으로 등록합니다. 다음을 확인합니다:

    * NameID가 사용자의 이메일 주소로 설정되어 있습니다.
    * Assertion이 서명되어 있습니다.
    * 어드러스/엔티티 ID가 EK의 SP 메타데이터의 값과 일치합니다.
  </Step>

  <Step title="IdP 메타데이터 XML 수신">
    애플리케이션이 생성되면 IdP 관리자에게 IdP 메타데이터 XML을 요청합니다. 이것이 다음 단계에서 업로드할 파일입니다.
  </Step>

  <Step title="IdP 메타데이터를 EK에 업로드">
    슈퍼 관리자로서 EK에 로그인하고 **슈퍼 관리자 대시보드 → SSO 메타데이터**를 열고 **메타데이터 추가**를 클릭합니다. 이메일 도메인을 입력하고 XML을 업로드합니다.
  </Step>

  <Step title="로그인 테스트">
    실제 `@<도메인>` 사용자로 테스트합니다. 사용자가 인증에 성공했지만 접근이 거부되면 SAML 접근 제어 구성을 확인하세요 — [**SAML 접근 제어**](/super-admin/sa-access-controls) 가이드를 참조하세요.
  </Step>

  <Step title="변경 사항 문서화">
    내부 변경 관리 시스템에 다음을 기록합니다: 도메인, IdP 유형, 업로드 날짜 및 업로드를 수행한 슈퍼 관리자.
  </Step>

  <Step title="메타데이터 새로고침 예약">
    IdP 서명 인증서가 로테이션 예정인지 확인하고 해당 날짜 전에 업데이트된 메타데이터를 업로드하도록 리마인더를 설정합니다. 새 메타데이터가 사용 가능한 경우 SSO 메타데이터 탭의 **업데이트** 작업을 사용합니다.
  </Step>
</Steps>

***

문제가 발생하나요? [SSO 문제 해결 및 참고](/super-admin/sso/saml-sso-troubleshooting) 가이드를 참조하세요.