快捷JS 的 Cedar 授权
一个中间软件包,可以让Cedar基于Express.js应用程序的授权. 这个软件包使得在与您 Express.js 应用程序的认证系统进行无缝整合的同时,使用 Cedar 政策来实施精细的授权控制变得容易.
特征
- * Express.js基于锡达的授权中间软件
- 使用Cedar政策的精细出入控制
- 与OIDC/JWT认证的无缝集成
- 最佳授权检查
- QQ 自定义主要实体映射
- 终点排除支持
- 配置式记录
安装
npm install @cedar-policy/authorization-for-expressjs
快速启动
先决条件
在实施"快递"集成之前,确保您有:
建立一体化
让我们通过如何保护您的应用程序 API 使用 Cedar 与新包为快递.
步骤1: 添加 Cedar 授权中件包
Cedar Authority Middleware 软件包将被用于生成Cedar schema,创建样本授权政策,并在您的应用程序中执行授权.
npm i --save @cedar-policy/authorization-for-expressjs
第2步:从您的 API 生成 Cedar 计划
锡达 计划 定义应用程序的授权模式,包括应用程序中的实体类型和允许用户采取的行动。 我们建议界定 命名空间 为了你的计划。 在此示例中, 我们使用您的命名空间 。 当您运行此应用程序时, 您的政策会被验证 .
这个 authorization-for-expressjs 软件包可以分析 OpenAPI 规格 并生成 Cedar 计划。 具体来说,路径对象在您的规格中是需要的.
如果您没有 OpenAPI 规格, 您可以遵守快速指令 特快- openapi 生成器 生成 OpenAPI 规格的软件包.
通过运行,替换来生成 Cedar 计划 openapi.json 和您的计划的文件 YourNamespace 使用我们选择的命名空间:
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 政策样本 :
npx @cedar-policy/authorization-for-expressjs generate-policies --schema v4.cedarschema.json
这将产生/政策目录中的抽样政策。 您可以根据您的使用案例定制这些政策 。 例如:
// 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 帮助开发商对其政策进行政策分析.
第4步:更新应用程序代码以呼叫Cedar并授权API访问
应用程序将使用Cedar中间软件来授权反对Cedar政策的每一项请求. 首先,在项目中添加软件包并定义 CedarInlineAuthorizationEngine 财务报告和审定财务报表 ExpressAuthorizationMiddleware上方可添加此块代码 app.js 文件 :
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 授权中间软件 :
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 在初始配置中生成主实体。 您需要执行此功能以生成用户实体 :
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 主机的配置 。 这种类型的工会:
| {type: 'identityToken'}
| {type: 'accessToken'}
| {
type: 'custom',
getPrincipalEntity: (req: Request) => Promise<Entity>,
};
这个 identityToken 财务报告和审定财务报表 access Token 类型分别用于身份和访问符号。 他们通过标志本身作为本金,应该与 AuthorizationEngine 认证和授权。 例如 AVPAuthorizationEngine 规定 核查许可/授权-客户-js 名为 Amazon 验证权限 API 的软件包 认证 用托肯语。 。 。 .
这个 custom 类型用于任何 AuthorizationEngine,并假定您在运行中间软件之前已经进行了认证.
完整示例
看看这个 实例 使用此中间软件完整执行受保护的 API 的目录 .
从 OpenAPI 规格和样本策略生成计划的工具
这些工具存在不同的软件包,叫做 @cedar-policy/cedar-authorization 复发. 关于他们如何工作的详情,请参见该包 读取我。 。 。 .
警卫
见 捐款 更多信息.
许可证
这个项目根据Apache-2.0许可证获得许可证.
出版
向npm的发布是根据这些链接完成的: