From 91906c704097e606e1761787c8515b8c00516828 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Fri, 14 Nov 2025 12:37:01 +0100 Subject: [PATCH 1/7] improve Troubleshooting guide with example logs and more common root causes --- docs/Troubleshooting.md | 154 ++++++++++++++++++++++++++++++++++------ 1 file changed, 131 insertions(+), 23 deletions(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 384a922..273f555 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -19,53 +19,161 @@ Refer to the **[Testing Guide](/Authorization/Testing)** for guidance. ### Step 2: Analyze Authorization Check -Reproduce the issue and check which part of the authorization check doesn't meet your expectations: +Reproduce the issue and check the debug logs to see which part of the authorization check doesn't meet your expectations. + +#### CAP role check + +In CAP applications, the following output is expected when the AMS plugin determines cds roles from authorization policies: + +::: code-group +```bash [Node.js] +[ams] - Determined potential actions for resource '$SCOPES': Reader { + resource: '$SCOPES', + potentialActions: Set(1) { 'Reader' }, + policies: [ 'local.JuniorReader' ], + limitingPolicies: [ 'internal.ReadCatalog' ], + correlation_id: '057c0278-1d2f-4797-8762-435e948db42d' + } +``` + +```text [Java] +An example for debug log output in Java is coming soon. +``` +::: + +- Which **principal**/**policies** was used? -> `local.JuniorReader` +- Which **roles** have been granted? -> `Reader` +- Has any customization logic been applied that influenced the check, such as technical communication logic? -> yes, the `internal.ReadCatalog` policy is used as an upper limit for the roles due to consumption of an App-to-App provided API that was mapped to this policy. + +::: info +If the CAP application uses `@ams.attributes` annotations for instance-based authorization, additional [generic privilege checks](#generic-privilege-check) are logged per role to determine the filter conditions. +::: -- Which **action** is checked on which **resource**? -- Which **principal**/**policies** was used? -- Which **attribute input** was provided? -- What was the resulting **DCN condition** from the authorization engine? -- Has any customization logic been applied that influenced the check, such as technical communication logic? +#### Generic Privilege check + +::: code-group +```bash [Node.js] +[ams] - Privilege check for 'Reader' on '$SCOPES' was conditional. { + action: 'Reader', + resource: '$SCOPES', + input: {}, + defaultInput: { '$user.scim_id': 'principalPropagation' }, + result: 'conditional', + dcn: "($app.genre IN ['Fantasy', 'Fairy Tale', 'Mystery'] AND $app.stock < 30)", + policies: [ 'local.JuniorReader' ], + limitingPolicies: [ 'internal.ReadCatalog' ], + correlation_id: '057c0278-1d2f-4797-8762-435e948db42d' + } +``` + +```text [Java] +An example for debug log output in Java is coming soon. +As of today, the logs show the content of the Attributes object. +The limiting policies can be inferred from the scopeFilter property. +``` + +::: + +- Which **action** is checked on which **resource**? -> `Reader` on `$SCOPES` +::: tip CAP applications +The action in CAP application is the cds role name for which a check is performed. +The resource is always the special resource [`$SCOPES`](/CAP/Basics#role-policies) and *not* the entity name. +::: +- Which **principal**/**policies** was used? -> `local.JuniorReader` +- Which **attribute input** was provided? -> no check-spefific input, only default input for `$user.scim_id` +- What was the resulting **DCN condition** from the authorization engine? -> `($app.genre IN ['Fantasy', 'Fairy Tale', 'Mystery'] AND $app.stock < 30)` +- Has any customization logic been applied that influenced the check, such as technical communication logic? -> yes, the `internal.ReadCatalog` policy is used as an upper limit for the permissions due to consumption of an App-to-App provided API that was mapped to this policy. ### Step 3: Check for Common Root Causes -The following are common root causes for authorization problems: +In case your logs contain unexpected information, check for explanations in the common root causes below before opening a new ticket. + +### Step 4: Solving the Issue + +If you've identified a misconfiguration or a setup issue in your application, try to resolve the issue based on your findings and the documentation. + +::: info Consulting +If you need help with fixing your application setup, this is a **consulting** request. +::: + +For both consulting and issues inside the AMS modules or services, such as bugs or outages, please refer to our **[Support Guide](/Support)** for how to get help. + + + +## Common Root Causes ### Unexpected `403 Forbidden` -- **Outdated Dependencies**: Ensure that you are using the correct combination of the Authorization Management Service (**AMS**) modules for your project setup and in the latest versions as recommended in the **[Getting Started Guide](/Authorization/GettingStarted.md)**. -- **Caching Delays**: Policy assignment changes usually take up to 15 seconds to propagate due to caching (but can sometimes take longer). Wait a moment before retrying. +#### Outdated Dependencies + +Ensure that you are using the correct combination of the Authorization Management Service (**AMS**) modules for your project setup and in the latest versions as recommended in the **[Getting Started Guide](/Authorization/GettingStarted.md)**. + +#### Wrong policies used + +You should see debug output like this that shows how the list of policies for an authorization check was determined: + +::: code-group +```bash [Node.js] +[ams] - User with scim_id 7c1d5056-b334-44ab-b2e1-14afba1f3b8b in tenant 93127375-beab-43c7-b5a8-c1bc2265997d has the following assigned policies: [ 'local.JuniorReader' ] +``` + +```text [Java] +An example for debug log output in Java is coming soon. +``` +::: + +If the policies listed here do not match your expectations, double-check the assignment of the policies in the administration console. + +Check that the application successfully received a bundle update from the AMS server after a short waiting period. +Policy assignment changes usually take up to 15 seconds to propagate due to caching (but can sometimes take longer). Wait a moment before retrying. ::: warning Missing policy assignments in Token -The policies that are assigned to a user are **not** contained in his SCI user tokens. This is normal. +As of today, the policies that are assigned to a user are **not** contained in his SCI user tokens. This is normal. A token refresh is **NOT** necessary after making changes to policy assignments. The AMS module retrieves the user policies separately from the token directly from the AMS server. ::: -- **Incorrect Policy Names**: Policies must be **fully-qualified**, including the DCL package name (for example, `cap.Reader`). This applies to: +If the policies listed here are different from the ones used for the authorization check (see Step 2), check for any customization logic that modifies the policies used for the check, such as overridden `AuthProvider` logic or an `AttributeProcessor` implementation in Java. + +#### Unexpected limiting policies + +##### Typo in API names + +Make sure there are no typos in API names in the mapping functions. + +::: warning +If you want to enable the special [`principal-propagation`](/Authorization/TechnicalCommunication#authorization-via-api-permission-groups) API, make sure to name it correctly. The name is case-sensitive and must be exactly `principal-propagation` and *not* `principle-propagation`. +::: + +##### Incorrect Policy Names +Policy names must be **fully-qualified**, including the DCL package name (for example, `cap.Reader`). This applies to: - Mocked policy assignments in tests. - Policy mappings for technical communication. -#### Unexpected `Access Granted` +### Unexpected `2xx` Response + +If you receive an unexpected successful response (HTTP 2xx) when you expect a `403 Forbidden`, check the following common root causes: + +#### Left-over policy assignments - A user might have multiple policies assigned that grant the same privilege. Ensure you've unassigned all of them before testing that a specific policy doesn't grant access. -#### Authorization bundle issues +#### Non-AMS authorization logic -- **No authorization data loaded error**: The application must wait for the **[AMS Startup Check](/Authorization/StartupCheck)** before making authorization checks. +Check if there is any non-AMS authorization logic in your application that could grant access independently from AMS policies. -::: warning -The startup check is also necessary before unit tests that perform authorization checks. -::: +For example, the standard CAP authentication handlers use the list of ias_apis to automatically grant cds roles with the same name in case of technical user tokens. -- **Incorrect Test Setup**: Make sure to follow the **[Testing Guide](/Authorization/Testing.md)** carefully by including all steps, such as DCN compilation and DCN loading. +### Unexpected HTTP response in CAP applications -### Step 4: Solving the Issue +The AMS CAP plugins are not responsible for the HTTP response codes or messages returned by the application. Instead, they integrate into the CAP framework itself, e.g. by providing user roles and filter conditions, but it is the framework itself which decides whether requests are forbidden and with which message. In particular, users may receive roles from other sources than the AMS plugin, which can therefore lead to access being granted even though the roles from the AMS plugin would not grant access. -If you've identified a misconfiguration or a setup issue in your application, try to resolve the issue based on your findings and the documentation. +### Authorization bundle issues -::: info Consulting -If you need help with fixing your application setup, this is a **consulting** request. +- **No authorization data loaded error**: The application must wait for the **[AMS Startup Check](/Authorization/StartupCheck)** before making authorization checks. + +::: warning +The startup check is also necessary before unit tests that perform authorization checks. ::: -For both consulting and issues inside the AMS modules or services, such as bugs or outages, please refer to our **[Support Guide](/Support)** for how to get help. \ No newline at end of file +- **Incorrect Test Setup**: Make sure to follow the **[Testing Guide](/Authorization/Testing.md)** carefully by including all steps, such as DCN compilation and DCN loading. \ No newline at end of file From ec203675838dc0fddbb47ea00bb7586805ce5d38 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Fri, 14 Nov 2025 12:40:09 +0100 Subject: [PATCH 2/7] replace $user.scim id with realistic example in debug log --- docs/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 273f555..52c974b 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -57,7 +57,7 @@ If the CAP application uses `@ams.attributes` annotations for instance-based aut action: 'Reader', resource: '$SCOPES', input: {}, - defaultInput: { '$user.scim_id': 'principalPropagation' }, + defaultInput: { '$user.scim_id': '7c1d5056-b334-44ab-b2e1-14afba1f3b8b' }, result: 'conditional', dcn: "($app.genre IN ['Fantasy', 'Fairy Tale', 'Mystery'] AND $app.stock < 30)", policies: [ 'local.JuniorReader' ], From 81fd51d89e0c2be0bf810087030fff1af4b0c941 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Tue, 24 Feb 2026 16:13:10 +0100 Subject: [PATCH 3/7] add Java examples --- docs/Troubleshooting.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 52c974b..2454ba4 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -36,8 +36,14 @@ In CAP applications, the following output is expected when the AMS plugin determ } ``` -```text [Java] -An example for debug log output in Java is coming soon. +```java [Java] +[main] DEBUG c.s.c.s.a.e.AuthorizationCheckEvent -- GetPotentialActionsEvent { + "policies" : [ "local.JuniorReader" ], + "limitingPolicies" : [ ], + "description" : "Determined potential actions for resource '$SCOPES': Reader", + "resource" : "$SCOPES", + "potentialActions" : [ "Reader" ] +} ``` ::: @@ -66,10 +72,18 @@ If the CAP application uses `@ams.attributes` annotations for instance-based aut } ``` -```text [Java] -An example for debug log output in Java is coming soon. -As of today, the logs show the content of the Attributes object. -The limiting policies can be inferred from the scopeFilter property. +```java [Java] +[main] DEBUG c.s.c.s.a.e.AuthorizationCheckEvent -- PrivilegeCheckEvent { + "policies" : [ "local.JuniorReader" ], + "limitingPolicies" : [ "internal.ReadCatalog" ], + "description" : "Privilege check for 'Reader' on '$SCOPES' was conditional.", + "action" : "Reader", + "resource" : "$SCOPES", + "result" : "CONDITIONAL", + "dcn" : "Genre ['Fantasy', 'Fairy Tale', 'Mystery'] AND stock < 30", + "input" : { }, + "defaultInput" : { } +} ``` ::: From 05520402919d54e2c15d578f10a4b2e80dccfe88 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Tue, 24 Feb 2026 16:16:40 +0100 Subject: [PATCH 4/7] add Java example log for policy assignment --- docs/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 2454ba4..4982a21 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -132,7 +132,7 @@ You should see debug output like this that shows how the list of policies for an ``` ```text [Java] -An example for debug log output in Java is coming soon. +[main] DEBUG c.s.c.s.a.c.IasAuthorizationsProvider -- User with scim_id mock/stock-manager-fiction in tenant null has the following assigned policies: [local.StockManagerFiction] ``` ::: From e164e8ffb94104a05601c2998a60d8c8c5665ecc Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Tue, 24 Feb 2026 16:28:31 +0100 Subject: [PATCH 5/7] remove concrete time estimate --- docs/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 4982a21..1affa8b 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -139,7 +139,7 @@ You should see debug output like this that shows how the list of policies for an If the policies listed here do not match your expectations, double-check the assignment of the policies in the administration console. Check that the application successfully received a bundle update from the AMS server after a short waiting period. -Policy assignment changes usually take up to 15 seconds to propagate due to caching (but can sometimes take longer). Wait a moment before retrying. +Policy assignment changes are an asynchronous operation that takes some time to propagate to the application. Wait some time before retrying. ::: warning Missing policy assignments in Token As of today, the policies that are assigned to a user are **not** contained in his SCI user tokens. This is normal. From 6db5901f02a65849548077857dd94f7a251b7499 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Tue, 24 Feb 2026 16:28:58 +0100 Subject: [PATCH 6/7] add "up to a few minutes" --- docs/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 1affa8b..c9459eb 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -139,7 +139,7 @@ You should see debug output like this that shows how the list of policies for an If the policies listed here do not match your expectations, double-check the assignment of the policies in the administration console. Check that the application successfully received a bundle update from the AMS server after a short waiting period. -Policy assignment changes are an asynchronous operation that takes some time to propagate to the application. Wait some time before retrying. +Policy assignment changes are an asynchronous operation that takes some time to propagate to the application. Wait up to a few minutes before retrying. ::: warning Missing policy assignments in Token As of today, the policies that are assigned to a user are **not** contained in his SCI user tokens. This is normal. From b2d6361174203c138c273fdbf1a36c5ecd1179f9 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Tue, 24 Feb 2026 16:36:10 +0100 Subject: [PATCH 7/7] harmonize assignment example log --- docs/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index c9459eb..1085fe4 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -132,7 +132,7 @@ You should see debug output like this that shows how the list of policies for an ``` ```text [Java] -[main] DEBUG c.s.c.s.a.c.IasAuthorizationsProvider -- User with scim_id mock/stock-manager-fiction in tenant null has the following assigned policies: [local.StockManagerFiction] +[main] DEBUG c.s.c.s.a.c.IasAuthorizationsProvider -- User with scim_id 7c1d5056-b334-44ab-b2e1-14afba1f3b8b in tenant 93127375-beab-43c7-b5a8-c1bc2265997d has the following assigned policies: [local.JuniorReader] ``` :::