keycloak-授权服务-授权策略执行器

总览

策略执行点（Policy Enforcemnt Point / PEP）是一种设计模式，可以通过不同的方式实现这种设计。Keycloak为在不同的平台、环境以及编程语言下实现PEP提供了所有必须的方法。Keyclope授权服务提供了一个RESTful API，并利用OAuth2授权功能，使用集中授权服务器进行细粒度授权。

PEP通过keycloak服务，基于与受保护的资源相关联的策略做出访问决策。它在应用程序中充当过滤器或拦截器，以检查是否可以根据这些决定授予的权限满足对受保护资源的特定请求。
权限判断方法和服务使用的协议有关。如果使用UMA，则策略执行器需要通过bearer token获取RPT，并通过RPT决策资源是否可以被访问。所以客户端需要先从keycloak获取RPT，再发送给资源服务器。
但是，如果没有使用UMA，用户也可以使用常规的access token给资源服务器。这种情况下，策略执行器会尝试直接向keycloak请求权限。
如果你使用keycloak OIDC适配器，你可以轻易通过向如下字段添加策略执行器：
keycloak.json

{
   
	"policy-enforcer": {
   }
}

当启用策略执行器时，发送给应用程序的所有请求都会被策略执行器拦截。策略执行器根据Keycloak授予的权限决策是否授予对受保护资源的访问。
策略执行器和应用路径以及使用Keycloak管理控制台创建的资源紧密关联。当你在keycloak创建资源服务器时，keycloak会创建默认配置，所以可以很快的使用策略执行器。

配置

要为应用启用策略执行器，需要在中keycloak.json中添加如下属性：
keycloak.json:

{
   
	"policy-enforcer": {
   }
}

如果希望手动添加被保护资源，则可以配置更多的细节：

{
   
  "policy-enforcer": {
   
    "user-managed-access" : {
   },
    "enforcement-mode" : "ENFORCING",
    "paths": [
      {
   
        "path" : "/someUri/*",
        "methods" : [
          {
   
            "method": "GET",
            "scopes" : ["urn:app.com:scopes:view"]
          },
          {
   
            "method": "POST",
            "scopes" : ["urn:app.com:scopes:create"]
          }
        ]
      },
      {
   
        "name" : "Some Resource",
        "path" : "/usingPattern/{id}",
        "methods" : [
          {
   
            "method": "DELETE",
            "scopes" : ["urn:app.com:scopes:delete"]
          }
        ]
      },
      {
   
        "path" : "/exactMatch"
      },
      {
   
        "name" : "Admin Resources",
        "path" : "/usingWildCards/*"
      }
    ]
  }
}

配置项解释如下

• policy-enforcer
  配置项，这些配置项指明策略的逻辑以及需要有此策略保护的路径。如果没有配置，则策略执行器将通过服务查询所有和受保护资源服务器相关联的资源。所以，你需要确保正确地配置了资源地URIs参数，这些参数可以匹配真正需要被保护的资源。
  • user-managed-access
    配置适配器是否使用UMA协议。如果配置此选项，则适配器会向服务查询权限票据，并根据UMA规范返回票据给客户端。如果没有配置，则策略执行器会基于常规的access token或RPT鉴权。这种话情况下，如果token中缺少权限，策略执行器会尝试直接向服务器获取权限。
  • enforcement-mode
    指明策略执行模式
    • ENFORCING
      默认模式，即使请求的资源没有关联的鉴权策略，也会被拒绝
    • PERMISSIVE
      即使没有鉴权策略与请求的资源关联，也会授权访问
    • DSIABLED
      禁用鉴权策略，允许对任何资源的访问。应用依然可以通过及安全上下文向keycloak请求所有权限
  • on-deny-redirecr-to
    定义当查询到access denied信息时，客户端应该被重定向的URL。默认情况下适配器返回403响应状态码
  • path-cache
    定义策略执行器应如何跟踪应用程序中的路径与Keycloak中定义的资源之间的关联。通过缓存路径和受保护资源之间的关联，需要缓存来避免对keycloak服务的不必要请求。
    • lifespan
      定义实体过期时间，以毫秒为单位。默认值是30000。设置为0时表明禁用缓存。设置为-1时禁用缓存过期时间。
    • max-entires
      定义缓存的最高实体数量，默认值是1000
  • paths
    指定被保护的路径。如果没有配置，那么策略执行器会通过Keycloak中注册的定义了URIS的应用找出所有所有的路径。
    • name
      和路径关联的资源名称。当和path联合使用时，策略执行器会忽略资源的URIS属性
    • path
      必须，和应用上下文路径关联的URI。如果定义了这个选项，策略执行器会向服务查询URI相同和这个选项值相同的资源。目前支持如下路径匹配逻辑：
      • 通配符：/*
      • 后缀：/*.html
      • 子路径：/path/*
      • 路径参数：/resource/{id}
      • 精确匹配：/resource
      • 按模式匹配：/{version}/resource，/api/{version}/resource，/api/{version}/resource/*
    • methods
      受保护的http请求方法以及与之相关的资源操作
      • method
        http方法名称
      • scopes
        字符数组，表示和method相关的一组操作。当把操作和http方法关联的时候，客户端访问受保护资源时必须提供包含全部操作权限的RPT。比如，定义了POST方法和create关联，那么使用POST方法访问路径时必须携带含有create操作权限的RPT。
      • scope-enforcement-mode
        字符串，代表与操作相关的策略执行模式，可以是ALL或ANY。如果设置为ALL，那么使用设置的方法访问指定的路径时必须获得全部权限。如果设置为ANY，则需要至少满足一个权限。
    • enforcement-mode
      定义策略如何执行。
      • ENFORCING
        默认模式。如果请求访问的资源没有关联的策略，则拒绝访问。
      • DISABLED
    • claim-information-point
      定义一组claim，这些claim必须被解析并发送给keycloak服务，这样策略才可以收到相关claim。
  • lazy-load-paths
    指定适配器应如何从服务器获取与应用程序中的路径相关联的资源。这个配置项设置为true时，策略执行器会根据请求的路径向服务获取资源。当您不想在部署过程中从服务器获取所有资源（如果您没有提供路径）或只定义了一个子集的路径并希望按需获取其他资源时，此配置特别有用
  • http-method-as-scope
    指明请求的操作如何和http方法关联。如果设置为true，策略执行器会使用HTTP方法检查当前请求是否可以被授权。使用这个特性的时候，要确保在key