本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

將 Express 與 Amazon Verified Permissions 整合

Verified Permissions Express 整合提供在 Express.js 應用程式中實作授權的中介軟體型方法。透過此整合，您可以使用精細的授權政策來保護 API 端點，而無需修改現有的路由處理常式。整合會透過攔截請求、針對您定義的政策進行評估，以及確保只有授權使用者可以存取受保護的資源，來自動處理授權檢查。

本主題會逐步引導您設定 Express 整合，從建立政策存放區到實作和測試授權中介軟體。遵循這些步驟，您可以將強大的授權控制新增至您的 Express 應用程式，並將程式碼變更降至最低。

本主題會參考下列GitHub儲存庫：

先決條件

實作 Express 整合之前，請確定您有：

設定整合

步驟 1：建立政策存放區

使用 建立政策存放區 AWS CLI：

aws verifiedpermissions create-policy-store --validation-settings "mode=STRICT"

步驟 2：安裝相依性

在 Express 應用程式中安裝必要的套件：

npm i --save @verifiedpermissions/authorization-clients-js
npm i --save @cedar-policy/authorization-for-expressjs

設定授權

步驟 1：產生和上傳 Cedar 結構描述

結構描述會定義應用程式的授權模型，包括應用程式中的實體類型，以及允許使用者採取的動作。建議您為結構描述定義命名空間。在此範例中，我們使用 YourNamespace. 您可以將結構描述連接至 Verified Permissions 政策存放區，並在新增或修改政策時，服務會自動針對結構描述驗證政策。

@cedar-policy/authorization-for-expressjs 套件可以分析應用程式的 OpenAPI 規格，並產生 Cedar 結構描述。具體而言，您的規格中需要路徑物件。

如果您沒有 OpenAPI 規格，您可以遵循 express-openapi-generator 套件的快速指示來產生 OpenAPI 規格。

從 OpenAPI 規格產生結構描述：

npx @cedar-policy/authorization-for-expressjs generate-schema --api-spec schemas/openapi.json --namespace YourNamespace --mapping-type SimpleRest

接著，格式化要與 搭配使用的 Cedar 結構描述 AWS CLI。如需所需特定格式的詳細資訊，請參閱 Amazon Verified Permissions 政策存放區結構描述。如果您需要格式化結構描述的說明，在已驗證許可/範例GitHub儲存庫prepare-cedar-schema.sh中會有一個名為 的指令碼。 https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts以下是對該指令碼的呼叫範例，該指令碼會在 v2.cedarschema.forAVP.json 檔案中輸出 Verified Permissions 格式的結構描述。

./scripts/prepare-cedar-schema.sh v2.cedarschema.json v2.cedarschema.forAVP.json

將格式化的結構描述上傳至您的政策存放區，policy-store-id以您的政策存放區 ID 取代 ：

aws verifiedpermissions put-schema \
  --definition file://v2.cedarschema.forAVP.json \
  --policy-store-id policy-store-id

步驟 2：建立授權政策

如果未設定任何政策，Cedar 會拒絕所有授權請求。Express 架構整合可根據先前產生的結構描述產生範例政策，協助引導此程序。

在生產應用程式中使用此整合時，我們建議您使用基礎設施做為程式碼 (IaaC) 工具建立新的政策。如需詳細資訊，請參閱使用 建立 Amazon Verified Permissions 資源 AWS CloudFormation。

產生範例 Cedar 政策：

npx @cedar-policy/authorization-for-expressjs generate-policies --schema v2.cedarschema.json

這將在 /policies目錄中產生範例政策。然後，您可以根據您的使用案例自訂這些政策。例如：

// Defines permitted administrator user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|administrator",
    action,
    resource
);

// Defines permitted employee user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|employee",
    action in
        [YourNamespace::Action::"GET /resources",
         YourNamespace::Action::"POST /resources",
         YourNamespace::Action::"GET /resources/{resourceId}",
         YourNamespace::Action::"PUT /resources/{resourceId}"],
    resource
);

格式化要與 搭配使用的政策 AWS CLI。如需所需格式的詳細資訊，請參閱 AWS CLI 參考中的 create-policy。如果您需要格式化政策的說明，在已驗證許可/範例GitHub儲存庫convert_cedar_policies.sh中會有一個名為 的指令碼。 https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts以下是對該指令碼的呼叫：

./scripts/convert_cedar_policies.sh

將格式化政策上傳至 Verified Permissions，將 取代policy_1.json為政策檔案的路徑和名稱，並將 policy-store-id取代為政策存放區 ID：

aws verifiedpermissions create-policy \
  --definition file://policies/json/policy_1.json \
  --policy-store-id policy-store-id

步驟 3：連接身分提供者

根據預設，Verified Permissions 授權方中介軟體會讀取 API 請求的授權標頭中提供的 JSON Web Token (JWT)，以取得使用者資訊。除了執行授權政策評估之外，已驗證許可還可以驗證權杖。

使用 userPoolArn和 建立名為 的身分來源組態檔案identity-source-configuration.txt，如下所示clientId：

{
    "cognitoUserPoolConfiguration": {
        "userPoolArn": "arn:aws:cognito-idp:region:account:userpool/pool-id",
        "clientIds": ["client-id"],
        "groupConfiguration": {
            "groupEntityType": "YourNamespace::UserGroup"
        }
    }
}

執行下列 AWS CLI 命令來建立身分來源，將 取代policy-store-id為您的政策存放區 ID：

aws verifiedpermissions create-identity-source \
  --configuration file://identity-source-configuration.txt \
  --policy-store-id policy-store-id \
  --principal-entity-type YourNamespace::User

實作授權中介軟體

更新您的 Express 應用程式以包含授權中介軟體。在此範例中，我們使用身分字符，但您也可以使用存取字符。如需詳細資訊，請參閱 上的 authorization-for-expressjsGitHub。

const { ExpressAuthorizationMiddleware } = require('@cedar-policy/authorization-for-expressjs');

const { AVPAuthorizationEngine } = require('@verifiedpermissions/authorization-clients');

const avpAuthorizationEngine = new AVPAuthorizationEngine({
    policyStoreId: 'policy-store-id',
    callType: 'identityToken'
});

const expressAuthorization = new ExpressAuthorizationMiddleware({
    schema: {
        type: 'jsonString',
        schema: fs.readFileSync(path.join(__dirname, '../v4.cedarschema.json'), 'utf8'),
    },
    authorizationEngine: avpAuthorizationEngine,
    principalConfiguration: { type: 'identityToken' },
    skippedEndpoints: [],
    logger: {
        debug: (s) => console.log(s),
        log: (s) => console.log(s),
    }
});

// Add the middleware to your Express application
app.use(expressAuthorization.middleware);

測試整合

您可以使用不同的使用者字符向 API 端點提出請求，以測試授權實作。授權中介軟體會根據您定義的政策自動評估每個請求。

例如，如果您已設定具有不同許可的不同使用者群組：

您可以向不同的使用者登入並嘗試各種操作，以驗證許可政策是否如預期般運作。在 Express 應用程式的終端機中，您可以看到提供授權決策其他詳細資訊的日誌輸出。

故障診斷

後續步驟

實作基本整合之後，請考慮：