keycloak 認證服務

阿新 • • 發佈：2018-12-21

1. 概述

Keycloak支援細粒度的授權策略，並且能夠組合不同的訪問控制機制，例如:

Attribute-based access control (ABAC): 基於屬性的安全控制
Role-based access control (RBAC): 基於角色的安全控制
User-based access control (UBAC): 基於使用者的安全控制
Context-based access control (CBAC): 基於上下文的安全控制
Rule-based access control: 基於規則的安全控制
- 使用Javascript
- 使用 JBoss Drools
Time-based access control: 基於時間的安全控制
通過策略提供程式服務提供程式介面（SPI）支援自定義訪問控制機制（ACMs）

Keycloak基於一組管理UI和RESTful API，為受保護資源和作用域建立許可權，將這些許可權與授權策略相關聯以及在應用程式和服務中強制執行授權決策的必要方法。

資源伺服器（為受保護資源提供服務的應用程式或服務）通常依賴某種資訊來決定是否應該向受保護資源授予訪問許可權。
對於基於RESTful的資源伺服器，該資訊通常從安全令牌獲取，通常在每次請求傳送到伺服器時作為承載令牌傳送。
對於依賴會話對使用者進行身份驗證的Web應用程式，該資訊通常儲存在使用者的會話中，並從那裡為每個請求檢索。

通常，資源伺服器僅基於基於角色的訪問控制（RBAC）執行授權決策，其中，針對對映到這些相同資源的角色檢查授予嘗試訪問受保護資源的使用者的角色。
雖然角色非常有用並且被應用程式使用，但它們也有一些限制：

資源和角色緊密耦合，角色更改（例如新增，刪除或更改訪問上下文）可能會影響多個資源
對安全性要求的更改可能意味著對應用程式程式碼進行深度更改以反映這些更改
根據您的應用程式大小，角色管理可能變得困難且容易出錯
不是最靈活的訪問控制機制。角色不能代表你是誰，缺乏上下文資訊。如果您已被授予角色，則您至少擁有一些訪問許可權。

考慮到今天我們需要考慮使用者分佈在不同地區，不同本地策略，使用不同裝置以及對資訊共享的高需求的異構環境，Keycloak授權服務可以幫助您提高應用程式和服務的授權功能通過提供：

使用細粒度授權策略和不同訪問控制機制的資源保護
資源,許可權的策略的集中管理
集中的策略決策點
基於REST的授權服務的REST安全性
授權工作流程和使用者管理的訪問許可權
有助於避免跨專案（並重新部署）程式碼複製並快速適應安全要求變化的基礎架構

1.1 架構

從設計角度來看，授權服務基於一組明確定義的授權模式，提供以下功能：

策略管理點(Policy Administration Point/PAP)

提供基於Keycloak管理控制檯的一組UI，以管理資源伺服器，資源，範圍，許可權和策略。部分內容也可以通過使用Protection API遠端完成。
策略決策點(PDP)

提供可分發的策略決策點，指向傳送授權請求的位置，並根據請求的許可權相應地評估策略。有關更多資訊，請參閱獲取許可權。
策略執行點（PEP）

提供不同環境的實現，以在資源伺服器端實際執行授權決策。 Keycloak提供了一些內建的Policy Enforcer。
策略資訊點（PIP）

基於Keycloak Authentication Server，可以從身份和執行時環境中獲取屬性。

1.1.1 認證流程

主要步驟為三個流程，以瞭解如何使用Keycloak為您的應用程式啟用細粒度授權：

資源管理
許可權和策略管理
策略執行

資源管理

![image](https://www.keycloak.org/docs/latest/authorization_services/images/resource-mgmt-process.png)

首先，您需要指定Keycloak您希望保護的內容，通常代表Web應用程式或一組一個或多個服務。有關資源伺服器的更多資訊，請參閱術語。

使用Keycloak管理控制檯管理資源伺服器。在那裡，您可以啟用任何已註冊的客戶端應用程式作為資源伺服器，並開始管理您要保護的資源和範圍。

資源可以是網頁，RESTFul資源，檔案系統中的檔案，EJB等。它們可以表示一組資源（就像Java中的類一樣），也可以表示單個特定資源。

例如，您可能擁有代表所有銀行賬戶的銀行賬戶資源，並使用它來定義所有銀行賬戶共有的授權策略。但是，您可能希望為Alice帳戶（屬於客戶的資源例項）定義特定策略，其中只允許所有者訪問某些資訊或執行操作。

可以使用Keycloak管理控制檯或Protection API管理資源。在後一種情況下，資源伺服器能夠遠端管理其資源。

範圍通常表示可以對資源執行的操作，但它們不限於此。您還可以使用範圍來表示資源中的一個或多個屬性。

許可權策略管理

定義資源伺服器和要保護的所有資源後，必須設定許可權和策略。

此過程涉及實際定義管理資源的安全性和訪問要求的所有必要步驟。

策略定義了訪問或執行某些操作（資源或範圍）必須滿足的條件，但它們與它們保護的內容無關。
它們是通用的，可以重用來構建許可權甚至更復雜的策略。

例如，要僅允許授予角色“User Premium”的使用者訪問一組資源，您可以使用RBAC（基於角色的訪問控制）。

Keycloak提供了一些內建策略型別（及其各自的策略提供者），涵蓋了最常見的訪問控制機制。您甚至可以根據使用JavaScript或JBoss Drools編寫的規則建立策略。

定義策略後，即可開始定義許可權。
許可權與他們保護的資源相結合。
在此處指定要保護的內容（資源或範圍）以及授予或拒絕許可權必須滿足的策略。

策略執行

策略實施涉及實際執行資源伺服器的授權決策的必要步驟。這是通過在資源伺服器上啟用策略強制點或PEP來實現的，該策略強制點或PEP能夠與授權伺服器通訊，請求授權資料並根據伺服器返回的決策和許可權控制對受保護資源的訪問。

Keycloak提供了一些內建的Policy Enforcer實現，您可以使用它們來保護您的應用程式，具體取決於它們執行的平臺。

1.1.2 認證服務

授權服務由以下RESTFul端點組成：

令牌端點
資源管理端點
許可權管理端點

這些服務中的每一個都提供了一個特定的API，涵蓋了授權過程中涉及的不同步驟。

令牌端點

OAuth2客戶端（例如前端應用程式）可以使用令牌端點從伺服器獲取訪問令牌，並使用這些相同的令牌來訪問受資源伺服器保護的資源（例如後端服務）。

同樣，Keycloak授權服務提供對OAuth2的擴充套件，以允許基於與所請求的資源或範圍相關聯的所有策略的處理來發布訪問令牌。

這意味著資源伺服器可以根據伺服器授予的許可權強制訪問其受保護資源，並由訪問令牌持有。
在Keycloak授權服務中，具有許可權的訪問令牌稱為請求方令牌或簡稱RPT。

更多資訊，請參閱獲取許可權。

Protection API

Protection API是一組符合UMA的端點，為資源伺服器提供操作，以幫助他們管理與之關聯的資源，範圍，許可權和策略。

只允許資源伺服器訪問此API，這也需要uma_protection範圍。

Protection API提供的操作可以分為兩大類：

資源管理
- 建立資源
- 刪除資源
- 根據ID查詢
- 查詢
許可權管理
- 簽發許可證

預設情況下，啟用遠端資源管理。您可以使用Keycloak管理控制檯更改它，並且只允許通過控制檯進行資源管理。

使用UMA協議時，Protection API釋出許可權票證是整個授權過程的重要部分。如後續部分所述，它們表示客戶端請求的許可權，並且傳送到伺服器以獲取最終令牌，該最終令牌具有在評估與請求的資源和範圍相關聯的許可權和策略期間授予的所有許可權。

更多資訊，請參閱Protection API。

1.2 術語

1.2.1 資源伺服器(Resource Server)

資源伺服器是託管受保護資源並能夠接受和響應受保護資源請求的伺服器

資源伺服器通常依賴某種資訊來決定是否應該授予對受保護資源的訪問許可權。
對於基於RESTful的資源伺服器，該資訊通常在安全令牌中攜帶，通常作為承載令牌以及每個請求傳送到伺服器。

依賴會話對使用者進行身份驗證的Web應用程式通常將該資訊儲存在使用者的會話中，並從那裡為每個請求檢索它。

1.2.2 資源(Resource)

資源伺服器通常依賴某種資訊來決定是否應該授予對受保護資源的訪問許可權。
對於基於RESTful的資源伺服器，該資訊通常在安全令牌中攜帶，通常作為承載令牌以及每個請求傳送到伺服器。
依賴會話對使用者進行身份驗證的Web應用程式通常將該資訊儲存在使用者的會話中，並從那裡為每個請求檢索它。

每個資源都有一個唯一識別符號，可以表示單個資源或一組資源。
例如，您可以管理銀行賬戶資源，該資源代表並定義所有銀行賬戶的一組授權政策。
但您也可以使用名為Alice的銀行賬戶的不同資源，該賬戶代表單個客戶擁有的單一資源，該客戶可以擁有自己的一組授權策略。

1.2.3 範圍(Scope)

資源的範圍是可以在資源上執行的有限訪問範圍。

在授權策略術語中，範圍是可以邏輯地應用於資源的潛在許多動詞之一。它通常表示可以使用給定資源執行的操作。

範圍的示例包括檢視，編輯，刪除等。但是，範圍也可以與資源提供的特定資訊相關。在這種情況下，您可以擁有專案資源和成本範圍，其中成本範圍用於定義使用者訪問專案成本的特定策略和許可權。

1.2.4 許可權(Permission)

許可權將受保護的物件與必須評估的策略相關聯，以確定是否授予訪問許可權。

X CAN DO Y ON RESOURCE Z

X: 表示一個或多個使用者，角色或組，或它們的組合
Y: 表示要執行的操作，例如，寫入，檢視等
Z: 表示受保護資源，例如“/ accounts”。

Keycloak提供了一個豐富的平臺，用於構建一系列許可權策略，範圍從簡單到非常複雜，基於規則的動態許可權。它提供了靈活性，有助於：

減少程式碼重構和許可權管理成本
支援更靈活的安全模型，幫助您輕鬆適應安全要求的變化
在執行時進行更改;應用程式只關心受保護的資源和範圍，而不關心它們的保護方式。

1.2.5 策略(Policy)

策略定義了授予物件訪問許可權必須滿足的條件。與許可權不同，您不指定要保護的物件，而是指定訪問給定物件必須滿足的條件（例如，資源，範圍或兩者）。策略與可用於保護資源的不同訪問控制機制（ACM）密切相關。使用策略，您可以實施基於屬性的訪問控制（ABAC），基於角色的訪問控制（RBAC），基於上下文的訪問控制或這些的任意組合的策略。

Keycloak利用策略的概念以及如何通過提供聚合策略的概念來定義它們，您可以在其中構建“policy of policies”並仍然控制評估的行為。Keycloak授權服務中的策略實現遵循分而治之的技術，而不是編寫一個具有訪問給定資源必須滿足的所有條件的大型策略。也就是說，您可以建立單獨的策略，然後使用不同的許可權重用它們，並通過組合各個策略來構建更復雜的策略。

1.2.6 策略提供者(Policy Provider)

策略提供者是特定策略型別的實現。Keycloak提供內建策略，由相應的策略提供商提供支援，您可以建立自己的策略型別以支援您的特定需求。

Keycloak提供了一個SPI（服務提供程式介面），您可以使用它來插入自己的策略提供程式實現。

1.2.7 許可權票據(Permission Ticket)

許可權票證是由 使用者管理訪問(UMA) 規範定義的特殊型別的令牌，其提供不透明結構，其形式由授權伺服器確定。此結構表示客戶端請求的資源和/或範圍，訪問上下文，以及必須應用於授權資料請求的策略（請求方令牌[RPT]）。

在UMA中，許可票證對於支援人與人之間的共享以及人與組織之間的共享至關重要。使用授權工作流的許可權票證可以實現從簡單到複雜的一系列方案，其中資源所有者和資源伺服器可以根據管理對這些資源的訪問的細粒度策略完全控制其資源。

更多資訊, 查閱UMA章節使用者管理控制(User-Managed-Access)

2 入門指南

首先需要安裝keycloak

啟動Keycloak Server

Linux/Unix

$ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100

Windows

> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100

2.1 保護Servlet應用程式

入門指南的目的是讓您儘快啟動並執行，以便您可以試驗並測試Keycloak提供的各種授權功能。
此快速瀏覽很大程度上依賴於預設的資料庫和伺服器配置，並不包括複雜的部署選項。
有關功能或配置選項的詳細資訊，請參閱本文件中的相應部分。

指南介紹了有關Keycloak授權服務的主要概念：

為客戶端應用程式啟用細粒度授權
將客戶端應用程式配置為具有受保護資源的資源伺服器
定義許可權和授權策略以管理對受保護資源的訪問
在應用中啟用許可權策略

2.2 建立 Realm 和使用者

主要為以下步驟:

建立一個名為hello-world-authz的領域。建立後，將顯示類似於以下內容的頁面： Realm hello-world-authz
在新建立的領域中建立使用者。
單擊 Users。
在使用者列表的右側，單擊Add user。
建立新使用者，請填寫“使用者名稱”，“電子郵件”，“名字”和“姓氏”欄位。單擊“User Enabled”開關，單擊“On”，然後單擊“Save”。
單擊“憑據”選項卡為使用者設定密碼。
使用密碼填寫“新密碼”和“密碼確認”欄位，關閉“Temporary”選項。
單擊“重置密碼”以設定使用者密碼

2.3 啟用授權服務

您可以在配置為使用OpenID Connect協議的現有客戶端應用程式中啟用授權服務。您還可以建立新客戶端。

建立客戶端

單擊“Clients”以開始建立新的客戶端應用程式，並填寫“Client ID”，“Client Protocol”和“Root URL”欄位。
單擊儲存, 客戶端詳情頁面
開啟授權: Authorization Enabled 並儲存,會展示一個新的 Authorization 選項卡
單擊“授權”選項卡，將顯示類似於以下內容的“授權設定”頁面

為客戶端應用程式啟用授權服務時，Keycloak會自動為客戶端授權配置建立多個預設設定。

更多資訊,檢視啟用授權服務章節

2.4 構建,部署,測試你的應用

前一章節已正確配置app-authz-vanilla資源伺服器（或客戶端）並啟用了授權服務，則可以將其部署到伺服器。

Keycloak Quickstarts Repository中提供了您要部署的應用程式的專案和程式碼。
您需要在計算機上安裝以下內容並在PATH中使用，然後才能繼續：

Java JDK 8
Apache Maven 3.1.1+
Git

克隆專案

$ git clone https://github.com/keycloak/keycloak-quickstarts

本節構建和部署的專案位於:

$ cd keycloak-quickstarts/app-authz-jee-vanilla

2.4.1 獲取介面卡配置

在構建和部署應用程式之前，必須首先獲取介面卡配置。

要從Keycloak管理控制檯獲取介面卡配置，請完成以下步驟:

單擊“客戶端”。在客戶端列表中，單擊app-authz-vanilla客戶端應用程式。
單擊“Installation”選項卡。從Format Option下拉列表中，選擇Keycloak OIDC JSON。介面卡配置以JSON格式顯示。單擊Download。
複製檔案 keycloak.json 到 app-authz-jee-vanilla/config 目錄
(可選)預設情況下，當用戶缺少訪問資源伺服器上受保護資源的許可權時，策略實施器將使用403狀態程式碼進行響應。但是，您也可以為未授權使用者指定重定向URL。要指定重定向URL，請編輯在步驟3中更新的keycloak.json檔案，並使用以下內容替換策略實施器配置：預設情況下，當用戶缺少訪問資源伺服器上受保護資源的許可權時，策略實施器將使用403狀態程式碼進行響應。但是，您也可以為未授權使用者指定重定向URL。要指定重定向URL，請編輯在步驟3中更新的keycloak.json檔案，並使用以下內容替換策略實施器配置：

"policy-enforcer": {
    "on-deny-redirect-to" : "/app-authz-vanilla/error.jsp"
}

如果使用者沒有訪問受保護資源的必要許可權，而不是無用的403 Unauthorized訊息，則此更改指定策略實施者將使用者重定向到/app-authz-vanilla/error.jsp頁面。

2.4.2 構建部署應用

$ cd redhat-sso-quickstarts/app-authz-jee-vanilla
$ mvn clean package wildfly:deploy

2.4.3 測試應用

登入頁面:

使用之前建立的 alice 使用者登入

主頁面:

為客戶端應用程式啟用授權服務時，Keycloak定義的預設設定提供了一個簡單的策略，該策略將為資源提供授權訪問許可權

您可以從更改預設許可權和策略開始，測試應用程式的響應方式，甚至使用Keycloak提供的不同策略型別建立新策略

你現在可以做很多事情來測試這個應用程式。
例如，您可以通過單擊客戶端的“Authorization”選項卡，然後單擊“Policies”選項卡，然後單擊列表中的“Default Policy”來更改預設策略，以允許您更改它，如下所示：

// The default value is $evaluation.grant(),
// let's see what happens when we change it to $evaluation.deny()
$evaluation.deny();

現在登出掉重新登入, 將無法訪問應用

恢復預設的策略這個問題，不更改預設策略程式碼，而是使用策略程式碼文字區域下方的下拉列表將Logic更改為Negative。

這會重新啟用對應用程式的訪問，因為我們正在否定該策略的結果，該策略預設拒絕所有訪問請求。
同樣，在測試此更改之前，請務必登出並再次登入。

2.4.4 下一步

您還可以執行其他操作，例如：

建立範圍，為其定義策略和許可權，並在應用程式端對其進行測試。使用者可以執行操作（或您建立的範圍表示的任何其他內容）嗎？
建立不同型別的策略（如基於規則），並將這些策略與預設許可權相關聯。
將多個策略應用於“預設許可權”並測試該行為。例如，組合多個策略並相應地更改決策策略。
有關如何檢視和測試應用程式內部許可權的詳細資訊，請參閱獲取授權上下文

2.5 授權 Quickstarts

除了在上一節中用作示例應用程式的app-authz-jee-vanilla快速入門之外，Keycloak Quickstarts Repository還包含其他使用本文件中描述的授權服務的應用程式。

每個quickstarts都有一個README檔案，其中包含有關如何構建，部署和測試示例應用程式的說明。下表提供了可用授權快速入門的簡要說明：

Name	Description
app-authz-jee-servlet	演示如何為Java EE應用程式啟用細粒度授權，以便根據從Keycloak Server獲取的許可權保護特定資源並構建動態選單。
app-authz-jee-vanilla	演示如何為Java EE應用程式啟用細粒度授權，並使用預設授權設定來保護應用程式中的所有資源。
app-authz-rest-springboot	演示如何使用Keycloak授權服務保護SpringBoot REST服務。
app-authz-springboot	演示如何編寫SpringBoot Web應用程式，其中身份驗證和授權方面由Keycloak管理。
app-authz-uma-photoz	一個基於HTML5 + AngularJS + JAX-RS的簡單應用程式，演示如何啟用對應用程式的使用者管理訪問，並允許使用者管理其資源的許可權。

3. 管理資源伺服器

根據OAuth2規範，資源伺服器是託管受保護資源並能夠接受和響應受保護資源請求的伺服器。

在Keycloak中，資源伺服器具有豐富的平臺，用於對其受保護資源進行細粒度授權，其中可以基於不同的訪問控制機制做出授權決策。

可以將任何客戶端應用程式配置為支援細粒度許可權。
這樣做，您在概念上將客戶端應用程式轉換為資源伺服器。

3.1 建立 Client Application

啟用Keycloak授權服務的第一步是建立要轉換為資源伺服器的客戶端應用程式。

Click Clients.
Click Create
輸入 Client ID, 例如: my-resource-server
輸入 Root URL

http://${host}:${port}/my-resource-server

Click Save

3.2 啟用授權服務

要將OIDC客戶端應用程式轉換為資源伺服器並啟用細粒度授權，請啟用 Authorization Enabled 選項。

將為此客戶端顯示新的“Authorization”選項卡。單擊“Authorization”選項卡，將顯示類似於以下內容的頁面：

“Authorization”選項卡包含其他子選項卡，其中包含實際保護應用程式資源必須遵循的不同步驟。
每個選項卡都由本文件中的特定主題單獨介紹。
但這裡有一個關於每一個的快速描述：

Settings

資源伺服器的常規設定。有關此頁面的更多詳細資訊，請參閱資源伺服器設定部分。
Resource

在此頁面中，您可以管理應用程式的資源。
Authorization Scopes
在此頁面中，您可以管理範圍。
Policies
在此頁面中，您可以管理授權策略並定義授予許可權時必須滿足的條件。
Permissions
在此頁面中，您可以通過將受保護資源和範圍與您建立的策略相連結來管理受保護資源和範圍的許可權。
Evaluate

在此頁面中，您可以模擬授權請求並檢視已定義的許可權和授權策略的評估結果。
Export: 匯出配置

3.2.1 資源伺服器設定

在“資源伺服器設定”頁面上，您可以配置策略強制模式，允許遠端資源管理以及匯出授權配置設定。

Policy Enforcement Mode

指定在處理髮送到伺服器的授權請求時如何強制實施策略
- Enforcing
  
  (預設),預設情況下，即使沒有與給定資源關聯的策略，也會拒絕請求
- Permissive
  
  即使沒有與給定資源關聯的策略，也允許請求。
- Disabled
  
  禁用所有策略的評估，並允許訪問所有資源。

3.3 預設配置

建立資源伺服器時，Keycloak會為新建立的資源伺服器建立預設配置.

預設配置包括:

一個預設受保護的資源匹配系統中所有的資源
始終授予對此策略保護的資源的訪問許可權的策略。
根據預設策略管理對所有資源的訪問的許可權。

預設受保護資源稱為預設資源，如果導航到“Resource”選項卡，則可以檢視它。

此資源定義了一個Type，即urn:my-resource-server:resources:default和URI / *。這裡，URI欄位定義了一個萬用字元模式，該模式向Keycloak指示此資源表示應用程式中的所有路徑。換句話說，在為應用程式啟用策略實施時，將在授予訪問許可權之前檢查與資源關聯的所有許可權。

前面提到的型別定義了一個值，該值可用於建立必須應用於預設資源或使用相同型別建立的任何其他資源的型別化資源許可權。

預設策略被稱為唯一來自領域策略，如果導航到“Policy”選項卡，則可以檢視它。

此策略是基於JavaScript的策略，用於定義始終授予對此策略保護的資源的訪問許可權的條件。如果單擊此策略，您可以看到它定義了一條規則，如下所示：

// by default, grants any permission associated with this policy
$evaluation.grant();

最後，預設許可權稱為預設許可權，如果導航到“Permission”選項卡，則可以檢視它。

此許可權是基於資源的許可權，用於定義一組應用於具有給定型別的所有資源的一個或多個策略。

3.3.1 更改預設配置

您可以通過刪除預設資源，策略或許可權定義並建立自己的配置來更改預設配置。

使用URI建立預設資源，該URI使用/ *模式對映到應用程式中的任何資源或路徑。
在建立自己的資源，許可權和策略之前，請確保預設配置不會與您自己的設定衝突。

預設配置定義對映到應用程式中所有路徑的資源。如果您要為自己的資源寫入許可權，請確保刪除預設資源或將其URIS欄位更改為應用程式中更具體的路徑。否則，與預設資源關聯的策略（預設情況下始終授予訪問許可權）將允許Keycloak授予對任何受保護資源的訪問許可權。

3.4 匯出和匯入授權配置

可以匯出和下載資源伺服器（或客戶端）的配置設定。
您還可以匯入資源伺服器的現有配置檔案。
當您要為資源伺服器建立初始配置或更新現有配置時，匯入和匯出配置檔案很有用。
配置檔案包含以下定義：

受保護的資源合範圍
策略(Policies)
許可權(Permissions)

3.4.1 匯出配置檔案

導航到 Resource Server Settings 頁面
點選 Export Settings 選項卡
點選 Export 匯出

配置檔案以JSON格式匯出並顯示在文字區域中，您可以從中複製和貼上。
您也可以單擊“下載”下載配置檔案並儲存。

4. 管理資源和範圍

資源管理比較簡單
建立資源伺服器後，您可以開始建立要保護的資源和範圍。
可以通過分別導航到Resource和Scope選項卡來管理資源和範圍。

4.1 檢視資源

在“資源”頁面上，您可以看到與資源伺服器關聯的資源列表。

資源列表提供有關受保護資源的資訊:

Type: 型別
URIS: URIS
Owner: 資源擁有者
Associated scopes, if any: 相關範圍, 如果有
Associated permissions: 相關許可權

在此列表中，您還可以通過單擊要為其建立許可權的資源的“Create Permission”來直接建立許可權。

在為資源建立許可權之前，請確保已經定義了要與許可權關聯的策略。

4.2 建立資源

建立資源非常簡單和通用。
您主要關心的是您建立的資源的粒度。
換句話說，可以建立資源來表示一組一個或多個資源，並且定義它們的方式對於管理許可權至關重要。

在Keycloak中，資源定義了一組對不同型別資源通用的資訊，例如：

Name

資源名稱
Type

唯一標識一個或多個資源集的型別的字串。

該型別是用於對不同資源例項進行分組的字串。
例如，自動建立的預設資源的預設型別是urn:resource-server-name:resources:default
Scopes

與資源關聯的一個或多個範圍。

4.2.1 資源屬性

資源可能具有與之關聯的屬性。這些屬性可用於提供有關資源的其他資訊，並在評估與資源關聯的許可權時為策略提供其他資訊。

每個屬性都是鍵和值對，其中值可以是一個或多個字串的集合。
通過用逗號分隔每個值，可以為屬性定義多個值。

4.2.2 Typed Resources

資源的型別欄位可用於將不同的資源組合在一起，因此可以使用一組通用許可權來保護它們。

4.2.3 資源所有者

資源也有所有者。預設情況下，資源由資源伺服器擁有。

但是，資源也可以與使用者關聯，因此您可以基於資源所有者建立許可權。
例如，僅允許資源所有者刪除或更新給定資源。

4.2.4 遠端管理資源

資源管理也通過Protection API公開，以允許資源伺服器遠端管理其資源。

使用Protection API時，可以實施資源伺服器來管理其使用者擁有的資源。在這種情況下，您可以指定使用者識別符號以將資源配置為屬於特定使用者。

Keycloak為資源伺服器提供對其資源的完全控制。
將來，我們應該能夠允許使用者控制自己的資源以及批准授權請求和管理許可權，尤其是在使用UMA協議時。

5. 管理策略

如上所述，策略定義在授予物件訪問許可權之前必須滿足的條件。

通過在編輯資源伺服器時單擊“Policy”選項卡，可以檢視與資源伺服器關聯的所有策略。

在此選項卡上，您可以檢視以前建立的策略列表以及建立和編輯策略。
要建立新策略，請在策略列表的右上角，從“建立策略”下拉列表中選擇策略型別。有關每種策略型別的詳細資訊，請參閱本節。

5.1 基於使用者的訪問策略(User-Based Policy)

可以使用此類策略來定義允許一組一個或多個使用者訪問物件許可權。

要建立新的基於使用者的策略，請在策略列表右上角的下拉列表中選擇User。

Add a User-Based Policy

5.1.1 配置

Name

策略名稱。最佳做法是使用與您的業務和安全要求密切相關的名稱，以便您可以更輕鬆地識別它們。
Description

此策略的描述資訊
Users

指定此策略授予哪些使用者訪問許可權。
Logic

在評估其他條件後應用此政策的邏輯。

5.2 基於角色的訪問策略(Role-Based Policy)

您可以使用此類策略為允許一組一個或多個角色訪問物件的許可權定義條件。

預設情況下，沒有指定新增到此策略的角色，如果該使用者的任何一個角色被授予該許可權,則策略將授予訪問許可權。

如果要強制執行特定角色，則可以根據需要指定特定角色。您還可以組合必需和非必需的角色，無論它們是領域角色還是客戶角色。

當您需要更多受限制的基於角色的訪問控制（RBAC）時，角色策略非常有用，其中必須強制執行特定角色以授予對物件的訪問許可權。
例如，您可以強制使用者必須同意允許客戶端應用程式（代表使用者）訪問使用者的資源。
您可以使用Keycloak客戶端作用域對映來啟用同意頁面，甚至強制客戶端在從Keycloak伺服器獲取訪問令牌時顯式提供作用域。

要建立新的基於角色的策略，請在策略列表右上角的下拉列表中選擇“Role”。

Add Role-Based Policy

5.2.1 配置

Name

策略名稱
Description

描述資訊
Realm Roles

指定此策略允許的領域角色。
Client Roles

指定此策略允許的客戶端角色。要啟用此欄位，必須先選擇一個客戶端。
Logic
在評估其他條件後應用策略的邏輯。

5.2.2 定義必須的角色

建立基於角色的策略時，可以將特定角色指定為必需。執行此操作時，僅當請求訪問許可權的使用者已被授予所有必需角色時，策略才會授予訪問許可權。可以像這樣配置域和客戶端角色。

定義必須的角色,需要勾選"Required"複選框

當您的策略定義多個角色但只有其中一部分是必需的時，必須的角色非常有用。
在這種情況下，您可以組合領域和客戶端角色，以便為您的應用程式啟用更細粒度的基於角色的訪問控制（RBAC）模型。
例如，您可以擁有特定於客戶端的策略，並且需要與該客戶端關聯的特定客戶端角色。
或者，您可以強制僅在存在特定領域角色的情況下授予訪問許可權。
您還可以在同一策略中組合這兩種方法。

5.3 JavaScript-Based Policy

您可以使用此類策略來使用JavaScript定義許可權的條件。
它是Keycloak支援的基於規則的策略型別之一，並提供基於Evaluation API編寫任何策略的靈活性。

要建立基於JavaScript的策略，請在策略列表右上角的下拉列表中選擇JavaScript。

Add Javascript Policy

5.3.1 配置

Name

策略名稱
Description

描述資訊
Code

提供此策略條件的JavaScript程式碼。
Logic
在評估其他條件後應用策略的邏輯。

5.3.2 示例

從Evaluation上下文檢查屬性

以下是基於JavaScript的策略的簡單示例，該策略使用基於屬性的訪問控制（ABAC）來定義基於從執行上下文獲取的屬性的條件：

var context = $evaluation.getContext();
var contextAttributes = context.getAttributes();

if (contextAttributes.containsValue('kc.client.network.ip_address', '127.0.0.1')) {
    $evaluation.grant();
}

從當前 Identity 檢查屬性

以下是基於JavaScript的策略的簡單示例，該策略使用基於屬性的訪問控制（ABAC）來定義基於與當前標識關聯的屬性的條件：

var context = $evaluation.getContext();
var identity = context.getIdentity();
var attributes = identity.getAttributes();
var email = attributes.getValue('email').asString(0);

if (email.endsWith('@keycloak.org')) {
    $evaluation.grant();
}

這些屬性是根據授權請求中使用的令牌中定義的任何宣告進行對映的

檢查當前身份所授予的角色

您還可以在策略中使用基於角色的訪問控制（RBAC）。在下面的示例中，我們檢查使用者是否被授予keycloak_user領域角色：

var context = $evaluation.getContext();
var identity = context.getIdentity();

if (identity.hasRealmRole('keycloak_user')) {
    $evaluation.grant();
}

或者，您可以檢查使用者是否被授予my-client-role客戶端角色，其中my-client是客戶端應用程式的客戶端ID：

var context = $evaluation.getContext();
var identity = context.getIdentity();

if (identity.hasClientRole('my-client', 'my-client-role')) {
    $evaluation.grant();
}

檢查使用者授予的角色

要檢查授予使用者的領域角色：

var realm = $evaluation.getRealm();

if (realm.isUserInRealmRole('marta', 'role-a')) {
    $evaluation.grant();
}

或者檢查客戶端角色是否授予使用者

var realm = $evaluation.getRealm();

if (realm.isUserInClientRole('marta', 'my-client', 'some-client-role')) {
    $evaluation.grant();
}

檢查領域角色是否授權給組

var realm = $evaluation.getRealm();

if (realm.isGroupInRole('/Group A/Group D', 'role-a')) {
    $evaluation.grant();
}

將任意宣告推送到資源伺服器要將任意宣告推送到資源伺服器，以便提供有關如何強制執行許可權的其他資訊：

var permission = $evaluation.getPermission();

// decide if permission should be granted

if (granted) {
    permission.addClaim('claim-a', 'claim-a');
    permission.addClaim('claim-a', 'claim-a1');
    permission.addClaim('claim-b', 'claim-b');
}

檢查組成員身份

var realm = $evaluation.getRealm();

if (realm.isUserInGroup('marta', '/Group A/Group B')) {
    $evaluation.grant();
}

混合不同的訪問控制機制

您還可以使用多種訪問控制機制的組合。以下示例顯示瞭如何在同一策略中使用角色（RBAC）和宣告/屬性（ABAC）檢查。在這種情況下，我們檢查使用者是否被授予管理員角色或是否有來自keycloak.org域的電子郵件：

var context = $evaluation.getContext();
var identity = context.getIdentity();
var attributes = identity.getAttributes();
var email = attributes.getValue('email').asString(0);

if (identity.hasRealmRole('admin') || email.endsWith('@keycloak.org')) {
    $evaluation.grant();
}

編寫自己的規則時，請記住$ evaluation物件是實現org.keycloak.authorization.policy.evaluation.Evaluation的物件。有關可從此介面訪問的內容的更多資訊，請參閱Evaluation API。

5.4 基於規則的訪問策略

使用此類策略，您可以使用Drools（規則評估環境）定義許可權的條件。它是Keycloak支援的基於規則的策略型別之一，並提供基於Evaluation API編寫任何策略的靈活性。

要建立新的基於規則的策略，請在策略列表右上角的下拉列表中選擇“Rule”

Add Rule Policy

5.4.1 配置

Name

規則名稱
Description

規則描述
Policy Maven Artifact

Maven groupId-artifactId-version（GAV）指向定義規則的工件。提供GAV後，可以單擊“Resolve”以載入“Module”和“Session”欄位。
- Group Id
  
  The groupId of the artifact.
- Artifact Id
  
  The artifactId of the artifact.
- Version
  The version of the artifact.
Module

策略使用的模組。您必須提供一個模組來選擇將從中載入規則的特定會話。
Session

策略使用的會話。會話提供了處理策略時要評估的所有規則。
Update Period

指定掃描更新的間隔。
Logic

在Evaluation其他條件後應用此政策的邏輯。

5.4.2 示例

以下是基於Drools的策略的簡單示例，該策略使用基於屬性的訪問控制（ABAC）來定義僅在經過身份驗證的使用者是所請求資源的所有者時才評估為GRANT的條件：

import org.keycloak.authorization.policy.evaluation.Evaluation;
rule "Authorize Resource Owner"
    dialect "mvel"
    when
       $evaluation : Evaluation(
           $identity: context.identity,
           $permission: permission,
           $permission.resource != null && $permission.resource.owner.equals($identity.id)
       )
    then
        $evaluation.grant();
end

您可以使用另一個ABAC變體來從標識中獲取屬性並相應地定義條件：

import org.keycloak.authorization.policy.evaluation.Evaluation;
rule "Authorize Using Identity Information"
    dialect "mvel"
    when
       $evaluation : Evaluation(
           $identity: context.identity,
           identity.attributes.containsValue("someAttribute", "you_can_access")
       )
    then
        $evaluation.grant();
end

有關可以從org.keycloak.authorization.policy.evaluation.Evaluation介面訪問的內容的更多資訊，請參閱Evaluation API。

5.5 基於時間的訪問策略

您可以使用此類策略來定義許可權的時間條件。

要建立新的基於時間的策略，請在策略列表右上角的下拉列表中選擇"Time"。

Add Time Policy

5.5.1 配置

Name

規則名稱
Description

規則描述
Not Before

定義不得授予訪問許可權的時間。
僅噹噹前日期/時間晚於或等於此值時才授予許可權
Not On or After

定義不得授予訪問許可權的時間。僅噹噹前日期/時間早於或等於此值時才授予許可權。
Day of Month

定義必須授予訪問許可權的日期。您還可以指定一系列日期。在這種情況下，僅當月中的當前日期介於或等於指定的兩個值時才授予許可權
Month

定義必須授予訪問許可權的月份。您還可以指定一個月的範圍。在這種情況下，僅噹噹前月份介於或等於指定的兩個值時才授予許可權。
Year

定義必須授予訪問許可權的年份。您還可以指定年份範圍。在這種情況下，僅噹噹前年份介於或等於指定的兩個值時才授予許可權。
Hour

定義必須授予訪問許可權的小時。您還可以指定一個小時範圍。在這種情況下，僅噹噹前小時介於或等於指定的兩個值時才授予許可權。
Minute

定義必須授予訪問許可權的分鐘。您還可以指定分鐘範圍。在這種情況下，僅噹噹前分鐘介於或等於指定的兩個值時才授予許可權。
Logic

在Evaluation其他條件後應用此政策的邏輯。

只有滿足所有條件，才能授予訪問許可權。 Keycloak將根據每個條件的結果執行AND。

5.6 聚合策略

如前所述，Keycloak允許您構建策略策略，這一概念稱為聚合策略。您可以使用策略聚合來重用現有策略來構建更復雜的策略，並使您的許可權與處理授權請求期間評估的策略更加分離。

要建立新的聚合策略，請在策略列表右上角的下拉列表中選擇“Aggregated”。

Add an Aggregated Policy

假設您有一個名為機密資源的資源，只能由來自keycloak.org域的使用者和特定範圍的IP地址訪問。您可以使用這兩個條件建立單個策略。但是，您希望重用此策略的域部分以應用於無論源網路如何都執行的許可權。您可以為域和網路條件建立單獨的策略，並根據這兩個策略的組合建立第三個策略。使用聚合策略，您可以自由組合其他策略，然後將新聚合策略應用於您想要的任何許可權。

建立聚合策略時，請注意不要在策略之間引入迴圈引用或依賴關係。如果檢測到迴圈依賴關係，則無法建立或更新策略。

5.6.1 配置

Name

規則名稱
Description

規則描述
Apply Policy

定義一組與聚合策略關聯的一個或多個策略。要關聯策略，您可以選擇現有策略，也可以通過選擇要建立的策略型別來建立新策略。
Decision Strategy

此許可權的決策策略。
Logic

在Evaluation其他條件後應用此政策的邏輯。

5.6.2 決策策略(Decision Strategy)

在建立聚合策略時，您還可以定義決策策略，該策略將用於根據每個策略的結果確定最終決策。

Unanimous

預設策略（如果未提供）。一致的,所有的策略都必須決策通過，最終決策通過.
Affirmative

肯定的, 只要有一項策略決策通過, 最終則決策通過
Consensus

共識, 當決策通過的數量大於或等於決策不同過的策略, 則最終決策通過, 反之不通過

5.7 基於客戶端的訪問策略

您可以使用此類策略來定義允許一組一個或多個客戶端訪問物件的許可權條件。

要建立新的基於客戶端的策略，請在策略列表右上角的下拉列表中選擇“Client”

Add a Client-Based Policy

5.7.1 配置

Name

規則名稱
Description

規則描述
Clients

指定要搜於哪些客戶端的訪問許可權
Logic

在Evaluation其他條件後應用此政策的邏輯。

5.8 基於組的訪問策略

Add Group-Based Policy

5.8.1 配置

Name

規則名稱
Description

規則描述
Groups Claim

組宣告, 指定包含組名稱和/或路徑的令牌中的宣告的名稱。
通常，授權請求獲取某個使用者的客戶端的ID令牌或訪問令牌。
如果已定義，則令牌必須包含此策略將從哪裡獲取使用者所屬的組的宣告。
如果未定義，則從您的領域配置中獲取使用者組。
Groups

允許您在評估許可權時選擇應由此策略強制執行的組。新增組後，您可以通過標記“Extend to Children 擴充套件到子項”複選框來擴充套件對組的子項的訪問許可權。
如果未標記，則訪問限制僅適用於所選組。
Logic

在Evaluation其他條件後應用此政策的邏輯。

5.8.2 擴充套件訪問許可權到子分組

預設情況下，向此策略新增組時，訪問限制僅適用於所選組的成員。

在某些情況下，可能有必要不僅允許訪問組本身，還允許訪問層次結構中的任何子組。對於新增的任何組，您可以標記一個複選框Extend to Children以擴充套件對子組的訪問。

Extending Access to Child Groups

在上面的示例中，該策略授予IT或其任何子級的任何使用者成員的訪問許可權

5.9 正面和負面推理(Logic)

可以使用正邏輯或負邏輯配置策略。
簡而言之，您可以使用此選項來定義策略結果是保持原樣還是被否定。

例如，假設您要建立一個策略，其中只應授予未授予特定角色的使用者訪問許可權。
在這種情況下，您可以使用該角色建立基於角色的策略，並將其邏輯欄位設定為Negative。
如果保持 Positive，這是預設行為，則策略結果將保持不變。

Positive: 保持策略結果
Negative: 對策略結果進行取反

5.10 Policy Evaluation API

使用JavaScript或JBoss Drools編寫基於規則的策略時，Keycloak提供了一個評估API，它提供了有用的資訊來幫助確定是否應該授予許可權。

此API由幾個介面組成，可讓您訪問資訊，例如:

正在評估的許可權，表示所請求的資源和範圍。
與請求的資源關聯的屬性
執行時環境以及與執行上下文關聯的任何其他屬性
有關使用者的資訊，例如組成員身份和角色

主介面是org.keycloak.authorization.policy.evaluation.Evaluation，它定義了以下合同：

public interface Evaluation {

    /**
     * Returns the {@link ResourcePermission} to be evaluated.
     *
     * @return the permission to be evaluated
     */
    ResourcePermission getPermission();

    /**
     * Returns the {@link EvaluationContext}. Which provides access to the whole evaluation runtime context.
     *
     * @return the evaluation context
     */
    EvaluationContext getContext();

    /**
     * Returns a {@link Realm} that can be used by policies to query information.
     *
     * @return a {@link Realm} instance
     */
    Realm getRealm();

    /**
     * Grants the requested permission to the caller.
     */
    void grant();

    /**
     * Denies the requested permission.
     */
    void deny();
}

處理授權請求時，Keycloak會在評估任何策略之前建立一個Evaluation例項。
然後將此例項傳遞給每個策略以確定訪問是GRANT還是DENY。

策略通過在Evaluation例項上呼叫grant（）或deny（）方法來確定此方法。

預設情況下，Evaluation例項的狀態為拒絕，這意味著您的策略必須顯式呼叫grant（）方法，以向策略評估引擎指示應該授予許可權。
有關Evaluation

API的更多資訊，請參閱JavaDocs。

5.10.1 The Evaluation Context

public interface EvaluationContext {

    /**
     * Returns the {@link Identity} that represents an entity (person or non-person) to which the permissions must be granted, or not.
     *
     * @return the identity to which the permissions must be granted, or not
     */
    Identity getIdentity();

    /**
     * Returns all attributes within the current execution and runtime environment.
     *
     * @return the attributes within the current execution and runtime environment
     */
    Attributes getAttributes();
}

通過該介面，策略可以獲取：

認證過的身份 - Identity
上下文環境資訊

Identity是基於與授權請求一起傳送的OAuth2訪問令牌構建的，並且此構造可以訪問從原始令牌中提取的所有宣告。例如，如果您使用Protocol Mapper 在OAuth2訪問令牌中包含自定義宣告，您還可以從策略訪問此宣告並使用它來構建條件。

EvaluationContext還允許您訪問與執行和執行時環境相關的屬性。目前，只有少數內建屬性。

Name	Description	Type
kc.time.date_time	當前日期時間	String. Format MM/dd/yyyy hh:mm:ss
kc.client.network.ip_address	IPv4 address of the client	String
kc.client.network.host	客戶端主機名稱	String
kc.client.user_agent	The value of the ‘User-Agent’ HTTP header	String[]
The name of the realm	String

6. 管理許可權

許可權將受保護的物件與必須評估的策略相關聯，以決定是否應授予訪問許可權。

在建立要保護的資源以及要用於保護這些資源的策略之後，您可以開始管理許可權。
要管理許可權，請在編輯資源伺服器時單擊“Permissions”選項卡。

Permissions

可以建立許可權以保護兩種主要型別的物件：

Resources: 資源
Scopes: 範圍

要建立許可權，請從許可權列表右上角的下拉列表中選擇要建立的許可權型別。以下部分更詳細地描述了這兩種型別的物件。

6.1 建立基於資源的許可權

要建立新的基於資源的許可權，請在許可權列表右上角的下拉列表中選擇“Resource-based”。

Add Resource-Based Permission

6.1.1 配置

Name

名稱
Description

描述
Apply To Resource Type

指定是否將許可權應用於具有給定型別的所有資源。選擇此欄位時，系統會提示您輸入要保護的資源型別。
- Resource Type
  
  定義要保護的資源型別。定義時，將評估與該型別匹配的所有資源的此許可權。
Resources

定義一組要保護的一個或多個資源。
Apply Policy

定義一組與許可權關聯的一個或多個策略。要關聯策略，您可以選擇現有策略，也可以通過選擇要建立的策略型別來建立新策略。
Decision Strategy

此許可權的決策策略。

6.1.2 資源許可權型別

資源許可權還可用於定義要應用於具有給定型別的所有資源的策略。
當您擁有共享公共訪問要求和約束的資源時，這種基於資源的許可權形式非常有用。

通常，應用程式中的資源可以根據它們封裝的資料或它們提供的功能進行分類（或型別）。例如，財務應用程式可以管理不同的銀行賬戶，其中每個賬戶屬於特定客戶。雖然它們是不同的銀行賬戶，但它們共享由銀行組織全球定義的共同安全要求和約束。使用資源許可權型別，您可以定義要應用於所有銀行帳戶的公共策略，例如：

只有所有者才能管理他的帳戶
僅允許所有者的國家/地區和/或地區訪問
執行特定的身份驗證

要建立資源許可權型別，請在建立新的基於資源的許可權時單擊“ Apply to Resource Type”。
通過將“Apply to Resource Type”設定為“On”，您可以指定要保護的型別以及要應用的策略，以管理對您指定型別的所有資源的訪問。

6.2 建立基於範圍的許可權

基於範圍的許可權定義一組一個或多個範圍，以使用一組一個或多個授權策略進行保護。與基於資源的許可權不同，您可以使用此許可權型別不僅為資源建立許可權，還為與其關聯的作用域建立許可權，在定義管理資源的許可權以及可對其執行的操作時提供更多粒度。

要建立新的基於範圍的許可權，請在許可權列表右上角的下拉列表中選擇“Scope-based”。

Add Scope-Based Perission

6.2.1 配置

Name

許可權名稱
Description

許可權描述
Resource

將範圍限制為與所選資源關聯的範圍。
如果未選擇任何選項，則所有範圍均可用。
Apply Policy

定義一組與許可權關聯的一個或多個策略。要關聯策略，您可以選擇現有策略，也可以通過選擇要建立的策略型別來建立新策略。
Decision Strategy

決策策略

6.2 決策策略

Unanimous

預設策略（如果未提供）。一致的,所有的策略都必須決策通過，最終決策通過.
Affirmative

肯定的, 只要有一項策略決策通過, 最終則決策通過
Consensus

共識, 當決策通過的數量大於或等於決策不同過的策略, 則最終決策通過, 反之不通過

7. 評估、測試策略

在設計策略時，您可以模擬授權請求以測試策略的評估方式。

可以通過單擊“Evaluate”選項卡來訪問策略評估工具。在那裡，您可以指定不同的輸入來模擬真實的授權請求並測試策略的效果。

7.1 Providing Identity Information

身份資訊過濾器可用於指定請求許可權的使用者

7.2 Providing Contextual Information

上下文資訊過濾器可用於為評估上下文定義其他屬性，以便策略可以獲取這些相同的屬性。

7.3 Providing the Permissions

許可權過濾器可用於構建授權請求。您可以為一組一個或多個資源和範圍請求許可權。如果要基於所有受保護資源和作用域模擬授權請求，請單擊“新增”，而不指定任何“資源”或“作用域”。

輸入所需資訊後，單擊“Evaluate”。

8. 授權服務

Keycloak授權服務建立在眾所周知的標準之上，例如OAuth2和使用者管理訪問規範。

OAuth2客戶端（例如前端應用程式）可以使用令牌端點從伺服器獲取訪問令牌，並使用這些相同的令牌來訪