Crate cedar_policy

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 by running

cargo add cedar-policy

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(), None).unwrap();

    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(), None).unwrap();

    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.

If you’re looking to integrate Cedar into a production system, please be sure the read the security best practices

Building

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

What’s New

See CHANGELOG

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
• EntityAttrEvaluationError
  Error when evaluating an entity attribute
• EntityId
  Identifier portion of the EntityUid type.
• EntityNamespace
  Represents a namespace.
• EntityTypeName
  Represents an entity type name. Consists of a namespace and the type name.
• EntityUid
  Unique id for an entity, such as User::"alice".
• EvaluationError
  An error generated while evaluating an expression
• EvaluationResponsepartial-eval
  A policy evaluation response obtained from evaluate_policies_partial.
• Expression
  Expressions to be evaluated
• ParseErrors
  Multiple 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
  An authorization request is a tuple <P, A, R, C> where
• RequestBuilderpartial-eval
  Builder for a Request
• ResidualResponsepartial-eval
  A residual response obtained from is_authorized_partial.
• 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
• UnsetSchemapartial-eval
  A marker type that indicates Schema is not set for a request
• 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 issues found by validation and whether validation succeeds or fails. Validation succeeds if there are no fatal errors. There may still be non-fatal warnings present when validation passes.
• ValidationWarning
  Warnings found in Cedar policies
• Validator
  Validator object, which provides policy validation and typechecking.

Enums

• ActionConstraint
  Head constraint on policy actions.
• AuthorizationError
  Errors that can occur during authorization
• ContextJsonError
  Error type for parsing Context from JSON
• ContextOrShape
  Describes in what action context or entity type shape a schema parsing error occurred.
• 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
• EvaluationErrorKind
  Enumeration of the possible errors that can occur during evaluation
• HumanSchemaError
  Errors when parsing schemas
• PartialResponsepartial-eval
  Authorization response returned from is_authorized_partial. It can either be a full concrete response, or a residual response.
• 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
• SchemaWarning
• TemplatePrincipalConstraint
  Head constraint on policy principals for templates.
• TemplateResourceConstraint
  Head constraint on policy resources for templates.
• ToHumanSyntaxError
  Errors serializing Schemas to the natural syntax
• TypeErrorKind
  Represents the different kinds of type errors and contains information specific to that type error kind.
• UnsupportedFeature
• 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. These checks are also provided through Validator::validate which provides more comprehensive error detection, but this function can be used to check for confusable strings without defining a schema.
• 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