Keycloak中授权的实现

Keycloak提供了完善的授权功能，即在Keycloak端对资源服务器的各种资源进行管理，然后就可以完成对它们的管控，这些资源可以根据Keycloak的用户、角色、组等信息进行授权。

在Keycloak中实现授权，首先需要了解与授权相关的一些概念。授权，简单地说就是某个（些）用户或者某个（些）用户组（Policy），是否具有对某个资源（Resource）具有某种操作（Scope）的权限（Permission）。所以，授权是一种权限管理，它建立在认证的基础上：用户首先要完成认证（Authentication），才能谈授权（Authorization）。在讨论认证与授权的文章或论坛里，往往用Authn代表认证（Authentication），而用Authz代表授权（Authorization）。

Keycloak中的授权模型

在上面这段描述中，我已经将几个重要的概念用黑体字标注了。或许会有这样的疑问：用户/用户组不应该是User/Group吗？在谈授权的时候，至少也应该是角色（Role）吧，比如我们熟悉的基于角色的访问控制（RBAC），里面就是角色，怎么会是策略（Policy）呢？在回答这个问题前，还是先看一下Keycloak中的授权模型：

这个模型中，包含了几个重要的概念：

1. 资源（Resource）：资源是应用程序中能够被访问的对象。假设有个有关天气预报的API，它的URL是http://localhost:5678/WeatherForecast，那么，在这台资源服务器上，URI /WeatherForecast就是一个资源的地址，它表示一个跟天气预报相关的API端点资源

2. 操作（Scope）：其实Scope并不翻译为“操作”，这里我使用“操作”来表示Scope，是因为在授权的场景中，Scope就是定义针对资源的一些“操作”。比如：对于上面的天气预报API资源，我们可以有获取资源的操作，也可以有更新资源的操作（比如，让气象员根据其它科学数据来调整某地的天气预报）。于是，在定义Scope的时候，可以用“weather.read”、“weather.update”这样的名字来命名

3. 对于某个资源，它可以声明自己所需要的操作，例如，在RESTful API中，/WeatherForecast这个API可以有读取（read/HTTP GET）的操作，也可以有更新（update/HTTP PATCH）的操作，那么，就可以在这个API资源上声明weather.read和weather.update这两个Scope

4. 一个用户组（Group）可以包含多个子组，一个组下可以有多个用户（User），一个用户又可以属于多个用户组。对于一个用户或者一个组而言，它可以扮演多种角色（Role），而一个角色又可以被赋予多个用户或者多个用户组，这些都是耳熟能详的RBAC授权的基本概念，就不多说明了

5. 策略（Policy）可以理解为满足某种条件的资源访问者（可以是用户或用户组），所以，Policy定义的是条件：角色就是一种条件，表示“被赋予某种角色”的条件。基于角色的策略实现的访问控制，就是RBAC。当然条件不仅仅只有角色，用户满足某个条件也可以成为一种策略，比如要求某个用户年龄大于18岁。除此之外，策略是可以被聚合的，聚合策略的投票结果（允许还是拒绝），取决于被聚合的策略以及投票的方式（是所有被聚合策略都允许，结果才被允许，还是只要有一个投票为“允许”，整个聚合策略的结果就是“允许”），比如要求用户是年龄大于18岁（User Policy）的系统管理员（Role Policy）。上图中只简单列了几个继承于Policy的子类用以示意，Keycloak所支持的策略类型不止这些

6. 权限（Permission）是资源（Resource）或者操作（Scope）与策略（Policy）之间的关联关系。在Keycloak中，权限分为两种：基于资源的权限和基于操作的权限。表达的语义是：符合某些策略的访问者对指定的资源或者操作可以访问

理解了这些概念后，在Keycloak中实现授权并不困难。

演练：在Keycloak中实现授权

还是以Weather API为例，设置这样的业务场景：

1. 服务供应商（Service Provider）发布/WeatherForecast API供外部访问

2. 在企业应用（Client）里有三个用户：super，daxnet，nobody

3. 在企业应用里有两个用户组：administrators，users

4. 在企业应用里定义了两个用户角色：administrator，regular user

5. super用户同时属于users和administrators组，daxnet属于users组，nobody不属于任何组

6. administrators组被赋予了administrator角色，users组被赋予了regular user角色

7. 对于/WeatherForecast API，它支持两种操作：GET /WeatherForecast，用以返回天气预报数据；PATCH /WeatherForecast，用以调整天气预报数据

8. 拥有administrator角色的用户/组，具有PATCH操作的权限；拥有regular user角色但没有administrator角色的用户/组，具有GET操作的权限；没有任何角色的用户，就没有访问/WeatherForecast API的权限

这个业务场景也可以用下面的图来表述：

首先，在Keycloak中新建一个名为aspnetcoreauthz的Realm，在这个Realm下，新建三个User，分别是super，daxnet和nobody；然后新建两个Group：administrators和users，将super用户放到administrators组和users组里，并将daxnet用户放入users组里。

然后，新建一个名为weatherapiclient的Client，在weatherapiclient的页面里，点击Roles选项卡，创建两个名为administrator和regular user的角色，然后回到Groups里，选中administrators组，在Role mapping中，将administrator角色赋予该组：

用同样的方法，将regular user角色赋予users组。

现在进入Authorization选项卡，点击Scopes选项卡，然后点击Create authorization scope按钮：

在Create authorization scope页面中，Name字段输入weather.read，用同样的方法，新建另一个Scope，名称为weather.update。然后点击Resources选项卡，并点击Create resource按钮，创建API resource：

在Create resource页面，新建名为weather-api的资源，填入如下字段，然后点击Save按钮保存：

回到Authorization标签页，点击Policies标签页，点击Create client policy按钮，在弹出的对话框中，选择Role，表示需要创建一个基于角色的策略。在Create role policy页面，新建一个名为require-admin-policy的策略，在Roles部分，点击Add roles按钮，选择weatherapiclient下的administrator角色，然后点击Save按钮保存：

用同样的方法创建require-registered-user策略，并将regular user作为角色加入。接下来开始创建权限实体（Permission）。在Authorization选项卡里，点击Permission选项卡，然后点击Create permission，然后选择Create scope-based permission。在Create scope-based permission页面，创建一个名为weather-view-permission的Permission，Authorization scopes选择weather.read，Policies选择require-registered-user，这里的语义已经很明白了：执行weather.read操作，需要require-registered-user策略，也就是要读取天气预报信息，就需要已注册用户。点击Save按钮保存即可。

用同样的方法创建另一个名为weather-modify-permission的Permission，Authorization scopes为weather.update，Policies为require-admin-policy。

接下来，就可以测试权限的设置是否正确了。仍然在Authorization选项卡下，点击Evaluate选项卡，在Identity Information部分，Users里选择super：

然后点击Evaluate按钮，之后就可以看到，weather-modify-permission和weeather-view-permission均投票为Permit，表示该用户具有两者权限：

如果点击Show authorization data，则在弹出的Authorization data对话框中，可以看到token里已经包含了授权信息（authorization Claim）：

{
"exp": 1712996185,
"iat": 1712995885,
"jti": "4f1178f2-5e8b-41e4-b726-da9120d77baa",
"aud": "weatherapiclient",
"sub": "44bbfc3a-16a0-499a-aae9-a2aa36219d33",
"typ": "Bearer",
"azp": "weatherapiclient",
"session_state": "2b228dd4-38c8-4002-bc11-b35ecd109a63",
"acr": "1",
"allowed-origins": [
"/*"
],
"realm_access": {
"roles": [
"default-roles-aspnetcoreauthz",
"offline_access",
"uma_authorization"
]
},
"resource_access": {
"weatherapiclient": {
"roles": [
"administrator",
"regular user"
]
},
"account": {
"roles": [
"manage-account",
"manage-account-links",
"view-profile"
]
}
},
"authorization": {
"permissions": [
{
"scopes": [
"weather.update",
"weather.read"
],
"rsid": "f6fd1d6f-3bfd-44a1-a6fb-a1fb49769ac9",
"rsname": "weather-api"
}
]
},
"scope": "email profile",
"sid": "2b228dd4-38c8-4002-bc11-b35ecd109a63",
"email_verified": false,
"name": "Admin User",
"groups": [
"/administrators",
"/users"
],
"preferred_username": "super",
"given_name": "Admin",
"family_name": "User",
"email": "super@abc.com"
}

换一个用户，如果选择daxnet，可以看到，weather-view-permission为Permit，而weather-modify-permission为Deny：

再将用户换为nobody测试一下，发现两个Permission的结果都为Deny：

通过token API端点请求授权信息

要使用OpenID Connect的token API端点获得某个用户的授权信息，需要首先得到Bearer token：

然后，使用这个Bearer token，再次调用token API，注意此时的grant_type为 urn:ietf:params:oauth:grant-type:uma-ticket，audience为Client ID，即weatherapiclient：

在jwt.io中解码第二步生成的这个access_token，就可以拿到授权信息了：