Phiên bản: Latest(v3.0) 🔥

Multi Auth Guide (SAML & LDAP)

개요

Tài liệu này là hướng dẫn đầy đủ về cách thiết lập và vận hành xác thực SAML (Security Assertion Markup Language) và LDAP (Active Directory) trong APIM BFF.

*Bao gồm cả thiết lập Backend (Kubernetes) và 프론트엔드(BFF 콘솔).

toc_min_heading_level: 1 toc_max_heading_level: 3

기본 개념

도메인별 인증 분기란?

APIM BFF có thể sử dụng các phương thức xác thực khác nhau tùy thuộc vào miền truy cập:

기본 인증: Xác thực cơ bản thông thường
SAML 인증: Xác thực qua SAML IDP cho miền cụ thể
LDAP 인증: Xác thực qua LDAP/Active Directory cho miền cụ thể

전체 설정 흐름

백엔드 설정 (Kubernetes): Thiết lập hồ sơ xác thực và biến môi trường trong Tenant Manager
프론트엔드 설정 (BFF 콘솔): Thiết lập phân nhánh phương thức xác thực theo miền

사용 시나리오

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

Backend: Sử dụng hồ sơ k8s_saml
Frontend: console1.xxx.com → Thiết lập miền SAML, kích hoạt đăng xuất IDP ON
Đặc điểm: Nút đăng xuất không hiển thị, xóa thông báo lỗi

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

Backend: Sử dụng hồ sơ k8s_saml
Frontend: console1.xxx.com → Thiết lập miền SAML, kích hoạt đăng xuất IDP OFF
Đặc điểm: Hoạt động giống như xác thực thông thường (hiển thị nút đăng xuất, hiển thị thông báo lỗi)

예시 3: LDAP 인증 도메인

Backend: Sử dụng hồ sơ k8s_ldap
Frontend: console2.xxx.com → Thiết lập miền LDAP

예시 4: 기본 인증 도메인

Backend: Sử dụng hồ sơ mặc định
Frontend: miền chưa được thiết lập
Phương thức xác thực: xác thực cơ bản mặc định

백엔드 설정 (Kubernetes)

2.1 각 프로파일 설명

k8s_ldap

설명: Hồ sơ chỉ sử dụng xác thực LDAP (Lightweight Directory Access Protocol)
사용 사례: Xác thực người dùng sử dụng Active Directory hoặc máy chủ LDAP nội bộ của doanh nghiệp
특징:
- Xác thực người dùng bằng cách giao tiếp trực tiếp với máy chủ LDAP
- Hỗ trợ quản lý quyền dựa trên nhóm
- Tính năng SAML bị vô hiệu hóa

k8s_saml

설명: Hồ sơ chỉ sử dụng xác thực SAML (Security Assertion Markup Language)
사용 사례: Xác thực SSO qua IdP (Identity Provider) bên ngoài như Keycloak, Okta, Azure AD
특징:
- Hỗ trợ tự động phân tích siêu dữ liệu IdP
- Hỗ trợ nhiều nguồn siêu dữ liệu như URL, classpath, hệ thống tệp
- Tính năng LDAP bị vô hiệu hóa

k8s_multi

설명: Hồ sơ hỗ trợ đồng thời xác thực LDAP và SAML
사용 사례: Môi trường cần sử dụng linh hoạt nhiều phương thức xác thực
특징:
- Kích hoạt cả hai phương thức xác thực LDAP và SAML
- Người dùng có thể chọn phương thức xác thực để đăng nhập
- Quản lý phiên độc lập cho từng phương thức xác thực

2.2 k8s_ldap 전용 환경변수

필수 환경변수

LDAP 서버 설정

Biến môi trường	Mô tả	Ví dụ	Giá trị mặc định	Bắt buộc
LDAP_SERVER_URL	Địa chỉ máy chủ 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	DN (Distinguished Name) của quản trị viên LDAP	CN=Apim,OU=Users,DC=skbb,DC=co,DC=kr	cn=admin,dc=skapim,dc=com	✅
LDAP_MANAGER_PASSWORD	Mật khẩu quản trị viên LDAP	akemfdj1@	-	✅

LDAP 인증 설정

Biến môi trường	Mô tả	Ví dụ	Giá trị mặc định	Bắt buộc
LDAP_USER_DN_PATTERNS	Mẫu DN người dùng (0 sẽ được thay thế bằng tên người dùng)	cn=0,OU=partners,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	cn=0,ou=people	⚠️
LDAP_GROUP_SEARCH_BASE	DN cơ sở tìm kiếm nhóm	OU=Groups,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	ou=groups	⚠️
LDAP_GROUP_ROLE_ATTRIBUTE	Tên thuộc tính vai trò nhóm	cn	cn	⚠️
LDAP_PASSWORD_ATTRIBUTE	Tên thuộc tính mật khẩu	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:
# Cài đặt hồ sơ- name: SPRING_PROFILES_ACTIVE
          value: "k8s_ldap"


# Cài đặt máy chủ 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

# Cài đặt xác thực 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 phải được thiết lập thành k8s_ldap
Địa chỉ URL máy chủ LDAP cũng có thể được sử dụng như tên dịch vụ nội bộ của Kubernetes (ví dụ: ldap://ldap-service.namespace.svc.cluster.local:389)

2.3 k8s_saml 전용 환경변수

필수 환경변수

SAML SP (Service Provider) 설정

Biến môi trường	Mô tả	Ví dụ	Giá trị mặc định	Bắt buộc
SAML_SP_ENTITY_ID	SP Entity ID (định danh duy nhất)	apim-tenant-manager	apim-tenant-manager	⚠️
SAML_SP_METADATA_URL	URL siêu dữ liệu SP	/saml/metadata	/saml/metadata	⚠️
SAML_SP_SSO_URL	URL SSO SP	/saml/sso	/saml/sso	⚠️
SAML_SP_SLO_URL	URL SLO (Đăng xuất đơn) SP	/saml/slo	/saml/slo	⚠️
SAML_SP_ACS_URL	URL ACS (Dịch vụ tiêu thụ xác nhận) SP	/saml/acs	/saml/acs	⚠️
SAML_SP_KEYSTORE_LOCATION	Vị trí tệp keystore	classpath:saml/keystore.jks	classpath:saml/keystore.jks	⚠️
SAML_SP_KEYSTORE_PASSWORD	Mật khẩu keystore	changeit	-	✅
SAML_SP_PRIVATE_KEY_PASSWORD	Mật khẩu khóa riêng	changeit	-	✅
SAML_SP_CERTIFICATE_ALIAS	Bí danh chứng chỉ	saml	saml	⚠️

SAML IdP (Identity Provider) 설정

Biến môi trường	Mô tả	Ví dụ	Giá trị mặc định	Bắt buộc
SAML_IDP_METADATA_URL	Nguồn siêu dữ liệu IdP (tệp XML hoặc URL)주의: Tự động phân tích entity-id, sso-url, slo-url từ siêu dữ liệu	URL: https://keycloak.api.skapim.com/realms/saml/protocol/saml/descriptorTệp: 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 khi phân tích siêu dữ liệu thất bại)	https://keycloak.api.skapim.com/realms/saml	-	⚠️
SAML_IDP_SSO_URL	URL SSO IdP (Fallback khi phân tích siêu dữ liệu thất bại)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	-	⚠️
SAML_IDP_SLO_URL	URL SLO IdP (Fallback khi phân tích siêu dữ liệu thất bại)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	-	⚠️
SAML_IDP_CERTIFICATE_LOCATION	Vị trí tệp chứng chỉ IdP	classpath:saml/idp-certificate.crt	classpath:saml/idp-certificate.crt	⚠️

SAML 보안 설정

Biến môi trường	Mô tả	Ví dụ	Giá trị mặc định	Bắt buộc
SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS	Cần thiết có chữ ký cho xác nhận	true	true	⚠️
SAML_SECURITY_REQUIRE_SIGNED_RESPONSES	Cần thiết có chữ ký cho phản hồi	true	true	⚠️
SAML_SECURITY_REQUIRE_ENCRYPTED_ASSERTIONS	Cần thiết mã hóa xác nhận	false	false	⚠️
SAML_SECURITY_ASSERTION_VALIDITY_TIME	Thời gian hiệu lực của xác nhận (giây)	300	300 (5 phút)	⚠️
SAML_SECURITY_RESPONSE_VALIDITY_TIME	Thời gian hiệu lực của phản hồi (giây)	300	300 (5 phút)	⚠️

표 기호 설명:

✅: Cài đặt bắt buộc
⚠️: Cài đặt tùy chọn (có thể sử dụng giá trị mặc định)

배포용 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:
# cấu hình hồ sơ- name: SPRING_PROFILES_ACTIVE
          value: "k8s_saml"


# cấu hình 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

# cấu hình SAML IdP (ví dụ sử dụng ConfigMap)- name: SAML_IDP_METADATA_URL
          value: "file:/etc/config/idp-metadata.xml"

# cấu hình SAML IdP Fallback (khi phân tích cú pháp metadata thất bại)- 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"

# cấu hình bảo mật SAML- name: SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS
          value: "true"
        - name: SAML_SECURITY_REQUIRE_SIGNED_RESPONSES
          value: "true"

# gắn kết ConfigMapvolumeMounts:
        - name: idp-metadata
          mountPath: /etc/config
          readOnly: true

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

Điều quan trọng:

SAML_IDP_METADATA_URL hỗ trợ URL, classpath, và đường dẫn tệp
Metadata IdP có thể được quản lý bằng ConfigMap (tham khảo bên dưới)

Cách cấu hình ConfigMap metadata IdP

Chuẩn bị tệp XML metadata IdP

Nhận hoặc tải xuống tệp XML metadata từ IdP.

Ví dụ tệp XML metadata:

<?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">

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

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

<!-- Chứng chỉ --><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>

Áp dụng:

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

Sau khi cập nhật ConfigMap, khởi động lại Pod để áp dụng metadata mới:

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

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

Bạn cũng có thể tham chiếu trực tiếp bằng URL mà không cần sử dụng ConfigMap:

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

Trong trường hợp này, ứng dụng sẽ tự động tải xuống và phân tích metadata từ URL khi khởi động.

2.4 k8s_multi 설명

k8s_ldap, k8s_saml 동시 설정

Hồ sơ k8s_multi hỗ trợ xác thực LDAP và SAML đồng thời. Người dùng có thể chọn phương thức xác thực khi đăng nhập.

환경변수 설정

Hồ sơ k8s_multi cần phải thiết lập tất cả các biến môi trường của k8s_ldap và k8s_saml cùng nhau.

필수 환경변수:

LDAP 설정

환경변수	설명	예시	필수
LDAP_SERVER_URL	Địa chỉ máy chủ LDAP	ldap://skbb.co.kr:389/DC=skbb,DC=co,DC=kr	✅
LDAP_MANAGER_DN	DN quản trị viên LDAP	CN=Apim,OU=Users,DC=skbb,DC=co,DC=kr	✅
LDAP_MANAGER_PASSWORD	Mật khẩu quản trị viên LDAP	akemfdj1@ (Khuyến nghị Secret)	✅
LDAP_USER_DN_PATTERNS	Mẫu DN người dùng	cn=0,OU=partners,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	⚠️
LDAP_GROUP_SEARCH_BASE	DN cơ sở tìm kiếm nhóm	OU=Groups,OU=HQ,OU=SKB,DC=skbb,DC=co,DC=kr	⚠️
LDAP_GROUP_ROLE_ATTRIBUTE	Tên thuộc tính vai trò nhóm	cn	⚠️

SAML SP 설정

환경변수	설명	예시	필수
SAML_SP_ENTITY_ID	SP Entity ID	apim-tenant-manager-v3	⚠️
SAML_SP_KEYSTORE_PASSWORD	Mật khẩu keystore	changeit (Khuyến nghị Secret)	✅
SAML_SP_PRIVATE_KEY_PASSWORD	Mật khẩu khóa riêng	changeit (Khuyến nghị Secret)	✅

SAML IdP 설정

환경변수	설명	예시	필수
SAML_IDP_METADATA_URL	Nguồn metadata IdP (URL/Tệp/ConfigMap)	URL: https://keycloak.api.skapim.com/realms/saml/protocol/saml/descriptor Tệp: 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	Cần chữ ký cho Assertion hay không	true	true	⚠️
SAML_SECURITY_REQUIRE_SIGNED_RESPONSES	Cần chữ ký cho Response hay không	true	true	⚠️

표 기호 설명:

✅: Cài đặt bắt buộc
⚠️: Cài đặt tùy chọn (Có thể sử dụng giá trị mặc định hoặc tùy chọn)

배포용 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:
# Cấu hình hồ sơ- name: SPRING_PROFILES_ACTIVE
          value: "k8s_multi"


# ========== Cấu hình 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"

# ========== Cấu hình 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

# ========== Cấu hình 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"

# ========== Cài đặt bảo mật SAML ==========- name: SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS
          value: "true"
        - name: SAML_SECURITY_REQUIRE_SIGNED_RESPONSES
          value: "true"

# ========== Gắn kết Volume ==========volumeMounts:
        - name: idp-metadata
          mountPath: /etc/config
          readOnly: true

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

Đặc điểm chính

Hỗ trợ đồng thời: Kích hoạt đồng thời hai phương thức xác thực LDAP và SAML
Phiên độc lập: Quản lý phiên độc lập cho từng phương thức xác thực
Đăng nhập tùy chọn: Người dùng có thể chọn phương thức xác thực khi đăng nhập
Giới hạn phiên: Cho phép tối đa 2 phiên, mỗi phương thức LDAP và SAML 1 phiên

Chú ý

Cần thiết lập tất cả các biến môi trường bắt buộc cho LDAP và SAML
Secret phải được quản lý bằng Kubernetes Secret
Metadata IdP có thể được cung cấp qua ConfigMap hoặc URL
SESSION_SECURE chỉ được thiết lập là true trong môi trường HTTPS

Cài đặt Frontend (BFF Console)

3.1 Cài đặt phân nhánh xác thực theo miền

Truy cập trang cài đặt

Đăng nhập vào APIM Console với quyền quản trị
Nhấp vào Cài đặt trong menu bên trái
Cuộn xuống phần Phân nhánh phương thức xác thực theo miền

Kích hoạt phân nhánh xác thực theo miền

Đặt công tắc Phân nhánh phương thức xác thực theo miền thành ON
Nếu công tắc này tắt, phương thức xác thực mặc định sẽ được sử dụng cho tất cả các miền

3.2 Cài đặt xác thực SAML

Cài đặt miền sử dụng xác thực SAML

Đặt công tắc Miền xác thực SAML thành ON
Nhập miền vào trường Miền Console SAML
- Ví dụ: console1.xxx.com

Kích hoạt đăng xuất IDP

Sau khi thiết lập miền SAML, hộp kiểm Kích hoạt đăng xuất IDP sẽ hiển thị
Nếu IDP là hệ thống quan trọng như hệ thống nội bộ, hãy đánh dấu vào hộp kiểm
Khi đánh dấu:
- Nút đăng xuất sẽ tự động bị ẩn trong APIM
- Không hiển thị thông báo lỗi khi có lỗi như hết phiên
- Tự động xử lý đăng xuất và chuyển đến trang đăng nhập

3.3 Cài đặt xác thực LDAP

Cài đặt miền sử dụng xác thực LDAP

Đặt công tắc Xác thực LDAP (AD) thành ON
Nhập miền vào trường Miền Console LDAP (AD)
- Ví dụ: console2.xxx.com

Chú ý

Không nhập giao thức (http://, https://) và số cổng
Không nhập đường dẫn (/path)

Ví dụ nhập đúng:

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

Ví dụ nhập sai:

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

Lưu cài đặt

Sau khi hoàn tất tất cả các cài đặt, nhấp vào nút Lưu
Xác nhận thông báo thành công khi lưu
Cài đặt sẽ được áp dụng ngay lập tức (không cần khởi động lại)

Kiểm tra cài đặt

Kiểm tra xem cài đặt đã được lưu đúng chưa:

Làm mới trang cài đặt
Kiểm tra miền đã nhập và trạng thái công tắc
Truy cập miền đó từ trình duyệt khác hoặc chế độ ẩn danh để kiểm tra phương thức xác thực

Chức năng chính

Hoạt động trên miền SAML (Kích hoạt đăng xuất IDP ON)

1. Ẩn nút đăng xuất

Nút đăng xuất sẽ tự động bị ẩn chỉ khi kích hoạt đăng xuất IDP là ON
Xác thực SAML quản lý phiên từ IDP (Nhà cung cấp danh tính) nên không cần nút đăng xuất riêng
Người dùng có thể đăng xuất trực tiếp từ IDP

2. Xử lý đăng xuất

Nếu cần đăng xuất trên miền SAML:
- Đăng xuất trực tiếp từ IDP
- Hoặc kết thúc phiên trình duyệt
Hệ thống sẽ tự động gọi điểm cuối đăng xuất SAML

3. Xử lý thông báo lỗi

Khi kích hoạt đăng xuất IDP là ON, nếu có lỗi như hết phiên:
- Thông báo "Phiên đã kết thúc. Cần đăng nhập." sẽ không hiển thị
- Tự động xử lý đăng xuất và chuyển đến trang đăng nhập
Điều này là do đặc điểm của xác thực SAML, IDP quản lý phiên

Hoạt động trên miền SAML (Kích hoạt đăng xuất IDP OFF)

Nút đăng xuất sẽ hiển thị bình thường
Khi có lỗi, thông báo lỗi thông thường sẽ hiển thị
Hoạt động giống như phương thức xác thực thông thường

Hoạt động trên miền thông thường

Nút đăng xuất sẽ hiển thị bình thường
Khi có lỗi, thông báo lỗi thông thường sẽ hiển thị
Phương thức xác thực mặc định (Basic) sẽ được sử dụng

Cài đặt biến môi trường

Các biến môi trường cần thiết cho BFF Frontend

Để sử dụng xác thực SAML, cần thiết lập các biến môi trường sau:

1. URL đăng nhập mặc định

APIM_LOGIN_URL=https://login.example.com

URL đăng nhập được sử dụng trong phương thức xác thực cơ bản
Sử dụng chung cho tất cả các miền (trừ miền SAML)

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

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

URL đăng nhập được sử dụng trong miền SAML
Điểm cuối đăng nhập của SAML IDP
주의: Nếu đã thiết lập miền SAML nhưng biến này không có, URL đăng nhập mặc định sẽ được sử dụng

3. Tenant Manager URL

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

URL dịch vụ Tenant Manager
Sử dụng khi xử lý đăng xuất

환경 변수 설정 방법

Kubernetes 환경:
- Thêm biến môi trường vào ConfigMap hoặc Secret
- Chỉnh sửa tệp YAML triển khai

주의사항

1. 도메인 입력 형식

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

2. 도메인 중복 설정

Không thiết lập nhiều phương thức xác thực cho một miền
Ví dụ: Không được thiết lập đồng thời SAML và LDAP cho console1.xxx.com

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

활성화 권장: Khi IDP là hệ thống quan trọng như hệ thống nội bộ, hệ thống tài chính
비활성화 권장: Khi IDP là dịch vụ bên ngoài thông thường

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

Nếu sử dụng hồ sơ k8s_saml ở backend, thì cũng phải thiết lập miền SAML ở frontend
Nếu sử dụng hồ sơ k8s_ldap ở backend, thì cũng phải thiết lập miền LDAP ở frontend
Nếu sử dụng hồ sơ k8s_multi ở backend, có thể thiết lập miền SAML và LDAP ở frontend cho các miền khác nhau

5. 환경 변수 설정

Để sử dụng miền SAML, phải thiết lập biến môi trường APIM_SAML_LOGIN_URL cho BFF
Cần khởi động lại ứng dụng sau khi thay đổi biến môi trường

6. 테스트 방법

Phải kiểm tra sau khi thay đổi cấu hình:
1. Kiểm tra cấu hình backend (hồ sơ Tenant Manager và biến môi trường)
2. Kiểm tra cấu hình frontend (cấu hình miền BFF console)
3. Truy cập vào miền đã thiết lập
4. Kiểm tra quy trình đăng nhập
5. Kiểm tra xem nút đăng xuất có hiển thị hay không (nếu IDP đăng xuất được kích hoạt thì ẩn)
6. Kiểm tra hành động đăng xuất

개요​

목차​

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 중요부분만​

Cách cấu hình ConfigMap metadata IdP​

Chuẩn bị tệp XML metadata IdP​

ConfigMap 생성​

ConfigMap 업데이트 방법​

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

2.4 k8s_multi 설명​

k8s_ldap, k8s_saml 동시 설정​

환경변수 설정​

LDAP 설정​

SAML SP 설정​

SAML IdP 설정​

SAML 보안 설정​

배포용 k8s deploy 전체 예시​

Đặc điểm chính​

Chú ý​

Cài đặt Frontend (BFF Console)​

3.1 Cài đặt phân nhánh xác thực theo miền​

Truy cập trang cài đặt​

Kích hoạt phân nhánh xác thực theo miền​

3.2 Cài đặt xác thực SAML​

Cài đặt miền sử dụng xác thực SAML​

Kích hoạt đăng xuất IDP​

3.3 Cài đặt xác thực LDAP​

Cài đặt miền sử dụng xác thực LDAP​

Chú ý​

Lưu cài đặt​

Kiểm tra cài đặt​

Chức năng chính​

Hoạt động trên miền SAML (Kích hoạt đăng xuất IDP ON)​

1. Ẩn nút đăng xuất​

2. Xử lý đăng xuất​

3. Xử lý thông báo lỗi​

Hoạt động trên miền SAML (Kích hoạt đăng xuất IDP OFF)​

Hoạt động trên miền thông thường​

Cài đặt biến môi trường​

Các biến môi trường cần thiết cho BFF Frontend​

1. URL đăng nhập mặc định​

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 중요부분만

Cách cấu hình ConfigMap metadata IdP

Chuẩn bị tệp XML metadata IdP

ConfigMap 생성

ConfigMap 업데이트 방법

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

2.4 k8s_multi 설명

k8s_ldap, k8s_saml 동시 설정

환경변수 설정

LDAP 설정

SAML SP 설정

SAML IdP 설정

SAML 보안 설정

배포용 k8s deploy 전체 예시

Đặc điểm chính

Chú ý

Cài đặt Frontend (BFF Console)

3.1 Cài đặt phân nhánh xác thực theo miền

Truy cập trang cài đặt

Kích hoạt phân nhánh xác thực theo miền

3.2 Cài đặt xác thực SAML

Cài đặt miền sử dụng xác thực SAML

Kích hoạt đăng xuất IDP

3.3 Cài đặt xác thực LDAP

Cài đặt miền sử dụng xác thực LDAP

Chú ý

Lưu cài đặt

Kiểm tra cài đặt

Chức năng chính

Hoạt động trên miền SAML (Kích hoạt đăng xuất IDP ON)

1. Ẩn nút đăng xuất

2. Xử lý đăng xuất

3. Xử lý thông báo lỗi

Hoạt động trên miền SAML (Kích hoạt đăng xuất IDP OFF)

Hoạt động trên miền thông thường

Cài đặt biến môi trường

Các biến môi trường cần thiết cho BFF Frontend

1. URL đăng nhập mặc định

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

3. Tenant Manager URL

환경 변수 설정 방법

주의사항

1. 도메인 입력 형식

2. 도메인 중복 설정

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

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

5. 환경 변수 설정

6. 테스트 방법