AVP CLI Tool

This is a command-line interface (CLI) tool designed to interact with the Amazon Verified Permissions (AVP) service. You can use it to create, manage, and delete policy stores, schemas, and policies.

Big Picture

The Amazon Verified Permissions (AVP) service is a powerful tool for managing permissions across your AWS resources. However, not everyone prefers to interact with it through the AWS console. Some developers prefer to quickly prototype and check something using a command-line interface, which can be faster and more flexible. This tool is designed to meet that need.

This tool is intended for learning and prototyping. It provides a quick and easy way to interact with the AVP service, allowing you to create, manage, and delete policy stores, schemas, and policies. However, it's not intended for production workloads.

To learn more about Cedar and AVP with this tool refer to series of blogposts here.

Setup

1. Clone the repository.
2. Run npm install to install the dependencies.
3. Ensure that you have set up your AWS credentials correctly to use this tool.

Prerequisites

Before you can use this tool, you need to set up your AWS credentials on your local machine. If you're using a MacBook, you can do this by adding the following to your ~/.aws/credentials file:

[default]
aws_access_key_id=YOUR_ACCESS_KEY
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY
region=eu-west-1 // or any other region

For those wishing to use a specific profile:

[personal]
aws_access_key_id=YOUR_ACCESS_KEY
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY
region=eu-west-1 // or any other region

Then, you can use the tool with the specific profile by running:

AWS_PROFILE=personal avp-cli

➜  avp-cli git:(main) ✗ AWS_PROFILE=personal avp-cli
🚀 Welcome to the AVP CLI Tool!
Designed to streamline your interactions with the Amazon Verified Permissions (AVP) service.
🔧 Create, manage, and delete policy stores, schemas, and policies. Plus, deploy and test with predefined scenarios!
⚠️ Ensure your AWS credentials are correctly set up before proceeding.
? What would you like to do? (Use arrow keys)
❯ Test Scenario
  Manual approach
  Use prepared scenarios
  Exit

Usage

The AVP CLI Tool supports all API operations provided by the Amazon Verified Permissions service. Upon launching, it prompts users to select from a comprehensive list of actions, including:

Making authorization decisions (with or without Cognito Identity Token) Using prepared scenarios Testing prepared scenarios Managing policy stores (listing, creating, updating, deleting) Handling schemas (adding, retrieving) Managing policies (creating static or template-linked, updating, retrieving, deleting) And many more...

To initiate the tool:

avp-cli

When you run the tool, it will prompt you to choose an action and then ask for any necessary additional information. Right now AVP does not support naming of the policy stores, so it's autogenerated ID. Soon it should be improved.

Testing with the isAuthorized Action

The most critical aspect of testing the Amazon Verified Permissions (AVP) service is verifying whether specific actions are authorized based on the policies you've set up. The AVP CLI Tool provides a dedicated action for this purpose: isAuthorized.

By using the isAuthorized action, you can submit an authorization request to check against your policy store. This request will evaluate the policies within the store and determine if the action is allowed or denied based on the conditions you've defined.

If you would like to test integration with Cognito you need to use isAuthorizedWithToken.

To perform a test:

• Run the AVP CLI Tool and select the isAuthorized action.
• Provide the necessary details for the authorization request within the .json file (refer to structureAuthorizationRequest.json or to tests scenarios in scenarios directory), such as the principal, action type, resource, and any relevant context.
• The tool will then evaluate the request against the policies in the specified policy store and return a decision: ALLOW or DENY.

This testing mechanism ensures that your policies are functioning as expected, granting permissions where appropriate and restricting access where necessary. It's a powerful way to validate the effectiveness of your policies and troubleshoot any potential issues.

? What would you like to do? Manual approach
? What would you like to do? Make an authorization decision
? Enter the path for json test file scenarios/documentsScenario/allow_test_1.json
Making authorization decision...
┌──────────┬──────────────────────────────┬────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│ Decision │ Determining Policies         │ Errors             │ Policy Store ID              │ Principal                    │ Action                       │ Resource                     │ Context                      │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ ALLOW    │ B6jTYy5txf4MSMc4fgizaS       │                    │ ycFnEx6pY3axp7S8VZrHr        │ DocumentManagementPlatform:: │ DocumentManagementPlatform:: │ DocumentManagementPlatform:: │ {}                           │
│          │                              │                    │                              │ User::Daniel                 │ Action::View                 │ Document::Payslip            │                              │
└──────────┴──────────────────────────────┴────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘

Using the batchIsAuthorized Action

The batchIsAuthorized action in the AVP CLI Tool allows you to make authorization decisions for multiple requests in a single operation. This is particularly useful when you need to evaluate a batch of authorization requests simultaneously, improving efficiency and reducing the number of individual calls to the Amazon Verified Permissions service.

How to use batchIsAuthorized:

• Prepare the JSON File: Create a JSON file with the structure defined in structureBatchAuthorizationRequest.json located in the root directory of the project. This file should contain common entities list, and an array of authorization requests, each specifying the principal, action, resource, and context.
• Limitation: The batchIsAuthorized action can process up to 30 requests at a time. Ensure that your JSON file does not contain more than 30 requests to avoid errors.
• Launch the AVP CLI Tool and select the batchIsAuthorized action (from the manual approach option).
• When prompted, enter the path to your JSON file containing the batch authorization requests.
• The tool will process each request in the batch and return the authorization decisions (ALLOW or DENY) for each one. The results will be displayed in a formatted table, showing the decision, determining policies, and any errors for each request.

Example Usage:

? What would you like to do? Manual approach
? What would you like to do? Make a batch authorization decision
? Enter the path for the JSON test file structureBatchAuthorizationRequest.json
Making batch authorization decisions...
┌──────────┬──────────────────────────────┬────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│ Decision │ Determining Policies         │ Errors             │ Policy Store ID              │ Principal                    │ Action                       │ Resource                     │ Context                      │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ ALLOW    │ [Policy IDs]                 │                    │ [Policy Store ID]            │ [Principal]                  │ [Action]                     │ [Resource]                   │ [Context]                    │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ DENY     │ [Policy IDs]                 │                    │ [Policy Store ID]            │ [Principal]                  │ [Action]                     │ [Resource]                   │ [Context]                    │
└──────────┴──────────────────────────────┴────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘

{ "policyStoreId": "Nc3gsTLjat4WHyNyfT1KYX", "principalEntityType": "DocumentManagementPlatform::User", "configuration": { "cognitoUserPoolConfiguration": { "userPoolArn": "arn:aws:cognito-idp:eu-west-1:862403288926:userpool/eu-west-1_sXVC4jUDf", "clientIds": [ "5b33v2gf0cr1c4n6qj04rajjhf" ] } }, "clientToken": "7c823fb3-c206-4ff1-a069-427b23659326" }

Using the batchIsAuthorizedWithToken Action

The batchIsAuthorizedWithToken action enables batch processing of authorization decisions using tokens provided by an external identity source, such as Amazon Cognito. This function is helpful when you need to authorize multiple actions in one go, based on the authenticated principal's identity token or access token.

How to use batchIsAuthorizedWithToken:

• Create a JSON file following the structure specified in structureBatchAuthorizationWithTokenRequest.json. This file should contain your policyStoreId, an optional identityToken or accessToken, and a list of requests that you wish to authorize in a batch.
• Within the JSON file, define the entities (resources and/or principals) involved in the authorization, as well as the requests array detailing action types, resource identifiers, and any contextual information required for the authorization checks.
• With the JSON file ready, invoke the batchIsAuthorizedWithToken action from the AVP CLI tool by selecting the manual approach.
• Limitation: The batchIsAuthorizedWithToken action can process up to 30 requests at a time. Ensure that your JSON file does not contain more than 30 requests to avoid errors.

Run the following commands in your console to initialize the CLI tool and execute the batch authorization with a token:

? What would you like to do? Manual approach
? What would you like to do? Make a batch authorization decision with Cognito Identity Token
? Enter the path for the batch authorization with token json test file (e.g., structureBatchAuthorizationWithTokenRequest.json)
Making batch authorization decisions...
┌──────────┬──────────────────────────────┬────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│ Decision │ Determining Policies         │ Errors             │ Policy Store ID              │ Principal                    │ Action                       │ Resource                     │ Context                      │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ ALLOW    │ [Policy IDs]                 │                    │ [Policy Store ID]            │ [Principal]                  │ [Action]                     │ [Resource]                   │ [Context]                    │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ DENY     │ [Policy IDs]                 │                    │ [Policy Store ID]            │ [Principal]                  │ [Action]                     │ [Resource]                   │ [Context]                    │
└──────────┴──────────────────────────────┴────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘

Scenarios

Scenarios are predefined sets of policies (policy store, schema, and policies) that you can run to interact with the AVP service. Each scenario is defined in a JSON file and includes a validation mode, a schema, and a set of policies.

To use a scenario, select "Use prepared scenarios" from the main menu, then select the scenario you want to use. The CLI will run all the operations defined in the scenario.

Upon the successful execution of each scenario, the AVP CLI Tool will display a confirmation message indicating the completion of the scenario setup. Alongside this, the tool will provide a direct reference to a test file tailored for that specific scenario. This test file contains predefined sets of inputs and expected outcomes, allowing users to comprehensively test the policies and configurations established by the scenario. By utilizing this test file, users can ensure that the scenario's policies function as intended, offering a seamless way to validate and troubleshoot the configurations.

➜  avp-cli git:(main) ✗ AWS_PROFILE=personal avp-cli
🚀 Welcome to the AVP CLI Tool!
Designed to streamline your interactions with the Amazon Verified Permissions (AVP) service.
🔧 Create, manage, and delete policy stores, schemas, and policies. Plus, deploy and test with predefined scenarios!
⚠️ Ensure your AWS credentials are correctly set up before proceeding.
? What would you like to do? Use prepared scenarios
? Choose a scenario Documents Scenario
Starting creating scenario: Documents Scenario
description: This is a basic scenario with a document management platform schema and two policies.
Policy store created with ID: 6C5VTfSPaPxrqaaUf29xgB
Schema put successfully for policy store ID: 6C5VTfSPaPxrqaaUf29xgB
Static policy created with ID: 3icFETQBeAP4gVuRpmVbaQ
Static policy created with ID: T7GR1rDEwaEc8ZkC4R9974
┌────────────────────────────────────────┬────────────────────────────────────────┬────────────────────────────────────────┐
│ Policy ID                              │ Policy Store ID                        │ Created Date                           │
├────────────────────────────────────────┼────────────────────────────────────────┼────────────────────────────────────────┤
│ 3icFETQBeAP4gVuRpmVbaQ                 │ 6C5VTfSPaPxrqaaUf29xgB                 │ 2023-08-15 11:34                       │
├────────────────────────────────────────┼────────────────────────────────────────┼────────────────────────────────────────┤
│ T7GR1rDEwaEc8ZkC4R9974                 │ 6C5VTfSPaPxrqaaUf29xgB                 │ 2023-08-15 11:34                       │
└────────────────────────────────────────┴────────────────────────────────────────┴────────────────────────────────────────┘
Generating of the documentsScenario is finished. Open the AWS console to play around with that.

Consider testing it with our prepared test scenarios:
 Use below path as argument to `IsAuthorized` from the manual approach option of the CLI:
- ./scenarios/documentsScenario/allow_test_1.json (User Daniel is allowed the ability to view (action) the Payslip (resource)) allow
- ./scenarios/documentsScenario/deny_test_1.json (User xyz is denied the ability to view (action) the Payslip (resource)) forbid
- ./scenarios/documentsScenario/deny_test_2.json (User Daniel is denied the ability to edit (action) the Payslip (resource)) forbid

Added scenarios

| Scenario Name | Description | | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Documents Scenario | This is a basic scenario with a document management platform schema and two policies. | | Ecommerce with Context usage Scenario | This scenario demonstrates the use of context in AVP. It allows customers to view products only when they are in the US region. | | Ecommerce with Group usage Scenario | This scenario demonstrates the use of Groups in Amazon Verified Permissions. It allows customers who belong to the VIP group to preorder products. | | Ecommerce with Policy Template usage Scenario | This scenario demonstrates the use of policy templates and template-linked policies in Amazon Verified Permissions. It allows sellers to list their own products. | | Ecommerce with Cognito Integration usage Scenario | This scenario demonstrates the use of Cognito integration in Amazon Verified Permissions. It allows sellers to discount if they have agreed discount privilege. Refer to this blogpost for setup. | | Ecommerce with Hierarchy and ABAC Scenario | This scenario demonstrates the use of Hierarchy and ABAC (with Entities) in Amazon Verified Permissions. It allows sellers to sell car if department matches the car's department. | | Ecommerce with Batch Authorization Scenario | This scenario demonstrates the use of Batch Authorization in Amazon Verified Permissions. | | Ecommerce with Cognito Groups Scenario | This scenario demonstrates the use of Cognito Groups in Amazon Verified Permissions. There is CF for Cognito to be reused. Refer to this blogpost. |

Note

While AWS provides sample scenarios, they are not included here. However, during policy store creation, you can easily select a "Sample policy store" tailored for your project.

Scenario Structure

A scenario is defined in a JSON file with the following structure:

{
  "validationMode": "STRICT",
  "policyStoreDescription": "Policy store for the Context Scenario, created via avp-cli tool",
  "name": "Ecommerce with Context usage Scenario",
  "description": "This scenario demonstrates the use of context in Amazon Verified Permissions. It allows customers to view products only when they are in the US region.",
  "schemaPath": "./scenarios/ecommerceContextScenario/schema.json",
  "policies": [
    {
      "path": "./scenarios/ecommerceContextScenario/allow_policy.cedar",
      "description": "Allow viewing of products for customers in the US region"
    }
  ],
  "tests": [
    {
      "path": "./scenarios/ecommerceContextScenario/allow_test_1.json",
      "description": "User Bob is allowed the ability to view (action) the basketball (resource), with region us",
      "type": "allow"
    },
    {
      "path": "./scenarios/ecommerceContextScenario/deny_test_1.json",
      "description": "User Bob is denied the ability to view (action) the basketball (resource), with region eu",
      "type": "forbid"
    },
    {
      "path": "./scenarios/ecommerceContextScenario/deny_test_2.json",
      "description": "User Bob is denied the ability to view (action) the basketball (resource), with no region specified",
      "type": "forbid"
    }
  ]
}

Testing Scenarios

I've enhanced the AVP CLI Tool with the addition of batch authorization tests, allowing to efficiently test multiple authorization scenarios in a single operation. This feature is particularly useful for scenarios where you need to check multiple resources or principals in one go. As with the standard test scenarios, you only need to replace the policy store id to get started.

Standard Test Scenario

The "Test Scenario" feature in the AVP CLI Tool offers a streamlined way to test individual authorization scenarios. The CLI dynamically loads available test scenarios, allowing you to select and execute them with ease. This approach simplifies the testing process, making it faster and more user-friendly.

? What would you like to do? Test Scenario
? Choose a scenario documentsScenario
? Choose a test User Daniel is allowed the ability to view (action) the Payslip (resource) (allow)
Making authorization decision...
┌──────────┬──────────────────────────────┬────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│ Decision │ Determining Policies         │ Errors             │ Policy Store ID              │ Principal                    │ Action                       │ Resource                     │ Context                      │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ ALLOW    │ UeLnsJJiAjYxZx9xy3yNgE       │                    │ Yc72495SiKGbsA5N1wa5Ng       │ DocumentManagementPlatform:: │ DocumentManagementPlatform:: │ DocumentManagementPlatform:: │ {}                           │
│          │                              │                    │                              │ User::Daniel                 │ Action::View                 │ Document::Payslip            │                              │
└──────────┴──────────────────────────────┴────────────────────┴──────────────────────────────

Batch Authorization Scenario

The new "Test Batch Authorization Scenario" feature allows you to test multiple authorization decisions simultaneously. This is particularly useful in scenarios, where a single user action might involve multiple resources or actions.

? What would you like to do? Test Batch Authorization Scenario
? Choose a scenario ecommerceBatchScenario
? Choose a test Checking multiple resources, to check which orders can admin edit.
./scenarios/ecommerceBatchScenario/multiple_resource_batch_test.json
Making batch authorization decision...
┌──────────┬──────────────────────────────┬────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│ Decision │ Determining Policies │ Errors │ Policy Store ID │ Principal │ Action │ Resource │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ ALLOW │ RqTig3UirX1KxPCesHDjjj │ │ PCBQvq25n9296Cq4w76CJu │ EcommerceStore::User::Daniel │ EcommerceStore::Action::Edit │ EcommerceStore::Order::12345 │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ DENY │ │ │ PCBQvq25n9296Cq4w76CJu │ EcommerceStore::User::Daniel │ EcommerceStore::Action::Edit │ EcommerceStore::Order::67890 │
├──────────┼──────────────────────────────┼────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ DENY │ │ │ PCBQvq25n9296Cq4w76CJu │ EcommerceStore::User::Daniel │ EcommerceStore::Action::Edit │ EcommerceStore::Order::44444 │
└──────────┴──────────────────────────────┴────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘

Roles and Permissions

This tool requires certain permissions to interact with the Amazon Verified Permissions service. It is recommended to use this tool on an AWS sandbox account where admin access is granted. Always follow the principle of least privilege and only grant the necessary permissions for the tasks you need to perform.

Next Steps

If there will be new functionalities from Cedar and AVP, I will adjust AVP CLI to support it, as well will be more scenarios with those new features. Stay tuned and go build!