# Active Directory / LDAP 访问管理

LLMS 索引： [llms.txt](/zh/llms.txt)

---

<a id="active-directory-ldap"></a>
<a id="minio-external-identity-management-ad-ldap"></a>

MinIO 支持配置单个 Active Directory 或 LDAP (AD/LDAP) 服务，用于对用户身份进行外部管理。 启用 AD/LDAP 外部身份管理会禁用 [MinIO 内部 IDP](/zh/administration/identity-access-management/minio-identity-management/#minio-internal-idp)。

对于由外部 AD/LDAP 提供方管理的身份，SILO 加载显式关联到用户 Distinguished Name（DN）的现有[策略](/zh/administration/identity-access-management/policy-based-access-control/#minio-policy)。策略名称不需要与 DN 相同。

如果 AD/LDAP 配置包含查询组成员关系所需的设置，SILO 还会加载显式关联到返回的组 DN 的策略。

默认情况下，MinIO 会拒绝访问所有未被用户已分配或继承的 [策略](/zh/administration/identity-access-management/policy-based-access-control/#minio-policy) 明确允许的操作或资源。 管理员通过 `mcli idp ldap policy attach` 将现有策略关联到 LDAP 用户或组。 如果没有任何策略与用户 DN 或组 DN 匹配，MinIO 会阻止该部署上对所有操作和资源的访问。

MinIO 用于认证用户并获取其组成员关系的具体 AD/LDAP 查询，是在 [使用 Active Directory / LDAP 身份管理部署集群](/zh/operations/external-iam/#minio-external-iam-ad-ldap) 时配置的。 本页介绍如何创建 SILO 策略，并将它们显式关联到返回的 Distinguished Name。

<a id="id2" data-td-print-local></a>

## 认证与授权流程 {#authentication-and-authorization-flow}

使用 Active Directory / LDAP 凭证的应用程序登录流程如下：

1. 将 AD/LDAP 凭证提供给 MinIO Security Token Service (STS) [AssumeRoleWithLDAPIdentity](/zh/developers/security-token-service/AssumeRoleWithLDAPIdentity/#minio-sts-assumerolewithldapidentity) API 端点。
2. MinIO 针对 AD/LDAP 服务器校验所提供的凭证。
3. SILO 加载显式关联到用户 DN 的[策略](/zh/administration/identity-access-management/policy-based-access-control/#minio-policy)。

   如果配置为执行组查询，MinIO 还会查询该用户所属的 AD/LDAP 组列表。 SILO 加入显式关联到各个返回的组 DN 的策略。
4. MinIO 会在 STS API 响应中返回临时凭证，其形式为 access key、 secret key 和 session token。这些凭证的权限来自显式关联到已认证用户 DN *或* 组 DN 的策略。

MinIO 提供了一个示例 Go 应用程序 [ldap.go](https://github.com/pgsty/silo/blob/RELEASE.2026-10-26T00-00-00Z/docs/sts/ldap.go)，用于处理完整的 登录流程。

AD/LDAP 用户也可以创建与其 AD/LDAP 用户 Distinguished Name 关联的 [访问密钥](/zh/administration/identity-access-management/minio-user-management/#minio-idp-service-account)。 访问密钥是长期有效的凭证，会继承父用户的权限。 父用户在创建访问密钥时还可以进一步限制这些权限。 使用以下方法之一创建新的访问密钥：

使用 [`mc admin user svcacct add`](/zh/reference/minio-mc-admin/mc-admin-user-svcacct-add/#command-mc.admin.user.svcacct.add) 命令创建访问密钥。 将用户 Distinguished Name 指定为要关联访问密钥的用户名。

<a id="dn" data-td-print-local></a>

## 将策略映射到用户 DN {#mapping-policies-to-user-dn}

以下命令使用 [`mc idp ldap policy attach`](/zh/reference/minio-mc/mc-idp-ldap-policy-attach/#command-mc.idp.ldap.policy.attach) 将现有 MinIO [策略](/zh/administration/identity-access-management/policy-based-access-control/#minio-policy) 关联到 AD/LDAP 用户 DN。

```shell
mc idp ldap policy attach myminio consoleAdmin \
  --user='cn=sisko,cn=users,dc=example,dc=com'

mc idp ldap policy attach myminio readwrite diagnostics \
  --user='cn=dax,cn=users,dc=example,dc=com'
```

- MinIO 会将 [`consoleAdmin`](/zh/administration/identity-access-management/policy-based-access-control/#userpolicy.consoleAdmin) 策略分配给 DN 匹配 `cn=sisko,cn=users,dc=example,dc=com` 的已认证用户， 从而授予其对 MinIO 服务器的完全访问权限。
- MinIO 会将 [`readwrite`](/zh/administration/identity-access-management/policy-based-access-control/#userpolicy.readwrite) 和 [`diagnostics`](/zh/administration/identity-access-management/policy-based-access-control/#userpolicy.diagnostics) 两个策略分配给 DN 匹配 `cn=dax,cn=users,dc=example,dc=com` 的已认证用户，从而授予其对 MinIO 服务器的一般读写访问权限，*以及* 诊断性管理操作的访问权限。
- MinIO 不会为 DN 匹配 `cn=quark,cn=users,dc=example,dc=com` 的 已认证用户分配任何策略，并会拒绝其对所有 API 操作的访问。

<a id="id3" data-td-print-local></a>

## 将策略映射到组 DN {#mapping-policies-to-group-dn}

以下命令使用 [`mc idp ldap policy attach`](/zh/reference/minio-mc/mc-idp-ldap-policy-attach/#command-mc.idp.ldap.policy.attach) 将现有 MinIO [策略](/zh/administration/identity-access-management/policy-based-access-control/#minio-policy) 关联到 AD/LDAP 组 DN。

```shell
mc idp ldap policy attach myminio consoleAdmin \
  --group='cn=ops,cn=groups,dc=example,dc=com'

mc idp ldap policy attach myminio diagnostics \
  --group='cn=engineering,cn=groups,dc=example,dc=com'
```

- MinIO 会将 [`consoleAdmin`](/zh/administration/identity-access-management/policy-based-access-control/#userpolicy.consoleAdmin) 策略分配给任何属于 `cn=ops,cn=groups,dc=example,dc=com` AD/LDAP 组的认证用户，从而授予其对 MinIO 服务器的完全访问权限。
- MinIO 会将 [`diagnostics`](/zh/administration/identity-access-management/policy-based-access-control/#userpolicy.diagnostics) 策略分配给任何属于 `cn=engineering,cn=groups,dc=example,dc=com` AD/LDAP 组的认证用户，从而授予其对 诊断性管理操作的访问权限。

## 规范化长 DN {#long-distinguished-names}

[Server 20261026](/zh/blog/release/silo-20261026/#server-20261026)合入了 [LDAP 长 DN 修复](/zh/blog/design/ldap-long-dn/)（Server 20261018 不包含此修复）。当用户仅依赖组策略登录、但其规范化 DN 长度超过对象存储后端的文件名上限时，服务端会将纯 ASCII 路径分量超过 255 字节所触发的文件名超长错误视为“无个人策略映射记录”并继续加载组策略；完整路径超限（`PATH_MAX`）、不可读撤销记录及其他存储错误仍按 Fail-Closed 报错，对象后端也仍不支持写入超长路径记录。

### 存储身份记录的组关系刷新 {#stored-record-group-refresh}

在下一版本 SILO 构建（`a0de92fcb`）中，当 LDAP 用户通过存储的身份记录（`fromStored`）进行认证或刷新时，只要缓存的组列表超过 1 小时（`ldapStoredGroupRefreshInterval = 1h`），服务端就会重新向 LDAP 查询组成员关系，并在刷新失败时按 Fail-Closed 拒绝访问。参见 [LDAP 规范化长 DN](/zh/blog/design/ldap-long-dn/)。