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 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§
- Error subtypes for
AuthorizationError
- Error subtypes for
CedarSchemaError
- Errors related to schema conformance checking for entities
- Error subtypes for
ContextJsonError
- Utilities for defining
IntoIterator
overEntities
- Errors related to
crate::Entities
- Errors related to serializing/deserializing entities or contexts to/from JSON
- Error subtypes for
EvaluationError
- Error subtypes for
ExpressionConstructionError
- Error subtypes for
ExtensionFunctionLookupError
- FFI utilities, see comments in the module itself
- Error subtypes for
PolicySetError
- Error subtypes for
PolicyToJsonError
- Error subtypes for
RequestValidationError
- Error subtypes for
RestrictedExpressionError
- Error subtypes for
SchemaError
- Error subtypes for
SchemaWarning
- Error subtypes for
ToCedarSchemaError
- Error subtypes for
ValidationError
. Errors are primarily documented on their variants inValidationError
. - Error subtypes for
ValidationWarning
. Validation warnings are primarily documented on their variants inValidationWarning
.
Structs§
- Access
Trie entity-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. - Entity
Manifest entity-manifest
Data structure storing what data is needed based on the theRequestType
. For each request type, theEntityManifest
stores aRootAccessTrie
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
ParseError
s encountered when parsing a policy or expression. By default, theDiagnostic
andError
implementations will only print the first error. If you want to see all errors, use.iter()
or.into_iter()
. - Partial
Response partial-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
Policy
s - A record of Cedar values
- An authorization request is a tuple
<P, A, R, C>
where - Request
Builder partial-eval
Builder for aRequest
- The “type” of a
Request
, i.e., theEntityTypeName
s of principal and resource, and theEntityUid
of action - Authorization response returned from the
Authorizer
- “Restricted” expressions are used for attribute values and
context
. - Root
Access Trie entity-manifest
ARootAccessTrie
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
- Unset
Schema partial-eval
A marker type that indicatesSchema
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§
- Scope constraint on policy actions.
- Errors that can occur during authorization
- Errors when parsing schemas
- Errors while trying to create a
Context
- Error type for parsing
Context
from JSON - Decision returned from the
Authorizer
- the Effect of a policy
- Entity
Manifest Error entity-manifest
An error generated by entity slicing. SeeFailedAnalysisError
for details on the fragment of Cedar handled by entity slicing. - Entity
Root entity-manifest
The root of a data path orRootAccessTrie
. - Result of Evaluation
- Enumeration of the possible errors that can occur during evaluation
- Errors when constructing an expression
- Errors thrown when looking up an extension function in
Extensions
. - Errors encountered when converting
PartialValue
toValue
- Potential errors when adding to a
PolicySet
. - Errors that can happen when getting the JSON representation of a policy
- Scope constraint on policy principals.
- Errors that can be encountered when re-evaluating a partial response
- The request does not conform to the schema
- Scope constraint on policy resources.
- Error when constructing a restricted expression from unrestricted expression
- Error type for parsing a
RestrictedExpression
- Error when constructing a schema
- Warning when constructing a schema
- Scope constraint on policy principals for templates.
- Scope constraint on policy resources for templates.
- Errors serializing Schemas to the Cedar syntax
- An error generated by the validator when it finds a potential problem in a policy.
- Used to select how a policy will be validated.
- Represents the different kinds of validation warnings and information specific to that warning. Marked as
non_exhaustive
to allow adding additional warnings in the future as a non-breaking change.
Functions§
- compute_
entity_ manifest entity-manifest
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§
- Fields
entity-manifest
A map of data fields toAccessTrie
s. The keys to this map form the edges in the access trie, pointing to sub-tries.