AWS verifiedpermissions documentation change
Summary
Updated FAQ content regarding Cedar 4 upgrade process, including compatibility checks, version identification methods, upgrade procedures, error resolution, and schema compatibility guidance
Security assessment
The changes primarily document version migration procedures rather than address specific vulnerabilities. However, they mention security-relevant features like entity tags and improved policy validation. The update adds documentation about security-enhancing features (like the 'is' operator) but doesn't reference any specific security incidents or vulnerabilities being patched.
Diff
diff --git a/verifiedpermissions/latest/userguide/cedar4-faq.md b/verifiedpermissions/latest/userguide/cedar4-faq.md index 029c867a0..85cc20cfc 100644 --- a//verifiedpermissions/latest/userguide/cedar4-faq.md +++ b//verifiedpermissions/latest/userguide/cedar4-faq.md @@ -5 +5 @@ -What is the current state on the upgrade?Do I need to do anything right now?Does the upgrade of the console impact the authorization service?What are the breaking changes in Cedar v3 and Cedar v4?When will the upgrade to Cedar v4 be complete? +Why are some policies, policy templates and schemas not compatible with Cedar 4? How do I tell whether my policy store is using Cedar 2 or Cedar 4? How do I upgrade to Cedar 4? Can I downgrade my policy store from Cedar 4 to Cedar 2? Why am I receiving an error message saying my policy store is configured for Cedar 2? How do I make my schema compatible with Cedar 4? @@ -7 +7 @@ What is the current state on the upgrade?Do I need to do anything right now?Does -# Amazon Verified Permissions upgrade to Cedar v4 FAQ +# Amazon Verified Permissions upgrade to Cedar 4 FAQ @@ -9 +9,3 @@ What is the current state on the upgrade?Do I need to do anything right now?Does -Amazon Verified Permissions is in the process of updating to Cedar v4. We're working to make this as seamless as possible for you. The following FAQs should answer your questions and help you prepare. +Amazon Verified Permissions is upgrading the version of Cedar it uses from version 2 to version 4. Cedar is the open-source language you use to write the policies, policy templates and schemas in your policy stores. With Cedar 4 support in Verified Permissions, you can use new features such as the `is` operator and entity tags to write more expressive policies. + +Amazon Verified Permissions is automatically upgrading policy stores to Cedar 4. However, some policies, schemas and authorization requests written for Cedar 2 are incompatible with Cedar 4. If this is the case for your policy store, then we will not upgrade it automatically. You may need to make changes to your policies, policy templates, schemas or application code before you can upgrade to Cedar 4. @@ -13 +15,7 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor - * What is the current state on the upgrade? + * Why are some policies, policy templates and schemas not compatible with Cedar 4? + + * How do I tell whether my policy store is using Cedar 2 or Cedar 4? + + * How do I upgrade to Cedar 4? + + * Can I downgrade my policy store from Cedar 4 to Cedar 2? @@ -15 +23 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor - * Do I need to do anything right now? + * Why am I receiving an error message saying my policy store is configured for Cedar 2? @@ -17 +25 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor - * Does the upgrade of the console impact the authorization service? + * How do I make my schema compatible with Cedar 4? @@ -19 +26,0 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor - * What are the breaking changes in Cedar v3 and Cedar v4? @@ -21 +27,0 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor - * When will the upgrade to Cedar v4 be complete? @@ -23,0 +30 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor +## Why are some policies, policy templates and schemas not compatible with Cedar 4? @@ -24,0 +32 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor +The Cedar team has made several backwards-incompatible changes since Cedar 2, to fix bugs and simplify the language. These changes include: @@ -26 +34 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor -## What is the current state on the upgrade? + * syntax changes for policies, policy templates and schemas @@ -28 +36 @@ Amazon Verified Permissions is in the process of updating to Cedar v4. We're wor -As a first step we've upgraded the console to use Cedar v4.3, however the back end is still running on Cedar v2.5.0. This means that while you can now use the console to author policies using new features like the `is` operator, when you attempt to save them you will still get an error until we complete the upgrade. + * a more precise policy validator, which detects more errors @@ -30 +38 @@ As a first step we've upgraded the console to use Cedar v4.3, however the back e -## Do I need to do anything right now? + * changes to the behaviour of built-in functions like `isInRange` @@ -32 +39,0 @@ As a first step we've upgraded the console to use Cedar v4.3, however the back e -**No**. You can start exploring Cedar v4 using the console, if you want, but don't need to do anything. @@ -34 +40,0 @@ As a first step we've upgraded the console to use Cedar v4.3, however the back e -## Does the upgrade of the console impact the authorization service? @@ -36 +41,0 @@ As a first step we've upgraded the console to use Cedar v4.3, however the back e -**No**. Prior to upgrading we will run tests to check that your policy store works correctly with Cedar v4. There are some minor breaking changes between v2.5.0 and v4.3, but it’s very unlikely that your policy store will be impacted. If it is, then your policy store will not be upgraded, and will continue to authorize using Cedar v2.5.0. Should this happen, we will reach out to explain any changes you need to make before being able to upgrade. @@ -38 +43 @@ As a first step we've upgraded the console to use Cedar v4.3, however the back e -## What are the breaking changes in Cedar v3 and Cedar v4? +For a full list of backwards-incompatible changes, look for items marked with `(*)` in the [Cedar changelog](https://github.com/cedar-policy/cedar/blob/main/cedar-policy/CHANGELOG.md). @@ -40 +45,3 @@ As a first step we've upgraded the console to use Cedar v4.3, however the back e -Breaking changes are identified in the [Cedar change log](https://github.com/cedar-policy/cedar/releases), marked with an `(*)`. +## How do I tell whether my policy store is using Cedar 2 or Cedar 4? + +You can check the version of Cedar your policy store uses using the Amazon Verified Permissions console, or using the GetPolicyStore operation. @@ -44 +51,112 @@ Breaking changes are identified in the [Cedar change log](https://github.com/ced -If your policy store is affected by breaking changes it won't be upgraded, and we'll work with you to update the policy store so it can be upgraded. +All policy stores in the same AWS account and region use the same version of Cedar. + +Console + + +###### To check the Cedar version of a policy store (console) + + 1. Sign in to the AWS Management Console and open the Amazon Verified Permissions console at [https://console.aws.amazon.com/verifiedpermissions/](https://console.aws.amazon.com/verifiedpermissions). + + 2. From the navigation pane, choose **Policy stores** and then choose the policy store that you want to check. + + 3. Choose **Settings** in the navigation pane. + + 4. In the **Details** box, locate the **Cedar version** field. + + + + +The field reads `CEDAR_2` if your policy store is using Cedar 2, and `CEDAR_4` if it uses Cedar 4. + +CLI + + +###### To check the Cedar version of a policy store (AWS CLI) + + 1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + + 2. Use the `get-policy-store` command. In the following example, replace `policy-store-id` with the identifier of your policy store: + + aws verifiedpermissions get-policy-store \ + --policy-store-id policy-store-id + + + + +The `cedarVersion` field in the output shows which version of Cedar the policy store is using. For example: + + + { + "policyStoreId": "ABCDEFG12345678abcdefg", + "arn": "arn:aws:verifiedpermissions::111122223333:policy-store/ABCDEFG12345678abcdefg", + "validationSettings": { + "mode": "STRICT" + }, + "createdDate": "2025-06-03T13:09:47.752255+00:00", + "lastUpdatedDate": "2025-06-03T13:09:47.752255+00:00", + "deletionProtection": "ENABLED", + "cedarVersion": "CEDAR_2" + } + +The field reads `CEDAR_2` if your policy store is using Cedar 2, and `CEDAR_4` if it uses Cedar 4. + +## How do I upgrade to Cedar 4? + +Amazon Verified Permissions has already upgraded most customers to Cedar 4. If you have never created a policy store, then any new policy stores you create will use Cedar 4. If you are an existing customer, then we have likely already upgraded you to Cedar 4. See How do I tell whether my policy store is using Cedar 2 or Cedar 4? to check which version of Cedar your policy stores use. + +If you have not been upgraded, then Verified Permissions detected a policy, policy template, schema or authorization request in one of your policy stores which is incompatible with Cedar 4. We will send you an email notification describing which resources are incompatible later in 2025. To upgrade sooner, open a case with Support. + +###### Important + +All policy stores in the same AWS account use the same version of Cedar. If one policy store in your account is incompatible with Cedar 4, then you can’t use Cedar 4 in any policy store in that account. + +## Can I downgrade my policy store from Cedar 4 to Cedar 2? + +No. If you experience issues after your policy store is upgraded to Cedar 4, open a case with Support. + +## Why am I receiving an error message saying my policy store is configured for Cedar 2? + +Some features of Amazon Verified Permissions rely on the new features in Cedar 4. If your policy store does not use Cedar 4, then you can’t use the following API fields: + + * In the IsAuthorized, BatchIsAuthorized, IsAuthorizedWithToken and BatchIsAuthorizedWithToken operations: + + * `datetime`, `decimal` or `duration` values in the `attributes` or `context` fields + + + + +You can’t use syntax or data types in policies, policy templates or schemas introduced after Cedar 2 until your policy store is upgraded. + +## How do I make my schema compatible with Cedar 4? + +You can use the code editor in the Verified Permissions console to see which errors are stopping your schema from being used with Cedar 4. + +###### Important + +The code editor in the Amazon Verified Permissions console always shows errors and warnings from Cedar 4, even if your policy store uses Cedar 2. You can continue to make schema updates that are not compatible with Cedar 4 using the **Save changes** button, or the Verified Permissions API. + +###### To view a schema's errors in the console + + 1. Sign in to the AWS Management Console and open the Amazon Verified Permissions console at [verifiedpermissions](https://console.aws.amazon.com/verifiedpermissions). + + 2. From the navigation pane, choose **Policy stores** and then choose the policy store you want to check. + + 3. Choose **Schema** in the navigation pane. + + 4. Choose **Edit schema**. + + 5. Select **JSON mode**. + + 6. Hover over the red error icon in the gutter on the left-hand side of the code editor. The error message is displayed in a tooltip. + + + + +Here are some common errors you may encounter and how to resolve them: + +**failed to parse schema from JSON: ``field-name``** + + +With Cedar 2, you can include arbitrary fields in parts of schemas like type definitions, even if they do not have any meaning as part of a Cedar schema. In Cedar 4, this is no longer permitted. To resolve this error, remove the field called `field-name` from your JSON schema. For a list of valid schema fields, see the [Cedar documentation](https://docs.cedarpolicy.com/schema/json-schema.html). + +**unknown extension type ``extension-name``** @@ -46 +163,0 @@ If your policy store is affected by breaking changes it won't be upgraded, and w -## When will the upgrade to Cedar v4 be complete? @@ -48 +165 @@ If your policy store is affected by breaking changes it won't be upgraded, and w -Our goal is for all accounts to be upgraded by December 31, 2025. +In Cedar 2, when you declare an attribute whose `type` is `Extension`, you can specify any value for the `name` field, whether or not the value is a valid extension type name. This is now an error with Cedar 4. To resolve it, replace `extension-name` with a valid extension type name. You can find a list of valid extension type names in the [Cedar documentation](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-extension).