使用Amazon Verified Permissions快速为Express应用API添加安全防护

使用Amazon Verified Permissions在几分钟内保护您的Express应用API

今天，Amazon Verified Permissions发布了@verifiedpermissions/authorization-clients-js，这是一个开源包，开发人员可以在使用Verified Permissions时，用它为Express.js Web应用API快速实现外部细粒度授权。

Express是一个极简且灵活的Node.js Web应用框架，为Web和移动应用提供了一套强大的功能。通过使用这种与Verified Permissions的标准化集成，开发人员可以用比编写自定义集成少90%的代码外部化授权，节省时间和精力，并通过减少自定义集成代码量来提升应用安全状况。

为什么要外部化授权？

传统上，开发人员通过将授权逻辑直接嵌入应用代码中来实现授权。这种嵌入式授权逻辑设计用于支持少量权限，但随着应用的发展，通常需要逐步更新嵌入式授权逻辑以支持更复杂的用例，导致代码复杂且难以维护。随着代码复杂性的增加，进一步演进安全模型和执行权限审计变得更加困难，导致应用在其生命周期中越来越难以维护。

通过外部化授权，您可以将授权逻辑与应用解耦。这带来了多重好处，包括解放开发团队专注于应用逻辑，并简化软件审计。

使用Cedar外部化授权

一种从应用代码外部化授权的方法是使用Cedar。Cedar是一种开源语言和软件开发工具包（SDK），用于编写和执行应用的授权策略。您可以将细粒度权限指定为Cedar策略，应用通过调用Cedar SDK来授权访问请求。例如，如果您正在构建一个宠物商店应用，可以使用以下Cedar策略来控制只有jobLevel为employee的用户才能访问POST /pets API。

cedar 复制代码

permit (
    principal,
    action in [Action::"POST /pets"], 
    resource
) when {
    principal.jobLevel = "employee"
};

使用Cedar的一种选项是自我管理实现；您可以在另一篇文章中找到此模式的示例：使用Cedar在5分钟内保护您的应用API。

自我管理的Cedar提供了外部化授权的好处，但需要持续的操作管理。组织负责Cedar版本升级、应用安全补丁、管理策略和审计授权。使用Cedar的另一种选项是使用Verified Permissions。Verified Permissions通过提供Cedar的托管服务来消除这些操作需求。Verified Permissions管理扩展，通过支持集中策略管理简化策略治理，并记录策略更改和授权请求以简化审计。

集成Verified Permissions到Express应用

本文描述了Web应用开发人员如何使用新的Express包来简化Express Web应用与Verified Permissions的集成。分步指南使用一个示例宠物商店应用来展示如何基于用户组限制API访问。您可以在GitHub上的verifiedpermissions存储库中找到示例宠物商店应用。

宠物商店应用API概述

宠物商店应用用于管理宠物商店。该宠物商店使用Express与Node.js构建，并暴露了下表中的API。

API	描述
GET /api/pets	返回可用宠物列表
GET /api/pets/{petId}	返回找到的指定宠物
POST /api/pets	向宠物商店添加宠物
PUT /api/pets/{petId}	更新现有宠物
DELETE /api/pets/{petId}	从宠物商店移除宠物

该应用不允许所有用户访问所有API。相反，它强制执行以下规则：

管理员：对宠物和管理功能的完全访问权限
员工：可以查看、创建和更新宠物
客户：可以查看宠物和创建新宠物

实现宠物商店API的授权

让我们逐步介绍如何使用Verified Permissions和新的Express包来保护您的应用API。初始应用（无授权）可以在start文件夹中找到；使用它来跟随本文。您可以在finish文件夹中找到应用的完成版本。

完成后，您将实现图1中所示的应用架构。一个使用Amazon Cognito进行身份验证的React前端应用。然后，应用将Cognito返回的身份令牌作为授权头包含到Express后端API中。Express后端使用新的Verified Permissions授权中间件包调用Verified Permissions来授权用户请求。

先决条件

在开始之前，请确保满足以下先决条件。

步骤1：设置AWS CLI

某些命令需要AWS命令行界面（AWS CLI）。请参阅安装或更新到最新版本的AWS CLI和配置AWS CLI设置。

步骤2：设置OpenID Connect身份提供者和数据库

宠物商店应用使用OpenID Connect（OIDC）身份提供者来管理用户。对于此示例，您使用名为PetStoreUserPool的Amazon Cognito用户池，其中包含三个用户：一个管理员、一个员工和一个客户。

该应用还使用Amazon DynamoDB数据库来存储宠物。

您可以通过在/start目录中运行以下命令在AWS账户中设置Amazon Cognito和DynamoDB。

bash 复制代码

./scripts/setup-infrastructure.sh

设置脚本将提示您为三个用户设置密码（密码必须至少8个字符，并需要至少一个数字、一个大写字母和一个小写字母）。

注意运行此脚本的输出，因为您将在"集成Verified Permissions"的步骤5中使用它们。

注意：在您自己的应用中，您可以按照在Amazon Cognito控制台中创建新应用的说明设置Amazon Cognito，或者您可以自带OIDC身份提供者。

步骤3（可选）：运行应用

现在基础设施已设置，您可以运行应用。在两个单独的终端中，在/start目录中运行以下命令：

bash 复制代码

./scripts/run-backend-dev.sh
./scripts/run-frontend-dev.sh

通过创建一些宠物来测试应用。

集成Verified Permissions

先决条件就绪后，下一步是集成Verified Permissions。Verified Permissions可以通过六个步骤集成到Express应用中：

创建Verified Permissions策略存储
添加Cedar和Verified Permissions授权中间件包
创建和部署Cedar模式
创建和部署Cedar策略
将Verified Permissions策略存储连接到您的OIDC身份提供者
更新应用代码以调用Verified Permissions来授权API访问

Verified Permissions集成发生在Express Web应用后端。本节中的所有命令都应在/start/backend目录中运行。

步骤1：创建Verified Permissions策略存储

使用AWS CLI通过运行以下命令在Verified Permissions中创建策略存储。

bash 复制代码

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

示例成功命令输出：

json 复制代码

{
    "policyStoreId": "AAAAbbbbCCCCdddd",
    "arn": "arn:aws:verifiedpermissions::111122223333:policy-store/AAAAbbbbCCCCdddd",
    "createdDate": "2025-06-05T19:30:37.896119+00:00",
    "lastUpdatedDate": "2025-06-05T19:30:37.896119+00:00"
}

保存命令输出中的policyStoreId值以在步骤3中使用。

步骤2：添加Cedar和Verified Permissions授权中间件包

运行以下命令以添加两个新依赖项：@verifiedpermissions/authorization-clients-js和@cedar-policy/authorization-for-expressjs。

bash 复制代码

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

步骤3：创建和部署Cedar模式

Cedar模式定义了应用的授权模型，包括应用中的实体类型和允许用户执行的操作。您将模式附加到Verified Permissions策略存储，当策略被添加或修改时，服务会自动根据模式验证策略。

@cedar-policy/authorization-for-expressjs包可以分析应用的OpenAPI规范并生成Cedar模式。具体来说，您的规范中需要OpenAPI模式中的paths对象。

如果您没有OpenAPI规范，可以使用您选择的工具生成一个。有几个开源库可以用于Express；您可能需要向应用添加一些代码，生成OpenAPI规范，然后删除代码。或者，一些基于生成式AI的工具，如Amazon Q Developer CLI，可以有效地生成OpenAPI规范文档。无论您如何生成规范，请确保验证工具的正确输出。

对于示例应用，已包含一个名为openapi.json的OpenAPI规范文档。

运行以下命令生成Cedar模式。

bash 复制代码

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

示例成功命令输出：

csharp 复制代码

Cedar schema successfully generated. Your schema files are named: v2.cedarschema.json, v4.cedarschema.json.
v2.cedarschema.json is compatible with Cedar 2.x and 3.x
v4.cedarschema.json is compatible with Cedar 4.x and required by the nodejs Cedar plugins.

接下来，格式化Cedar模式以与AWS CLI一起使用。所需的特定格式在Amazon Verified Permissions策略存储模式文档中描述。要格式化Cedar模式，请运行以下命令。

bash 复制代码

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

示例成功命令输出：

yaml 复制代码

Cedar schema prepared successfully: v2.cedarschema.forAVP.json
You can now use it with AWS CLI:

模式格式化后，运行以下命令将模式上传到Verified Permissions。注意，您需要将替换为实际的策略存储ID，该ID由步骤1中的命令输出提供。

bash 复制代码

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

示例成功命令输出：

json 复制代码

{
    "policyStoreId": "AAAAbbbbCCCCdddd",
    "namespaces": [
        "PetStoreApp"
    ],
    "createdDate": "2025-06-03T20:19:33.480528+00:00",
    "lastUpdatedDate": "2025-06-05T19:42:45.198325+00:00"
}

步骤4：创建和部署Cedar策略

如果未配置任何策略，Cedar会拒绝授权请求。下一步是创建策略，这些策略将允许特定用户组访问特定资源。Express框架集成通过基于先前生成的模式生成示例策略来帮助引导此过程。然后，您可以根据您的用例自定义这些策略。

运行以下命令生成示例Cedar策略。

bash 复制代码

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

示例成功命令输出：

bash 复制代码

Cedar policy successfully generated in policies/policy_1.cedar
Cedar policy successfully generated in policies/policy_2.cedar

两个示例策略在/policies目录中生成：policy_1.cedar和policy_2.cedar。policy_1.cedar为admin用户组中的用户提供对任何资源执行任何操作的权限。

cedar 复制代码

// policy_1.cedar
// Allows admin usergroup access to everything
permit (
    principal in PetStoreApp::UserGroup::"admin",
    action,
    resource
);

policy_2.cedar为Cedar模式中定义的单个操作提供更多访问权限，并为特定组提供了占位符。

cedar 复制代码

// policy_2.cedar
// Allows more granular user group control, change actions as needed
permit (
    principal in PetStoreApp::UserGroup::"ENTER_THE_USER_GROUP_HERE",
    action in
        [PetStoreApp::Action::"GET /pets",
         PetStoreApp::Action::"POST /pets",
         PetStoreApp::Action::"GET /pets/{petId}",
         PetStoreApp::Action::"PUT /pets/{petId}",
         PetStoreApp::Action::"DELETE /pets/{petId}"],
    resource
);

注意，如果您在OpenAPI规范中指定了operationId，则Cedar模式中定义的操作名称将使用该operationId，而不是默认的 /格式。在这种情况下，请确保Cedar策略中的操作命名与Cedar模式中的操作命名匹配。例如，如果您想将操作称为AddPet而不是POST /pets，您可以将OpenAPI规范中的operationId设置为AddPet。Cedar策略中的结果操作将是PetStoreApp::Action::"AddPet"。

创建第三个策略文件，名为policy_3.cedar，然后将每个文件的内容替换为以下策略。将每个策略中的替换为之前复制的Cognito用户池ID。

注意：在实际用例中，考虑根据内容重命名Cedar策略文件，例如allow_customer_group.cedar。

cedar 复制代码

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

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

// Defines permitted customer user group actions
permit (
    principal in PetStoreApp::UserGroup::"<userPoolId>|customer",
    action in
        [PetStoreApp::Action::"GET /pets",
         PetStoreApp::Action::"POST /pets",
         PetStoreApp::Action::"GET /pets/{petId}"],
    resource
);

策略需要格式化以便与AWS CLI for Verified Permissions一起使用。特定格式在AWS CLI Verified Permissions文档中描述。运行以下命令格式化策略。

bash 复制代码

../scripts/convert_cedar_policies.sh

示例成功命令输出：

bash 复制代码

Converting policies/policy_1.cedar to policies/json/policy_1.json
Created policies/json/policy_1.json
Converting policies/policy_2.cedar to policies/json/policy_2.json
Created policies/json/policy_2.json
Converting policies/policy_3.cedar to policies/json/policy_3.json
Created policies/json/policy_3.json
Conversion complete. JSON policy files are in ../policies/json/

格式化后的策略将输出到backend/policies/json/目录。

格式化策略后，运行以下三个命令，每个策略一个，将它们上传到Verified Permissions。策略存储ID在完成步骤2后返回。将替换为实际的策略存储ID。

bash 复制代码

aws verifiedpermissions create-policy --definition file://policies/json/policy_1.json --policy-store-id <policy store id>
aws verifiedpermissions create-policy --definition file://policies/json/policy_2.json --policy-store-id <policy store id>
aws verifiedpermissions create-policy --definition file://policies/json/policy_3.json --policy-store-id <policy store id>

示例成功命令输出：

json 复制代码

{
    "policyStoreId": "AAAAbbbbCCCCdddd",
    "policyId": "8AmzZYMw6Ux5DGBoX7w24m",
    "policyType": "STATIC",
    "principal": {
        "entityType": "PetStoreApp::UserGroup",
        "entityId": "<userPoolId>|administrator"
    },
    "createdDate": "2025-06-05T19:46:45.848602+00:00",
    "lastUpdatedDate": "2025-06-05T19:46:45.848602+00:00",
    "effect": "Permit"
}

或者，您也可以在AWS管理控制台中将Cedar策略复制并粘贴到Verified Permissions中。

步骤5：将Verified Permissions策略存储连接到您的OIDC身份提供者

默认情况下，Verified Permissions授权器中间件读取API请求的授权头中提供的JSON Web令牌（JWT）以获取用户信息。Verified Permissions可以验证令牌，并执行授权策略评估。

为此，在Verified Permissions策略存储中创建身份源。为了简化AWS CLI命令中的格式化，我们已在identity-source-configuration.txt中定义了身份源配置。根据运行先决条件步骤2中的setup-infrastructure.sh脚本的输出，替换以下代码块中的和参数。

json 复制代码

// identity-source-configuration.txt
{
    "cognitoUserPoolConfiguration": {
        "userPoolArn": "<userPoolArn>",
        "clientIds":["<clientId>"] ,
        "groupConfiguration": {
              "groupEntityType": "PetStoreApp::UserGroup"
        }
    }
}

更新文件后，运行以下命令更新Verified Permissions策略存储。将替换为实际的策略存储ID。

bash 复制代码

aws verifiedpermissions create-identity-source --configuration file://identity-source-configuration.txt --policy-store-id <policy store id> --principal-entity-type PetStoreApp::User

示例成功命令输出：

json 复制代码

{
    "createdDate": "2025-06-05T20:02:53.992782+00:00",
    "identitySourceId": "DTLvwdiKfdPmk2RWzSVfu2",
    "lastUpdatedDate": "2025-06-05T20:02:53.992782+00:00",
    "policyStoreId": "AAAAbbbbCCCCdddd"
}

步骤6：更新应用代码以调用Verified Permissions来授权API访问

您现在需要更新应用以使用@verifiedpermissions/authorization-clients-js和@cedar-policy/authorization-for-expressjs依赖项。这将允许应用调用Verified Permissions来授权API请求。

通过将以下代码块添加到backend/app.ts的第13行（直接在import语句之后）来添加依赖项并定义CedarAuthorizerMiddleware和AVPAuthorizer。将以下代码块中的替换为您的实际Verified Permissions策略存储ID。

javascript 复制代码

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

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

const avpAuthorizationEngine = new AVPAuthorizationEngine({
    policyStoreId: <policyStoreId>,
    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: any) => console.log(s),
        log: (s: any) => console.log(s),
    }
});

配置Express应用以使用您刚刚定义的授权中间件。为此，在app.use(..)语句块之后添加以下代码行，该语句块在注释// Configure security and performance middleware之后开始（大约第48行，具体取决于您如何粘贴先前的代码块）。

javascript 复制代码

app.use(expressAuthorization.middleware);

您现在已成功在应用中设置授权，通过创建Verified Permissions策略存储、编写Cedar策略来定义授权，并将应用与Verified Permissions集成。

验证API安全性

您可以使用前端Web应用来验证授权是否已应用于API。在两个单独的终端中，在/start目录中运行以下命令。

bash 复制代码

./scripts/run-backend-dev.sh
./scripts/run-frontend-dev.sh

在浏览器中导航到http://localhost:3001，并使用您之前创建的Amazon Cognito用户之一登录。验证权限策略是否按预期工作：

管理员：可以查看、创建、更新和删除宠物。
员工：可以查看、创建和更新宠物。
客户：可以查看宠物和创建新宠物。

在Express应用的终端中，您可以看到提供授权决策额外详细信息的日志输出。例如，在未经授权的操作之后，终端输出以下内容：

sql 复制代码

Authorization result: {"type":"deny"}

结论

新的@verifiedpermissions/authorization-clients-js包允许Express开发人员将其应用与Verified Permissions集成，以将授权逻辑与代码解耦。通过解耦授权逻辑并将应用与Verified Permissions集成，您可以提高开发人员生产力并简化权限和访问审计。

为了支持在编写Cedar策略时分析和审计权限，开源Cedar项目最近还开源了Cedar Analysis CLI，以帮助开发人员对其策略执行策略分析。您可以在Introducing Cedar Analysis: Open Source Tools for Verifying Authorization Policies中了解有关此新工具的更多信息。

框架包是开源的，可在GitHub上根据Apache 2.0许可证获得，并通过NPM分发。要了解更多信息，请参阅Amazon Verified Permissions和Cedar。

如果您对此帖子有反馈，请在下面的评论部分提交评论。