在您的 Node.js Web 應用程式中使用角色型存取控制

發行項
06/19/2024

適用於：具有灰色 X 符號的白色圓圈。員工租用戶內含白色核取記號的綠色圓圈。外部租用戶 (深入了解)

角色型存取控制 (RBAC) 是一個可在應用程式中強制授權的機制。 Microsoft Entra 外部 ID 可讓您針對應用程式定義應用程式角色，並將這些角色指派給使用者和群組。您指派給使用者或群組的角色會定義其對應用程式中資源和作業的存取層級。當外部 ID 為已驗證的使用者發出安全性權杖時，它會包含您在安全性權杖的角色宣告中指派給使用者或群組的角色名稱。

您也可以設定外部租用戶，以傳回使用者的群組成員資格。然後，開發人員可以使用安全性群組在其應用程式中實作 RBAC，其中特定群組中的使用者成員資格會轉譯為其角色成員資格。

將使用者和群組指派給角色之後，角色宣告會在安全性權杖中發出。不過，若要在安全性權杖中發出群組成員資格宣告，您需要客戶租用戶中的其他設定。

在本文中，您將了解如何在 Node.js Web 應用程式的安全性權杖中接收使用者角色或群組成員資格或兩者作為宣告。

必要條件

如果您尚未這麼做，請完成使用應用程式的角色型存取控制一文中的步驟。本文會說明如何建立應用程式的角色、如何將使用者和群組指派給這些角色、如何將成員新增至群組，以及如何將群組宣告新增至安全性權杖。深入了解識別碼權杖和存取權杖。
如果您尚未這麼做，請完成在您自己的 Node.js Web 應用程式中登入使用者的步驟

在您的 Node.js Web 應用程式中接收群組和角色宣告

設定客戶的租用戶之後，您就可以在用戶端應用程式中擷取角色和群組宣告。角色和群組宣告同時存在識別碼權杖和存取權杖中，但用戶端應用程式只需要檢查識別碼權杖中的這些宣告，以在用戶端實作授權。 API 應用程式也可以在收到存取權杖時擷取這些宣告。

您可以檢查角色宣告值，如下列程式碼片段範例所示：

const msal = require('@azure/msal-node');
const { msalConfig, TENANT_SUBDOMAIN, REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

...
class AuthProvider {
...
    async handleRedirect(req, res, next) {
        const authCodeRequest = {
            ...req.session.authCodeRequest,
            code: req.body.code, // authZ code
            codeVerifier: req.session.pkceCodes.verifier, // PKCE Code Verifier
        };
    
        try {
            const msalInstance = this.getMsalInstance(this.config.msalConfig);
            const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);
            let roles = tokenResponse.idTokenClaims.roles;
        
            //Check roles
            if (roles && roles.includes("Orders.Manager")) {
                //This user can view the ID token claims page.
                res.redirect('/id');
            }
            
            //User can only view the index page.
            res.redirect('/');
        } catch (error) {
            next(error);
        }
    }
...
}

如果您將使用者指派給多個角色，roles 字串會包含以逗號分隔的所有角色，例如 Orders.Manager,Store.Manager,...。請確定您建置應用程式以處理下列條件：

權杖中沒有 roles 宣告
使用者尚未獲派任何角色
當您將使用者指派給多個角色時，roles 宣告中的多個值

您也可以檢查群組宣告值，如下列程式碼片段範例所示：

const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);
let groups = tokenResponse.idTokenClaims.groups;

群組宣告值是群組的 objectId。如果使用者是多個群組的成員，groups 字串會包含以逗號分隔的所有群組，例如 7f0621bc-b758-44fa-a2c6-...,6b35e65d-f3c8-4c6e-9538-...。

注意

如果您指派使用者 Microsoft Entra 內建角色或通常稱為目錄角色，這些角色會出現在安全性權杖的群組宣告中。

處理群組超額

為確保安全性權杖大小不會超過 HTTP 標頭大小限制，外部 ID 會限制在群組宣告中包含的物件識別碼數目。 SAML 權杖的超額限制是 150，JWT 權杖是 200。如果使用者屬於許多群組，而且您要求所有群組，就可以超過此限制。

偵測來源程式碼中的群組超額

如果您無法避免群組超額，則必須在程式碼中處理它。當您超過超額限制時，權杖不會包含群組宣告。相反地，權杖會包含一個包含陣列群組成員的 _claim_names 宣告。因此，您需要檢查 _claim_names 宣告是否存在，以得知已發生超額。下列程式碼片段會示範如何偵測群組超額：

const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);

if(tokenResponse.idTokenClaims.hasOwnProperty('_claim_names') && tokenResponse.idTokenClaims['_claim_names'].hasOwnProperty('groups')) {
    //overage has occurred
}

使用設定權杖中的群組宣告和應用程式角色一文的指示，來了解如何在群組超額發生時要求完整群組清單。

如何使用您 Node.js Web 應用程式中的群組和角色值

在用戶端應用程式中，您可以驗證登入的使用者是否具有存取受保護路由或呼叫 API 端點的必要角色。這可以藉由檢查識別碼權杖中的 roles 宣告來完成。若要在應用程式中實作此保護，您可以使用自訂中介軟體來建置防護。

在您的服務應用程式 (API 應用程式) 中，您也可以保護 API 端點。驗證用戶端應用程式所傳送的存取權杖之後，您可以檢查存取權杖承載宣告中的角色或群組宣告。

我該使用應用程式角色還是群組?

在本文中，您已了解您可以使用 應用程式角色 或群組在應用程式中實作 RBAC。慣用的方法是使用應用程式角色，因為它可在管理應用層級的存取/權限時提供更細微的控制。如需如何選擇方法的詳細資訊，請參閱選擇方法。

下一步

深入了解在權杖中設定群組宣告和應用程式角色。

共用方式為