在Keycloak中實現多租戶並在ASP.NET Core下進行驗證

Keycloak是一個功能強大的開源身份和訪問管理系統，提供了一整套解決方案，包括使用者認證、單點登入（SSO）、身份聯合、使用者註冊、使用者管理、角色對映、多因素認證和訪問控制等。它廣泛應用於企業和雲服務，可以簡化和統一不同應用程式和服務的安全管理，支援自託管或雲部署，適用於需要安全、靈活且易於擴充套件的使用者身份管理和訪問控制的場景。

SaaS（Software as a Service，軟體即服務）是一種軟體分發模式，其中軟體應用程式透過網際網路託管並由服務提供商管理。使用者通常透過訂閱模式訪問這些服務，而不是購買和安裝軟體。SaaS應用程式通常部署在雲環境中，只要使用者有網際網路連線，他們就可以隨時隨地訪問服務。在SaaS應用中，多租戶支援是關鍵需求之一。在多租戶環境中，一個服務例項需要為多個租戶（即不同的公司、組織或個人使用者）提供服務，同時保障資料隔離和安全性。因此，多租戶的支援也成為了與SaaS應用整合的身份和訪問管理（IAM）服務的基本需求，在選用Keycloak作為SaaS應用IAM服務的場景下，對於多租戶模式的支援，也是Keycloak實施的一個關鍵需求。

Keycloak中的基本概念及其之間的關係

要理解Keycloak對於多租戶的支援方式，首先需要了解Keycloak中的一些基本概念以及它們之間的關係。當然，本文不會詳細解釋這些概念是什麼，Keycloak的官方文件裡有詳細的解釋，瞭解這部分內容將有助於選擇以何種方式實現多租戶。

下圖簡要描述了Keycloak中的一些主要的基本概念及其之間的關係：

在一個Keycloak的部署中包含多個Realm，Realm是一個管理的域，它作為頂層組織單元，用來封裝和管理一組使用者、角色、群組和客戶端（即應用程式或服務）。每個Realm可以有自己的一套使用者目錄、身份驗證和授權規則、客戶端配置以及其他安全性設定，不同的Realm之間是相互隔離的。在一個Realm中，可以建立多個Client，Client是一個非常重要的概念，它代表了可以請求Keycloak進行認證和授權的實體。在OAuth 2.0和OpenID Connect（OIDC）的上下文中，客戶端通常指的是一個應用程式，它希望使用Keycloak作為身份提供者來驗證使用者的身份，並可能獲取使用者授權的令牌，以便訪問受保護的資源。在不同的Client下，可以建立互相隔離的一組Client Role，也就是Client下的角色，一個角色可以關聯到多個使用者（user）或者使用者組（group）上。與此同時，Client下還可以有一組Client Scope，而Client Scope還可以對映到某個或者某些使用者資訊屬性（user profile attribute）上，而使用者資訊屬性（user profile attribute）則可以是定義在使用者（user）上的自定義屬性。

Keycloak中多租戶的不同模式

從上面的結構可以分析得出，Keycloak對多租戶的支援主要有兩種模式：

1. 每個租戶（tenant）使用獨立的Realm，即Realm per tenant模式
2. 所有租戶共享同一個Realm，但使用不同的Client，即Single Realm模式

需要根據不同需求來選擇不同的模式。

Realm per Tenant

這種模式的實現比較簡單清晰：資料嚴格隔離，簡單地按照上圖中的關係對Realm進行配置就行了，比如，在Realm下可以直接建立使用者組，這些使用者組就是屬於當前這個租戶的；但另一方面，由於不同的Realm擁有完全不同的一套使用者（user）和使用者組（group）資料，於是，Realm per Tenant無法實現某個使用者同時屬於多個租戶的場景。你可以在不同的租戶中建立名字和電子郵件地址完全相同的使用者，但是，它們雖然名字相同，卻是完全不同的兩個實體。除此之外，當租戶數量越來越大時，Realm的個數也會相應增加，對於Keycloak來說也存在一定的效能影響（我沒有實際測試過，但是根據目前來自各方面的文件資料，Keycloak維護上百個Realm還是沒有太大問題的）。

Single Realm

在Single Realm模式下，每個租戶就是一個Client，好處是使用者及使用者組可以屬於多個租戶，比如：A使用者可以同時屬於T1和T2兩個租戶，也不必考慮Realm太多影響效能。每個Client都可以配置不同的登入選項，因此，可以滿足多租戶的需求。但實現這種模式相對比較複雜，而且有些資訊比如使用者的角色、所屬的使用者組等會全部出現在使用者的access token裡，而這些資訊有些是屬於特定租戶的，其資料隔離性沒有Realm per Tenant模式好。

使用Single Realm實現多租戶的一般思路是，針對每一個租戶建立一個Client，所以在這個Realm下，使用者是跨租戶的，使用者組理論上也是跨租戶的，但是，可以對不同的租戶，設定不同的使用者組，然後在這個租戶級別的使用者組下，還可以建立子組，所以，使用者組也可以做到按租戶隔離。對於角色而言，Client下本身就可以分配不同的角色，所要做的就是將使用者/使用者組分配到不同的角色上，只不過選擇角色的時候需要指定，是分配到哪個Client下的哪個角色。

演練：在Keycloak中配置Single Realm多租戶模式

注意：本文演練部分基於Keycloak 24.0.2，對於其它版本的Keycloak，介面操作可能會有出入。

建立一個新的Realm

啟動Keycloak本地開發環境，推薦使用docker，可以參考這篇文章。啟動成功後，用admin/admin登入管理介面，點選介面左邊的Keycloak下拉框，然後點選Create realm按鈕，以建立一個新的Realm。

在Create realm介面，只需要輸入Realm name即可，例如：multitenant，然後點選Create按鈕，系統提示Realm created successfully，表示Realm建立成功。

建立對應於租戶的Client

接下來，在側邊欄中點選Clients連結，開啟Clients列表介面，在介面中，點選Create client，注意：這裡我們就是為某個租戶建立一個Client，因此，可以考慮用租戶的名稱來命名這個Client，假設我們客戶的名字叫Globex Corporation，於是，Client就命名為globex。在Create client介面中，Client ID填globex，然後點選Next按鈕：

在Capability config下，啟用Client authentication，Authorization也可以考慮啟用，在Authentication flow中，暫時先勾選Direct access grants，以便後面的測試。在OIDC的Authorization Code Flow和Authorization Code Flow /w PKCE兩種flow下，該選項可以關閉，當然，具體的可以根據專案實際情況選擇。這部分的配置如下：

點選Next按鈕，在Login settings頁面，可以無需修改配置，直接點選Save按鈕，此時Client建立成功。

配置Client scopes

在左側側邊欄，點選Client scopes，然後點選Create client scope按鈕，在Create client scope頁面中，輸入Client scope名稱，其它的預設就行，然後點選Save按鈕：

在新建立的Client scope下，點選Mappers標籤頁，然後點選Configure a new mapper按鈕：

在Configure a new mapper列表中，找到Group Membership，直接點選選中，然後在Add mapper頁面下，輸入Mapper的名字，然後Token Claim Name也指定一下，其它的開關按鈕保持預設就行。這裡注意的是，Token Claim Name並不是必須的，但是如果你希望它出現在使用者的access token中，那麼這個是必填的：

完成配置後點選Save按鈕儲存配置。然後回到Clients列表，點選剛剛新建的Client：globex，進入Client scopes標籤頁，單擊Add client scope按鈕：

在彈出的Add client scopes to globex對話方塊中，選擇剛剛新建的Client scope，然後點選Add -> Default按鈕：

配置使用者（user）和使用者組（group）

注意：此處配置的使用者和使用者組是跨多租戶，也就是跨多個Client的，之後會在Client的Role下透過角色關聯來將使用者關聯到租戶上。

在左邊側邊欄點選Users連結，在Users介面中，點選Create new user按鈕，然後在General部分輸入Username，其它資訊可以按需填寫，然後點選Create按鈕：

在使用者詳細資訊頁面中，點選Credentials選項卡，然後點選Set password按鈕：

在彈出的對話方塊中，輸入密碼，然後關閉Temporary選項，再點選Save按鈕，在確認對話方塊中，點選紅色的Save password按鈕即可：

在左側側邊欄點選Groups連結，然後點選Create group按鈕，在彈出的Create a group對話方塊中，輸入組名。由於我們希望不同租戶具有不同的組配置策略，也就是租戶的使用者組也需要隔離，因此，在這裡組名就使用租戶的名稱，也就是globex。然後點選Create按鈕建立組。在成功建立組之後，點選Members選項卡，然後點選Add member按鈕，在彈出的Add member對話方塊中，將剛剛新建的super使用者新增到globex組中。

一個對應於租戶的組（比如這裡的globex組）下還可以建立多個子使用者組，也就可以定義針對不同租戶的使用者組層次結構。

配置使用者/使用者組角色

點選左邊側邊欄的Clients連結，在Clients列表中，點選globex Client，在Roles選項卡下，點選Create role按鈕，新建一個角色，比如administrator，然後點選Save按鈕：

回到Users或者Groups介面，選擇某個使用者或者使用者組，比如選擇剛剛新建的super使用者，在使用者的Role mapping選項卡下，點選Assign role按鈕：

在Assign roles to super對話方塊中，點選Filter by realm roles下拉框，選擇Filter by clients，然後選擇globex這個Client的administrator角色，表示需要將globex租戶的administrator角色分配給super使用者：

測試我們的配置

點選左側側邊欄的Clients連結，然後選擇globex Client，進入Credentials選項卡，在Client Secret部分點選複製按鈕，將Client Secret複製到剪貼簿中，然後開啟Postman，使用下面的HTTP請求：

• POST URL為http://<server>:<port>/realms/<realm>/protocol/openid-connect/token
• grant_type：password
• client_id：租戶的名稱，globex
• client_secret：上一步複製到剪貼簿的內容
• password：使用者密碼
• username：使用者名稱稱

點選Send按鈕後，即可得到access token。開啟https://jwt.io，將access token複製到Debugger的Encoded部分，即可解出access token的明文：

詳細內容類似如下：

{
  "exp": 1712410272,
  "iat": 1712409972,
  "jti": "8f18192e-c223-4f60-a23d-6e825f5e6b37",
  "iss": "http://localhost:5600/realms/multitenant",
  "aud": "account",
  "sub": "1a666edc-36c2-4704-ac14-2a8d88332781",
  "typ": "Bearer",
  "azp": "globex",
  "session_state": "448c536c-3f11-4275-b03c-78bec00deb56",
  "acr": "1",
  "allowed-origins": [
    "/*"
  ],
  "realm_access": {
    "roles": [
      "offline_access",
      "uma_authorization",
      "default-roles-multitenant"
    ]
  },
  "resource_access": {
    "globex": {
      "roles": [
        "administrator"
      ]
    },
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "email profile",
  "sid": "448c536c-3f11-4275-b03c-78bec00deb56",
  "email_verified": false,
  "name": "Super Admin",
  "groups": [
    "/globex"
  ],
  "preferred_username": "super",
  "given_name": "Super",
  "family_name": "Admin",
  "email": "super@globex.com"
}

可以看到：

1. azp代表了當前請求access token的租戶名稱
2. resource_access下列出了該使用者所屬的租戶名稱，以及在每個租戶下所屬的角色
3. groups下列出了該使用者所屬的使用者組，很遺憾，這裡它會將所有該使用者所屬的使用者組列出來，比如，如果還存在另一個租戶soylent，那麼，這個groups陣列裡就會出現/soylent這個專案。在實際專案中，可以在Action Filter中，透過程式碼來處理這個資訊

與ASP.NET Core Web API的整合

此時可以新建一個ASP.NET Core Web API應用程式，整合Keycloak身份認證，來檢視在User Principle上可以拿到哪些資料。修改Program.cs檔案，加入這些程式碼：

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "http://localhost:5600/realms/multitenant";
        options.MetadataAddress = 
            "http://localhost:5600/realms/multitenant/.well-known/openid-configuration";
        options.RequireHttpsMetadata = false;
        options.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters
        {
            NameClaimType = "preferred_username",
            RoleClaimType = ClaimTypes.Role,
            ValidateIssuer = true,
            ValidateAudience = false
        };
    });

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

然後，在Controller上加入[Authorize]特性：

[ApiController]
[Authorize]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
  // 省略N行
}

在某個Controller Action方法上設定一個除錯斷點，然後啟動ASP.NET Core Web API應用程式。接下來，在Postman中呼叫這個設定了除錯斷點的API服務，記得Authorization選擇Bearer Token，然後將上面透過Postman獲得的access_token作為Bearer Token填入，發起請求。此時，Visual Studio中斷點會被命中，檢視User物件，可以看到，有關租戶的一些資訊已經在User的Claims下：

之後，只需利用這些資訊來實現使用者授權即可。