버전: Latest(v3.0) 🔥

Multi Auth Guide (SAML & LDAP)

개요

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

*백엔드(Kubernetes)**와 프론트엔드(BFF 콘솔) 설정을 모두 포함합니다.

toc_min_heading_level: 1 toc_max_heading_level: 3

기본 개념

도메인별 인증 분기란?

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

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

전체 설정 흐름

백엔드 설정 (Kubernetes): Tenant Manager에 인증 프로파일 및 환경변수 설정
프론트엔드 설정 (BFF 콘솔): 도메인별 인증 방식 분기 설정

사용 시나리오

예시 1: SAML 인증 도메인 (IDP 로그아웃 활성화)

백엔드: k8s_saml 프로파일 사용
프론트엔드: console1.xxx.com → SAML 도메인 설정, IDP 로그아웃 활성화 ON
특징: 로그아웃 버튼이 표시되지 않음, 에러 메시지 제거

예시 2: SAML 인증 도메인 (IDP 로그아웃 비활성화)

백엔드: k8s_saml 프로파일 사용
프론트엔드: console1.xxx.com → SAML 도메인 설정, IDP 로그아웃 활성화 OFF
특징: 일반 인증과 동일하게 동작 (로그아웃 버튼 표시, 에러 메시지 표시)

예시 3: LDAP 인증 도메인

백엔드: k8s_ldap 프로파일 사용
프론트엔드: console2.xxx.com → LDAP 도메인 설정

예시 4: 기본 인증 도메인

백엔드: 기본 프로파일 사용
프론트엔드: 설정되지 않은 도메인
인증 방식: 기본 베이직 인증

백엔드 설정 (kubernetes)

2.1 각 프로파일 설명

k8s_ldap

설명: LDAP(Lightweight Directory Access Protocol) 인증만 사용하는 프로파일
사용 사례: 기업 내부 Active Directory나 LDAP 서버를 사용한 사용자 인증
특징:
- LDAP 서버와 직접 통신하여 사용자 인증
- 그룹 기반 권한 관리 지원
- SAML 기능 비활성화

k8s_saml

설명: SAML(Security Assertion Markup Language) 인증만 사용하는 프로파일
사용 사례: Keycloak, Okta, Azure AD 등 외부 IdP(Identity Provider)를 통한 SSO 인증
특징:
- IdP 메타데이터 자동 파싱 지원
- URL, 클래스패스, 파일 시스템 등 다양한 메타데이터 소스 지원
- LDAP 기능 비활성화

k8s_multi

설명: LDAP와 SAML 인증을 동시에 지원하는 프로파일
사용 사례: 다양한 인증 방식을 선택적으로 사용해야 하는 환경
특징:
- LDAP와 SAML 두 가지 인증 방식 모두 활성화
- 사용자가 인증 방식을 선택하여 로그인 가능
- 각 인증 방식별로 독립적인 세션 관리

2.2 k8s_ldap 전용 환경변수

필수 환경변수

LDAP 서버 설정

환경변수	설명	예시	기본값	필수
LDAP_SERVER_URL	LDAP 서버 주소	ldap://skbb.co.kr:389/DC=skbb,DC=co,DC=kr	ldap://goblin-ldap.goblin-ldap.svc.cluster.local:389/dc=skapim,dc=com	✅
LDAP_MANAGER_DN	LDAP 관리자 DN (Distinguished Name)	CN=Apim,OU=Users,DC=skbb,DC=co,DC=kr	cn=admin,dc=skapim,dc=com	✅
LDAP_MANAGER_PASSWORD	LDAP 관리자 비밀번호	akemfdj1@	-	✅

LDAP 인증 설정

환경변수	설명	예시	기본값	필수
LDAP_USER_DN_PATTERNS	사용자 DN 패턴 (0은 사용자명으로 치환됨)	cn=0,OU=partners,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	cn=0,ou=people	⚠️
LDAP_GROUP_SEARCH_BASE	그룹 검색 기본 DN	OU=Groups,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	ou=groups	⚠️
LDAP_GROUP_ROLE_ATTRIBUTE	그룹 역할 속성명	cn	cn	⚠️
LDAP_PASSWORD_ATTRIBUTE	비밀번호 속성명	userPassword	userPassword	⚠️

배포용 k8s deploy 중요부분만

apiVersion: apps/v1
kind: Deployment
metadata:
  name: apim-tenant-manager-deployment
  labels:
    app: apim-tenant-manager
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-tenant-manager
  template:
    metadata:
      labels:
        app: apim-tenant-manager
    spec:
      containers:
      - name: apim-tenant-manager
        image: registry.example.com/apim-tenant-manager:latest
        ports:
        - containerPort: 8080
        env:
# 프로파일 설정- name: SPRING_PROFILES_ACTIVE
          value: "k8s_ldap"


# LDAP 서버 설정- name: LDAP_SERVER_URL
          value: "ldap://skbb.co.kr:389/DC=skbb,DC=co,DC=kr"
        - name: LDAP_MANAGER_DN
          value: "CN=Apim,OU=Users,DC=skbb,DC=co,DC=kr"
        - name: LDAP_MANAGER_PASSWORD
          valueFrom:
            secretKeyRef:
              name: ldap-secret
              key: manager-password

# LDAP 인증 설정- name: LDAP_USER_DN_PATTERNS
          value: "cn={0},OU=partners,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr"
        - name: LDAP_GROUP_SEARCH_BASE
          value: "OU=Groups,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr"
        - name: LDAP_GROUP_ROLE_ATTRIBUTE
          value: "cn"

중요 사항:

SPRING_PROFILES_ACTIVE는 반드시 k8s_ldap로 설정
LDAP 서버 URL은 Kubernetes 내부 Service 이름으로도 사용 가능 (예: ldap://ldap-service.namespace.svc.cluster.local:389)

2.3 k8s_saml 전용 환경변수

필수 환경변수

SAML SP (Service Provider) 설정

환경변수	설명	예시	기본값	필수
SAML_SP_ENTITY_ID	SP Entity ID (고유 식별자)	apim-tenant-manager	apim-tenant-manager	⚠️
SAML_SP_METADATA_URL	SP 메타데이터 URL	/saml/metadata	/saml/metadata	⚠️
SAML_SP_SSO_URL	SP SSO URL	/saml/sso	/saml/sso	⚠️
SAML_SP_SLO_URL	SP SLO (Single Logout) URL	/saml/slo	/saml/slo	⚠️
SAML_SP_ACS_URL	SP ACS (Assertion Consumer Service) URL	/saml/acs	/saml/acs	⚠️
SAML_SP_KEYSTORE_LOCATION	키스토어 파일 위치	classpath:saml/keystore.jks	classpath:saml/keystore.jks	⚠️
SAML_SP_KEYSTORE_PASSWORD	키스토어 비밀번호	changeit	-	✅
SAML_SP_PRIVATE_KEY_PASSWORD	개인키 비밀번호	changeit	-	✅
SAML_SP_CERTIFICATE_ALIAS	인증서 별칭	saml	saml	⚠️

SAML IdP (Identity Provider) 설정

환경변수	설명	예시	기본값	필수
SAML_IDP_METADATA_URL	IdP 메타데이터 소스 (XML 파일 또는 URL)주의: 메타데이터에서 자동으로 entity-id, sso-url, slo-url 등을 파싱함	URL: https://keycloak.api.skapim.com/realms/saml/protocol/saml/descriptor파일: classpath:saml/idp-metadata.xmlConfigMap: file:/etc/config/idp-metadata.xml	https://keycloak.api.skapim.com/realms/saml/protocol/saml/descriptor	✅
SAML_IDP_ENTITY_ID	IdP Entity ID (메타데이터 파싱 실패 시 Fallback)	https://keycloak.api.skapim.com/realms/saml	-	⚠️
SAML_IDP_SSO_URL	IdP SSO URL (메타데이터 파싱 실패 시 Fallback)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	-	⚠️
SAML_IDP_SLO_URL	IdP SLO URL (메타데이터 파싱 실패 시 Fallback)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	-	⚠️
SAML_IDP_CERTIFICATE_LOCATION	IdP 인증서 파일 위치	classpath:saml/idp-certificate.crt	classpath:saml/idp-certificate.crt	⚠️

SAML 보안 설정

환경변수	설명	예시	기본값	필수
SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS	Assertion 서명 필요 여부	true	true	⚠️
SAML_SECURITY_REQUIRE_SIGNED_RESPONSES	Response 서명 필요 여부	true	true	⚠️
SAML_SECURITY_REQUIRE_ENCRYPTED_ASSERTIONS	Assertion 암호화 필요 여부	false	false	⚠️
SAML_SECURITY_ASSERTION_VALIDITY_TIME	Assertion 유효 시간 (초)	300	300 (5분)	⚠️
SAML_SECURITY_RESPONSE_VALIDITY_TIME	Response 유효 시간 (초)	300	300 (5분)	⚠️

표 기호 설명:

✅: 필수 설정
⚠️: 선택 설정 (기본값 사용 가능)

배포용 k8s deploy 중요부분만

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apim-tenant-manager-deployment
  labels:
    app: apim-tenant-manager
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-tenant-manager
  template:
    metadata:
      labels:
        app: apim-tenant-manager
    spec:
      containers:
      - name: apim-tenant-manager
        image: registry.example.com/apim-tenant-manager:latest
        ports:
        - containerPort: 8080
        env:
# 프로파일 설정- name: SPRING_PROFILES_ACTIVE
          value: "k8s_saml"


# SAML SP 설정- name: SAML_SP_ENTITY_ID
          value: "apim-tenant-manager"
        - name: SAML_SP_KEYSTORE_PASSWORD
          valueFrom:
            secretKeyRef:
              name: saml-secret
              key: keystore-password
        - name: SAML_SP_PRIVATE_KEY_PASSWORD
          valueFrom:
            secretKeyRef:
              name: saml-secret
              key: private-key-password

# SAML IdP 설정 (ConfigMap 사용 예시)- name: SAML_IDP_METADATA_URL
          value: "file:/etc/config/idp-metadata.xml"

# SAML IdP Fallback 설정 (메타데이터 파싱 실패 시)- name: SAML_IDP_ENTITY_ID
          value: "https://keycloak.api.skapim.com/realms/saml"
        - name: SAML_IDP_SSO_URL
          value: "https://keycloak.api.skapim.com/realms/saml/protocol/saml"
        - name: SAML_IDP_SLO_URL
          value: "https://keycloak.api.skapim.com/realms/saml/protocol/saml"

# SAML 보안 설정- name: SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS
          value: "true"
        - name: SAML_SECURITY_REQUIRE_SIGNED_RESPONSES
          value: "true"

# ConfigMap 마운트volumeMounts:
        - name: idp-metadata
          mountPath: /etc/config
          readOnly: true

      volumes:
      - name: idp-metadata
        configMap:
          name: idp-metadata-configmap

중요 사항:

SAML_IDP_METADATA_URL은 URL, 클래스패스, 파일 경로 모두 지원
IdP 메타데이터는 ConfigMap으로 관리 가능 (아래 참고)

IdP 메타데이터 ConfigMap 설정법

IdP 메타데이터 XML 파일 준비

IdP로부터 메타데이터 XML 파일을 받거나 다운로드합니다.

예시 메타데이터 XML:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://keycloak.api.skapim.com/realms/saml">

  <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

<!-- SSO 서비스 --><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                           Location="https://keycloak.api.skapim.com/realms/saml/protocol/saml"/>

<!-- SLO 서비스 --><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                           Location="https://keycloak.api.skapim.com/realms/saml/protocol/saml"/>

<!-- 인증서 --><md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIDXTCCAkWgAwIBAgIJAKoK/Ovj8u...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>

  </md:IDPSSODescriptor>

</md:EntityDescriptor>

ConfigMap 생성

방법 1: 파일로부터 직접 생성

kubectl create configmap idp-metadata-configmap \
  --from-file=idp-metadata.xml=/path/to/idp-metadata.xml \
  --namespace=default

방법 2: YAML 파일로 생성

idp-metadata-configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: idp-metadata-configmap
  namespace: default
data:
  idp-metadata.xml: |
    <?xml version="1.0" encoding="UTF-8"?>
    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                         entityID="https://keycloak.api.skapim.com/realms/saml">

      <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                               Location="https://keycloak.api.skapim.com/realms/saml/protocol/saml"/>

        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                               Location="https://keycloak.api.skapim.com/realms/saml/protocol/saml"/>

        <md:KeyDescriptor use="signing">
          <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
              <ds:X509Certificate>MIIDXTCCAkWgAwIBAgIJAKoK/Ovj8u...</ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
        </md:KeyDescriptor>

      </md:IDPSSODescriptor>

    </md:EntityDescriptor>

적용:

kubectl apply -f idp-metadata-configmap.yaml

ConfigMap 업데이트 방법

방법 1: 파일로부터 업데이트

kubectl create configmap idp-metadata-configmap \
  --from-file=idp-metadata.xml=/path/to/idp-metadata.xml \
  --dry-run=client -o yaml | kubectl apply -f -

방법 2: YAML 파일로 업데이트

kubectl apply -f idp-metadata-configmap.yaml

방법 3: 직접 편집

kubectl edit configmap idp-metadata-configmap

ConfigMap을 업데이트한 후, Pod를 재시작하면 새로운 메타데이터가 적용됩니다:

kubectl rollout restart deployment/apim-tenant-manager-deployment

메타데이터 URL 방식 사용 (ConfigMap 불필요)

ConfigMap을 사용하지 않고 URL로 직접 참조할 수도 있습니다:

env:
- name: SAML_IDP_METADATA_URL
  value: "https://keycloak.api.skapim.com/realms/saml/protocol/saml/descriptor"

이 경우 애플리케이션 시작 시 URL에서 메타데이터를 자동으로 다운로드하여 파싱합니다.

2.4 k8s_multi 설명

k8s_ldap, k8s_saml 동시 설정

k8s_multi 프로파일은 LDAP와 SAML 인증을 동시에 지원합니다. 사용자는 로그인 시 인증 방식을 선택할 수 있습니다.

환경변수 설정

k8s_multi 프로파일은 k8s_ldap와 k8s_saml의 모든 환경변수를 함께 설정해야 합니다.

필수 환경변수:

LDAP 설정

환경변수	설명	예시	필수
LDAP_SERVER_URL	LDAP 서버 주소	ldap://skbb.co.kr:389/DC=skbb,DC=co,DC=kr	✅
LDAP_MANAGER_DN	LDAP 관리자 DN	CN=Apim,OU=Users,DC=skbb,DC=co,DC=kr	✅
LDAP_MANAGER_PASSWORD	LDAP 관리자 비밀번호	akemfdj1@ (Secret 권장)	✅
LDAP_USER_DN_PATTERNS	사용자 DN 패턴	cn=0,OU=partners,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	⚠️
LDAP_GROUP_SEARCH_BASE	그룹 검색 기본 DN	OU=Groups,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	⚠️
LDAP_GROUP_ROLE_ATTRIBUTE	그룹 역할 속성명	cn	⚠️

SAML SP 설정

환경변수	설명	예시	필수
SAML_SP_ENTITY_ID	SP Entity ID	apim-tenant-manager-v3	⚠️
SAML_SP_KEYSTORE_PASSWORD	키스토어 비밀번호	changeit (Secret 권장)	✅
SAML_SP_PRIVATE_KEY_PASSWORD	개인키 비밀번호	changeit (Secret 권장)	✅

SAML IdP 설정

환경변수	설명	예시	필수
SAML_IDP_METADATA_URL	IdP 메타데이터 소스 (URL/파일/ConfigMap)	URL: https://keycloak.api.skapim.com/realms/saml/protocol/saml/descriptor파일: file:/etc/config/idp-metadata.xml	✅
SAML_IDP_ENTITY_ID	IdP Entity ID (Fallback)	https://keycloak.api.skapim.com/realms/saml	⚠️
SAML_IDP_SSO_URL	IdP SSO URL (Fallback)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	⚠️
SAML_IDP_SLO_URL	IdP SLO URL (Fallback)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	⚠️

SAML 보안 설정

환경변수	설명	예시	기본값	필수
SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS	Assertion 서명 필요 여부	true	true	⚠️
SAML_SECURITY_REQUIRE_SIGNED_RESPONSES	Response 서명 필요 여부	true	true	⚠️

표 기호 설명:

✅: 필수 설정
⚠️: 선택 설정 (기본값 사용 가능 또는 선택 사항)

배포용 k8s deploy 전체 예시

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apim-tenant-manager-deployment
  labels:
    app: apim-tenant-manager
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-tenant-manager
  template:
    metadata:
      labels:
        app: apim-tenant-manager
    spec:
      containers:
      - name: apim-tenant-manager
        image: registry.example.com/apim-tenant-manager:latest
        ports:
        - containerPort: 8080
        env:
# 프로파일 설정- name: SPRING_PROFILES_ACTIVE
          value: "k8s_multi"


# ========== LDAP 설정 ==========- name: LDAP_SERVER_URL
          value: "ldap://skbb.co.kr:389/DC=skbb,DC=co,DC=kr"
        - name: LDAP_MANAGER_DN
          value: "CN=Apim,OU=Users,DC=skbb,DC=co,DC=kr"
        - name: LDAP_MANAGER_PASSWORD
          valueFrom:
            secretKeyRef:
              name: ldap-secret
              key: manager-password
        - name: LDAP_USER_DN_PATTERNS
          value: "cn={0},OU=partners,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr"
        - name: LDAP_GROUP_SEARCH_BASE
          value: "OU=Groups,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr"
        - name: LDAP_GROUP_ROLE_ATTRIBUTE
          value: "cn"

# ========== SAML SP 설정 ==========- name: SAML_SP_ENTITY_ID
          value: "apim-tenant-manager-v3"
        - name: SAML_SP_KEYSTORE_PASSWORD
          valueFrom:
            secretKeyRef:
              name: saml-secret
              key: keystore-password
        - name: SAML_SP_PRIVATE_KEY_PASSWORD
          valueFrom:
            secretKeyRef:
              name: saml-secret
              key: private-key-password

# ========== SAML IdP 설정 ==========- name: SAML_IDP_METADATA_URL
          value: "file:/etc/config/idp-metadata.xml"
        - name: SAML_IDP_ENTITY_ID
          value: "https://keycloak.api.skapim.com/realms/saml"
        - name: SAML_IDP_SSO_URL
          value: "https://keycloak.api.skapim.com/realms/saml/protocol/saml"
        - name: SAML_IDP_SLO_URL

value: "https://keycloak.api.skapim.com/realms/saml/protocol/saml"

========== SAML 보안 설정 ==========- name: SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS

value: "true"

name: SAML_SECURITY_REQUIRE_SIGNED_RESPONSES value: "true"

========== Volume 마운트 ==========volumeMounts:

name: idp-metadata mountPath: /etc/config readOnly: true

volumes:

name: idp-metadata configMap: name: idp-metadata-configmap

### <b>주요 특징</b> \{#주요-특징}

1. <b>동시 지원</b>: LDAP와 SAML 두 가지 인증 방식을 동시에 활성화
1. <b>독립 세션</b>: 각 인증 방식별로 독립적인 세션 관리
1. <b>선택적 로그인</b>: 사용자가 로그인 시 인증 방식을 선택 가능
1. <b>세션 제한</b>: LDAP와 SAML 각각 1개씩 총 2개의 최대 세션 허용
### <b>주의사항</b> \{#주의사항}

- LDAP와 SAML의 모든 필수 환경변수를 설정해야 함
- Secret은 반드시 Kubernetes Secret으로 관리
- IdP 메타데이터는 ConfigMap 또는 URL로 제공 가능
- SESSION_SECURE는 HTTPS 환경에서만 true로 설정
---

## <b>프론트엔드 설정 (BFF 콘솔)</b> \{#프론트엔드-설정-(bff-콘솔)}

### <b>3.1 도메인별 인증 분기 설정</b> \{#3.1-도메인별-인증-분기-설정}

### <b>설정 페이지 접근</b> \{#설정-페이지-접근}

1. APIM 콘솔에 관리자 권한으로 로그인
1. 좌측 메뉴에서 <b>설정</b> 클릭
1. <b>도메인별 인증 방식 분기</b> 섹션으로 스크롤
### <b>도메인별 인증 분기 활성화</b> \{#도메인별-인증-분기-활성화}

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

### <b>3.2 SAML 인증 설정</b> \{#3.2-saml-인증-설정}

### <b>SAML 인증을 사용할 도메인 설정</b> \{#saml-인증을-사용할-도메인-설정}

1. <b>SAML 인증 콘솔 도메인</b> 스위치를 <b>ON</b>으로 설정
1. <b>SAML 콘솔 도메인</b> 필드에 도메인 입력
    - 예: console1.xxx.com
### <b>IDP 로그아웃 활성화 설정</b> \{#idp-로그아웃-활성화-설정}

1. SAML 도메인을 설정한 후, <b>IDP 로그아웃 활성화</b> 체크박스가 표시됩니다
1. IDP가 사내시스템 등 중요한 시스템일 때 체크박스를 <b>체크</b>합니다
1. 체크 시:
    - APIM에서 로그아웃 버튼이 자동으로 숨겨집니다
    - 세션 만료 등 에러 발생 시 에러 메시지가 표시되지 않습니다
    - 자동으로 로그아웃 처리되어 로그인 페이지로 이동합니다
---

### <b>3.3 LDAP 인증 설정</b> \{#3.3-ldap-인증-설정}

### <b>LDAP 인증을 사용할 도메인 설정</b> \{#ldap-인증을-사용할-도메인-설정}

1. <b>LDAP(AD) 인증 콘솔 도메인</b> 스위치를 <b>ON</b>으로 설정
1. <b>LDAP(AD) 콘솔 도메인</b> 필드에 도메인 입력
    - 예: console2.xxx.com
### <b>주의사항</b> \{#주의사항}

- 프로토콜(http://, https://)과 포트 번호는 입력하지 마세요
- 경로(/path)는 입력하지 마세요

<b>올바른 입력 예시:</b>

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

<b>잘못된 입력 예시:</b>

- ❌ https://console1.xxx.com
- ❌ console1.xxx.com:8080
- ❌ console1.xxx.com/path
### <b>설정 저장</b> \{#설정-저장}

1. 모든 설정을 완료한 후 <b>저장</b> 버튼 클릭
1. 저장 성공 메시지 확인
1. 설정이 즉시 적용됩니다 (재시작 불필요)
### <b>설정 확인</b> \{#설정-확인}


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

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

## <b>주요 기능</b> \{#주요-기능}

### <b>SAML 도메인에서의 동작 (IDP 로그아웃 활성화 ON)</b> \{#saml-도메인에서의-동작-(idp-로그아웃-활성화-on)}

### <b>1. 로그아웃 버튼 숨김</b> \{#1.-로그아웃-버튼-숨김}

- IDP 로그아웃 활성화가 <b>ON</b>일 때만 로그아웃 버튼이 자동으로 숨겨집니다
- SAML 인증은 IDP(Identity Provider)에서 세션을 관리하므로 별도의 로그아웃 버튼이 필요하지 않습니다
- 사용자는 IDP에서 직접 로그아웃할 수 있습니다
### <b>2. 로그아웃 처리</b> \{#2.-로그아웃-처리}

- SAML 도메인에서 로그아웃이 필요한 경우:
    - IDP에서 직접 로그아웃
    - 또는 브라우저 세션 종료
- 시스템이 자동으로 SAML 로그아웃 엔드포인트를 호출합니다
### <b>3. 에러 메시지 처리</b> \{#3.-에러-메시지-처리}

- IDP 로그아웃 활성화가 <b>ON</b>일 때 세션 만료 등의 에러 발생 시:
    - "세션이 종료되었습니다. 로그인이 필요합니다." 메시지가 <b>표시되지 않습니다</b>
    - 자동으로 로그아웃 처리되어 로그인 페이지로 이동합니다
- 이는 SAML 인증의 특성상 IDP에서 세션을 관리하기 때문입니다
### <b>SAML 도메인에서의 동작 (IDP 로그아웃 활성화 OFF)</b> \{#saml-도메인에서의-동작-(idp-로그아웃-활성화-off)}

- 로그아웃 버튼이 정상적으로 표시됩니다
- 에러 발생 시 일반적인 에러 메시지가 표시됩니다
- 일반 인증 방식과 동일하게 동작합니다
### <b>일반 도메인에서의 동작</b> \{#일반-도메인에서의-동작}

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

## <b>환경 변수 설정</b> \{#환경-변수-설정}

### <b>BFF 프론트엔드 필수 환경 변수</b> \{#bff-프론트엔드-필수-환경-변수}


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

### <b>1. 기본 로그인 URL</b> \{#1.-기본-로그인-url}

```bash
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
로그아웃 처리 시 사용

환경 변수 설정 방법

Kubernetes 환경:
- ConfigMap 또는 Secret에 환경 변수 추가
- Deployment YAML 파일 수정

주의사항

1. 도메인 입력 형식

✅ 올바른 형식: console1.xxx.com
❌ 잘못된 형식:
- https://console1.xxx.com
- console1.xxx.com:8080
- console1.xxx.com/path

2. 도메인 중복 설정

하나의 도메인에 여러 인증 방식을 설정하지 마세요
예: console1.xxx.com에 SAML과 LDAP을 동시에 설정하면 안 됩니다

3. IDP 로그아웃 활성화 사용 시기

활성화 권장: IDP가 사내시스템, 금융시스템 등 중요한 시스템일 때
비활성화 권장: IDP가 일반적인 외부 서비스일 때

4. 백엔드와 프론트엔드 설정 일치

백엔드에서 k8s_saml 프로파일을 사용하면 프론트엔드에서도 SAML 도메인을 설정해야 합니다
백엔드에서 k8s_ldap 프로파일을 사용하면 프론트엔드에서도 LDAP 도메인을 설정해야 합니다
백엔드에서 k8s_multi 프로파일을 사용하면 프론트엔드에서 SAML과 LDAP 도메인을 각각 다른 도메인에 설정할 수 있습니다

5. 환경 변수 설정

SAML 도메인을 사용하려면 반드시 APIM_SAML_LOGIN_URL 환경 변수를 BFF에 설정해야 합니다
환경 변수 변경 후에는 애플리케이션 재시작이 필요합니다

6. 테스트 방법

설정 변경 후 반드시 테스트하세요:
1. 백엔드 설정 확인 (Tenant Manager 프로파일 및 환경변수)
2. 프론트엔드 설정 확인 (BFF 콘솔 도메인 설정)
3. 설정한 도메인으로 접속
4. 로그인 프로세스 확인
5. 로그아웃 버튼 표시 여부 확인 (IDP 로그아웃 활성화 ON일 때 숨김)
6. 로그아웃 동작 확인

개요​

목차​

toc_min_heading_level: 1 toc_max_heading_level: 3​

기본 개념​

도메인별 인증 분기란?​

전체 설정 흐름​

사용 시나리오​

백엔드 설정 (kubernetes)​

2.1 각 프로파일 설명​

k8s_ldap​

k8s_saml​

k8s_multi​

2.2 k8s_ldap 전용 환경변수​

필수 환경변수​

LDAP 서버 설정​

LDAP 인증 설정​

배포용 k8s deploy 중요부분만​

2.3 k8s_saml 전용 환경변수​

필수 환경변수​

SAML SP (Service Provider) 설정​

SAML IdP (Identity Provider) 설정​

SAML 보안 설정​

배포용 k8s deploy 중요부분만​

IdP 메타데이터 ConfigMap 설정법​

IdP 메타데이터 XML 파일 준비​

ConfigMap 생성​

ConfigMap 업데이트 방법​

메타데이터 URL 방식 사용 (ConfigMap 불필요)​

2.4 k8s_multi 설명​

k8s_ldap, k8s_saml 동시 설정​

환경변수 설정​

LDAP 설정​

SAML SP 설정​

SAML IdP 설정​

SAML 보안 설정​

배포용 k8s deploy 전체 예시​

========== SAML 보안 설정 ==========- name: SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS

========== Volume 마운트 ==========volumeMounts:

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

3. Tenant Manager URL​

환경 변수 설정 방법​

주의사항​

1. 도메인 입력 형식​

2. 도메인 중복 설정​

3. IDP 로그아웃 활성화 사용 시기​

4. 백엔드와 프론트엔드 설정 일치​

5. 환경 변수 설정​

6. 테스트 방법​

개요

목차

toc_min_heading_level: 1 toc_max_heading_level: 3

기본 개념

도메인별 인증 분기란?

전체 설정 흐름

사용 시나리오

백엔드 설정 (kubernetes)

2.1 각 프로파일 설명

k8s_ldap

k8s_saml

k8s_multi

2.2 k8s_ldap 전용 환경변수

필수 환경변수

LDAP 서버 설정

LDAP 인증 설정

배포용 k8s deploy 중요부분만

2.3 k8s_saml 전용 환경변수

필수 환경변수

SAML SP (Service Provider) 설정

SAML IdP (Identity Provider) 설정

SAML 보안 설정

배포용 k8s deploy 중요부분만

IdP 메타데이터 ConfigMap 설정법

IdP 메타데이터 XML 파일 준비

ConfigMap 생성

ConfigMap 업데이트 방법

메타데이터 URL 방식 사용 (ConfigMap 불필요)

2.4 k8s_multi 설명

k8s_ldap, k8s_saml 동시 설정

환경변수 설정

LDAP 설정

SAML SP 설정

SAML IdP 설정

SAML 보안 설정

배포용 k8s deploy 전체 예시

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

3. Tenant Manager URL

환경 변수 설정 방법

주의사항

1. 도메인 입력 형식

2. 도메인 중복 설정

3. IDP 로그아웃 활성화 사용 시기

4. 백엔드와 프론트엔드 설정 일치

5. 환경 변수 설정

6. 테스트 방법