SSO 메타데이터 설정 가이드

참고

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

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

EK의 SAML SSO가 내부적으로 어떻게 작동하는지 잘 모르시나요? 먼저 SAML SSO 개요를 시작하세요.

전제 조건

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

• 온프레미스 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가 직접 가져올 수 있습니다.

팁

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

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

옵션 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 형식 및 서명 인증서 — 을 자동으로 채웁니다.

옵션 B — 파일을 다운로드하여 전달

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

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 재정의 변경 시.

수동 구성(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을 요구합니다.

경고

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

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 메타데이터 탭 열기

1. EK에 로그인

   슈퍼 관리자로서 EK에 로그인합니다.

2. 슈퍼 관리자 대시보드 열기

   오른쪽 상단의 계정 메뉴로 이동하여 슈퍼 관리자 대시보드를 클릭합니다.

3. SSO 메타데이터 탭으로 이동

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

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

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

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

1. 메타데이터 추가 대화 상자 열기

   SSO 메타데이터 탭의 오른쪽 상단에서 메타데이터 추가를 클릭합니다. 아직 도메인이 구성되지 않은 경우 빈 상태 카드에서도 클릭할 수 있습니다.
   

2. 이메일 도메인 입력

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

   경고

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

3. 업로드 방법을 선택하고 XML 제공
   파일 업로드

   IdP 관리자가 제공한 .xml 파일을 선택합니다. .xml 확장자가 있는 파일만 허용됩니다.

   XML 내용 붙여넣기

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

4. 제출

   메타데이터 업로드를 클릭합니다. 대화 상자가 닫히고 토스트 알림이 업로드를 확인하며 새 도메인이 테이블에 나타납니다.

참고

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

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

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

1. 도메인 행 찾기

   SSO 메타데이터 테이블에서 도메인을 찾습니다.

2. 업데이트 클릭

   행의 작업 열에서 업데이트를 클릭합니다.

3. 새 XML 제공

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

4. 제출

   메타데이터 업데이트를 클릭합니다. 교체는 즉시 적용됩니다 — 해당 도메인의 다음 SSO 로그인이 새 메타데이터를 사용합니다.

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

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

유용한 경우:

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

도메인의 메타데이터 삭제

1. 삭제 클릭

   행의 작업 열에서 삭제를 클릭합니다.

2. 확인

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

위험

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

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

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

끝에서 끝 체크리스트

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

1. EK SP 메타데이터를 IdP 관리자와 공유

   IdP 관리자에게 EK 백엔드의 SP 메타데이터를 제공합니다 — 프론트엔드 호스트가 아닙니다.

   • IdP가 백엔드에 직접 접근할 수 있는 경우 다음을 알려주세요:

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

   • 그렇지 않으면 XML을 다운로드하여 비대면으로 전달합니다:

     curl -o ek_sp_metadata.xml https://<your-backend-host>/saml/well-known/sp-metadata

2. IdP 관리자가 SAML 애플리케이션을 만듦

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

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

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

4. IdP 메타데이터를 EK에 업로드

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

5. 로그인 테스트

   실제 @<도메인> 사용자로 테스트합니다. 사용자가 인증에 성공했지만 접근이 거부되면 SAML 접근 제어 구성을 확인하세요 — SAML 접근 제어 가이드를 참조하세요.

6. 변경 사항 문서화

   내부 변경 관리 시스템에 다음을 기록합니다: 도메인, IdP 유형, 업로드 날짜 및 업로드를 수행한 슈퍼 관리자.

7. 메타데이터 새로고침 예약

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

---

문제가 발생하나요? SSO 문제 해결 및 참고 가이드를 참조하세요.