对于使用 MinIO Kubernetes Operator 部署的 MinIO Tenant，本流程包括：

• 配置 MinIO Tenant 使用外部 AD/LDAP 提供方
• 使用 AD/LDAP 凭证访问 Tenant Console
• 使用 MinIO AssumeRoleWithLDAPIdentity Security Token Service (STS) API 生成供应用程序使用的临时凭证

对于部署在裸金属基础设施上的 MinIO，本流程包括：

• 为 MinIO 集群配置外部 AD/LDAP 提供方
• 使用 AD/LDAP 凭证访问 MinIO Console
• 使用 MinIO AssumeRoleWithLDAPIdentity Security Token Service (STS) API 生成供应用程序使用的临时凭证

你必须能够访问 MinIO Operator Console Web UI。 你可以使用自己偏好的 Kubernetes 路由组件暴露 MinIO Operator Console service，也可以通过临时端口转发，在本地机器上暴露 Console service 端口。

本流程使用 mc 对 MinIO 集群执行操作。 请在一台能够访问该集群网络的机器上安装 mc。 关于如何下载和安装 mc，请参见 mc 安装快速开始。

本流程假定已为 MinIO 集群配置 alias。

• 如果 AD/LDAP 部署与 MinIO Tenant 位于同一 Kubernetes 集群内，你可以使用 Kubernetes service 名称，让 MinIO Tenant 能够连接到 AD/LDAP 服务。
• 如果 AD/LDAP 部署位于 Kubernetes 集群外部，则必须确保该集群支持 Kubernetes services、pods 与外部网络之间的通信路由。 这可能需要配置或部署额外的 Kubernetes 网络组件，和/或启用访问公网的能力。

MinIO 部署必须与目标 AD / LDAP 服务保持双向网络连通。

对于使用 MinIO Kubernetes Operator 部署的 MinIO Tenant，本流程包括：

• 配置 Keycloak 以配合 MinIO 认证与授权
• 配置新的或现有的 MinIO Tenant，使其使用 Keycloak 作为 OIDC 提供方
• 创建用于控制 Keycloak 认证用户访问权限的策略
• 使用 SSO 和 Keycloak 托管身份登录 MinIO Tenant Console
• 使用 AssumeRoleWithWebIdentity Security Token Service (STS) API 生成临时 S3 访问凭证

对于部署在裸金属基础设施上的 MinIO，本流程包括：

• 配置 Keycloak 以配合 MinIO 认证与授权
• 配置新的或现有的 MinIO 集群，使其使用 Keycloak 作为 OIDC 提供方
• 创建用于控制 Keycloak 认证用户访问权限的策略
• 使用 SSO 和 Keycloak 托管身份登录 MinIO Console
• 使用 AssumeRoleWithWebIdentity Security Token Service (STS) API 生成临时 S3 访问凭证

对于与 MinIO Tenant 位于同一 Kubernetes 集群内的 Keycloak 部署，本流程假定 Keycloak 与 MinIO 的 pods/services 之间具备双向访问能力。 对于位于 Kubernetes 集群外部的 Keycloak 部署，本流程假定已经存在用于管理 MinIO Tenant 入站和出站访问的 Ingress、Load Balancer 或类似 Kubernetes 网络控制组件。

MinIO 部署必须与目标 OIDC 服务保持双向访问。

你必须能够访问 MinIO Operator Console Web UI。 你可以使用自己偏好的 Kubernetes 路由组件暴露 MinIO Operator Console Service，也可以通过临时端口转发，在本地机器上暴露 Console Service 端口。

本流程使用 mc 对 MinIO 集群执行操作。 请在一台能够访问该集群网络的机器上安装 mc。 关于如何下载和安装 mc，请参见 mc 安装快速开始。

本流程假定已为 MinIO 集群配置 alias。

1. 配置或创建用于访问 Keycloak 的 Client

   认证到 Keycloak Administrative Console，然后进入 Clients。

   选择 Create client，按照提示为 MinIO 创建一个新的 Keycloak client。 按如下方式填写指定输入项：

   Client ID	设置为 MinIO 的唯一标识符（minio）
   Client type	设置为 OpenID Connect
   Always display in console	切换为 On
   Client authentication	切换为 On
   Authentication flow	打开 Standard flow
   （可选）Authentication flow	打开 Direct access grants （API 测试）

   Keycloak 会以一组默认配置值部署该 client。 请根据你的 Keycloak 环境和期望行为按需修改这些值。 下表提供了一组可用于配置的基线设置和值：

   Root URL	设置为 ${authBaseUrl}
   Home URL	设置为 MinIO 要使用的 Realm（/realms/master/account/）
   Valid Redirect URI	设置为 *
   Keys -> Use JWKS URL	切换为 On
   Advanced -> Advanced Settings -> Access Token Lifespan	设置为 1 Hour。

2. 为 MinIO Client 创建 Client Scope

   Client scope 允许 Keycloak 在认证请求返回的 JSON Web Token（JWT）中映射用户属性。 这样 MinIO 就可以在向用户分配策略时引用这些属性。 这一步会创建在 Keycloak 认证成功后支持 MinIO 授权所需的 client scope。

   进入 Client scopes 视图，为 MinIO 授权创建一个新的 client scope：

   Name	设置为任意易识别的策略名称（minio-authorization）
   Include in token scope	切换为 On

   创建完成后，从列表中选中该 scope，并进入 Mappers。

   选择 Configure a new mapper 创建新的映射：

   User Attribute	选择 Mapper Type
   Name	设置为任意易识别的映射名称（minio-policy-mapper）
   User Attribute	设置为 policy
   Token Claim Name	设置为 policy
   Add to ID token	设置为 On
   Claim JSON Type	设置为 String
   Multivalued	设置为 On 这样可以在单个 claim 中设置多个 policy 值。
   Aggregate attribute values	设置为 On 这样用户就可以继承其所属 Group 中设置的任意 policy。

   创建完成后，将该 Client Scope 分配给 MinIO client。

   1. 进入 Clients 并选择 MinIO client。
   2. 选择 Client scopes，然后选择 Add client scope。
   3. 选择先前创建的 scope，并将 Assigned type 设置为 default。

3. 将所需属性应用到 Keycloak Users/Groups

   你必须为 Keycloak Users 或 Groups 分配一个名为 policy 的属性。 将其值设置为 MinIO 部署上的任意 policy。

   对于 Users，进入 Users 并选择或创建 User：

   Credentials	如果尚未设置，将用户密码设置为永久值
   Attributes	创建一个新属性，键为 policy，值为 MinIO 部署上的任意 policy （consoleAdmin）

   对于 Groups，进入 Groups 并选择或创建 Group：

   Attributes

   创建一个新属性，键为 policy，值为 MinIO 部署上的任意 policy （consoleAdmin）

   你可以将用户加入组，使其继承指定的 policy 属性。 如果 Mapper 设置中启用了 Aggregate attribute values， Keycloak 会在已认证用户的 JWT token 中包含聚合后的策略数组。 MinIO 可以在为用户授权时使用这份策略列表。

   你可以使用 Keycloak API 测试某个用户配置的策略：

   curl -d "client_id=minio" \
        -d "client_secret=secretvalue" \
        -d "grant_type=password" \
        -d "username=minio-user-1" \
        -d "password=minio-user-1-password" \
        http://keycloak-service.keycloak-namespace.svc.cluster-domain.example/realms/REALM/protocol/openid-connect/token

   如果成功，access_token 中会包含调用 MinIO AssumeRoleWithWebIdentity STS API 并生成 S3 凭证所需的 JWT。

   你可以使用 JWT 解码器检查其载荷，确认其中包含 policy 键， 且列出了一个或多个 MinIO policy。

4. 为 Keycloak 认证配置 MinIO

你可以使用 mc idp openid add 命令为 Keycloak 服务创建新配置。 该命令接受所有受支持的 OpenID Configuration Settings：

mc idp openid add ALIAS PRIMARY_IAM \
   client_id=MINIO_CLIENT \
   client_secret=MINIO_CLIENT_SECRET \
   config_url="https://keycloak-service.keycloak-namespace.svc.cluster-domain.example/realms/REALM/.well-known/openid-configuration" \
   display_name="SSO_IDENTIFIER"
   scopes="openid,email,preferred_username" \
   redirect_uri_dynamic="on"

重启 MinIO 部署以应用这些更改。

检查 MinIO 日志，确认启动成功，且没有与 OIDC 配置相关的错误。

1. 使用 Security Token Service（STS）生成应用程序凭证

   使用 S3 兼容 SDK 的应用程序必须以 Access Key 和 Secret Key 的形式提供凭证。 MinIO AssumeRoleWithWebIdentity API 会使用 Keycloak 在认证后返回的 JWT 返回所需的临时凭证， 其中包括必须提供的 session token。

   你可以使用以下 HTTP 调用序列和 curl 工具测试这一工作流：

   1. 以 Keycloak 用户身份认证并获取 JWT token

      curl -X POST "https://keycloak-service.keycloak-namespace.svc.cluster-domain.example/realms/REALM/protocol/openid-connect/token" \
           -H "Content-Type: application/x-www-form-urlencoded" \
           -d "username=USER" \
           -d "password=PASSWORD" \
           -d "grant_type=password" \
           -d "client_id=CLIENT" \
           -d "client_secret=SECRET"

      • 将 USER 和 PASSWORD 替换为 REALM 中某个 Keycloak 用户的凭证。
      • 将 CLIENT 和 SECRET 替换为该 REALM 中 MinIO 专用 Keycloak client 的 ID 和 secret。

      你可以使用 jq 或类似的 JSON 格式化工具处理返回结果。 提取 access_token 字段以获取所需的访问 token。 同时关注 expires_in 字段，以了解 token 过期前还剩多少秒。

   2. 使用 AssumeRoleWithWebIdentity API 生成 MinIO 凭证

      curl -X POST "https://minio.minio-tenant.svc.cluster-domain.example" \
           -H "Content-Type: application/x-www-form-urlencoded" \
           -d "Action=AssumeRoleWithWebIdentity" \
           -d "Version=2011-06-15" \
           -d "DurationSeconds=86000" \
           -d "WebIdentityToken=TOKEN"

      将 TOKEN 替换为 Keycloak 返回的 access_token 值。

      API 成功时会返回一个 XML 文档，其中包含以下键：

      • Credentials.AccessKeyId - Keycloak 用户的 Access Key
      • Credentials.SecretAccessKey - Keycloak 用户的 Secret Key
      • Credentials.SessionToken - Keycloak 用户的 Session Token
      • Credentials.Expiration - 生成凭证的过期时间

   3. 测试这些凭证

      使用你偏好的 S3 兼容 SDK，利用生成的凭证连接到 MinIO。

      例如，下面的 Python 代码使用 MinIO Python SDK 连接到 MinIO 部署并返回存储桶列表：

      from minio import Minio
      
      client = MinIO(
         "minio.minio-tenant.svc.cluster-domain.example",
         access_key = "ACCESS_KEY",
         secret_key = "SECRET_KEY",
         session_token = "SESSION_TOKEN"
         secure = True
      )
      
      client.list_buckets()

2. 后续步骤

应用程序应使用其选择的 SDK 实现 STS AssumeRoleWithWebIdentity 流程。 当 STS 凭证过期时，应用程序应具备在重试并继续操作之前重新生成 JWT token、 STS token 和 MinIO 凭证的逻辑。

或者，用户也可以通过 MinIO Console 使用其 Keycloak 凭证生成 access keys， 以创建类似长期 API key 的访问方式。

1. 配置或创建用于访问 Keycloak 的 Client

   认证到 Keycloak Administrative Console，然后进入 Clients。

   选择 Create client，按照提示为 MinIO 创建一个新的 Keycloak client。 按如下方式填写指定输入项：

   Client ID	设置为 MinIO 的唯一标识符（minio）
   Client type	设置为 OpenID Connect
   Always display in console	切换为 On
   Client authentication	切换为 On
   Authentication flow	打开 Standard flow
   （可选）Authentication flow	打开 Direct access grants （API 测试）

   Keycloak 会以一组默认配置值部署该 client。 请根据你的 Keycloak 环境和期望行为按需修改这些值。 下表提供了一组可用于配置的基线设置和值：

   Root URL	设置为 ${authBaseUrl}
   Home URL	设置为 MinIO 要使用的 Realm（/realms/master/account/）
   Valid Redirect URI	设置为 *
   Keys -> Use JWKS URL	切换为 On
   Advanced -> Advanced Settings -> Access Token Lifespan	设置为 1 Hour。

2. 为 MinIO Client 创建 Client Scope

   Client Scope 允许 Keycloak 在认证请求返回的 JSON Web Token（JWT）中映射用户属性。 这样 MinIO 就可以在向用户分配策略时引用这些属性。 此步骤会创建在 Keycloak 认证成功后支持 MinIO 授权所需的 Client Scope。

   进入 Client scopes 视图，为 MinIO 授权创建一个新的 client scope：

   Name	设置为任意易识别的策略名称（minio-authorization）
   Include in token scope	切换为 On

   创建完成后，从列表中选中该 scope，并进入 Mappers。

   选择 Configure a new mapper 创建新的映射：

   User Attribute	选择 Mapper Type
   Name	设置为任意易识别的映射名称（minio-policy-mapper）
   User Attribute	设置为 policy
   Token Claim Name	设置为 policy
   Add to ID token	设置为 On
   Claim JSON Type	设置为 String
   Multivalued	设置为 On 这样可以在单个 claim 中设置多个 policy 值。
   Aggregate attribute values	设置为 On 这样用户就可以继承其所属 Group 中设置的任意 policy。

   创建完成后，将该 Client Scope 分配给 MinIO client。

   1. 进入 Clients 并选择 MinIO client。
   2. 选择 Client scopes，然后选择 Add client scope。
   3. 选择先前创建的 scope，并将 Assigned type 设置为 default。

3. 将所需属性应用到 Keycloak Users/Groups

   必须为 Keycloak Users 或 Groups 分配一个名为 policy 的属性。 将其值设置为 MinIO 部署上的任意 policy。

   对于 Users，进入 Users 并选择或创建 User：

   Credentials	如果尚未设置，将用户密码设置为永久值
   Attributes	创建一个新属性，键为 policy，值为 MinIO 部署上的任意 policy （consoleAdmin）

   对于 Groups，进入 Groups 并选择或创建 Group：

   Attributes

   创建一个新属性，键为 policy，值为 MinIO 部署上的任意 policy （consoleAdmin）

   你可以将用户加入组，使其继承指定的 policy 属性。 如果 Mapper 设置中启用了 Aggregate attribute values， Keycloak 会在已认证用户的 JWT token 中包含聚合后的策略数组。 MinIO 可以在为用户授权时使用这份策略列表。

   你可以使用 Keycloak API 测试某个用户配置的策略：

   curl -d "client_id=minio" \
        -d "client_secret=secretvalue" \
        -d "grant_type=password" \
        -d "username=minio-user-1" \
        -d "password=minio-user-1-password" \
        http://keycloak-url.example.net:8080/realms/REALM/protocol/openid-connect/token

   如果成功，access_token 中会包含调用 MinIO AssumeRoleWithWebIdentity STS API 并生成 S3 凭证所需的 JWT。

   你可以使用 JWT 解码器检查其载荷，确认其中包含 policy 键， 且列出了一个或多个 MinIO policy。

4. 为 Keycloak 认证配置 MinIO

   MinIO 支持多种配置 Keycloak 认证的方法：

   • 使用终端/shell 以及 mc idp openid 命令
   • 使用在启动 MinIO 之前设置的环境变量

mc idp openid add ALIAS PRIMARY_IAM \
   client_id=MINIO_CLIENT \
   client_secret=MINIO_CLIENT_SECRET \
   config_url="https://keycloak-url.example.net:8080/realms/REALM/.well-known/openid-configuration" \
   display_name="SSO_IDENTIFIER"
   scopes="openid,email,preferred_username" \
   redirect_uri_dynamic="on"

MINIO_IDENTITY_OPENID_CONFIG_URL_PRIMARY_IAM="https://keycloak-url.example.net:8080/realms/REALM/.well-known/openid-configuration"
MINIO_IDENTITY_OPENID_CLIENT_ID_PRIMARY_IAM="MINIO_CLIENT"
MINIO_IDENTITY_OPENID_CLIENT_SECRET_PRIMARY_IAM="MINIO_CLIENT_SECRET"
MINIO_IDENTITY_OPENID_DISPLAY_NAME_PRIMARY_IAM="SSO_IDENTIFIER"
MINIO_IDENTITY_OPENID_SCOPES_PRIMARY_IAM="openid,email,preferred_username"
MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC_PRIMARY_IAM="on"