Crate cedar_policy

source
Expand description

§Cedar-Policy

Cedar Logo

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(alice, action, 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(bob, action, 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

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§

Structs§

  • AccessTrieentity-manifest
    A Trie representing a set of data paths to load, starting implicitly from a Cedar value.
  • Authorizer object, which provides responses to authorization queries
  • Errors that occur during concretizing a partial request
  • The PartialValue is a residual, i.e., contains an unknown
  • the Context object for an authorization request
  • Diagnostics providing more information on how a Decision was reached
  • Represents an entity hierarchy, and allows looking up Entity objects by Uid.
  • Entity datatype
  • Error when evaluating an entity attribute or tag
  • Identifier portion of the EntityUid type.
  • EntityManifestentity-manifest
    Data structure storing what data is needed based on the the RequestType. For each request type, the EntityManifest stores a RootAccessTrie of data to retrieve.
  • Represents a namespace.
  • Represents an entity type name. Consists of a namespace and the type name.
  • Unique id for an entity, such as User::"alice".
  • Expressions to be evaluated
  • Errors that can occur when parsing policies or expressions. Marked as non_exhaustive to support adding additional error information in the future without a major version bump.
  • Represents one or more ParseErrors encountered when parsing a policy or expression. By default, the Diagnostic and Error implementations will only print the first error. If you want to see all errors, use .iter() or .into_iter().
  • PartialResponsepartial-eval
    A partially evaluated authorization response. Splits the results into several categories: satisfied, false, and residual for each policy effect. Also tracks all the errors that were encountered during evaluation.
  • Structure for a Policy. Includes both static policies and template-linked policies.
  • Error when converting a policy or template from JSON format
  • Unique ids assigned to policies and templates.
  • Represents a set of Policys
  • A record of Cedar values
  • An authorization request is a tuple <P, A, R, C> where
  • RequestBuilderpartial-eval
    Builder for a Request
  • The “type” of a Request, i.e., the EntityTypeNames of principal and resource, and the EntityUid of action
  • Authorization response returned from the Authorizer
  • “Restricted” expressions are used for attribute values and context.
  • RootAccessTrieentity-manifest
    A RootAccessTrie is a trie describing a set of data paths to retrieve. Each edge in the trie is either a record or entity dereference.
  • Object containing schema information used by the validator.
  • Contains all the type information used to construct a Schema that can be used to validate a policy.
  • Sets of Cedar values
  • Identifier for a Template slot
  • Policy template datatype
  • UnsetSchemapartial-eval
    A marker type that indicates Schema is not set for a request
  • 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.
  • Validator object, which provides policy validation and typechecking.

Enums§

Functions§

  • Given a schema and policy set, compute an entity manifest. The policies must validate against the schema in strict mode, otherwise an error is returned. The manifest describes the data required to answer requests for each action.
  • 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.
  • 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
  • Get the Cedar language version
  • Get the Cedar SDK Semantic Versioning version

Type Aliases§

  • Fieldsentity-manifest
    A map of data fields to AccessTries. The keys to this map form the edges in the access trie, pointing to sub-tries.