EK SSO용 Azure AD 설정

이 가이드는 온프레미스 EK 인스턴스의 SAML SSO에 대한 ID 제공자(IdP)로 Azure Active Directory(Entra ID)를 구성하는 과정을 안내합니다. Azure AD에서 입력할 SAML 설정, 연합 메타데이터를 가져오는 방법 및 통합을 완료하기 위해 EK에 도메인을 등록하는 방법을 다룹니다.

참고

EK의 범용 SAML 흐름은 Azure AD / Entra ID와 기본적으로 작동합니다. 아직 읽지 않은 경우 시작하기 전에 SAML SSO 개요를 읽어 통합이 어떻게 작동하는지 이해하세요.

전제 조건

Azure AD / Entra ID 테넌트에 대한 관리자 접근 권한이 있습니다.
온프레미스 EK 인스턴스에 대한 슈퍼 관리자 접근 권한이 있습니다.
EK 백엔드 호스트의 정규화된 도메인 이름(FQDN)을 알고 있습니다(예: ek-api.corp.acme.com).
SSO를 활성화하려는 이메일 도메인을 알고 있습니다(예: acme.com).

1부 — Azure AD 구성

Azure AD에서 새 엔터프라이즈 애플리케이션 만들기

새 엔터프라이즈 애플리케이션 만들기
Azure 포털에서 Azure Active Directory → 엔터프라이즈 애플리케이션으로 이동하여 새 애플리케이션을 클릭합니다. 자신만의 애플리케이션 만들기를 선택하고 이름을 지정합니다(예: EK SSO). **갤러리에서 찾을 수 없는 다른 애플리케이션 통합(갤러리 외부)**을 선택합니다.
SSO 구성 열기
애플리케이션이 생성되면 관리 → 싱글 사인온으로 이동하고 로그인 방법으로 SAML을 선택합니다.

기본 SAML 구성 입력

기본 SAML 구성 섹션에서 다음 값을 입력합니다:

필드	값
식별자(엔티티 ID)	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
답장 URL(ACS URL)	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
로그인 URL	비워두기
릴레이 상태	`default`
로그아웃 URL	비워두기

속성 및 클레임 구성
속성 및 클레임 섹션에서 다음 매핑을 확인하거나 추가합니다:
속성 값
givenname user.givenname
surname user.surname
emailaddress user.mail
name user.userprincipalname
DisplayName user.displayname
email user.mail
고유 사용자 식별자(Name ID) user.userprincipalname

속성	값
`givenname`	`user.givenname`
`surname`	`user.surname`
`emailaddress`	`user.mail`
`name`	`user.userprincipalname`
`DisplayName`	`user.displayname`
`email`	`user.mail`
고유 사용자 식별자(Name ID)	`user.userprincipalname`

2부 — Azure AD 메타데이터 가져오기

Azure AD 애플리케이션이 구성되면 연합 메타데이터 URL을 가져옵니다:

SAML 인증서 섹션으로 이동
애플리케이션에서 관리 → 싱글 사인온 → SAML 인증서로 이동합니다.
앱 연합 메타데이터 URL 복사
앱 연합 메타데이터 URL을 찾아 복사합니다.
경로는:
```
관리 > 싱글 사인온 > SAML 인증서 > 앱 연합 메타데이터 URL
```
이 URL은 3부에서 필요합니다.

3부 — EK에 도메인 등록

도메인 등록 엔드포인트에 POST 요청을 보냅니다:

curl -X POST "https://<your-backend-host>/backend/sso/add_new_configuration" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "enterprise_id": "acme.com",
    "provider": "azure",
    "metadata_url": "https://your-azure-federation-metadata-url",
    "backend_root_url": "<your-backend-host>/backend"
  }'

필수 필드

필드	설명
`enterprise_id`	사용자의 이메일 도메인(예: `acme.com`).
`provider`	`"azure"`
`metadata_url`	2부의 앱 연합 메타데이터 URL.
`backend_root_url`	(선택 사항) 올바른 라우팅을 보장하기 위해 프록시 설정에서만 필요.

인증

엔드포인트는 X-API-KEY 및 X-API-SECRET 헤더로 전달되는 EKB API 키와 시크릿을 요구합니다.

성공 시 백엔드의 sso_providers 테이블에 레코드가 생성됩니다.

4부 — 프론트엔드 구성

도메인이 등록되면 프론트엔드 환경 변수를 설정하고 프론트엔드 서비스를 재시작합니다.

프론트엔드 환경 파일 열기
온프레미스 배포 서버에서 onprem-deployment/.env.web을 엽니다.
환경 변수 추가
다음 줄을 추가하고 acme.com을 실제 이메일 도메인으로 교체합니다:
```
VITE_SSO_ENTERPRISE_ID=acme.com
```

프론트엔드 서비스 재시작

docker compose -f docker-compose down
docker compose -f docker-compose up -d

통합 테스트

실제 @<도메인> 사용자로 EK에 로그인하여 전체 흐름이 작동하는지 확인합니다. 사용자가 인증에 성공했지만 접근이 거부되면 SAML 접근 제어 구성을 확인하세요 — EK SAML 접근 제어 및 자동 팀/프로젝트 할당 가이드를 참조하세요.

전제 조건​

1부 — Azure AD 구성​

Azure AD에서 새 엔터프라이즈 애플리케이션 만들기​

2부 — Azure AD 메타데이터 가져오기​

3부 — EK에 도메인 등록​

필수 필드​

인증​

4부 — 프론트엔드 구성​

통합 테스트​