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

MinIO Kubernetes Operator

确保您的目标 Kubernetes 集群具有有效且可正常运行的 MinIO Kubernetes Operator 安装. 本文档假定 Operator 为最新稳定版本 7.1.1.

MinIO 租户

本操作步骤假设您的 Kubernetes 集群具有足够的资源来 部署新的 MinIO 租户。

您还可以使用此过程作为修改现有 MinIO 租户以启用 Keycloak 身份管理的指导。

Keycloak 部署和领域配置

本操作步骤假设您可以访问一个现有的 Keycloak 部署并拥有管理员权限。 具体而言，您必须拥有在 Keycloak 部署中创建和配置领域、客户端、客户端范围、领域角色、用户和组的权限。

对于与 MinIO 租户位于同一 Kubernetes 集群中的 Keycloak 部署，本操作步骤假设 Keycloak 和 MinIO 的 pod/service 之间存在双向访问。

对于 Kubernetes 集群外部的 Keycloak 部署，本操作步骤假设存在一个现有的 Ingress、负载均衡器或类似的 Kubernetes 网络控制组件，用于管理与 MinIO 租户之间的网络访问。

安装和配置 mc ，以便访问 MinIO 集群

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

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

请查看 mc 安装快速入门 获取有关下载和安装 mc 的说明。

本操作步骤假定已经配置了 MinIO 集群的 alias。

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

在Keycloak的 管理控制台 中进行身份验证，并导航到 Clients 。

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

Keycloak部署客户端时使用默认的配置值集合。 根据您的Keycloak设置和所需的行为进行必要的值修改。 下表提供了配置设置和值的标准:

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

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

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

创建后，从列表中选择该作用域并导航到 Mappers。

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

创建后，将客户端作用域分配给MinIO客户端。

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

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

3. 选择先前创建的作用域，并将 Assigned type 设置为 default 。

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

您必须给Keycloak用户或组分配一个名为 policy 的属性。 将该值设置为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 minio-sts-assumerolewithwebidentity STS API并生成S3凭据所需的JWT。

您可以使用JWT解码器来查看有效载荷并确保其中包含带有一个或多个MinIO策略的 policy 键。

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）按钮，该按钮使用配置的 Display Name

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

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

使用 S3 兼容 SDK 的应用程序必须以访问密钥和密钥的形式指定凭证。 MinIO minio-sts-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-key的访问。

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": "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"