使用 Keycloak 配置 MinIO 进行身份验证

MinIO Kubernetes 运算符

确保您的目标 Kubernetes 集群具有 MinIO Kubernetes 运算符的有效且正常工作的安装。此文档假定最新的稳定运算符，版本 6.0.4。

MinIO 租户

此过程假定您的 Kubernetes 集群具有足够的资源来 部署新的 MinIO 租户.

您也可以使用此步骤作为修改现有 MinIO 租户以启用 Keycloak 身份管理的指南。

Keycloak 部署和 Realm 配置

此步骤假设您已有一个 Keycloak 部署，并且您拥有其管理员访问权限。具体来说，您必须有权在 Keycloak 部署中创建和配置 Realm、客户端、客户端范围、Realm 角色、用户和组。

对于与 MinIO 租户位于同一个 Kubernetes 集群中的 Keycloak 部署，此步骤假设 Keycloak 和 MinIO Pod/服务之间可以双向访问。

对于位于 Kubernetes 集群外部的 Keycloak 部署，此步骤假设您已有一个 Ingress、负载均衡器或类似的 Kubernetes 网络控制组件来管理 MinIO 租户的网络访问。

安装并配置 mc 以访问 MinIO 集群

此步骤使用 mc 对 MinIO 集群执行操作。在具有网络访问权限的机器上安装 mc。

您的本地主机必须能够访问 MinIO 租户，例如通过 Ingress、负载均衡器或类似的 Kubernetes 网络控制组件。

请参阅 mc Installation Quickstart 了解有关下载和安装 mc 的说明。

此步骤假设已配置 MinIO 集群的 alias。

1) 配置或创建用于访问 Keycloak 的客户端

验证 Keycloak Administrative Console 并导航到 Clients。

选择 Create client 并按照说明为 MinIO 创建新的 Keycloak 客户端。按照以下说明填写指定的输入

Keycloak 使用默认的一组配置值部署客户端。根据您的 Keycloak 设置和所需行为修改这些值。下表提供了一组基线设置和值来进行配置

2) 为 MinIO 客户端创建客户端范围

客户端范围允许 Keycloak 将用户属性映射为身份验证请求中返回的 JSON Web Token (JWT) 的一部分。这使得 MinIO 可以在将策略分配给用户时引用这些属性。此步骤创建支持 MinIO 授权的必要客户端范围，该授权将在 Keycloak 身份验证成功后进行。

导航到 Client scopes 视图并为 MinIO 授权创建一个新的客户端范围

创建后，从列表中选择该范围并导航到 Mappers。

选择 Configure a new mapper 以创建一个新的映射

创建后，将客户端范围分配给 MinIO 客户端。

1. 导航到 Clients 并选择 MinIO 客户端。

2. 选择 Client scopes，然后选择 Add client scope。

3. 选择之前创建的范围并将 Assigned type 设置为 default。

3) 将必要的属性应用于 Keycloak 用户/组

您必须将名为 policy 的属性分配给 Keycloak 用户或组。将值设置为 MinIO 部署上的任何 policy。

对于用户，导航到 Users 并选择或创建用户

对于组，导航到 Groups 并选择或创建组

您可以将用户分配到组，以便他们继承指定的 policy 属性。如果您将 Mapper 设置设置为启用 Aggregate attribute values，Keycloak 将汇总的策略数组包含在已验证用户的 JWT 令牌中。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 策略的值。

4) 为 Keycloak 身份验证配置 MinIO

MinIO 支持多种方法来配置 Keycloak 身份验证

• 使用 MinIO 租户控制台

• 使用终端/shell 和 mc idp openid 命令

kubectl describe svc/TENANT_NAME-console -n TENANT_NAMESPACE

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 配置相关的错误。

如果您尝试使用控制台登录，现在应该会看到一个使用配置的 显示名称 的 (SSO) 按钮。

指定一个配置的用户并尝试登录。MinIO 应该会自动将您重定向到 Keycloak 登录条目。成功身份验证后，Keycloak 应该会将您重定向回 MinIO 控制台，使用的是原始控制台 URL 或 如果配置了，则使用 重定向 URI。

5) 使用安全令牌服务 (STS) 生成应用程序凭据

使用 S3 兼容 SDK 的应用程序必须以访问密钥和密钥形式指定凭据。MinIO AssumeRoleWithWebIdentity API 使用 Keycloak 在身份验证后返回的 JWT 返回必要的临时凭据，包括所需的会话令牌。

您可以使用以下 HTTP 调用序列和 curl 实用程序来测试此工作流

1. 以 Keycloak 用户身份进行身份验证并检索 JWT 令牌

   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 客户端的客户端 ID 和密钥

   您可以使用 jq 或类似的 JSON 格式化实用程序处理结果。提取 access_token 字段以检索必要的访问令牌。注意 expires_in 字段，以记下令牌过期前的时间（以秒为单位）。

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 用户的访问密钥

   • Credentials.SecretAccessKey - Keycloak 用户的密钥

   • Credentials.SessionToken - Keycloak 用户的会话令牌

   • Credentials.Expiration - 生成的凭据的过期日期

3. 测试凭据

   使用您喜欢的 S3 兼容 SDK，使用生成的凭据连接到 MinIO。

   例如，以下使用 MinIO Python SDK 的 Python 代码连接到 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()
   

下一步

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

或者，用户可以使用 MinIO 控制台生成 访问密钥，以便使用其 Keycloak 凭据创建长期 API 密钥类型的访问。

1) 创建必要的客户端作用域

导航到 客户端作用域 视图并创建一个新作用域

导航到 客户端 并选择 MinIO 客户端

1. 从 服务帐户角色 中，选择 分配角色 并分配 admin 角色

2. 从 客户端作用域 中，选择 添加客户端作用域 并添加之前创建的作用域

导航到 设置 并确保 身份验证流程 包括 服务 帐户 角色。

2) 验证管理 API 访问

您可以使用 MinIO 客户端凭据通过管理 REST API 验证功能，以检索承载令牌和用户数据

1. 检索承载令牌

   curl -d "client_id=minio" \
        -d "client_secret=secretvalue" \
        -d "grant_type=password" \
        http://keycloak-url:port/admin/realms/REALM/protocol/openid-connect/token
   

2. 使用返回的值作为 access_token 访问管理 API

   curl -H "Authentication: Bearer ACCESS_TOKEN_VALUE" \
        http://keycloak-url:port/admin/realms/REALM/users/UUID
   

   将 UUID 替换为您要检索的用户唯一 ID。响应应类似于以下内容

   {
      "id": "954de141-781b-4eaf-81bf-bf3751cdc5f2",
      "createdTimestamp": 1675866684976,
      "username": "minio-user-1",
      "enabled": true,
      "totp": false,
      "emailVerified": false,
      "firstName": "",
      "lastName": "",
      "attributes": {
         "policy": [
            "readWrite"
         ]
      },
      "disableableCredentialTypes": [],
      "requiredActions": [],
      "notBefore": 0,
      "access": {
         "manageGroupMembership": true,
         "view": true,
         "mapRoles": true,
         "impersonate": true,
         "manage": true
      }
   }
   

   如果返回值具有 enabled: false 或 null（用户已从 Keycloak 中删除），MinIO 将撤销经过身份验证的用户的访问权限。

3) 在 MinIO 上启用 Keycloak 管理支持

MinIO 支持多种方法来配置 Keycloak 管理 API 支持

• 使用终端/shell 和 mc idp openid 命令

• 在启动 MinIO 之前使用环境变量设置

mc idp openid update ALIAS KEYCLOAK_IDENTIFIER \
   vendor="keycloak" \
   keycloak_admin_url="https://keycloak-url:port/admin"
   keycloak_realm="REALM"

MINIO_IDENTITY_OPENID_VENDOR_PRIMARY_IAM="keycloak"
MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL_PRIMARY_IAM="https://keycloak-url:port/admin"
MINIO_IDENTITY_OPENID_KEYCLOAK_REALM_PRIMARY_IAM="REALM"