> ## 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.

# EK의 SAML SSO — 작동 방식

> 구성을 시작하기 전에 EK가 SAML 2.0 SSO를 위해 ID 제공자와 통합하는 방법을 이해하세요.

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

EK는 온프레미스 배포를 위해 **SAML 2.0 SSO**를 지원하여 사용자가 조직의 기존 \*\*ID 제공자(IdP)\*\*를 통해 로그인할 수 있게 합니다. 설정은 **슈퍼 관리자 대시보드 → SSO 메타데이터** 탭을 통해 완전히 이루어집니다 — 코드 변경이 필요하지 않습니다.

EK는 모든 **표준 호환 SAML 2.0 IdP** — Okta, Azure AD / Entra ID, Ping, ADFS, OneLogin, Auth0, Keycloak, Google Workspace 등 — 와 작동합니다. 이메일 도메인에 대한 IdP 메타데이터를 업로드하면 해당 도메인에 속하는 모든 사용자에 대한 SSO가 자동으로 라우팅됩니다.

## 두 EK 호스트 이해

온프레미스 EK 배포에는 뚜렷한 역할을 가진 두 개의 호스트가 있습니다:

* `<your-backend-host>` — 모든 SAML 트래픽을 처리합니다: SP 메타데이터, SSO 시작 및 ACS 엔드포인트. **IdP가 알아야 할 유일한 호스트입니다.** *(예: `ek-api.corp.acme.com`)*
* `<your-frontend-host>` — 사용자가 브라우저에서 여는 웹 UI입니다. EK는 성공적인 로그인 후 사용자를 여기로 리다이렉션하며 `FRONTEND_ROOT_URL` 환경 변수를 통해 구성됩니다. **이 호스트는 IdP 구성에 나타나지 않습니다.** *(예: `ek.corp.acme.com`)*

## EK에서 SAML SSO가 작동하는 방식

SAML SSO를 설정하려면 두 시스템 간의 상호 신뢰 교환이 필요합니다. 어떤 인증이든 발생하기 전에 각 측은 상대방이 누구인지 알아야 합니다:

<CardGroup cols={2}>
  <Card title="서비스 제공자(SP) — EK" icon="server">
    귀하의 온프레미스 EK 인스턴스. EK는 SP 메타데이터를 게시하여 IdP가 SAML 응답을 보낼 위치, 사용할 NameID 형식 및 AuthnRequest에서 신뢰할 인증서를 알 수 있게 합니다.
  </Card>

  <Card title="ID 제공자(IdP) — 귀하의 조직" icon="shield-halved">
    귀하 조직의 Okta, Entra ID, Ping, ADFS 등. IdP는 발행자, SSO 엔드포인트 및 인증서를 설명하는 자체 메타데이터 XML을 게시합니다 — EK는 IdP가 반환하는 assertion을 확인하기 위해 이것을 필요로 합니다.
  </Card>
</CardGroup>

이메일 도메인(예: `acme.com`)에 대해 SSO를 활성화하려면 슈퍼 관리자가 이 교환의 양쪽을 완료해야 합니다:

<Steps>
  <Step title="IdP와 SP 메타데이터 공유">
    IdP 관리자에게 EK 인스턴스가 게시한 SP 메타데이터를 제공하여 IdP에서 EK를 SAML 애플리케이션으로 등록할 수 있게 합니다.
  </Step>

  <Step title="IdP 메타데이터를 EK에 업로드">
    IdP 애플리케이션이 생성되면 결과 IdP 메타데이터 XML을 **슈퍼 관리자 → SSO 메타데이터**를 통해 EK에 업로드합니다. 로그인할 사용자의 이메일 도메인을 키로 사용합니다.
  </Step>
</Steps>

양쪽이 모두 설정되면 `@<도메인>`으로 끝나는 이메일을 가진 모든 사용자가 기업 IdP를 통해 SAML SSO로 EK에 로그인할 수 있습니다.

## 사용자가 SSO 흐름에 도달하는 방식

EK 로그인 화면은 항상 "SSO로 로그인" 옵션을 표시합니다. 사용자가 이를 클릭하면 EKB 웹 UI 빌드에 포함된 두 프론트엔드 환경 변수에 따라 달라집니다:

| 변수                          | 목적                                   |
| --------------------------- | ------------------------------------ |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | 로그인 화면이 사용하는 SSO 모드를 결정합니다.          |
| `VITE_SSO_ENTERPRISE_ID`    | 단일 클릭 모드에서만 사용되어 인증할 이메일 도메인을 지정합니다. |

<AccordionGroup>
  <Accordion title="모드 A — 단일 클릭 SSO (VITE_ALLOW_ONLY_SSO_LOGIN=true)">
    로그인 화면에 SSO 버튼만 표시됩니다 — 이메일이나 비밀번호 필드가 없습니다. 이는 단일 이메일 도메인을 지원하는 온프레미스 배포의 일반적인 설정입니다.

    사용자가 버튼을 클릭하면 프론트엔드가 `VITE_SSO_ENTERPRISE_ID`를 읽고 즉시 다음으로 리다이렉션됩니다:

    ```
    https://<your-backend-host>/sso/login?enterprise_id=<VITE_SSO_ENTERPRISE_ID>&target_url=https://<your-frontend-host>/okta/authenticate
    ```

    작동하려면:

    * `VITE_SSO_ENTERPRISE_ID`가 프론트엔드에 설정되어야 합니다.
    * 그 값이 **SSO 메타데이터** 탭에 IdP 메타데이터가 업로드된 도메인과 일치해야 합니다.
    * 메타데이터를 업로드할 때 **SSO 팀 이메일 도메인**이 `VITE_SSO_ENTERPRISE_ID`와 정확히 일치해야 합니다(대소문자 구분 없음; 저장 시 소문자로 정규화됨).

    `VITE_SSO_ENTERPRISE_ID`가 설정되지 않으면 사용자는 \*"SSO 로그인용 도메인을 결정할 수 없습니다"\*라는 메시지를 보고 진행할 수 없습니다. 설정되었지만 해당 도메인에 대한 메타데이터가 없으면 리다이렉션이 이루어지지만 백엔드에서 SSO가 실패합니다.
  </Accordion>

  <Accordion title="모드 B — 이메일 모달 SSO (VITE_ALLOW_ONLY_SSO_LOGIN=false, 기본값)">
    로그인 화면에 이메일/비밀번호와 SSO 컨트롤이 함께 표시됩니다. SSO 버튼을 클릭하면 *"이메일을 입력하세요"* 모달이 열립니다. 사용자가 이메일을 제출하면 프론트엔드가 도메인을 추출하고 `POST https://<your-backend-host>/sso/verify_enterprise_id`를 통해 백엔드에 SSO가 구성되어 있는지 확인합니다.

    * **예인 경우**, 프론트엔드는 다음으로 리다이렉션됩니다:
      ```
      https://<your-backend-host>/sso/login?enterprise_id=<email-domain>&target_url=https://<your-frontend-host>/okta/authenticate
      ```
    * **아닌 경우**, 사용자는 \*"귀하의 조직은 SSO 로그인이 구성되지 않았습니다. 관리자에게 문의하세요."\*라는 메시지를 봅니다.

    이 모드에서는 `VITE_SSO_ENTERPRISE_ID`가 사용되지 않습니다. 여러 도메인이 공존할 수 있습니다 — 각각은 SSO 메타데이터 탭에 자체 IdP 메타데이터를 업로드해야 합니다.
  </Accordion>
</AccordionGroup>

<Info>
  두 모드 모두 동일한 `enterprise_id` 매개변수를 사용하여 동일한 백엔드 `/sso/login` 엔드포인트를 사용합니다. 유일한 차이점은 그 값이 프론트엔드 환경 변수에 의해 하드 코딩되는지(모드 A) 또는 로그인 시 사용자의 이메일에서 파생되는지(모드 B)입니다.
</Info>

## 백엔드가 `enterprise_id`로 하는 작업

백엔드가 `GET /sso/login?enterprise_id=acme.com`을 받으면 `acme.com`에 대해 업로드된 IdP 메타데이터를 조회하고 SAML SP 구성을 런타임에 구축합니다:

| 매개변수             | 값                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **엔티티 ID**       | 배포 시 설정된 경우 `CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`; 그렇지 않으면 기본값 `https://<your-backend-host>/user/generic/sso/saml/acs/admin` |
| **ACS 엔드포인트**    | `https://<your-backend-host>/user/generic/sso/saml/acs/admin` (HTTP-POST 바인딩)                                             |
| **NameID 형식**    | `emailAddress`                                                                                                            |
| **원격 IdP 메타데이터** | 스토리지의 업로드된 XML을 가리키는 서명된 URL                                                                                              |

제공된 `enterprise_id`에 대한 메타데이터가 없으면 백엔드는 SAML SP 구성을 구축할 수 없고 SSO 시도가 실패합니다.

## 브라우저 수준 리다이렉트 체인

`enterprise_id`가 업로드된 메타데이터로 해결되면 인증은 브라우저 리다이렉트 시퀀스로 진행됩니다:

<Steps>
  <Step title="사용자가 프론트엔드에서 시작">
    사용자가 `https://<your-frontend-host>`에서 EK를 열고 SSO 버튼을 클릭합니다.
  </Step>

  <Step title="프론트엔드 → 백엔드">
    프론트엔드가 브라우저를 백엔드 SSO 진입점으로 리다이렉션합니다:

    ```
    GET https://<your-backend-host>/sso/login?enterprise_id=acme.com&target_url=https://<your-frontend-host>/okta/authenticate
    ```
  </Step>

  <Step title="백엔드 → IdP">
    백엔드가 `acme.com`에 대한 업로드된 IdP 메타데이터에서 SAML AuthnRequest를 구축하고 브라우저를 IdP의 SSO 엔드포인트로 리다이렉션합니다.
  </Step>

  <Step title="IdP가 사용자를 인증">
    IdP가 인증을 처리합니다 — 비밀번호, MFA, 인증서 또는 조직에서 구성한 모든 것.
  </Step>

  <Step title="IdP → 백엔드">
    IdP가 SAML 응답을 EK 백엔드 ACS 엔드포인트에 POST합니다:

    ```
    POST https://<your-backend-host>/user/generic/sso/saml/acs/admin
    ```

    백엔드는 업로드된 메타데이터의 IdP 서명 인증서에 대해 assertion을 확인한 다음 사용자를 기존 EKB 계정에 로그인하거나 새 계정을 프로비저닝합니다.
  </Step>

  <Step title="백엔드 → 프론트엔드">
    백엔드가 사용자의 브라우저를 EKB의 `<your-frontend-host>`로 다시 리다이렉션합니다. 정확한 URL은 백엔드의 `FRONTEND_ROOT_URL` 환경 변수에 의해 결정됩니다 — 이것이 잘못 구성되면 사용자는 SSO를 성공적으로 완료한 것처럼 보이지만 잘못된 페이지에 도달하게 됩니다.
  </Step>
</Steps>

<Note>
  IdP는 `<your-backend-host>`와만 상호작용합니다. 프론트엔드 호스트는 흐름의 시작(사용자가 시작하는 곳)과 끝(로그인 후 도착하는 곳)에만 나타납니다 — 어떤 IdP 대면 URL에도 나타나지 않습니다.
</Note>

SSO를 구성할 준비가 되셨나요? 단계별 지침은 [SSO 메타데이터 설정 가이드](/super-admin/sso/saml-sso-metadata-setup-guide)를 참조하세요.