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

---