Authorization and Amazon Verified Permissions - A New Way to Manage Permissions Part X: AVP-CLI
Tags: aws, avp, authorization, awscommunitybuilders
Published: 2023-08-15 13:09:15

In previous [article](https://dev.to/aws-builders/authorization-and-amazon-verified-permissions-a-new-way-to-manage-permissions-part-ix-hierarchies-and-abac-8gm), we delved deep into the world of hierarchies and ABAC (Attribute-Based Access Control) within the AWS Verified Permissions (AVP). We've learned how to deal with hierarchy and ABAC with practical example.

Today, we shift our focus to a tool that aims to make your interactions with AVP smoother and more intuitive: the open-source [avp-cli](https://www.npmjs.com/package/avp-cli).

## The Big Picture behind avp-cli
AWS Verified Permissions (AVP) is a relatively new service. While AWS provides comprehensive documentation, workshops, and examples, there was a noticeable gap in community-driven resources. For developers like me, eager to dive deep and experiment with AVP, the initial journey was filled with manual setups via the AWS console. This process was not only repetitive but also prone to errors, especially when dealing with intricate components like schemas and policy definitions.

Imagine the hassle of setting up multiple policy stores, schemas, and policies, only to realize you made a small mistake and had to start over. Or the challenge of managing and deleting resources, especially when you find yourself with 85 policy stores cluttering your AWS account!

This is where the idea of avp-cli was born. I envisioned a tool that would simplify these interactions, making the process of learning and experimenting with AVP more efficient and enjoyable. The initial versions of the CLI focused on basic API operations, such as creating and deleting policy stores, schemas, and policies.

However, as I delved deeper into AVP, I had an "aha" moment. Why not create predefined scenarios? These scenarios would encapsulate a policy store, schema, and set of policies, providing a ready-to-use example for developers to play with, experiment, and modify. This not only reduced the setup time but also provided a tangible context for understanding how different AVP components interacted, as well as differences between Cedar and AVP format.

The most recent addition to avp-cli has been the test scenarios. These are designed to validate that the policies and configurations set up through the scenarios work as expected. 

## What is avp-cli?
The avp-cli is a command-line interface tool designed to streamline your interactions with the AWS Verified Permissions (AVP) service. Its primary goal is to enhance the learning and prototyping experience for developers diving into AVP. Whether you're a beginner trying to grasp the basics or an advanced user looking to experiment with complex policies, avp-cli offers a set of functionalities tailored to your needs.

```bash
🚀 Welcome to the AVP CLI Tool!
Designed to streamline your interactions with the AWS 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 
```

However, it's essential to note that while avp-cli is a powerful tool for learning and experimentation, it is not intended for production workloads. Always ensure that tools and configurations used in production environments are thoroughly vetted and adhere to best practices.

## Features of avp-cli
**API operations:** avp-cli supports all API operations provided by the AWS Verified Permissions service. This includes:


- Creating, listing, updating, and deleting policy stores.
- Adding and retrieving schemas.
- Creating, updating, retrieving, and deleting policies (both static and template-linked).
- Making authorization decisions (with or without Cognito Identity Token).
- Identity source and more...

```bash
? What would you like to do? Manual approach
? What would you like to do? (Use arrow keys)
❯ Make an authorization decision 
  Make an authorization decision with Cognito Identity Token 
  Add Policy Template 
  Add Schema to a Policy Store 
  Add Static Policy 
  Add Template Policy 
  Create a Policy Store 
(Move up and down to reveal more choices)
```

**Scenarios:** One of the standout features of avp-cli is the predefined scenarios. These scenarios encapsulate a policy store, schema, and a set of policies, providing developers with ready-to-use examples. Each scenario is designed to showcase a specific feature or use-case of AVP, making it easier to understand its practical applications.

| Scenario Name                                                                                                                               | Description                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Documents Scenario](https://github.com/Pigius/avp-cli/blob/main/scenarios/documentsScenario/documentsScenario.json)                                                                    | This is a basic scenario with a document management platform schema and two policies.                                                                                                                                                                                                                                                              |
| [Ecommerce with Context usage Scenario](https://github.com/Pigius/avp-cli/blob/main/scenarios/ecommerceContextScenario/ecommerceContextScenario.json)                                   | 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](https://github.com/Pigius/avp-cli/blob/main/scenarios/ecommerceGroupScenario/ecommerceGroupScenario.json)                                         | This scenario demonstrates the use of Groups in AWS Verified Permissions. It allows customers who belong to the VIP group to preorder products.                                                                                                                                                                                                    |
| [Ecommerce with Policy Template usage Scenario](https://github.com/Pigius/avp-cli/blob/main/scenarios/ecommercePolicyTemplateScenario/ecommercePolicyTemplateScenario.json)             | This scenario demonstrates the use of policy templates and template-linked policies in AWS Verified Permissions. It allows sellers to list their own products.                                                                                                                                                                                     |
| [Ecommerce with Cognito Integration usage Scenario](https://github.com/Pigius/avp-cli/blob/main/scenarios/ecommerceCognitoIntegrationScenario/ecommerceCognitoIntegrationScenario.json) | This scenario demonstrates the use of Cognito integration in AWS Verified Permissions. It allows sellers to discount if they have agreed discount privilege. Refer to this [blogpost](https://dev.to/aws-builders/authorization-and-amazon-verified-permissions-a-new-way-to-manage-permissions-part-viii-integration-with-cognito-pgb) for setup. |
| [Ecommerce with Hierarchy and ABAC Scenario](https://github.com/Pigius/avp-cli/blob/main/scenarios/ecommerceHierarchyAndAbacScenario/ecommerceCognitoIntegrationScenario.json)          | This scenario demonstrates the use of Hierarchy and ABAC (with Entities) in AWS Verified Permissions. It allows sellers to sell car if department matches the car's department.        

Usage:

```bash
⚠️ 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: 3rJVM5629fGKxxcuPg87es
Schema put successfully for policy store ID: 3rJVM5629fGKxxcuPg87es
Static policy created with ID: 5FcwTty3sAvgJPQGp7rcji
Static policy created with ID: XqJb31ZJ9E2VBLzFxTY7Y2
┌────────────────────────────────────────┬────────────────────────────────────────┬────────────────────────────────────────┐
│ Policy ID                              │ Policy Store ID                        │ Created Date                           │
├────────────────────────────────────────┼────────────────────────────────────────┼────────────────────────────────────────┤
│ 5FcwTty3sAvgJPQGp7rcji                 │ 3rJVM5629fGKxxcuPg87es                 │ 2023-08-15 14:52                       │
├────────────────────────────────────────┼────────────────────────────────────────┼────────────────────────────────────────┤
│ XqJb31ZJ9E2VBLzFxTY7Y2                 │ 3rJVM5629fGKxxcuPg87es                 │ 2023-08-15 14:52                       │
└────────────────────────────────────────┴────────────────────────────────────────┴────────────────────────────────────────┘
Generating of the documentsScenario is finished. Open the AWS console to play around with that.

Consider testing it with our prepared test scenarios:
Either use `Test Scenario` in main CLI to select the specific test scenario, or use below path as argument to `IsAuthorized` from the manual approach option of the CLI:
 Remember to update the policy-store-id within files.
- ./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
```

**Test Scenarios:** To complement the predefined scenarios, avp-cli also offers test scenarios. These are predefined sets of inputs and expected outcomes that allow users to test the policies and configurations set up by the scenarios. It's a seamless way to validate and troubleshoot configurations, ensuring they function as intended.

```bash
What would you like to do? Test Scenario
? Choose a scenario documentsScenario
? Choose a test (Use arrow keys)
❯ User Daniel is allowed the ability to view (action) the Payslip (resource) (allow) 
  User xyz is denied the ability to view (action) the Payslip (resource) (forbid) 
  User Daniel is denied the ability to edit (action) the Payslip (resource) (forbid) 
```

Example:

```
? 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    │ 5FcwTty3sAvgJPQGp7rcji       │                    │ 3rJVM5629fGKxxcuPg87es       │ DocumentManagementPlatform:: │ DocumentManagementPlatform:: │ DocumentManagementPlatform:: │ {}                           │
│          │                              │                    │                              │ User::Daniel                 │ Action::View                 │ Document::Payslip            │                              │
└──────────┴──────────────────────────────┴────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘
? What would you like to do? (Use arrow keys)
```

## Dive in and experiment
I encourage you to play around with avp-cli. Whether you're setting up a new policy store, experimenting with a scenario, or running a test, the tool is designed to make your AVP journey smoother and more insightful.

## Cedar Policy Language Slack
A significant portion of the success and functionality of avp-cli can be attributed to the invaluable support and guidance I received from the teams behind the Cedar Policy Language and AWS Verified Permissions (AVP) on the [Cedar Policy Language Slack](https://communityinviter.com/apps/cedar-policy/cedar-policy-language). I'd like to thank you all individuals at AWS who took the time to address my queries, clarify my doubts, and provide insights that were instrumental in shaping the tool.

## Looking Ahead
As the AWS Verified Permissions service and Cedar continue to evolve, so will avp-cli. I'm particularly excited about the upcoming `is` operator in Cedar and the potential to name policy-stores in AVP (which now is autogenrated string). Once these features are available, you can expect `avp-cli` to incorporate them, ensuring the tool remains up-to-date and continues to serve the AVP community effectively.

## Next steps

Feel free to read next [article](https://dev.to/aws-builders/authorization-and-amazon-verified-permissions-a-new-way-to-manage-permissions-part-xi-batch-authorization-mj8) from the series, about batch authorization.