配置 MinIO 使用 Keycloak 进行认证

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
   （可选）:guilabel: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
   （可选）:guilabel: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 之前设置的环境变量

   CLI

   你可以使用 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-url.example.net:8080/realms/REALM/.well-known/openid-configuration" \
      display_name="SSO_IDENTIFIER"
      scopes="openid,email,preferred_username" \
      redirect_uri_dynamic="on"
   

   PRIMARY_IAM	设置为该 Keycloak 服务的唯一标识符，例如 keycloak_primary
   MINIO_CLIENT MINIO_CLIENT_SECRET	设置为步骤 1 中配置的 Keycloak client ID 和 secret
   config_url	设置为 Keycloak OpenID 配置文档的地址（keycloak-url.example.net:8080）
   display_name	设置为 MinIO Console 在单点登录（SSO）流程中向用户显示的该 Keycloak 服务名称
   scopes	设置为你希望包含在 JWT 中的 OpenID scope 列表，例如 preferred_username 或 email
   redirect_uri_dynamic	设置为 on 这会将客户端所使用的 MinIO Console 地址替换到 Keycloak 重定向 URI 中。 Keycloak 会使用提供的 URI 将已认证用户返回到 Console。 对于位于反向代理、负载均衡器或类似网络控制平面之后的 MinIO Console 部署， 你也可以使用 MINIO_BROWSER_REDIRECT_URL 变量设置 Keycloak 应使用的重定向地址。

   环境变量

   在使用 -e ENVVAR=VALUE 标志启动容器之前， 设置以下 环境变量。

   下面的示例代码设置了将 Keycloak 配置为外部身份管理提供者所需的最小环境变量集合。

   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"
   

   _PRIMARY_IAM	将后缀 _PRIMARY_IAM 替换为该 Keycloak 配置的唯一标识符。 例如，MINIO_IDENTITY_OPENID_CONFIG_URL_KEYCLOAK_PRIMARY。 如果你只打算为该部署配置单个 OIDC 提供者，也可以省略该后缀。
   CONFIG_URL	指定 Keycloak OpenID 配置文档的地址（keycloak-url.example.net:8080） 确保其中的 REALM 与你希望用于 MinIO 用户认证的 Keycloak realm 一致
   CLIENT_ID CLIENT_SECRET	指定步骤 1 中配置的 Keycloak client ID 和 secret
   DISPLAY_NAME	指定 MinIO Console 在单点登录（SSO）流程中向用户显示的该 Keycloak 服务名称
   OPENID_SCOPES	指定你希望包含在 JWT 中的 OpenID scope，例如 preferred_username 或 email
   REDIRECT_URI_DYNAMIC	设置为 on 这会将客户端所使用的 MinIO Console 地址替换到 Keycloak 重定向 URI 中。 Keycloak 会使用提供的 URI 将已认证用户返回到 Console。 对于位于反向代理、负载均衡器或类似网络控制平面之后的 MinIO Console 部署， 你也可以使用 MINIO_BROWSER_REDIRECT_URL 变量设置 Keycloak 应使用的重定向地址。

   有关这些变量的完整文档，请参见 OpenID 身份管理设置

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

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

   如果尝试通过 Console 登录，现在应能看到一个使用已配置 Display Name 的（SSO）按钮。

   指定一个已配置的用户并尝试登录。 MinIO 应自动将您重定向到 Keycloak 登录页面。 认证成功后，Keycloak 应使用原始 Console URL 或已配置的 Redirect URI 将您重定向回 MinIO Console。

5. 使用 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-url.example.net:8080/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-url.example.net:9000" \
           -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-url.example.net:9000",
         access_key = "ACCESS_KEY",
         secret_key = "SECRET_KEY",
         session_token = "SESSION_TOKEN"
         secure = True
      )
      
      client.list_buckets()
      

6. 后续步骤

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

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