Amazon Verified Permissions (avp) 本地代理

此crate是实验性的。

avp-local-agent提供Amazon Verified Permissions策略和实体提供者。这些提供者用于构建simple::Authorizer。

avp-local-agent将在未来的版本中扩展其功能。

有关cedar本地代理的更多信息，请参阅cedar-local-agent。

有关Cedar语言/项目的更多信息，请参阅cedarpolicy.com。

有关Amazon Verified Permissions的更多信息，请参阅verified-permissions。

使用方法

Amazon Verified Permissions代理可以通过依赖avp-local-agentcrate在您的应用程序中使用。

在您的Cargo.toml文件中将avp-local-agent添加为依赖项。例如

[dependencies]
avp-local-agent = "2"

注意：指定区域和可选地构建凭证提供者所需的AWS依赖项。有关配置AWS凭证的更多详细信息，请参阅下面的管理AWS凭证。

管理AWS凭证

avp-local-agent通过AWS SDK客户端调用Amazon Verified Permissions API来获取远程策略数据并刷新本地缓存。对于代理的本地开发，推荐的做法是在将测试调用的机器上本地存储AWS SDK客户端的凭证。例如，

将AWS凭证放置在~/.aws/credentials

[default]
aws_access_key_id=<aws access key>
aws_secret_access_key=<aws secret access key>

一旦凭证存储在本地~/.aws/credentials中，请参阅下面的快速入门了解这一切是如何结合在一起的。简而言之，以下是凭证用于从AVP刷新远程策略的方式：

使用辅助程序构建Amazon Verified Permissions客户端

let client = verified_permissions_default_credentials(Region::new("us-east-1")).await;

此辅助工具将通过创建一个 SharedCredentialsProvider 来从 ~/.aws/credentials 文件中读取 AWS sigV4 凭证。请注意，SharedCredentialsProvider 是通过一个 DefaultCredentialsChain 实例化的。

let creds = SharedCredentialsProvider::new(
    DefaultCredentialsChain::builder()
        .region(region.clone())
        .build()
    .await,
);

总体而言，凭据提供者可以用于在本地各种位置搜索您的 AWS 凭证，并按照以下顺序解决

1. 环境变量：EnvironmentVariableCredentialsProvider
2. 共享配置 (~/.aws/config, ~/.aws/credentials)：SharedConfigCredentialsProvider
3. Web 身份令牌
4. ECS（任务 IAM 角色）和通用 HTTP 凭证：ecs
5. EC2 IMDSv2

如果 AWS 凭证存储在环境变量中，例如代理部署并运行在 EC2 实例上，请使用 EnvironmentVariableCredentialsProvider 而不是 SharedConfigCredentialsProvider。

let creds = SharedCredentialsProvider::new( 
    EnvironmentVariableCredentialsProvider::new()
); 
let client = verified_permissions_with_credentials(Region::new("us-east-1"), creds).await;

可以传递任何凭据提供者，或者您也可以创建自己的凭据提供者。

有关指定凭据的更多信息，请参阅以下 AWS 文档

Rust SDK - 指定您的凭证和默认区域

推荐的 IAM 策略

出于安全目的，我们建议您为本地代理创建一个具有最低权限 IAM 策略的用户，以便连接。以下是一个示例

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AVPLocalAgentPolicy",
            "Effect": "Allow",
                "Action": [
                    "verifiedpermissions:ListPolicies",
                    "verifiedpermissions:ListPolicyTemplates",
                    "verifiedpermissions:GetPolicyTemplate",
                    "verifiedpermissions:GetPolicy",
                    "verifiedpermissions:GetSchema"
                ],
            "Resource": "arn:aws:verifiedpermissions::<account_id>:policy-store/<policy store id>"
        }
    ]
}

有关如何创建假设 IAM 策略的说明，请参阅 此处

快速入门

构建一个使用现有 Amazon Verified Permissions 策略存储 的授权器。

构建 Amazon Verified Permissions 客户端

let client = verified_permissions_default_credentials(Region::new("us-east-1")).await;

构建策略集提供者

let policy_set_provider = PolicySetProvider::from_client("policy_store_id".to_string(), client.clone())
    .unwrap();

构建实体提供者（使用可选的策略存储模式生成操作实体）

let entity_provider =
    EntityProvider::from_client("policy_store_id".to_string(), client.clone())
    .unwrap();

构建授权器

let authorizer: Authorizer<PolicySetProvider, EntityProvider> = Authorizer::new(
    AuthorizerConfigBuilder::default()
        .entity_provider(Arc::new(entity_provider))
        .policy_set_provider(Arc::new(policy_set_provider))
        .build()
        .unwrap()
);

评估决策

assert_eq!(
    authorizer
        .is_authorized(&Request::new(
            Some(format!("User::\"Cedar\"").parse().unwrap()),
            Some(format!("Action::\"read\"").parse().unwrap()),
            Some(format!("Box::\"3\"").parse().unwrap()),
            Context::empty(),
        ), &Entities::empty())
        .await
        .unwrap()
        .decision(),
    Decision::Deny
);

异步更新策略和实体数据

请参阅 cedar-local-agent，应用相同的模式。

日志记录

请参阅 cedar-local-agent，应用相同的模式。

运行集成测试

集成测试需要在默认凭据提供者链上有有效的 AWS 凭证。有关此链以及如何正确配置您的凭据以运行集成测试的说明，请参阅 文档。

设置凭据后运行

cargo test --features integration-tests

注意：集成测试将在指定的账户和区域（例如 us-east-1）内创建 Amazon Verified Permissions 资源。

一般安全说明

以下是一些安全关注点的概述，这些关注点在使用 avp-local-agent 启用存储在 Amazon Verified Permissions 策略存储中的 Cedar 策略的本地评估时需要考虑。

可信计算环境

avp-local-agent 只是一个库，客户可以将其包装在 HTTP 服务器中，并部署到主机集群中。因此，用户需要采取所有必要的预防措施，以确保满足超出 avp-local-agent 能够实施的任何安全关注点。这包括

1. 确保不将 AWS 凭证存储在任何包装代理的源代码中。请参阅 管理 AWS 凭证
2. 磁盘上 OCSF 日志的文件系统权限遵循最小权限原则，请参阅 OCSF 日志目录权限
3. avp-local-agent 的配置是安全的，请参阅 安全代理配置

OCSF 日志目录权限

本包提供的本地授权器需要访问其写入OCFS日志的目录的读和写权限。

假设我们有以下目录结构

authz-agent/
  |- authz_daemon (executable)

ocsf-log-dir/
  |- authorization.log.2023-11-15-21-02
  ...

现在假设你有一个名为authz-daemon的OS用户来执行authz_daemon，该用户应属于名为"log-reader"的组。

并让authz-daemon用户成为ocsf-log-dir文件夹的所有者

$ chown -R authz-daemon:log-reader ocsf-log-dir

现在我们将使ocsf-log-dir对所有者可读可写，但对其他人不可写。我们允许log-reader组中的任何用户读取文件夹的内容，但不能写入。

$ chmod u=wrx,g=rx,o= ocsf-log-dir

注意：我们需要允许执行权限才能访问目录中的文件。

任何需要访问日志的代理，例如AWS Cloudwatch Agent，都应该作为日志读取组中的用户运行，以便它们具有适当的访问权限（有关如何配置Cloudwatch Agent以作为特定用户运行的信息，请参阅文档）。

安全代理配置

代理用户应确保他们遵循README中管理AWS凭证部分的说明，以及使用尽可能少的权限的IAM角色。我们在文档的推荐IAM策略中提供了一个最少的权限IAM角色示例。

如cedar-local-agent文档中所述，当设置从AVP异步更新策略集时，我们建议用户使用在cedar-local-agent crate中可用的现有信号器

1. clock_ticker_task
2. file_inspector_task

特别是，如cedar-local-agent中所述，用户应有一个至少15秒的RefreshRate，因为更长时间可能会导致AVP过载并导致节流行为。例如

let (clock_ticker_signal_thread, receiver) = clock_ticker_task(RefreshRate::FifteenSeconds);

许可协议

本项目采用Apache-2.0许可协议。