版本：Latest(v3.0) 🔥

Multi Auth Guide (SAML & LDAP)

概述

本文是关于如何在 APIM BFF 中设置和操作 SAML（安全声明标记语言）和 LDAP（活动目录）认证的完整指南。

*后端（Kubernetes）*和 프론트엔드(BFF 콘솔) 设置都包括在内。

toc_min_heading_level: 1 toc_max_heading_level: 3

基本概念

什么是基于域的认证分支？

APIM BFF 可以根据访问的域使用不同的认证方式：

기본 인증: 一般的基本认证
SAML 인증: 通过特定域的 SAML IDP 进行认证
LDAP 인증: 通过特定域的 LDAP/活动目录进行认证

整体设置流程

백엔드 설정 (Kubernetes): 在租户管理器中设置认证配置文件和环境变量
프론트엔드 설정 (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）

各配置文件说明

k8s_ldap

설명: 仅使用 LDAP（轻量级目录访问协议）认证的配置文件
사용 사례: 使用企业内部活动目录或 LDAP 服务器进行用户认证
특징:
- 直接与 LDAP 服务器通信进行用户认证
- 支持基于组的权限管理
- 禁用 SAML 功能

k8s_saml

설명: 仅使用 SAML（安全声明标记语言）认证的配置文件
사용 사례: 通过 Keycloak、Okta、Azure AD 等外部 IdP（身份提供者）进行 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 内部服务名称 (例如: ldap://ldap-service.namespace.svc.cluster.local:389)

2.3 k8s_saml 전용 환경변수

필수 환경변수

SAML SP (Service Provider) 설정

环境变量	描述	示例	默认值	必需
SAML_SP_ENTITY_ID	SP 实体 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 (单点注销) URL	/saml/slo	/saml/slo	⚠️
SAML_SP_ACS_URL	SP ACS (断言消费者服务) 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 实体 ID (元数据解析失败时的回退)	https://keycloak.api.skapim.com/realms/saml	-	⚠️
SAML_IDP_SSO_URL	IdP SSO URL (元数据解析失败时的回退)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	-	⚠️
SAML_IDP_SLO_URL	IdP SLO URL (元数据解析失败时的回退)	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	是否需要断言签名	true	true	⚠️
SAML_SECURITY_REQUIRE_SIGNED_RESPONSES	是否需要响应签名	true	true	⚠️
SAML_SECURITY_REQUIRE_ENCRYPTED_ASSERTIONS	是否需要断言加密	false	false	⚠️
SAML_SECURITY_ASSERTION_VALIDITY_TIME	断言有效时间 (秒)	300	300 (5分钟)	⚠️
SAML_SECURITY_RESPONSE_VALIDITY_TIME	响应有效时间 (秒)	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 回退设置 (元数据解析失败时)- 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 불필요)

可以直接通过 URL 引用，而不使用 ConfigMap：

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 实体 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 实体 ID (回退)	https://keycloak.api.skapim.com/realms/saml	⚠️
SAML_IDP_SSO_URL	IdP SSO URL (回退)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	⚠️
SAML_IDP_SLO_URL	IdP SLO URL (回退)	https://keycloak.api.skapim.com/realms/saml/protocol/saml	⚠️

SAML 보안 설정

环境变量	描述	示例	默认值	必需
SAML_SECURITY_REQUIRE_SIGNED_ASSERTIONS	是否需要签名的断言	true	true	⚠️
SAML_SECURITY_REQUIRE_SIGNED_RESPONSES	是否需要签名的响应	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 是内部系统等重要系统时，勾选此复选框
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 (身份提供者) 管理会话，因此不需要单独的登出按钮
- 用户可以直接在 IDP 中登出
### <b>2. 登出处理</b> \{#2.-登出-处理}

- 在 SAML 域中需要登出时:
    - 直接在 IDP 中登出
    - 或者结束浏览器会话
- 系统将自动调用 SAML 登出端点
### <b>3. 错误消息处理</b> \{#3.-错误-消息-处理}

- 当 IDP 登出启用为 <b>ON</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 域名，必须在 BFF 中设置 APIM_SAML_LOGIN_URL 环境变量
更改环境变量后需要重新启动应用程序

6. 테스트 방법

更改设置后务必进行测试：
1. 检查后端设置（Tenant Manager 配置文件及环境变量）
2. 检查前端设置（BFF 控制台域名设置）
3. 访问设置的域名
4. 确认登录流程
5. 确认注销按钮的显示情况（当 IDP 注销激活为 ON 时隐藏）
6. 确认注销操作

概述​

目录​

toc_min_heading_level: 1 toc_max_heading_level: 3​

基本概念​

什么是基于域的认证分支？​

整体设置流程​

使用场景​

后端设置（Kubernetes）​

各配置文件说明​

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）

各配置文件说明

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. 테스트 방법