From 540744cedc0f1149ff03c35fc89c94c05f07c20e Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Mon, 8 Dec 2025 17:09:07 +0100 Subject: [PATCH 1/2] ChangingDcl --- docs/.vitepress/config.js | 1 + docs/Authorization/ChangingDCL.md | 69 +++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 docs/Authorization/ChangingDCL.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 9d49e9e..3a206df 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -37,6 +37,7 @@ export default defineConfig(withMermaid({ { text: 'Testing', link: '/Authorization/Testing' }, { text: 'Technical Communication', link: '/Authorization/TechnicalCommunication' }, { text: 'Deploying DCL', link: '/Authorization/DeployDCL' }, + { text: 'Changing DCL', link: '/Authorization/ChangingDCL' }, { text: 'Value Help', link: '/Authorization/ValueHelp' }, { text: 'Logging', link: '/Authorization/Logging' }, ] diff --git a/docs/Authorization/ChangingDCL.md b/docs/Authorization/ChangingDCL.md new file mode 100644 index 0000000..c3fa6b4 --- /dev/null +++ b/docs/Authorization/ChangingDCL.md @@ -0,0 +1,69 @@ +# Changing DCL + +Once your application is delivered and in use (especially for multi-tenant applications), any changes to the Authorization model must be done with special care. + +## Allowed Changes + +The following changes are currently allowed: + +- Adding new policies +- Adding new schema attributes +- Changing actions and resources\* of policies +- Changing conditions of existing policies\* + - **Exception**: `IS [NOT] RESTRICTED` conditions may not be removed as that will break admin policies which restrict these attributes. + +\* In applications with multiple microservices, it is important that all microservices can handle the refactoring, see [Migration Strategy](#migration-strategy). + +## Forbidden Changes + +The following changes will lead to errors in admin policies that re-use the affected base policies. + +- Deleting policies +- Renaming policies (equivalent to deleting and adding new policy) +- Moving policies to a different package (equivalent to renaming) +- Moving policies to a different file in the same package +- Renaming DCL files (equivalent to moving policies to a different file) +- Deleting `IS (NOT) RESTRICTED` conditions from a policy. +- Adding or removing the ```DEFAULT``` keyword of policies. +- Adding or removing the ```INTERNAL``` keyword of policies. + +## Consequences of Forbidden Changes + +Admin policies with errors, e.g. an invalid reference to a base policy that has been deleted, are removed from the authorization bundle. +Users that had these policies assigned will effectively lose these authorizations after the policy deployment is mirrored to applications. +Policies with errors will be shown to the Administrator in the administration console of SAP Cloud Identity Services inside the authorization policies of the application. +These policies can then be corrected or removed. + +Example for a forbidden change that would **break** admin policies: + +**Policy before upgrade** +```sql +POLICY ReadSalesOrders { + GRANT read ON SalesOrders WHERE Country IS NOT RESTRICTED; +} +``` + +**Policy after upgrade** +```sql +POLICY ReadSalesOrders { + GRANT read ON SalesOrders WHERE CustomerCountry IS NOT RESTRICTED; +} +``` + +**Broken admin policy built on top of the base policy** +```sql +POLICY salesOrderRestricted { + USE shopping.ReadSalesOrders + RESTRICT Country = 'DE'; -- ⚡️⚡️⚡️ +} +``` + +Forbidden changes are not technically prevented. Please take utmost care when changing the delivered +policies. If you need to do any changes, you must inform your customers and allow a migration period. + +## Migration Strategy +Internal changes, such as changing actions, resources, or conditions, can be achieved in a three-step process if there are multiple microservices involved: + +1. Add the new *actions*/*resources*/*conditions* as an additional grant to the affected base policy. +2. Migrate the microservices individually to check for the new *actions*/*resources*/*conditions*. +3. Remove the grants with the old *actions*/*resources*/*conditions* from the affected base policy. \ No newline at end of file From 862fbd62979b9caf48ab1f0d7d0ad15a5a7d932e Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Mon, 8 Dec 2025 17:13:29 +0100 Subject: [PATCH 2/2] highlight warning --- docs/Authorization/ChangingDCL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/Authorization/ChangingDCL.md b/docs/Authorization/ChangingDCL.md index c3fa6b4..52254e6 100644 --- a/docs/Authorization/ChangingDCL.md +++ b/docs/Authorization/ChangingDCL.md @@ -58,8 +58,10 @@ POLICY salesOrderRestricted { } ``` +::: warning Forbidden changes are not technically prevented. Please take utmost care when changing the delivered policies. If you need to do any changes, you must inform your customers and allow a migration period. +::: ## Migration Strategy Internal changes, such as changing actions, resources, or conditions, can be achieved in a three-step process if there are multiple microservices involved: