跳到主要内容
版本：Latest(v3.0) 🔥

Multi Auth Guide(SAML / LDAP)

개요​

이 문서는 APIM 에서 SAML(Security Assertion Markup Language)과 LDAP(Active Directory) 인증을 도메인별로 설정하고 운영하는 방법에 대한 가이드입니다.

목차​

  1. 기본 개념
  2. 설정 방법
  3. 주요 기능
  4. 환경 변수 설정
  5. 문제 해결
  6. 주의사항

기본 개념​

도메인별 인증 분기란?​

APIM BFF는 접속하는 도메인에 따라 다른 인증 방식을 사용할 수 있습니다:

  • 기본 인증: 일반적인 Basic 인증
  • SAML 인증: 특정 도메인에서 SAML IDP를 통한 인증
  • LDAP 인증: 특정 도메인에서 LDAP/Active Directory를 통한 인증

사용 시나리오​

예시 1: SAML 인증 도메인

  • 도메인: console1.xxx.com
  • 인증 방식: SAML IDP를 통한 인증
  • 특징: 로그아웃 버튼이 표시되지 않음 (IDP에서 세션 관리)

예시 2: LDAP 인증 도메인

  • 도메인: console2.xxx.com
  • 인증 방식: LDAP/Active Directory 인증

예시 3: 기본 인증 도메인

  • 도메인: console3.xxx.com (설정되지 않은 도메인)
  • 인증 방식: Basic 인증

설정 방법​

1. 설정 페이지 접근​

  1. APIM 콘솔에 관리자 권한으로 로그인
  2. 좌측 메뉴에서 설정 클릭
  3. 도메인별 인증 방식 분기 섹션으로 스크롤

2. 도메인별 인증 분기 활성화​

  1. 도메인별 인증 방식 분기 스위치를 ON으로 설정
  2. 이 스위치가 OFF이면 모든 도메인에서 기본 인증 방식 사용

3. SAML 인증 설정​

SAML 인증을 사용할 도메인 설정:

  1. SAML 인증 콘솔 도메인 스위치를 ON으로 설정
  2. SAML 콘솔 도메인 필드에 도메인 입력

4. LDAP 인증 설정​

LDAP 인증을 사용할 도메인 설정:

  1. LDAP(AD) 인증 콘솔 도메인 스위치를 ON으로 설정
  2. LDAP(AD) 콘솔 도메인 필드에 도메인 입력
  • 예: console1.xxx.com
  • 주의: 프로토콜(http://, https://)과 포트 번호는 입력하지 마세요
  • 주의: 경로(/path)는 입력하지 마세요

올바른 입력 예시:

  • ✅ console1.xxx.com
  • ✅ apim.company.com
  • ✅ console.example.co.kr

잘못된 입력 예시:

  • ❌ https://console1.xxx.com
  • ❌ console1.xxx.com:8080
  • ❌ console1.xxx.com/path

5. 설정 저장​

  1. 모든 설정을 완료한 후 저장 버튼 클릭
  2. 저장 성공 메시지 확인
  3. 설정이 즉시 적용됩니다 (재시작 불필요)

6. 설정 확인​

설정이 올바르게 저장되었는지 확인:

  1. 설정 페이지를 새로고침
  2. 입력한 도메인과 스위치 상태 확인
  3. 다른 브라우저나 시크릿 모드에서 해당 도메인으로 접속하여 인증 방식 확인

주요 기능​

SAML 도메인에서의 동작​

1. 로그아웃 버튼 숨김​

  • SAML 도메인에서는 화면 상단의 로그아웃 버튼이 자동으로 숨겨집니다
  • SAML 인증은 IDP(Identity Provider)에서 세션을 관리하므로 별도의 로그아웃 버튼이 필요하지 않습니다

2. 로그아웃 처리​

  • SAML 도메인에서 로그아웃이 필요한 경우:
    • 세션 타임아웃,
    • 또는 브라우저 세션 종료
  • SAML 도메인에서 세션 만료 시:
    • 자동으로 로그아웃 처리되어 로그인 페이지로 이동합니다

일반 도메인에서의 동작​

  • 로그아웃 버튼이 정상적으로 표시됩니다
  • 에러 발생 시 일반적인 에러 메시지가 표시됩니다
  • 기본 인증 방식이 사용됩니다

환경 변수 설정​

필수 환경 변수​

SAML 인증을 사용하려면 다음 환경 변수를 설정해야 합니다:

1. 기본 로그인 URL​

APIM_LOGIN_URL=https://login.example.com

  • 기본 인증 방식에서 사용되는 로그인 URL
  • 모든 도메인에서 공통으로 사용 (SAML 도메인 제외)

2. SAML 로그인 URL (SAML 도메인 사용 시 필수)​

APIM_SAML_LOGIN_URL=https://saml-idp.example.com/sso/login

  • SAML 도메인에서 사용되는 로그인 URL
  • SAML IDP의 로그인 엔드포인트
  • 주의: SAML 도메인을 설정했지만 이 변수가 없으면 기본 로그인 URL이 사용됩니다

3. Tenant Manager URL​

APIM_TENANT_MANAGER_URL=https://tenant-manager.example.com

  • Tenant Manager 서비스 URL
  • 로그아웃 처리 시 사용

환경 변수 설정 방법​

  1. Kubernetes 환경:
    • ConfigMap 또는 Secret에 환경 변수 추가
    • Deployment YAML 파일 수정z