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

MinIO 部署

此过程假设现有 MinIO 集群运行 最新稳定的 MinIO 版本。 有关新 MinIO 部署的更完整文档，请参阅 安装和部署MinIO。

本操作步骤 可能 会按预期适用于较旧版本的 MinIO。

Keycloak 部署和领域配置

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

本操作步骤假设 Keycloak 和 MinIO 部署之间存在双向访问。

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

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

请查看 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-url.example.net:8080/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 命令

• 在启动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/.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"

重新启动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-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客户端的客户端ID和密钥。

   您可以使用 jq 或类似的JSON格式化实用程序处理结果。 提取 access_token 字段以检索必要的访问令牌。 请注意 expires_in 字段以记录令牌在过期之前的秒数。

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

   • Credentials.SecretAccessKey - Keycloak 用户的秘密密钥

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

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

3. 测试凭据

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

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

下一步

应用程序应使用其所选择的 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"