入门

对于某些应用程序，你可以参考以下资源，快速开始使用 Keycloak 授权服务：

• 在 Wildfly 中保护 JakartaEE 应用程序（https://github.com/keycloak/keycloak-quickstarts/tree/latest/jakarta/servlet-authz-client）
• 保护 Spring Boot 应用程序（https://github.com/keycloak/keycloak-quickstarts/tree/latest/spring/rest-authz-resource-server）
• 保护 Quarkus 应用程序（https://quarkus.io/guides/security-keycloak-authorization）
• Keycloak Node.js 适配器（https://www.keycloak.org/securing-apps/nodejs-adapter）

管理资源服务器

根据 OAuth2 规范，资源服务器是托管受保护资源的服务器，能够接受并响应受保护资源的请求。

在 Keycloak 中，资源服务器为其受保护资源提供了一个丰富的平台，用于实现细粒度授权，授权决策可以基于不同的访问控制机制做出。

任何客户端应用程序都可以配置为支持细粒度权限。这样做时，从概念上讲，你正在将客户端应用程序转变为资源服务器。

创建客户端应用程序

启用 Keycloak 授权服务的第一步是创建要转变为资源服务器的客户端应用程序。

1. 点击 “Clients”（客户端）。
   

2. 在页面上点击 “Create client”（创建客户端）。
   

3. 输入客户端的 “Client ID”（客户端 ID），例如 “my-resource-server”，然后点击 “Next”（下一步）。

4. 将 “Client authentication”（客户端认证）切换为 “ON”，然后点击 “Save”（保存）。

5. 输入应用程序的 “Root URL”（根 URL），例如 “http://{host}:{port}/my-resource-server”，然后点击 “Save”（保存）。客户端创建完成后，将打开客户端设置页面。
   

启用授权服务

你可以将 OIDC 客户端转变为资源服务器并启用细粒度授权。

1. 在客户端设置页面中，向下滚动到 “Capability Config”（功能配置）部分。

2. 将 “Authorization Enabled”（启用授权）切换为 “On”，然后点击 “Save”（保存）。
   
   此时，该客户端将显示一个新的 “Authorization”（授权）选项卡。点击该选项卡，将显示一个类似以下的页面：
   

• Settings（设置）：资源服务器的常规设置。有关此页面的更多详细信息，请参见 “

• Resource（资源）：在此页面，你可以管理应用程序的资源。

在Resources中可以维护应用的受限访问资源，所谓的“细粒度"即对应到每个资源。使用过Shiro的同学应该对“保护资源”的概念不陌生，Shiro也是将应用的URL视为资源、并使用“资源标识符:操作:对象实例ID“来描述权限，在Keycloak中也可以贯彻相同的理念。所以我们可以基于URL来创建一个资源:

• Authorization Scopes（授权作用域）：在此页面，你可以管理作用域。

• Policies（策略）：在此页面，你可以管理授权策略并定义授予权限时必须满足的条件。

相较于传统的“角色-权限-资源”的RBAC模型，Keycloak多了一个策略的概念来适配不同的授权对象。权限不再直接与角色关联，而是与策略关联；而策略除了与角色关联，还可以与客户端、分组、用户等关联，从而将所有的授权需求都统一起来，即策略定义了授予对象访问权时必须满足的条件。

• Permissions（权限）：在此页面，你可以通过将受保护资源和作用域与你创建的策略链接起来，管理它们的权限。

权限将策略和资源关联起来，一般基于资源新建权限(权限和资源、策略都是多对多的关系)

• Evaluate（评估）：从在此页面，你可以模拟授权请求并查看你定义的权限和授权策略的评估结果。

• Export Settings（导出设置）：在此页面，你可以将授权设置导出到一个 JSON 文件。

资源服务器设置

在Resource Server Settings （资源服务器设置）页面，你可以配置策略执行模式、允许远程资源管理以及导出授权配置设置。

• Policy enforcement mode（策略执行模式）：

  指定在处理发送到服务器的授权请求时如何执行策略。

  • Enforcing（强制执行）：默认模式，即使与给定资源没有关联的策略，请求也会被拒绝。

  含义：“强制执行” 模式意味着，即使某个特定资源没有关联任何策略，默认情况下，对该资源的访问请求也会被拒绝。在这种模式下，系统秉持 “没有明确允许就是禁止” 的原则，只有当资源明确关联了允许访问的策略时，请求才可能被放行。
  应用场景：适用于对安全性要求极高的环境，例如金融交易系统、军事指挥系统等。在这些场景中，任何未经授权的访问都可能带来严重的后果，因此需要严格控制资源的访问权限，即使没有额外的策略约束，也不允许随意访问。

  • Permissive（允许）：即使与给定资源没有关联的策略，请求也会被允许。

  含义：“宽松” 模式表示，即便某个资源没有关联任何策略，对该资源的访问请求也会被允许。此模式遵循 “没有明确禁止就是允许” 的理念，给予了更多的访问自由度。
  应用场景：常用于开发、测试环境或者对资源访问限制要求相对较低的场景。例如，在软件开发的测试阶段，为了方便开发人员快速验证功能，对于一些临时创建的资源，可以采用宽松模式，避免频繁配置策略的繁琐过程，提高开发效率。

  • Disabled（禁用）：禁用所有策略的评估，并允许访问所有资源。

  含义：“禁用” 模式会完全禁用策略评估过程，允许对任何资源进行访问。在这种模式下，系统不会检查任何与资源相关的策略，直接放行所有访问请求。
  应用场景：通常在特殊情况下使用，比如系统进行紧急维护、故障排查时，需要快速恢复对所有资源的访问权限，以便进行全面的检查和修复。但这种模式存在较大的安全风险，使用后应及时恢复到正常的策略执行模式

• Decision strategy（决策策略）：此配置会更改策略评估引擎根据所有评估权限的结果决定是否授予对资源或作用域的访问权限的方式。

  • “Affirmative”（肯定）意味着至少有一个权限必须评估为肯定决策，才能授予对资源及其作用域的访问权限。

  • “Unanimous”（一致同意）意味着所有权限必须评估为肯定决策，最终决策才为肯定。例如，如果对同一资源或作用域的两个权限发生冲突（一个授予访问权限，另一个拒绝访问权限），

  • 如果选择的策略是 “Affirmative”，则将授予对该资源或作用域的权限。否则，任何一个权限的拒绝都将拒绝访问该资源或作用域。

  Keycloak在评估-一个权限时会评估所有关联策略，每条策略会返回正或负的结果。

  • DecisionStrategy决定了策略的评估结果如何决定权限的评估结果
  • Unanimous：一致，所有的策略都评估为正是权限评估为正，否则为负。
  • Affirmative：肯定，至少有一个策略评估为正则权限评估为正，否则为负。Affirmative是常用的策略。
  • Consensus：共识，当评估为正的策略数大于评估为负的策略数时，权限评估为正，否则为负。

• 远程资源管理：指定资源服务器是否可以远程管理资源。如果为 “false”，则只能从管理控制台管理资源。

默认配置

当你创建一个资源服务器时，Keycloak 会为新创建的资源服务器创建一个默认配置。默认配置包括：

• 一个默认受保护资源，代表应用程序中的所有资源。

• 一个始终授予对受此策略保护的资源的访问权限的策略。

• 一个基于默认策略管理对所有资源的访问权限的权限。

默认受保护资源

默认受保护资源称为默认资源，你可以导航到 “Resources”（资源）选项卡查看它。

此资源定义了一个 Type为“urn:my-resource-server:resources:default”、URI为“/*”。这里，“URI” 字段定义了一个通配符模式，向 Keycloak 表明此资源代表应用程序中的所有路径。换句话说，为应用程序启用策略执行时，在授予访问权限之前，将检查与该资源关联的所有权限。

之前提到的 “Type（类型）” 定义了一个值，可用于创建类型化资源权限，这些权限必须应用于默认资源或使用相同类型创建的任何其他资源。

默认策略

默认策略称为 “only from realm policy（仅来自领域策略）”，你可以导航到 “Policies（策略）” 选项卡查看它。

此策略是一个基于 JavaScript 的策略，定义了一个始终授予对此策略保护的资源访问权限的条件。如果点击此策略，你会看到它定义了如下规则：

// by default, grants any permission associated with this policy
// 默认情况下，授予与此策略关联的任何权限
$evaluation.grant();

默认权限

最后，默认权限称为 “default permission（默认权限）”，你可以导航到 “Permissions（权限）” 选项卡查看它。

此权限是基于资源的权限，用于定义一组一个或多个策略，这些策略将应用于具有给定类型的所有资源

更改默认配置

你可以通过删除默认资源、策略或权限定义并创建自己的定义来更改默认配置。

默认资源是使用 URI 创建的，该 URI 使用 /* 模式映射到应用程序中的任何资源或路径。在创建自己的资源、权限和策略之前，请创建 确保默认配置不会与您自己的设置冲突。

💡默认配置定义了一个映射到应用程序中所有路径的资源。如果你要为自己的资源编写权限，请务必删除Default Resource 或将其 “URIs” 字段更改为应用程序中更具体的路径。否则，与默认资源关联的策略（默认情况下始终授予访问权限）将允许 Keycloak 授予对任何受保护资源的访问权限。

导出和导入授权配置

资源服务器（或客户端）的配置设置可以导出并下载。你还可以导入现有资源服务器的配置文件。导入和导出配置文件在你为资源服务器创建初始配置或更新现有配置时很有用。配置文件包含以下定义：

• 受保护资源和范围

• 策略

• 权限

导出配置文件

1. 点击菜单中的 “Clients（客户端）”。

2. 点击你创建的作为资源服务器的客户端。

3. 点击 “Export（导出）” 选项卡。
   

配置文件将以 JSON 格式导出并显示在文本区域中，你可以从中复制和粘贴。你也可以点击 “Download（下载）” 下载配置文件并保存。

导入配置文件

1. 导航到 “Resource Server Settings（资源服务器设置）” 页面。

   

2. 点击 “Import（导入）” 并选择包含要导入配置的文件。