# @cedar-policy/authorization-for-expressjs 中文文档

规范地址：https://npmcn.com/package/%40cedar-policy/authorization-for-expressjs/

版本：0\.3\.0
npm 元数据更新时间：2026-05-07T17:49:04.091Z
中文译文更新时间：2026-11-09T06:58:26.157Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cedar-policy/authorization-for-expressjs
原文对照：https://npmcn.com/package/%40cedar-policy/authorization-for-expressjs/?lang=original
项目主页：https://github.com/cedar-policy/authorization-for-expressjs#readme
源码仓库：https://github.com/cedar-policy/authorization-for-expressjs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：152 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-06-16T19:10:56.531Z
- 最新版本发布：2026-05-07T17:49:03.764Z
- 近 30 天下载量：10277（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 2 个）

## 中文简介

授权带有 Cedar 的 expressJS 应用程序的中间软件

## 安装

```sh
npm install @cedar-policy/authorization-for-expressjs
```

也可以使用：`pnpm add @cedar-policy/authorization-for-expressjs`、`yarn add @cedar-policy/authorization-for-expressjs`、`bun add @cedar-policy/authorization-for-expressjs`

## README

# 快捷JS 的 Cedar 授权

一个中间软件包,可以让Cedar基于Express.js应用程序的授权. 这个软件包使得在与您 Express.js 应用程序的认证系统进行无缝整合的同时,使用 Cedar 政策来实施精细的授权控制变得容易.

## 特征

-   \* Express.js基于锡达的授权中间软件
-   使用Cedar政策的精细出入控制
-   与OIDC/JWT认证的无缝集成
-   最佳授权检查
-   QQ 自定义主要实体映射
-   终点排除支持
-   配置式记录

## 安装

```bash
npm install @cedar-policy/authorization-for-expressjs
```

## 快速启动

### 先决条件

在实施"快递"集成之前,确保您有:

-   [节点.js](https://nodejs.org/) 财务报告和审定财务报表 [无](https://docs.npmjs.com/) 已安装
-   一个 [运通.js](https://expressjs.com/) 应用程序
-   OpenID 连接( OIDC) 身份提供者( 可选测试)

### 建立一体化

让我们通过如何保护您的应用程序 API 使用 Cedar 与新包为快递.

#### 步骤1: 添加 Cedar 授权中件包

Cedar Authority Middleware 软件包将被用于生成Cedar schema,创建样本授权政策,并在您的应用程序中执行授权.

```bash
npm i --save @cedar-policy/authorization-for-expressjs
```

#### 第2步:从您的 API 生成 Cedar 计划

锡达 [计划](https://npmcn.com/package/%40cedar-policy/overview/terminology.html#term-schema) 定义应用程序的授权模式,包括应用程序中的实体类型和允许用户采取的行动。 我们建议界定 [命名空间](https://npmcn.com/package/%40cedar-policy/overview/terminology.html#term-namespaces) 为了你的计划。 在此示例中, 我们使用您的命名空间 。 当您运行此应用程序时, 您的政策会被验证 .

这个 `authorization-for-expressjs` 软件包可以分析 [OpenAPI 规格](https://swagger.io/specification/) 并生成 Cedar 计划。 具体来说,路径对象在您的规格中是需要的.

如果您没有 OpenAPI 规格, 您可以遵守快速指令 [特快- openapi 生成器](https://github.com/nklisch/express-openapi-generator) 生成 OpenAPI 规格的软件包.

通过运行,替换来生成 Cedar 计划 `openapi.json` 和您的计划的文件 `YourNamespace` 使用我们选择的命名空间:

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

这将生成一个命名为 schema 文件 `v4.cedarschema.json` 在软件包根中.

#### 第3步:确定授权政策

如果没有配置政策,Cedar将拒绝所有授权请求. 我们将增加只允许授权用户群体访问API的政策.

生成 Cedar 政策样本 :

```bash
npx @cedar-policy/authorization-for-expressjs generate-policies --schema v4.cedarschema.json
```

这将产生/政策目录中的抽样政策。 您可以根据您的使用案例定制这些政策 。 例如:

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

注:如果您指定了 `operationId` 在 OpenAPI 规格中, Cedar Schema 定义的动作名称将使用 `operationId` 而不是默认 `<HTTP Method> /<PATH>` 格式。 在此情况下, 请确保您在 Cedar 政策中动作的命名与 您在 Cedar Schema 中动作的命名相匹配 .

对于具有复杂授权政策的大型应用程序,分析和审计许多不同政策提供的实际许可可能具有挑战性。 锡达还提供 [锡达分析CLI](https://github.com/cedar-policy/cedar-spec/tree/main/cedar-lean-cli) 帮助开发商对其政策进行政策分析.

#### 第4步:更新应用程序代码以呼叫Cedar并授权API访问

应用程序将使用Cedar中间软件来授权反对Cedar政策的每一项请求. 首先,在项目中添加软件包并定义 `CedarInlineAuthorizationEngine` 财务报告和审定财务报表 `ExpressAuthorizationMiddleware`上方可添加此块代码 `app.js` 文件 :

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

const policies = [
    fs.readFileSync(path.join(__dirname, 'policies', 'policy_1.cedar'), 'utf8'),
    fs.readFileSync(path.join(__dirname, 'policies', 'policy_2.cedar'), 'utf8')
];

const cedarAuthorizationEngine = new CedarInlineAuthorizationEngine({
    staticPolicies: policies.join('\n'),
    schema: {
        type: 'jsonString',
        schema: fs.readFileSync(path.join(__dirname, 'v4.cedarschema.json'), 'utf8'),
    }
});

const expressAuthorization = new ExpressAuthorizationMiddleware({
    schema: {
        type: 'jsonString',
        schema: fs.readFileSync(path.join(__dirname, 'v4.cedarschema.json'), 'utf8'),
    },
    authorizationEngine: cedarAuthorizationEngine,
    principalConfiguration: {
        type: 'custom',
        getPrincipalEntity: principalEntityFetcher
    },
    skippedEndpoints: [
        {httpVerb: 'get', path: '/login'},
        {httpVerb: 'get', path: '/api-spec/v3'},
    ],
    logger: {
        debug: s => console.log(s),
        log: s => console.log(s),
    }
});
```

下一步, 在应用程序中添加 Express 授权中间软件 :

```javascript
const app = express();

app.use(express.json());
app.use(verifyToken());   // validate user token
// ... other pre-authz middlewares

app.use(expressAuthorization.middleware);

// ... other middlewares
```

#### 步骤 5: 添加应用程序代码以配置用户

雪松授权者需要用户组和属性来授权请求. 授权中间软件依赖于传递给 `getPrincipalEntity` 在初始配置中生成主实体。 您需要执行此功能以生成用户实体 :

```javascript
async function principalEntityFetcher(req) {
    const user = req.user;   // it's common practice for the authn middleware to store the user info from the decoded token here
    const userGroups = user["groups"].map(userGroupId => ({
        type: 'PetStoreApp::UserGroup',
        id: userGroupId       
    }));
    return {
        uid: {
            type: 'PetStoreApp::User',
            id: user.sub
        },
        attrs: {
            ...user,
        },
        parents: userGroups 
    };
}
```

## 配置选项

### 表达式认证 中间软件

中间软件构建器接受具有以下属性的选项对象:

-   `schema`: Cedar schema配置. 星洲网. 计划是您应用程序中实体和动作的结构.
    -   `type`: Schema 类型(目前为"jsonString","cedar"即将到来)
    -   `schema`: Cedar schema 作为字符串, 格式由 `type`
-   `authorizationEngine`: 应用程序的授权引擎. 目前的选择是:
    -   雪松- @ cedar- policy/ authorization- for- expressionjs (中文(简体) )
    -   Amazon 验证权限( AVP) - @ 校验权限/授权客户端
    -   自定义 - 定义自己的授权引擎
-   `skippedEndpoints`: 组合端点来跳过授权检查. 例如,意在向所有人开放的终点(如:. `/login` 财务报告和审定财务报表 `/signup`)或用更颗粒版的中件保护的端点.
    -   `httpVerb`: 小写中的 HTTP 方法
    -   `path`: 快速路由路径模板
-   `contextConfiguration` (可选) : 在基于锡达的授权请求中传递的上下文对象 .
-   `logger`: 日志配置
    -   `debug`: 除错日志函数  
        **说明** - 调试日志器将记录不安全的信息,例如用户代号,并且绝不应用于生产应用程序.
    -   `log`: 标准日志函数
-   `principalConfiguration`: 用于将认证用户映射到 Cedar 主机的配置 。 这种类型的工会:

```typescript
    | {type: 'identityToken'}
    | {type: 'accessToken'}
    | {
        type: 'custom',
        getPrincipalEntity: (req: Request) => Promise<Entity>,
    };
```

这个 `identityToken` 财务报告和审定财务报表 `access Token` 类型分别用于身份和访问符号。 他们通过标志本身作为本金,应该与 `AuthorizationEngine` 认证和授权。 例如 `AVPAuthorizationEngine` 规定 [核查许可/授权-客户-js](https://github.com/verifiedpermissions/authorization-clients-js) 名为 Amazon 验证权限 API 的软件包 [认证 用托肯语](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)。 。 。 .

这个 `custom` 类型用于任何 `AuthorizationEngine`,并假定您在运行中间软件之前已经进行了认证.

## 完整示例

看看这个 [实例](https://npmcn.com/package/%40cedar-policy/authorization-for-expressjs/examples) 使用此中间软件完整执行受保护的 API 的目录 .

## 从 OpenAPI 规格和样本策略生成计划的工具

这些工具存在不同的软件包,叫做 `@cedar-policy/cedar-authorization` 复发. 关于他们如何工作的详情,请参见该包 [读取我](https://github.com/cedar-policy/cedar-authorization)。 。 。 .

## 警卫

见 [捐款](https://npmcn.com/package/%40cedar-policy/authorization-for-expressjs/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

这个项目根据Apache-2.0许可证获得许可证.

## 出版

向npm的发布是根据这些链接完成的:

-   [https://docs.github.com/en/actions/use-case-和-examples/出版-包装/出版-nodejs-包装](https://docs.github.com/en/actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages)
-   [https://docs.github.com/en/repositories/releasing-projects-on-github/manage-releases-in-a-repository#创建-a-leasing 互联网档案馆的存檔,存档日期2013-12-22](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)

## 常见问题

### @cedar-policy/authorization-for-expressjs 是什么？

授权带有 Cedar 的 expressJS 应用程序的中间软件

### 如何安装 @cedar-policy/authorization-for-expressjs？

在项目目录运行 npm install @cedar-policy/authorization-for-expressjs，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 authorization-for-expressjs，可以用 npx authorization-for-expressjs 直接运行。

### @cedar-policy/authorization-for-expressjs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cedar-policy/authorization-for-expressjs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cedar-policy/authorization-for-expressjs 可以商用吗？

@cedar-policy/authorization-for-expressjs 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cedar-policy/authorization-for-expressjs 的下载量有多少？

根据 npm 官方下载统计，@cedar-policy/authorization-for-expressjs 在 2026/10/10 – 2026/11/08 这 30 天内被下载 10,277 次，日均约 343 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cedar-policy/authorization-for-expressjs 还在维护吗？

最新版本 0\.3\.0 发布于 2026/05/08（6 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/06/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。