diff --git a/docs/index.md b/docs/index.md index bd50858..92d1949 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,12 +28,12 @@ In addition to supporting the authorization requirements for your own custom app To make secure authorization decisions that you can trust, Cedar uses the following elements: -+ **Authorization policies** – Policies describe who \(the ***principal***\) is allowed to perform which ***actions***, on which ***resources***, and in what ***context***. For example, a policy might state that only members of the `janeFriends` group \(the principals\) can view and comment \(the actions\) on the photos in the `janeVacation` album \(the resources\). Another example policy might state that the employees of a company \(the principals\) can read \(the actions\) only their own Human Resources records \(the resources\), and only during regular business hours \(the context\). A policy for a medical application might state that only a doctor currently associated with a patient can create a referral to a different doctor. For more information, see [Policy](overview/terminology.html#term-policy) in [Cedar terms and concepts](overview/terminology.html). ++ **Authorization policies** – Policies describe who \(the ***principal***\) is allowed to perform which ***actions***, on which ***resources***, and in what ***context***. For example, a policy might state that only members of the `janeFriends` group \(the principals\) can view and comment \(the actions\) on the photos in the `janeVacation` album \(the resources\). Another example policy might state that the employees of a company \(the principals\) can read \(the actions\) only their own Human Resources records \(the resources\), and only from certain IP addresses \(the context\). A policy for a medical application might state that only a doctor currently associated with a patient can create a referral to a different doctor. For more information, see [Policy](overview/terminology.html#term-policy) in [Cedar terms and concepts](overview/terminology.html). + **Entities** – Entities are application data that Cedar needs to see to make authorization decisions. For example, a request might ask if `User::"jane"` is allowed to perform `Action::"viewPhoto"` on the `Photo::"GoldenGateBridge.jpg"`. Here, `User`, `Action`, and `Photo` are all different types of entity, and the quoted strings are specific identifiers. To decide this request, Cedar's authorization engine must have access to these specific entities and any related entities, such as any groups that Jane is a member of, and any albums that contain the specified picture. The engine must also have access to all of those entities' attributes. This collection of information about the relevant entities must be provided to the authorization engine as part of the request, along with the policies to evaluate. -+ **Schema** – A schema defines the types of entities recognized by the application, and which are also the principals, resources, and actions referenced in policies. For example, in a media sharing application, the schema might define a `User` and the concept of nested "groups" that a `User` can belong to. It might also define a "photo" and the concept of nested "albums" that can contain photos. Each principal and resource can also have attributes defined, such as Name, Address, Age, and any others relevant to the scenario. Finally, the schema also defines the actions that the application supports, such as viewing photos or reading HR records. Cedar doesn't use the schema when evaluating an authorization request. Instead, it uses the schema to validate the policies only when you create or update them. This approach helps ensure that your authorization decisions are based on correctly designed policies that reflect your intentions for the application. For more information, see [Schema](overview/terminology.html#term-schema) in [Cedar terms and concepts](overview/terminology.html). -+ **Context** – The context is a part of a request that consists of transient data. The context can include session-specific elements, such as the time the request was made, the IP address the request was sent from, and whether the user authenticated using multi-factor authentication \(MFA\) when signing in. Policies can reference these elements to support requirements such as only allowing access during business hours, only allowing access from a recognized address in the company network's IP address range, or allowing sensitive administrator operations only when the user authenticated with MFA. ++ **Context** – The context is a part of a request that consists of transient data. The contextr is defined in the schema and each action has a context that has a fixed shape. The context can include session-specific elements, such as the time the request was made, the IP address the request was sent from, and whether the user authenticated using multi-factor authentication \(MFA\) when signing in. Policies can reference these elements to support requirements such as only allowing access from a recognized address in the company network's IP address range or allowing sensitive administrator operations only when the user authenticated with MFA. ++ **Schema** – A schema defines the types of entities recognized by the application/ The entities include the principals, resources, actions, and context referenced in policies. For example, in a media sharing application, the schema might define a `User` and the concept of nested `groups` that a `User` can belong to. It might also define a `photo` and the concept of nested `albums` that can contain photos. Each principal and resource can also have attributes defined, such as Name, Address, Age, and any others relevant to the scenario. Finally, the schema also defines the actions that the application supports, such as viewing photos or reading HR records. Cedar doesn't use the schema when evaluating an authorization request. Instead, it uses the schema to validate the policies only when you create or update them. This approach helps ensure that your authorization decisions are based on correctly designed policies that reflect your intentions for the application. For more information, see [Schema](overview/terminology.html#term-schema) in [Cedar terms and concepts](overview/terminology.html). -Cedar evaluates each request against the provided policies and entities to make an allow or deny decision. The policies are completely separate from your application's code. This design ensures that your security team can update permissions for your application without having to touch the application's code. A change to a policy can result in an immediate change in the logic used to authorize requests. +Cedar evaluates each request against the provided policies and entities to make an allow or deny decision. The policies are completely separate from your application's code. This design ensures that your security team can update permissions for your application without having to touch the application's code. If you have multiple teams owning multiple backends, you can update your policies without needing to coordinate the updates across teams. A change to a policy can result in an immediate change in the logic used to authorize requests. Separating the authorization model froom your application code makes it easier to test. Cedar is analyzable, meaning it can be easily read and understood by new team members. ## Are you a first-time Cedar user? {#first-time-user} @@ -43,6 +43,7 @@ If you are a first-time user of Cedar, we recommend that you begin by reading th + Review and become familiar with the [scenario upon which the examples in this guide are based](overview/scenario.html). + Learn [basic Cedar policy syntax and its construction](policies/syntax-policy.html). + Learn how to [define a Cedar schema that can validate your policies](schema/schema.html) and ensure you're getting the evaluation results you intend. ++ Complete the [tutorial](https://www.cedarpolicy.com/en/tutorial). ## Features of Cedar {#feature-overview} @@ -50,11 +51,11 @@ Cedar provides several important features. #### Policy-based {#policy-based} -Cedar policies are written as rules that specify the conditions under which access to resources is to be allowed or denied. You define a policy as a set of statements that include conditions that evaluate the attributes of the requester, the resource being accessed, and the context of the request. +Cedar policies are written as rules that specify the conditions under which access to resources is to be allowed or denied. Policies include conditions that evaluate the attributes of the principal, the resource being accessed, and the context of the request. #### Supports attributes on entities and sessions {#attribute-based} -Cedar policies can use attributes, which are key-value pairs that represent various aspects of the principal, the resource, and the caller's current session which defines the context of the request. Attributes can include information such as user roles, resource types, time of day, location, and any other relevant contextual information. +Cedar policies can use attributes, which are key-value pairs that represent various aspects of the principal, the resource, and the context of the request. Attributes can include information such as user roles, resource types, time of day, location, and any other relevant contextual information. #### Expressive {#feature-expressive} @@ -74,4 +75,4 @@ Cedar policies are designed to be easy to read and understand, making them acces ## Services that use Cedar {#related-services} -For a list of some of the services that use Cedar as their policy language, see [Cedar Integrations](https://www.cedarpolicy.com/en/integrations) +[Amazon Verified Pernmissions](https://aws.amazon.com/verified-permissions/) is a managed service using Cedar. For a list of some of the other services that use Cedar as their policy language, see [Cedar Integrations](https://www.cedarpolicy.com/en/integrations)