Skip to content

Improve Troubleshooting guide #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
finkmanAtSap wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Improve Troubleshooting guide #18

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91906c7
improve Troubleshooting guide with example logs and more common root …
finkmanAtSap Nov 14, 2025
ec20367
replace $user.scim id with realistic example in debug log
finkmanAtSap Nov 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 131 additions & 23 deletions docs/Troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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': '7c1d5056-b334-44ab-b2e1-14afba1f3b8b' },
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.
- **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.