Crate cedar_policy

Expand description

§Cedar-Policy

Cedar is a language for defining permissions as policies, which describe who should have access to what. It is also a specification for evaluating those policies. Use Cedar policies to control what each user of your application is permitted to do and what resources they may access.

§Using Cedar

Cedar can be used in your application by depending on the cedar-policy crate.

Just add cedar-policy as a dependency in your Cargo.toml. For example:

[dependencies]
cedar-policy = "2.4"

§Quick Start

Let’s write a super simple Cedar policy and test it:

permit(principal == User::"alice", action == Action::"view", resource == File::"93");

This policy permits exactly one authorization request, alice is allowed to view file 93. Any other authorization request will be implicitly denied. Let’s embed this policy in Rust and use the Cedar Authorizer:

use cedar_policy::*;

fn main() {
    const POLICY_SRC: &str = r#"
permit(principal == User::"alice", action == Action::"view", resource == File::"93");
"#;
    let policy: PolicySet = POLICY_SRC.parse().unwrap();

    let action = r#"Action::"view""#.parse().unwrap();
    let alice = r#"User::"alice""#.parse().unwrap();
    let file = r#"File::"93""#.parse().unwrap();
    let request = Request::new(Some(alice), Some(action), Some(file), Context::empty());

    let entities = Entities::empty();
    let authorizer = Authorizer::new();
    let answer = authorizer.is_authorized(&request, &policy, &entities);

    // Should output `Allow`
    println!("{:?}", answer.decision());

    let action = r#"Action::"view""#.parse().unwrap();
    let bob = r#"User::"bob""#.parse().unwrap();
    let file = r#"File::"93""#.parse().unwrap();
    let request = Request::new(Some(bob), Some(action), Some(file), Context::empty());

    let answer = authorizer.is_authorized(&request, &policy, &entities);

    // Should output `Deny`
    println!("{:?}", answer.decision());
}

If you’d like to see more details on what can be expressed as Cedar policies, see the documentation.

Examples of how to use Cedar in an application are contained in the repository cedar-examples. The most full-featured of these is TinyTodo, which is a simple task list management service whose users’ requests, sent as HTTP messages, are authorized by Cedar.

§Documentation

General documentation for Cedar is available at docs.cedarpolicy.com, with source code in the cedar-policy/cedar-docs repository.

Generated documentation for the latest version of the Rust crates can be accessed on docs.rs.

§Building

To build, simply run cargo build (or cargo build --release).

§What’s New

Changelogs for all release branches and the main branch of this repository are all maintained on the main branch; the most up-to-date changelog for this crate is here.

For a list of the current and past releases, see crates.io or Releases.

§Security

See SECURITY

§Contributing

We welcome contributions from the community. Please either file an issue, or see CONTRIBUTING

§License

This project is licensed under the Apache-2.0 License.

Modules§

extensions: This module contains all of the standard Cedar extensions.
frontend: Frontend utilities, see comments in the module itself

Structs§

Authorizer: Authorizer object, which provides responses to authorization queries
Context: the Context object for an authorization request
Diagnostics: Diagnostics providing more information on how a Decision was reached
Entities: Represents an entity hierarchy, and allows looking up Entity objects by Uid.
Entity: Entity datatype
EntityId: unique identifier portion of the EntityUid type
EntityNamespace: Represents a namespace
EntityTypeName: Represents a concatenation of Namespaces and TypeName
EntityUid: Unique Id for an entity, such as User::"alice"
Expression: Expressions to be evaluated
ParseErrors: Multiple related parse errors.
Policy: Structure for a Policy. Includes both static policies and template-linked policies.
PolicyId: Unique Ids assigned to policies and templates
PolicySet: Represents a set of Policys
Record: A record of Cedar values
Request: Represents the request tuple <P, A, R, C> (see the Cedar design doc).
Response: Authorization response returned from the Authorizer
RestrictedExpression: “Restricted” expressions are used for attribute values and context.
Schema: Object containing schema information used by the validator.
SchemaFragment: Contains all the type information used to construct a Schema that can be used to validate a policy.
Set: Sets of Cedar values
SlotId: Identifier for a Template slot
SourceLocation: Represents a location in Cedar policy source.
Template: Policy template datatype
ValidationError: An error generated by the validator when it finds a potential problem in a policy. The error contains a enumeration that specifies the kind of problem, and provides details specific to that kind of problem. The error also records where the problem was encountered.
ValidationResult: Contains the result of policy validation. The result includes the list of of issues found by the validation and whether validation succeeds or fails. Validation succeeds if there are no fatal errors. There are currently no non-fatal warnings, so any issues found will cause validation to fail.
ValidationWarning: Warnings found in Cedar policies
Validator: Validator object, which provides policy validation and typechecking.

Enums§

ActionConstraint: Head constraint on policy actions.
ContextJsonError: Error type for parsing Context from JSON
Decision: Decision returned from the Authorizer
Effect: the Effect of a policy
EntitiesError: Error type for errors raised in entities.rs.
EvalResult: Result of Evaluation
EvaluationError: Errors encountered while evaluating policies or expressions, or making authorization decisions.
PolicySetError: Potential errors when adding to a PolicySet.
PolicyToJsonError: Errors that can happen when getting the JSON representation of a policy
PrincipalConstraint: Head constraint on policy principals.
ResourceConstraint: Head constraint on policy resources.
SchemaError: Errors encountered during construction of a Validation Schema
TemplatePrincipalConstraint: Head constraint on policy principals for templates.
TemplateResourceConstraint: Head constraint on policy resources for templates.
TypeErrorKind: Represents the different kinds of type errors and contains information specific to that type error kind.
ValidationErrorKind: Enumeration of the possible diagnostic error that could be found by the verification steps.
ValidationMode: Used to select how a policy will be validated.
ValidationWarningKind

Functions§

confusable_string_checker: Scan a set of policies for potentially confusing/obfuscating text.
eval_expression: Evaluates an expression. If evaluation results in an error (e.g., attempting to access a non-existent Entity or Record, passing the wrong number of arguments to a function etc.), that error is returned as a String