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 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 to 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§

authorization_errors: Error subtypes for AuthorizationError
cedar_schema_errors: Error subtypes for CedarSchemaError
conformance_errors: Errors related to schema conformance checking for entities
context_json_errors: Error subtypes for ContextJsonError
entities: Utilities for defining IntoIterator over Entities
entities_errors: Errors related to crate::Entities
entities_json_errors: Errors related to serializing/deserializing entities or contexts to/from JSON
evaluation_errors: Error subtypes for EvaluationError
expression_construction_errors: Error subtypes for ExpressionConstructionError
extension_function_lookup_errors: Error subtypes for ExtensionFunctionLookupError
ffi: FFI utilities, see comments in the module itself
policy_set_errors: Error subtypes for PolicySetError
policy_to_json_errors: Error subtypes for PolicyToJsonError
protoprotobufs: Protobuf models of cedar-policy types
request_validation_errors: Error subtypes for RequestValidationError
restricted_expr_errors: Error subtypes for RestrictedExpressionError
schema_errors: Error subtypes for SchemaError
schema_warnings: Error subtypes for SchemaWarning
to_cedar_syntax_errors: Error subtypes for ToCedarSchemaError
tpe_errtpe: This module contains possible errors thrown by various components of the type-aware partial evaluator.
validation_errors: Error subtypes for ValidationError.
validation_warnings: Error subtypes for ValidationWarning.

Structs§

AccessTrieentity-manifest: A Trie representing a set of data paths to load, starting implicitly from a Cedar value.
ActionQueryRequesttpe: Defines a PartialRequest which additionally leaves the action undefined, enabling queries listing what actions might be authorized.
Authorizer: Authorizer object, which provides responses to authorization queries
ConcretizationError: Errors that occur during concretizing a partial request
ContainsUnknown: The PartialValue is a residual, i.e., contains an unknown
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 or tag
EntityId: Identifier portion of the EntityUid type.
EntityManifestentity-manifest: Data structure storing what data is needed based on the the RequestType.
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".
Expression: Expressions to be evaluated
ParseError: Errors that can occur when parsing policies or expressions.
ParseErrors: Represents one or more ParseErrors encountered when parsing a policy or expression.
PartialEntitiestpe: Partial Entities
PartialEntityUidtpe: A partial EntityUid. That is, its EntityId could be unknown
PartialRequesttpe: A partial Request Its principal/resource types and action must be known and its context must either be fully known or unknown
PartialResponsepartial-eval: A partially evaluated authorization response.
Policy: Structure for a Policy. Includes both static policies and template-linked policies.
PolicyFromJsonError: Error when converting a policy or template from JSON format
PolicyId: Unique ids assigned to policies and templates.
PolicySet: Represents a set of Policys
PrincipalQueryRequesttpe: Like PartialRequest but only principal can be unknown
Record: A record of Cedar values
Request: An authorization request is a tuple <P, A, R, C> where
RequestBuilderpartial-eval: Builder for a Request
RequestEnv: The “type” of a Request, i.e., the EntityTypeNames of principal and resource, the EntityUid of action, and Option<EntityTypeName>s of principal slot and resource slot
ResourceQueryRequesttpe: Like PartialRequest but only resource can be unknown
Response: Authorization response returned from the Authorizer
RestrictedExpression: “Restricted” expressions are used for attribute values and context.
RootAccessTrieentity-manifest: A trie describing a set of data paths to retrieve.
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
TPEResponsetpe: A partial version of crate::Response.
Template: Policy template datatype
TestEntityLoadertpe: Simple entity loader implementation that loads from a pre-existing Entities store
UnsetSchemapartial-eval: A marker type that indicates Schema is not set for a request
ValidationResult: Contains the result of policy validation.
Validator: Validator object, which provides policy validation and typechecking.

Enums§

ActionConstraint: Scope constraint on policy actions.
AuthorizationError: Errors that can occur during authorization
CedarSchemaError: Errors when parsing schemas
ContextCreationError: Errors while trying to create a Context
ContextJsonError: Error type for parsing Context from JSON
Decision: Decision returned from the Authorizer
Effect: the Effect of a policy
EntityManifestErrorentity-manifest: An error generated by entity slicing.
EntityRootentity-manifest: The root of a data path or RootAccessTrie.
EntitySliceErrorentity-manifest: An error generated by entity slicing. TODO make public API wrapper
EvalResult: Result of Evaluation
EvaluationError: Enumeration of the possible errors that can occur during evaluation
ExpressionConstructionError: Errors when constructing an expression
ExtensionFunctionLookupError: Errors thrown when looking up an extension function in Extensions.
PartialRequestCreationErrortpe: Error thrown when creating a PartialRequest
PartialValueToValueError: Errors encountered when converting PartialValue to Value
PermissionQueryErrortpe: Errors that can be encountered when performing a permission query
PolicySetError: Potential errors when adding to a PolicySet.
PolicyToJsonError: Errors that can happen when getting the JSON representation of a policy
PrincipalConstraint: Scope constraint on policy principals.
ReauthorizationError: Errors that can be encountered when re-evaluating a partial response
RequestValidationError: The request does not conform to the schema
ResourceConstraint: Scope constraint on policy resources.
RestrictedExpressionError: Error when constructing a restricted expression from unrestricted expression
RestrictedExpressionParseError: Error type for parsing a RestrictedExpression
SchemaError: Error when constructing a schema
SchemaWarning: Warning when constructing a schema
TPEReauthorizationErrortpe: Errors that can be encountered when re-evaluating a partial response
TemplatePrincipalConstraint: Scope constraint on policy principals for templates.
TemplateResourceConstraint: Scope constraint on policy resources for templates.
ToCedarSchemaError: Errors serializing Schemas to the Cedar syntax
ValidationError: An error generated by the validator when it finds a potential problem in a policy.
ValidationMode: Used to select how a policy will be validated.
ValidationWarning: Represents the different kinds of validation warnings and information specific to that warning.

Traits§

EntityLoadertpe: Entity loader trait for batched evaluation.

Functions§

compute_entity_manifestentity-manifest: Given a schema and policy set, compute an entity manifest.
confusable_string_checker: Scan a set of policies for potentially confusing/obfuscating text.
eval_expression: Evaluates an expression.
get_lang_version: Get the Cedar language version
get_sdk_version: Get the Cedar SDK Semantic Versioning version
validate_scope_variables: Validates scope variables against the provided schema

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.