# Amazon Verified Permissions and Cedar policy language terms and concepts Terms & concepts You should understand the following concepts to use Amazon Verified Permissions. **Topics** + [ ## Authorization model ](#term-authorization-model) + [ ## Authorization request ](#term-authorization-request) + [ ## Authorization response ](#term-authorization-response) + [ ## Considered policies ](#term-considered-policies) + [ ## Context data ](#term-context-data) + [ ## Determining policies ](#term-determining-policies) + [ ## Entity data ](#term-entity-data) + [ ## Permissions, authorization, and principals ](#term-permissions-authorization-principals) + [ ## Policy enforcement ](#term-policy-enforcement) + [ ## Policy store ](#term-policy-store) + [ ## Policy store alias ](#term-policy-store-alias) + [ ## Policy name ](#term-policy-name) + [ ## Policy template name ](#term-policy-template-name) + [ ## Satisfied policies ](#term-satisfied-policies) + [ # Differences between Amazon Verified Permissions and the Cedar policy language ](terminology-differences-avp-cedar.md) **Cedar policy language concepts** + [Authorization](https://docs.cedarpolicy.com/overview/terminology.html#authorization) + [Entity](https://docs.cedarpolicy.com/overview/terminology.html#entity) + [Groups and hierarchies](https://docs.cedarpolicy.com/overview/terminology.html#term-group) + [Namespaces](https://docs.cedarpolicy.com/policies/validation.html#namespaces) + [Policy](https://docs.cedarpolicy.com/overview/terminology.html#policy) + [Policy template](https://docs.cedarpolicy.com/overview/terminology.html#policy-template) + [Schema](https://docs.cedarpolicy.com/overview/terminology.html#schema) ## Authorization model The *authorization model* describes the scope of the [authorization requests](#term-authorization-request) made by the application and the basis for evaluating those requests. It is defined in terms of the different types of resources, the actions taken on those resources, and the types principals that take those actions. It also considers the context in which those actions are being taken. *Role-based Access Control (RBAC)* is an evaluation basis in which roles are defined and associated with a set of permissions. These roles can then be assigned to one or more identities. The assigned identity acquires the permissions associated with the role. If the permissions associated with the role are modified, then the modification automatically impacts any identity to which the role has been assigned. Cedar can support RBAC decisions through the use of principal groups. *Attribute-based Access Control (ABAC)* is an evaluation basis in which the permissions associated with an identity are determined by attributes of that identity. Cedar can support ABAC decisions through the use of policy conditions that reference attributes of the principal. The Cedar policy language enables the combination of RBAC and ABAC in a single policy by allowing permissions to be defined for a group of users, which have attribute-based conditions. ## Authorization request An *authorization request* is a request made of Verified Permissions by an application to evaluate a set of policies in order to determine whether a principal may perform an action on a resource for a given context. ## Authorization response The *authorization response* is the response to the [authorization request](#term-authorization-request). It includes an allow or deny decision, plus additional information, such as the IDs of the determining policies. ## Considered policies *Considered policies* are the full set of policies that are selected by Verified Permissions for inclusion when evaluating an [authorization request](#term-authorization-request). ## Context data *Context data* are attribute values that provide additional information to be evaluated. ## Determining policies *Determining policies* are the policies that determine the [authorization response](#term-authorization-response). For example, if there are two [satisfied policies](#term-satisfied-policies), where one is a deny and the other is an allow, then the deny policy will be the determining policy. If there are multiple satisfied permit policies and no satisfied forbid policies, then there are multiple determining policies. In the case that no policies match and the response is deny, there are no determining policies. ## Entity data *Entity data* are data about the principal, action, and resource. Entity data relevant for policy evaluation are group membership all the way up the entity hierarchy and attribute values of the principal and resource. ## Permissions, authorization, and principals Verified Permissions manages fine-grained *permissions* and *authorization* within custom applications that you build. A *principal* is user of an application, either human or machine, that has an identity bound to an identifier such as a username or machine ID. The process of authentication determines whether the principal is truly the identity they claim to be. Associated with that identity are a set of application *permissions* that determine what that principal is permitted to do within that application. *Authorization* is the process of assessing those permissions to determine whether a principal is permitted to perform a particular action in the application. These permissions can be expressed as [policies](https://docs.cedarpolicy.com/overview/terminology.html#policy). ## Policy enforcement *Policy enforcement* is the process of enforcing the evaluation decision within the application outside of Verified Permissions. If Verified Permissions evaluation returns a deny, then enforcement would ensure that the principal was prevented from accessing the resource. ## Policy store A *policy store* is a container for policies and templates. Each store contains a schema that is used to validate policies added to the store. By default, each application has its own policy store, but multiple applications can share a single policy store. When an application makes an authorization request, it identifies the policy store used to evaluate that request. Policy stores provide a way to isolate a set of policies, and can therefore be used in a multi-tenant application to contain the schemas and policies for each tenant. A single application can have separate policy stores for each tenant. When evaluating an [authorization request](#term-authorization-request), Verified Permissions only considers the subset of the policies in the policy store that are relevant to the request. Relevance is determined based on the *scope* of the policy. The scope identifies the specific principal and resource to which the policy applies, and the actions that the principal can perform on the resource. Defining the scope helps improve performance by narrowing the set of considered policies. ## Policy store alias A *policy store alias* is a friendly name for a policy store. You can use a policy store alias to identify a policy store in any Verified Permissions operation that accepts a `policyStoreId` parameter. Policy store aliases are independent Amazon resources with their own ARNs. Each alias is associated with one policy store at a time, and multiple aliases can be associated with the same policy store. For more information, see [Amazon Verified Permissions policy store aliases](policy-store-aliases.md). ## Policy name A *policy name* is an optional friendly name for a policy. Policy names must be unique for all policies within the policy store and prefixed with `name/`. You can use a policy name in place of the policy ID in control plane operations that accept a `policyId` parameter. Names can be set when creating or updating a policy. Only `GetPolicy` and `ListPolicies` return the name in the output. ## Policy template name A *policy template name* is an optional friendly name for a policy template. Policy template names must be unique for all policy templates within the policy store and prefixed with `name/`. You can use a policy template name in place of the policy template ID in control plane operations that accept a `policyTemplateId` parameter. Names can be set when creating or updating a policy template. Only `GetPolicyTemplate` and `ListPolicyTemplates` return the name in the output. ## Satisfied policies *Satisfied policies* are the policies that match the parameters of the [authorization request](#term-authorization-request). # Differences between Amazon Verified Permissions and the Cedar policy language Differences with Cedar Amazon Verified Permissions uses the Cedar policy language engine to perform its authorization tasks. However, there are some differences between the native Cedar implementation and the implementation of Cedar found in Verified Permissions. This topic identifies those differences. ## Namespace definition Verified Permissions implementation of Cedar has the following differences from the native Cedar implementation: + Verified Permissions supports only one [namespace in a schema](https://docs.cedarpolicy.com/schema/schema.html#namespace) defined in a policy store. + Verified Permissions doesn't allow you to create a [namespace](https://docs.cedarpolicy.com/schema/schema.html#namespace) that's an empty string or includes the following values: `aws`, `amazon`, or `cedar`. ## Policy template support Both Verified Permissions and Cedar allow placeholders in the scope for only the `principal` and `resource`. However, Verified Permissions also requires that neither the `principal` and `resource` are unconstrained. The following policy is valid in Cedar but is rejected by Verified Permissions because the `principal` is unconstrained. ``` permit(principal, action == Action::"view", resource == ?resource); ``` Both of the following examples are valid in both Cedar and Verified Permissions because both the `principal` and `resource` have constraints. ``` permit(principal == User::"alice", action == Action::"view", resource == ?resource); ``` ``` permit(principal == ?principal, action == Action::"a", resource in ?resource); ``` ## Schema support Verified Permissions requires all schema JSON key names to be non-empty strings. Cedar allows empty strings in a few cases, such as for properties or namespaces. ## Action groups definition The Cedar authorization methods require a list of the entities to be considered when evaluating an authorization request against the policies. You can define the actions and action groups used by your application in the schema. However, Cedar doesn't include the schema as part of an evaluation request. Instead, Cedar uses the schema only to validate the policies and policy templates that you submit. Because Cedar doesn't reference the schema during evaluation requests, even if you defined action groups in the schema, you must also include the list of any action groups as part of the entities list you must pass to the authorization API operations. Verified Permissions does this for you. Any action groups that you define in your schema are automatically appended to the entities list that you pass to as a parameter to the `IsAuthorized` or `IsAuthorizedWithToken` operations. ## Entity formatting The JSON formatting of entities in Verified Permissions using the `entityList` parameter differs from Cedar in the following ways: + In Verified Permissions, a JSON object must have all of its key-value pairs wrapped in a JSON object with the name of `Record`. + A JSON list in Verified Permissions must be wrapped in a JSON key-value pair where the key name is `Set` and the value is the original JSON list from Cedar. + For `String`, `Long`, and `Boolean` type names, each key-value pair from Cedar is replaced by a JSON object in Verified Permissions. The name of the object is the original key name. Inside the JSON object, there is one key-value pair where the key name is the type name of the scalar value (`String`, `Long`, or `Boolean`) and the value is the value from the Cedar entity. + The syntax formatting of Cedar entities and Verified Permissions entities differs in the following ways: [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/verifiedpermissions/latest/userguide/terminology-differences-avp-cedar.html) **Example - Lists** The following examples show how a list of entities is expressed in Cedar and Verified Permissions, respectively. ``` [ { "number": 1 }, { "sentence": "Here is an example sentence" }, { "Question": false } ] ``` ``` { "Set": [ { "Record": { "number": { "Long": 1 } } }, { "Record": { "sentence": { "String": "Here is an example sentence" } } }, { "Record": { "question": { "Boolean": false } } } ] } ``` **Example - Policy evaluation** The following examples shows how entities are formatted for evaluating a policy in an authorization request in Cedar and Verified Permissions, respectively. ``` [ { "uid": { "type": "PhotoApp::User", "id": "alice" }, "attrs": { "age": 25, "name": "alice", "userId": "123456789012" }, "parents": [ { "type": "PhotoApp::UserGroup", "id": "alice_friends" }, { "type": "PhotoApp::UserGroup", "id": "AVTeam" } ] }, { "uid": { "type": "PhotoApp::Photo", "id": "vacationPhoto.jpg" }, "attrs": { "private": false, "account": { "__entity": { "type": "PhotoApp::Account", "id": "ahmad" } } }, "parents": [] }, { "uid": { "type": "PhotoApp::UserGroup", "id": "alice_friends" }, "attrs": {}, "parents": [] }, { "uid": { "type": "PhotoApp::UserGroup", "id": "AVTeam" }, "attrs": {}, "parents": [] } ] ``` ``` [ { "Identifier": { "EntityType": "PhotoApp::User", "EntityId": "alice" }, "Attributes": { "age": { "Long": 25 }, "name": { "String": "alice" }, "userId": { "String": "123456789012" } }, "Parents": [ { "EntityType": "PhotoApp::UserGroup", "EntityId": "alice_friends" }, { "EntityType": "PhotoApp::UserGroup", "EntityId": "AVTeam" } ] }, { "Identifier": { "EntityType": "PhotoApp::Photo", "EntityId": "vacationPhoto.jpg" }, "Attributes": { "private": { "Boolean": false }, "account": { "EntityIdentifier": { "EntityType": "PhotoApp::Account", "EntityId": "ahmad" } } }, "Parents": [] }, { "Identifier": { "EntityType": "PhotoApp::UserGroup", "EntityId": "alice_friends" }, "Parents": [] }, { "Identifier": { "EntityType": "PhotoApp::UserGroup", "EntityId": "AVTeam" }, "Parents": [] } ] ``` ## Length and size limits Verified Permissions supports storage in the form of policy stores to hold your schema, policies, and policy templates. That storage causes Verified Permissions to impose some length and size limits that aren't relevant to Cedar. | Object | Verified Permissions limit (in bytes) | Cedar limit | | --- | --- | --- | | Policy size¹ | 10,000 | None | | Inline policy description | 150 | Not applicable to Cedar | | Policy template size | 10,000 | None | | Schema size | 100,000 | None | | Entity type | 200 | None | | Policy ID | 64 | None | | Policy template ID | 64 | None | | Entity ID | 200 | None | | Policy store ID | 64 | Not applicable to Cedar | ¹ There is a limit for policies per policy store in Verified Permissions based on the combined size of principals, actions, and resources of policies created in the policy store. The total size of all policies pertaining to a single resource can't exceed 200,000 bytes. For template-linked policies, the size of the policy template is counted only once, plus the size of each set of parameters used to instantiate each template-linked policy.