使用 Keycloak 配置 MinIO 身份验证

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

   验证 Keycloak管理控制台并导航到客户端.

   选择创建客户端并按照说明为 MinIO 创建一个新的 Keycloak 客户端。 按如下所示填写指定的输入：

   Client ID	设置为 MinIO 的唯一标识符（minio)
   客户端类型	设置为OpenID Connect
   始终在控制台中显示	切换至On
   客户端认证	切换至On
   认证流程	开启Standard flow
   （可选）认证流程	开启Direct access grants(API测试)

   Keycloak 使用一组默认配置值部署客户端。 请根据您的 Keycloak 设置和期望行为按需修改这些值。 下表提供了需要配置的设置和值的基准参考：

   根URL	设置为${authBaseUrl}
   首页 URL	设置为 MinIO 要使用的 Realm（/realms/master/account/)
   有效重定向 URI	设置为*
   Keys -> 使用 JWKS URL	切换至On
   Advanced -> Advanced Settings -> Access Token Lifespan	设置为1 Hour.

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

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

   Navigate to the客户端作用域查看并为 MinIO 授权创建新的客户端范围：

   名称	设置为策略的任何可识别名称（minio-authorization)
   包含在令牌范围内	切换至On

   创建后，从列表中选择范围并导航至Mappers.

   选择配置一个新的映射器创建新映射：

   用户属性	选择 Mapper 类型
   名称	设置为映射的任何可识别名称（minio-policy-mapper)
   用户属性	设置为policy
   Token Claim Name	设置为policy
   添加到 ID 令牌	设置为On
   Claim JSON 类型	设置为String
   多值	设置为On 这允许设置多个policy单个声明中的值。
   聚合属性值	设置为On 这允许用户继承任何policy设置在其群组中

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

   1. Navigate to客户端并选择 MinIO 客户端。

   2. 选择客户端作用域，然后选择添加客户端范围.

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

3. 对 Keycloak 用户/组应用必要属性

   你必须分配一个名为policy到 Keycloak 用户或群组。 将值设置为任意政策在 MinIO 部署上。

   对于用户，请导航至用户并选择或创建用户：

   凭据	如果尚未设置，请将用户密码设置为永久值
   属性	创建一个具有键的新属性policy以及任何价值政策 (consoleAdmin)

   对于群组，请导航至群组并选择或创建组：

   属性	创建一个具有键的新属性policy以及任何价值政策 (consoleAdmin)

   您可以将用户分配到组中，这样他们就能继承指定的policy属性。 如果您将 Mapper 设置设为启用聚合属性值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 所需的 JWTAssumeRoleWithWebIdentitySTS API 和生成 S3 凭据。

   您可以使用JWT解码器来查看有效载荷并确保它包含policy列出一个或多个 MinIO 策略的密钥。

4. 配置 MinIO 以使用 Keycloak 身份验证

您可以使用mc idp openid add创建 Keycloak 服务新配置的命令。 该命令接受所有支持的OpenID 配置设置:

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. 使用安全令牌服务（STS）生成应用程序凭据

   使用S3兼容SDK的应用程序必须以访问密钥和秘密密钥的形式指定凭据。 MinIOAssumeRoleWithWebIdentityAPI返回必要的临时凭证，包括必需的会话令牌，这些凭证使用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使用 Keycloak 用户的凭据REALM.

      • 替换CLIENT和SECRET使用 MinIO 特定 Keycloak 客户端的客户端 ID 和密钥REALM

      您可以使用以下方式处理结果：jq或类似的 JSON 格式化工具。 提取access_tokenfield to retrieve the necessary access token. 注意expires_in记录令牌过期前秒数的字段。

   2. 使用以下命令生成 MinIO 凭据AssumeRoleWithWebIdentityAPI

      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随着access_tokenKeycloak 返回的值。

      API 成功时返回包含以下键的 XML 文档：

      • Credentials.AccessKeyId- Keycloak 用户的访问密钥

      • Credentials.SecretAccessKey- Keycloak 用户的密钥

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

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

   3. 测试凭据

      使用您偏好的 S3 兼容 SDK，通过生成的凭据连接到 MinIO。

      例如，以下使用 MinIO 的 Python 代码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. 下一步

应用程序应实现STS AssumeRoleWithWebIdentity使用他们的流程SDKof choice. 当STS凭证过期时，应用程序应内置相应逻辑，在重试和继续操作前重新生成JWT令牌、STS令牌和MinIO凭证。

或者，用户也可以生成访问密钥通过 MinIO 控制台，使用其 Keycloak 凭据创建类似长期有效的 API 密钥的访问权限。

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

   验证 Keycloak管理控制台并导航到客户端.

   选择创建客户端并按照说明为 MinIO 创建一个新的 Keycloak 客户端。 按如下所示填写指定的输入：

   Client ID	设置为 MinIO 的唯一标识符（minio)
   客户端类型	设置为OpenID Connect
   始终在控制台中显示	切换至On
   客户端认证	切换至On
   认证流程	开启Standard flow
   （可选）认证流程	开启Direct access grants(API测试)

   Keycloak 使用一组默认配置值部署客户端。 请根据您的 Keycloak 设置和期望行为按需修改这些值。 下表提供了需要配置的设置和值的基准参考：

   根URL	设置为${authBaseUrl}
   首页 URL	设置为 MinIO 要使用的 Realm（/realms/master/account/)
   有效重定向 URI	设置为*
   Keys -> 使用 JWKS URL	切换至On
   Advanced -> Advanced Settings -> Access Token Lifespan	设置为1 Hour.

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

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

   Navigate to the客户端作用域查看并为 MinIO 授权创建新的客户端范围：

   名称	设置为策略的任何可识别名称（minio-authorization)
   包含在令牌范围内	切换至On

   创建后，从列表中选择范围并导航至Mappers.

   选择配置一个新的映射器创建新映射：

   用户属性	选择 Mapper 类型
   名称	设置为映射的任何可识别名称（minio-policy-mapper)
   用户属性	设置为policy
   Token Claim Name	设置为policy
   添加到 ID 令牌	设置为On
   Claim JSON 类型	设置为String
   多值	设置为On 这允许设置多个policy单个声明中的值。
   聚合属性值	设置为On 这允许用户继承任何policy设置在其群组中

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

   1. Navigate to客户端并选择 MinIO 客户端。

   2. 选择客户端作用域，然后选择添加客户端范围.

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

3. 对 Keycloak 用户/组应用必要属性

   你必须分配一个名为policy到 Keycloak 用户或群组。 将值设置为任意政策在 MinIO 部署上。

   对于用户，请导航至用户并选择或创建用户：

   凭据	如果尚未设置，请将用户密码设置为永久值
   属性	创建一个具有键的新属性policy以及任何价值政策 (consoleAdmin)

   对于群组，请导航至群组并选择或创建组：

   属性	创建一个具有键的新属性policy以及任何价值政策 (consoleAdmin)

   您可以将用户分配到组中，这样他们就能继承指定的policy属性。 如果您将 Mapper 设置设为启用聚合属性值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 所需的 JWTAssumeRoleWithWebIdentitySTS API 和生成 S3 凭据。

   您可以使用JWT解码器来查看有效载荷并确保它包含policy列出一个或多个 MinIO 策略的密钥。

4. 配置 MinIO 以使用 Keycloak 身份验证

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

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

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

   CLI

   您可以使用mc idp openid add创建 Keycloak 服务新配置的命令。 该命令接受所有支持的OpenID 配置设置:

   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 客户端 ID 和密钥
   config_url	设置为 Keycloak OpenID 配置文档的地址 (keycloak-url.example.net:8080)
   display_name	设置为 MinIO 控制台在配置的 Keycloak 服务的单点登录 (SSO) 工作流程中显示的用户可见名称
   scopes	设置为要在 JWT 中包含的 OpenID 作用域列表，例如preferred_username or email
   redirect_uri_dynamic	设置为on 将客户端使用的 MinIO 控制台地址替换为 Keycloak 重定向 URI 的一部分。 Keycloak 使用提供的 URI 将经过身份验证的用户返回到控制台。 对于部署在反向代理、负载均衡器或类似网络控制平面后面的 MinIO 控制台，您可以改用MINIO_BROWSER_REDIRECT_URL用于设置 Keycloak 使用的重定向地址的变量。

   环境变量

   设置以下内容环境变量在使用容器之前，-e ENVVAR=VALUEflag.

   以下示例代码设置了配置 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 域
   CLIENT_ID CLIENT_SECRET	指定在步骤1中配置的 Keycloak 客户端 ID 和密钥
   DISPLAY_NAME	指定 MinIO 控制台在单点登录 (SSO) 工作流程中为已配置的 Keycloak 服务显示的用户可见名称
   OPENID_SCOPES	指定您希望在 JWT 中包含的 OpenID 作用域，例如preferred_username or email
   REDIRECT_URI_DYNAMIC	设置为on 将客户端使用的 MinIO 控制台地址替换为 Keycloak 重定向 URI 的一部分。 Keycloak 使用提供的 URI 将经过身份验证的用户返回到控制台。 对于部署在反向代理、负载均衡器或类似网络控制平面后面的 MinIO 控制台，您可以改用MINIO_BROWSER_REDIRECT_URL用于设置 Keycloak 使用的重定向地址的变量。

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

   重启 MinIO 部署以使更改生效。

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

   如果您尝试通过控制台登录，现在应该能看到一个使用已配置的（SSO）按钮显示名称.

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

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

   使用S3兼容SDK的应用程序必须以访问密钥和秘密密钥的形式指定凭据。 MinIOAssumeRoleWithWebIdentityAPI返回必要的临时凭证，包括必需的会话令牌，这些凭证使用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使用 Keycloak 用户的凭据REALM.

      • 替换CLIENT和SECRET使用 MinIO 特定 Keycloak 客户端的客户端 ID 和密钥REALM

      您可以使用以下方式处理结果：jq或类似的 JSON 格式化工具。 提取access_tokenfield to retrieve the necessary access token. 注意expires_in记录令牌过期前秒数的字段。

   2. 使用以下命令生成 MinIO 凭据AssumeRoleWithWebIdentityAPI

      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随着access_tokenKeycloak 返回的值。

      API 成功时返回包含以下键的 XML 文档：

      • Credentials.AccessKeyId- Keycloak 用户的访问密钥

      • Credentials.SecretAccessKey- Keycloak 用户的密钥

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

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

   3. 测试凭据

      使用您偏好的 S3 兼容 SDK，通过生成的凭据连接到 MinIO。

      例如，以下使用 MinIO 的 Python 代码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. 下一步

   应用程序应实现STS AssumeRoleWithWebIdentity使用他们的流程SDKof choice. 当STS凭证过期时，应用程序应内置相应逻辑，在重试和继续操作前重新生成JWT令牌、STS令牌和MinIO凭证。

   或者，用户也可以生成访问密钥通过 MinIO 控制台，使用其 Keycloak 凭据创建类似长期有效的 API 密钥的访问权限。