permitio/cedar-agent

Cedar-agent is the easiest way to deploy and run Cedar

Cedar Agent

What is Cedar-Agent?

Cedar-Agent is an HTTP server designed to efficiently manage a policy store and a data store. It provides a seamless integration with Cedar, a language for defining permissions as policies.
With Cedar-Agent, you can easily control and monitor access to your application's resources by leveraging Cedar policies. If you are not familiar with Cedar, we encourage you to visit the Cedar website and playground to learn more about it.

Learn more reading these blog posts:

• Policy as Code: OPA's Rego vs. AWS Cedar
• Open-Sourcing AWS Cedar is a Gamechanger for IAM

Policy Store Management

Cedar-Agent includes a store that allows you to create, retrieve, update, and delete policies. These policies define who should have access to what resources within your application. The policy store provides a centralized and flexible way to manage permissions, enabling fine-grained control over user access.
Featured Policy Stores :

• In-Memory
• Redis

Data Store Management

In addition to the policy store, Cedar-Agent also provides an in-memory data store. This data store allows you to store and manage your application's data efficiently. By integrating the data store with Cedar-Agent, you can perform authorized checks on the stored data based on incoming HTTP requests.
Featured Data Stores :

• In-Memory
• Redis

Schema Store Management

Cedar-Agent support storing custom schemas, which hold the shape of your data types and actions. Utilising the schema store enables you to create a strict definition of all the objects used by your application. Cedar-Agent will validate all your policies and data against this schema. Featured Polict Stores :

• In-Memory
• Redis

Authorization Checks

One of the key features of Cedar-Agent is its ability to perform authorization checks on stored policies and data.
By evaluating the Cedar policies, Cedar-Agent ensures that each user's access is restricted to the resources they are permitted to access.
Authorization checks are performed based on the incoming HTTP requests, providing an easy-to-use robust and secure mechanism for controlling access to your application.

Cedar-Agent offers a comprehensive solution for managing policies, data, and authorization checks within your application. With its seamless integration with Cedar and its robust HTTP server capabilities, Cedar-Agent empowers you to enforce fine-grained access control and protect your resources effectively.

How to Use

To use Cedar-Agent, follow the steps below:

Prerequisites

Before proceeding, ensure that you have Rust and Cargo installed on your system. If you don't have them installed, you can visit the official Rust installation page and follow the instructions specific to your operating system.

Clone the Repository

Start by cloning the Cedar-Agent repository to your local machine:

git clone https://github.com/permitio/cedar-agent.git
cd cedar-agent

Build

To build Cedar-Agent, use the following command:

cargo build

Configuration

Cedar Agent configuration is available using environment variables and command line arguments.

• The port on which the Cedar Agent will listen for incoming HTTP requests. Defaults to 8180.
  CEDAR_AGENT_PORT environment variable.
  --port, -p command line argument.
• Authentication token to enforce using the Authorization header. Defaults to None.
  CEDAR_AGENT_AUTHENTICATION environment variable.
  --authentication, -a command line argument.
• The address of the HTTP server. Defaults to 127.0.0.1.
  CEDAR_AGENT_ADDR environment variable.
  --addr command line argument.
• The log level to filter logs. Defaults to info.
  CEDAR_AGENT_LOG_LEVEL environment variable.
  --log-level, -l command line argument.
• Load schema from json file. Defaults to None.
  CEDAR_AGENT_SCHEMA environment variable. --schema, -s command line argument.
• Load data from json file. Defaults to None.
  CEDAR_AGENT_DATA environment variable. --data, -d command line argument.
• Load policies from json file. Defaults to None. CEDAR_AGENT_POLICIES environment variable. --policies command line argument.

command line arguments take precedence over environment variables when configuring the Cedar Agent

Run

There are several ways to run the Cedar Agent

Run with cargo

To run Cedar-Agent, use the following command:

cargo run

to add any arguments to the command append them after --, for example:

cargo run -- --port 8080

Run the binary

To run the binary, make sure you've done the build step, and run this command:

./target/debug/cedar-agent

To check the arguments you can pass to the binary, run:

./target/debug/cedar-agent --help

Run with docker

To execute the Cedar Agent docker image, use the following command:

docker run -p 8180:8180 permitio/cedar-agent

Test

To test Cedar-Agent, use the following command:

cargo test

API Endpoints

After running Cedar-Agent, the application provides comprehensive API documentation and endpoint schema using Rapidoc and Swagger UI, that you can access through the following routes:

• http://localhost:8180/rapidoc: Visit this route in your web browser to explore the interactive API documentation powered by the Rapidoc tool. It provides detailed information about each endpoint, including their parameters, request bodies, and response structures.
• http://localhost:8180/swagger-ui: Access this route to interact with the Swagger UI, which offers a user-friendly interface to browse the API endpoints. It presents a visual representation of the available routes, along with their descriptions, request and response schemas, and example requests.

Quickstart

1. Run the Cedar Agent

2. Store schema using this command:

   curl -X PUT -H "Content-Type: application/json" -d @./examples/schema.json http://localhost:8180/v1/schema

3. Store policy using this command:

   curl -X PUT -H "Content-Type: application/json" -d @./examples/policies.json http://localhost:8180/v1/policies

4. Store data using this command:

   curl -X PUT -H "Content-Type: application/json" -d @./examples/data.json http://localhost:8180/v1/data

5. Perform IsAuthorized check using this command:

   curl -X POST -H "Content-Type: application/json" -d @./examples/allowed_authorization_query.json http://localhost:8180/v1/is_authorized

   The response is:

   {
     "decision": "Allow",
     "diagnostics": {
       "reason": [
         "admins-policy"
       ],
       "errors": []
     }
   }

   As you can see the user is allowed to access the resource because policy id admins-policy permits it.
   Check for a user that is not allowed to access the resource:

   curl -X POST -H "Content-Type: application/json" -d @./examples/denied_authorization_query.json http://localhost:8180/v1/is_authorized

   The response is:

   {
   "decision": "Deny",
   "diagnostics": {
     "reason": [],
     "errors": []
     }
   }

   As you can see the user is denied access to the resource because no policy allows this request.

For more details about the performed requests you can check the examples directory

Run Cedar-agents at scale with OPAL

Want to run multiple Cedar-agents and have them loaded with the data and policeis you need? Try OPAL. OPAL (Open Policy Administration Layer) is a sister project to Cedar-Agent, which has become the de-facto way to manage policy agents (including others like OPA) at scale. Check out the tutorial for Cedar+OPAL in the OPAL docs.

Community

Come talk to us about Cedar Agent, or authorization in general - we would love to hear from you ❤️

You can raise questions and ask for features to be added to the road-map in our GitHub discussions, report issues in GitHub issues, join our Slack community to chat about authorization, open-source, realtime communication, tech, or anything else!

If you are using our project, please consider giving us a ⭐️

Contributing

If you encounter any issues or have suggestions for improvement, please open an issue, on the Cedar-Agent GitHub repository to get assistance from the community.

• Pull requests are welcome! (please make sure to include passing tests and docs)
• Prior to submitting a PR - open an issue on GitHub, or make sure your PR addresses an existing issue well.

cedar-agent's Issues

Condensing and escaping CEDAR into JSON file

Hey, this is a wonderful library.

I actually just packaged it up into @teaxyz's ecosystem.

One thing I'm wondering is if there's a recommended workflow for formatting/stringifying real .cedar files into something resembling policies.json?

(I can probably hack together some convoluted bash script, but I'm wondering if there's a known CLI or a better way).

(I'm also iterating on a real-life example here:
https://github.com/kevinmichaelchen/cedar-learning/tree/main/examples/policies)

Partial Evaluation

Is Cedar Agent able to support Partial Evaluation?

In this permit.io video with Mike Hicks and the Cedar team, they present a Partial Evaluation feature that lets you answer the question:

What resources could this principal perform this action on successfully?

The result is a series of residual expressions that can enumerate all of the allowed resources, from which we can derive a where clause (e.g., WHERE id IN [1, 2, 3]) to constrain which resources get retrieved by the database, thereby saving unnecessary data transfer.

Impact

The impact of this feature would be huge for service calls dealing with large batches of resources, which may only be partially accessible to the principal.

Example Scenario

Consider a university application where teachers may only view data (subjects, classroom blocks, other teachers, etc.) that they specifically teach.

We could try to model this fine-grained authorization logic using where clauses, but eventually, the database may exhaust its ability to do so. (Maybe, for example, authz decisions will be decided by data that simply is not in the database, e.g., Salesforce or some other external system).

query {
  schoolByPk(id: 42) {
    name
    teachers {
      id
      fullName
    }
    subjects {
      name # e.g., Linear Algebra
      blocks {
        recurrenceRules
        teacher {
          id
          fullName
        }
      }
    }
  }
}

Current Approach

My current approach to make sure the client sees only what is accessible is to:

1. Constrain the query by some kind of notion of multi-tenancy (e.g., school 42)
2. Retrieve everything under that from the database
3. Aggregate all the resources and submit them, one by one, in parallel, to Cedar Agent.
4. Filter out any resources that are not accessible.

I can't help but think an approach using Partial Evaluation would be cleaner.

unexpected HTML response

just playing with this, I ran into a surprising HTML response -- not surprising in its error, but rather that it wasn't JSON

% curl -X PUT -H "Content-Type: application/json" -d @./examples/policies.json http://localhost:8180/v1/policies/viewers-policy
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>422 Unprocessable Entity</title>
</head>
<body align="center">
    <div role="main" align="center">
        <h1>422: Unprocessable Entity</h1>
        <p>The request was well-formed but was unable to be followed due to semantic errors.</p>
        <hr />
    </div>
    <div role="contentinfo" align="center">
        <small>Rocket</small>
    </div>
</body>
</html>
%         

Passing additional entities to `POST /is_authorized` endpoint

Our system has a substantial number of entities, making it impractical to store them all in the memory of the Cedar Agent. To overcome this limitation, we propose enhancing the functionality of the POST /is_authorized endpoint by allowing to pass in additional entities. These entities would be considered when evaluating policies for the current request.

How I would expect it to work:

Let's say that the data stored in the memory of Cedar Agent is the following:

[
  {
    "attrs": {},
    "parents": [],
    "uid": {
      "id": "fraud",
      "type": "ResourceGroup"
    }
  },
  {
    "attrs": {},
    "parents": [
      {
        "id": "Admin",
        "type": "Role"
      }
    ],
    "uid": {
      "id": "[email protected]",
      "type": "User"
    }
  },
  {
    "attrs": {},
    "parents": [],
    "uid": {
      "id": "get",
      "type": "Action"
    }
  },
  {
    "attrs": {},
    "parents": [],
    "uid": {
      "id": "Admin",
      "type": "Role"
    }
  }
]

Additionally, let's consider the following policies:

[
  {
    "id": "fraud-docs-policy",
    "content": "permit(principal in Role::\"Admin\",action in [Action::\"get\"],resource in ResourceGroup::\"fraud\");"
  }
]

Consider the authorization request:

{
  "principal": "User::\"[email protected]\"",
  "action": "Action::\"get\"",
  "resource": "Document::\"fraud-doc\"",
  "additional_entities": [
    {
      "attrs": {},
      "parents": [
        {
          "id": "fraud",
          "type": "ResourceGroup"
        }
      ],
      "uid": {
        "id": "fraud-doc",
        "type": "Document"
      }
    }
  ]
}

The expected decision for this authorization request is "Allow" because the principal User:"[email protected]"
is permitted to perform action get on resources belonging to ResourceGroup:"fraud",and the resource Document:"fraud-doc" belongs to that resource group.

Of course, if you have any other ideas how to solve this, then feel free to let us know.

(Review Cedar) How to update part of entites

The api requires uploading the entire entities,
if I modify part of data , I should regenerate json to upload.

Any suggestions?

Could not access rapidoc or swagger ...

Cant load the swagger or rapidoc after running using docker as per the README instructions.
docker run permitio/cedar-agent
OS: Mac M1 Pro Ventura

Is agent support Cedar Policy template ?

To avoid the same policy compilation, cedar has policy template to use.
cedar policy template

Does cedar-agent support cedar policy template ?

I got error when I POST policy.

permit(
    principal == ?principal, 
    action in [Action::"readFile", Action::"writeFile"] 
    resource  == ?resource
  );