Keycloak客户端作用域(Client Scopes)深度解析

Keycloak客户端作用域(Client Scopes)深度解析

keycloak Keycloak 是一个开源的身份和访问管理解决方案，用于保护应用程序和服务的安全和访问。 * 身份和访问管理解决方案、保护应用程序和服务的安全和访问 * 有什么特点：支持多种认证和授权协议、易于使用、可扩展性强 项目地址: https://gitcode.com/gh_mirrors/ke/keycloak

什么是客户端作用域

在Keycloak中，客户端作用域(Client Scopes)是一种用于定义共享客户端配置的实体。它允许管理员为多个客户端统一配置协议映射器(Protocol Mappers)和角色作用域映射(Role Scope Mappings)，从而简化客户端管理并提高配置的一致性。

客户端作用域的核心功能

客户端作用域主要提供两大核心功能：

1. 协议映射器配置：定义如何将用户信息映射到令牌中的声明(claims)
2. 角色作用域映射：控制哪些角色可以包含在令牌中

此外，客户端作用域还支持OAuth 2的scope参数，客户端应用可以通过此参数请求访问令牌中包含特定的声明或角色。

协议类型与内置作用域

创建客户端作用域时，必须选择协议类型(Protocol)，且同一作用域下的客户端必须使用相同协议。Keycloak为每个领域(Realm)预定义了一组内置客户端作用域：

SAML协议作用域

• role_list：包含一个协议映射器，用于在SAML断言中添加角色列表

OpenID Connect协议作用域

• roles：将用户角色添加到访问令牌，并为至少有一个客户端角色的客户端添加受众(audience)
• web-origins：将允许的web来源添加到访问令牌的allowed-origins声明
• microprofile-jwt：处理MicroProfile/JWT Auth规范定义的声明
• offline_access：用于客户端需要获取离线令牌的场景
• profile/email/address/phone：这些作用域遵循OpenID Connect规范定义的标准声明

客户端作用域与客户端的关联方式

客户端作用域可以通过两种方式与客户端关联：

1. 默认客户端作用域(Default Client Scopes)

• 适用于OpenID Connect和SAML客户端
• 在颁发令牌时自动应用，无需在scope参数中显式请求
• 客户端会继承作用域中定义的所有协议映射器和角色作用域映射

2. 可选客户端作用域(Optional Client Scopes)

• 仅适用于OpenID Connect客户端
• 只有在scope参数中显式请求时才会应用

专用客户端作用域(Dedicated Client Scope)

每个客户端都有一个专用的客户端作用域，它代表直接链接到客户端本身的协议映射器和角色作用域映射。这个专用作用域：

• 不能从客户端取消链接
• 不能链接到其他客户端
• 适用于特定于单个客户端的配置

客户端作用域评估机制

当向用户颁发令牌时，客户端作用域仅在用户被允许使用时才会应用：

1. 如果客户端作用域没有定义任何角色作用域映射，则所有用户都可以使用它
2. 如果定义了角色作用域映射，用户必须是至少一个角色的成员才能使用该作用域

如果用户不被允许使用客户端作用域，则在生成令牌时不会使用任何协议映射器或角色作用域映射，且该作用域不会出现在令牌的scope值中。

作用域相关设置

同意屏幕设置(Consent related settings)

• 在同意屏幕上显示：控制是否在同意屏幕上显示该作用域
• 同意屏幕文本：自定义在同意屏幕上显示的文本

包含在令牌作用域中(Include in token scope)

控制该作用域的名称是否包含在访问令牌的scope属性中，以及令牌响应和令牌自省端点响应中。

作用域术语澄清

在Keycloak和OAuth/OIDC规范中，"scope"一词有多种含义：

1. 客户端作用域：Keycloak中的配置实体
2. 角色作用域映射：限制可用于访问令牌的角色
3. 授权作用域：定义应用程序中可以执行的操作

最佳实践建议

1. 对于需要在多个客户端间共享的配置，创建共享的客户端作用域
2. 对于特定于单个客户端的配置，使用专用客户端作用域
3. 合理使用默认和可选客户端作用域，优化用户体验
4. 定期审查角色作用域映射，确保最小权限原则

通过合理使用客户端作用域，管理员可以显著简化Keycloak的配置管理，提高系统的安全性和可维护性。

keycloak Keycloak 是一个开源的身份和访问管理解决方案，用于保护应用程序和服务的安全和访问。 * 身份和访问管理解决方案、保护应用程序和服务的安全和访问 * 有什么特点：支持多种认证和授权协议、易于使用、可扩展性强 项目地址: https://gitcode.com/gh_mirrors/ke/keycloak