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

# 將 Express 與 Amazon Verified Permissions 整合
<a name="integration-express"></a>

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

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

本主題會參考下列GitHub儲存庫：
+ [cedar-policy/authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs) - Express.js 的 Cedar 授權中介軟體
+ [verifiedpermissions/authorization-clients-js](https://github.com/verifiedpermissions/authorization-clients-js) - JavaScript 的 Verified Permissions 授權用戶端
+ [verifiedpermissions/examples/express-petstore](https://github.com/verifiedpermissions/examples/tree/main/express-petstore) - 使用 Express.js 中介軟體的範例實作

## 先決條件
<a name="express-integration-prerequisites"></a>

實作 Express 整合之前，請確定您有：
+ 可存取 Verified Permissions [AWS 的帳戶](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html) 
+ 已安裝 [Node.js](https://nodejs.org/) 和 [npm](https://docs.npmjs.com/) 
+ [Express.js](https://expressjs.com/) 應用程式
+ OpenID Connect (OIDC) 身分提供者 （例如 [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html))
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html) 已設定適當的許可

## 設定整合
<a name="express-integration-setup"></a>

### 步驟 1：建立政策存放區
<a name="setup-create-policy-store"></a>

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

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

**注意**  
儲存回應中傳回的政策存放區 ID，以用於後續步驟。

### 步驟 2：安裝相依性
<a name="setup-install-dependencies"></a>

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

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

## 設定授權
<a name="express-integration-configuration"></a>

### 步驟 1：產生和上傳 Cedar 結構描述
<a name="config-generate-cedar-schema"></a>

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

`@cedar-policy/authorization-for-expressjs` 套件可以分析應用程式的 [OpenAPI 規格](https://swagger.io/specification/)，並產生 Cedar 結構描述。具體而言，您的規格中需要路徑物件。

如果您沒有 OpenAPI 規格，您可以遵循 [express-openapi-generator](https://github.com/nklisch/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 政策存放區結構描述](schema.md)。如果您需要格式化結構描述的說明，在已驗證許可/範例GitHub儲存庫`prepare-cedar-schema.sh`中會有一個名為 的指令碼。 [https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts](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：建立授權政策
<a name="config-create-authorization-policies"></a>

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

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

產生範例 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](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-policy.html)。如果您需要格式化政策的協助，在已驗證許可/範例GitHub儲存庫`convert_cedar_policies.sh`中會有一個名為 的指令碼。 [https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts](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：連接身分提供者
<a name="config-connect-identity-provider"></a>

根據預設，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
```

## 實作授權中介軟體
<a name="express-integration-implementing-middleware"></a>

更新您的 Express 應用程式以包含授權中介軟體。在此範例中，我們使用身分字符，但您也可以使用存取字符。如需詳細資訊，請參閱 上的 [authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs)GitHub。

```
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);
```

## 測試整合
<a name="testing-authorization"></a>

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

例如，如果您已設定具有不同許可的不同使用者群組：
+ 管理員：完整存取所有資源和管理函數
+ 員工：可以檢視、建立和更新資源
+ 客戶：只能檢視資源

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

## 疑難排解
<a name="troubleshooting"></a>

如果您有授權失敗，請嘗試下列動作：  
+ 驗證您的政策存放區 ID 是否正確
+ 確保您的身分來源已正確設定
+ 檢查您的政策格式是否正確
+ 驗證您的 JWT 權杖是否有效

## 後續步驟
<a name="express-integration-next-steps"></a>

實作基本整合之後，請考慮：
+ 針對特定授權案例實作自訂映射器
+ 為授權決策設定監控和記錄
+ 為不同的使用者角色建立其他政策