` is relevant for instance-based filters.
## Instance-Based Access Control { #instance-based-auth }
The [restrict annotation](#restrict-annotation) for an entity allows you to enforce authorization checks that statically depend on the event type and user roles.
In addition, you can define a `where`-condition that further limits the set of accessible instances.
This condition, that acts like a filter, establishes *instance-based authorization*.
### Filter Conditions
For instance, a user is allowed to read or edit `Orders` (defined with the `managed` aspect) that they have created:
```cds
annotate Orders with @(restrict: [
{ grant: ['READ', 'UPDATE', 'DELETE'], where: (CreatedBy = $user) } ]);
```
Or a `Vendor` can only edit articles on stock (that means `Articles.stock` positive):
```cds
annotate Articles with @(restrict: [
{ grant: ['UPDATE'], to: 'Vendor', where: (stock > 0) } ]);
```
::: tip
Filter conditions declared as **compiler expressions** ensure validity at compile time and therefore strengthen security.
:::
The condition defined in the `where` clause typically associates domain data with static [user claims](cap-users#claims).
Basically, it *either filters the result set in queries or accepts only write operations on instances that meet the condition*.
This means that, the condition applies to following standard CDS events only:
- `READ` (as result filter)
- `UPDATE` (as reject condition)
- `DELETE` (as reject condition)
In addition, the runtime [checks the filter condition of the input data](#input-data-auth) for following standard CDS events:
- `CREATE` (input filter)
- `UPDATE` (input filer)
You can define filter conditions in the `where`-clause of restrictions based on [CQL](/cds/cql)-predicates, declared as [compiler expressions](../../cds/cdl#expressions-as-annotation-values):
* Predicates with arithmetic operators.
* Combining predicates to expressions with `and` and `or` logical operators.
* Value references to constants, [user attributes](#user-attrs), and entity data (elements including [association paths](#association-paths))
* [Exists predicate](#exists-predicate) based on subselects.
* [Exists with a subquery](#exists-subquery) for access to ACL like entities.
At runtime you'll find filter predicates attached to the appropriate CQN queries matching the instance-based condition.
:::warning Modification of Statements
Be careful when you modify or extend the statements in custom handlers.
Make sure you keep the filters for authorization.
:::
#### User Attributes { #user-attrs}
To refer to attribute values from the user claim, prefix the attribute name with '`$user.`' as outlined in [static user claims](cap-users#claims). For instance, `$user.country` refers to the attribute with the name `country`.
In general, `$user.` contains a **list of attribute values** that are assigned to the user. The following rules apply:
* A predicate in the `where` clause evaluates to `true` if one of the attribute values from the list matches the condition.
* An empty (or not defined) list means that the user is fully restricted with regard to this attribute (that is, the predicate evaluates to `false`).
For example, the condition `where: $user.country = countryCode` will grant a user with attribute values `country = ['DE', 'FR']` access to entity instances that have `countryCode = DE` _or_ `countryCode = FR`. In contrast, the user has no access to any entity instances if the value list of country is empty or the attribute is not available at all.
##### Unrestricted XSUAA Attributes
By default, all attributes defined in [XSUAA instances](./cap-users#xsuaa-roles) require a value (`valueRequired:true`), which is well-aligned with the CAP runtime that enforces restrictions on empty attributes.
If you explicitly want to offer unrestricted attributes to customers, you need to do the following:
1. Switch your XSUAA configuration to `valueRequired:false`
2. Adjust the filter-condition accordingly, for example: `where: $user.country = countryCode or $user.country is null`.
> If `$user.country` is undefined or empty, the overall expression evaluates to `true`, reflecting the unrestricted attribute.
::: warning
Refrain from unrestricted XSUAA attributes as they need to be designed very carefully as shown in the following example.
:::
Consider this bad example with *unrestricted* attribute `country` (assuming `valueRequired:false` in XSUAA configuration):
```cds
service SalesService @(requires: ['SalesAdmin', 'SalesManager']) {
entity SalesOrgs @(restrict: [
{ grant: '*',
to: ['SalesAdmin', 'SalesManager'],
where: ($user.country = countryCode or $user.country is null) } ]) {
countryCode: String; /*...*/
}
}
```
Let's assume a customer creates XSUAA roles `SalesManagerEMEA` with dedicated values (`['DE', 'FR', ...]`) and `SalesAdmin` with *unrestricted* values.
As expected, a user assigned only to `SalesAdmin` has access to all `SalesOrgs`. But when role `SalesManagerEMEA` is added, *only* EMEA organizations are accessible suddenly!
The preferred way is to model with restricted attribute `country` (`valueRequired:true`) and an additional grant:
```cds
service SalesService @(requires: ['SalesAdmin', 'SalesManager']) {
entity SalesOrgs @(restrict: [
{ grant: '*',
to: 'SalesManager',
where: ($user.country = countryCode) },
{ grant: '*',
to: 'SalesAdmin' } ]) {
countryCode: String; /*...*/
}
}
```
#### Exists Predicate { #exists-predicate }
In many cases, the authorization of an entity needs to be derived from entities reachable via association path. See [domain-driven authorization](#domain-driven-authorization) for more details.
You can leverage the `exists` predicate in `where` conditions to define filters that directly apply to associated entities defined by an association path:
```cds
service ProjectService @(requires: 'authenticated-user') {
entity Projects @(restrict: [
{ grant: ['READ', 'WRITE'],
where: (exists members[userId = $user and role = 'Editor']) } ]) {
members: Association to many Members; /*...*/
}
@readonly entity Members {
key userId : User;
key role: String enum { Viewer; Editor; }; /*...*/
}
}
```
In the `ProjectService` example, only projects for which the current user is a member with role `Editor` are readable and editable. Note that with exception of the user ID (`$user`) **all authorization information originates from the business data**.
Supported features of `exists` predicate:
* Combine with other predicates in the `where` condition (`where: 'exists a1[...] or exists a2[...]`).
* Define recursively (`where: 'exists a1[exists b1[...]]`).
* Use target paths (`where: 'exists a1.b1[...]`).
* Usage of [user attributes](#user-attrs).
::: warning
Paths *inside* the filter (`where: (exists a1[b1.c = ...])`) are not yet supported.
:::
The following example demonstrates the last two features:
```cds
service ProductsService @(requires: 'authenticated-user') {
entity Products @(restrict: [
{ grant: '*',
where: (exists producers.division[$user.division = name])}]): cuid {
producers : Association to many ProducingDivisions
on producers.product = $self;
}
@readonly entity ProducingDivisions {
key product : Association to Products;
key division : Association to Divisions;
}
@readonly entity Divisions : cuid {
name : String;
producedProducts : Association to many ProducingDivisions
on producedProducts.division = $self;
}
}
```
Here, the authorization of `Products` is derived from `Divisions` by leveraging the *n:m relationship* via entity `ProducingDivisions`. Note that the path `producers.division` in the `exists` predicate points to target entity `Divisions`, where the filter with the user-dependent attribute `$user.division` is applied.
::: warning Consider Access Control Lists
Be aware that deep paths might introduce a performance bottleneck. Access Control List (ACL) tables, managed by the application, allow efficient queries and might be the better option in this case.
:::
### Association Paths { #association-paths}
The `where`-condition in a restriction can also contain [CQL path expressions](../../cds/cql#path-expressions) that navigate to elements of associated entities:
```cds
service SalesOrderService @(requires: 'authenticated-user') {
entity SalesOrders @(restrict: [
{ grant: 'READ',
where: (product.productType = $user.productType) } ]) {
product: Association to one Products;
}
entity Products {
productType: String(32); /*...*/
}
}
```
Paths on 1:n associations (`Association to many`) evaluate to `true`, _if the condition selects at most one associated instance_ (`exists` semantic).
### Checking Input Data { #input-data-auth .java}
Input data of `CREATE` and `UPDATE` events is also validated with regards to instance-based authorization conditions.
Invalid input that does not meet the condition is rejected with response code `400`.
Let's assume an entity `Orders` that restricts access to users classified by assigned accounting areas:
```cds
annotate Orders with @(restrict: [
{ grant: '*', where: 'accountingArea = $user.accountingAreas' } ]);
```
A user with accounting areas `[Development, Research]` is not able to send an `UPDATE` request, that changes `accountingArea` from `Research` or `Development` to `CarFleet`, for example.
Note that the `UPDATE` on instances _not matching the request user's accounting areas_ (for example, `CarFleet`) are rejected by standard instance-based authorization checks.
Starting with CAP Java `4.0`, deep authorization is active by default.
It can be disabled by setting cds.security.authorization.instanceBased.checkInputData: false.
### Rejected Entity Selection { #reject-403 .java}
Entities that have an instance-based authorization condition, that is [`@restrict.where`](/guides/security/authorization#restrict-annotation),
are guarded by the CAP Java runtime by adding a filter condition to the DB query **excluding not matching instances from the result**.
Hence, if the user isn't authorized to query an entity, requests targeting a *single* entity return *404 - Not Found* response and not *403 - Forbidden*.
To allow the UI to distinguish between *not found* and *forbidden*, CAP Java can detect this situation and rejects `UPDATE` and `DELETE` requests to single entities with forbidden accordingly.
The additional authorization check might affect performance.
::: warning Avoid enumerable keys
To avoid disclosure of the existence of such entities to unauthorized users, make sure that the key is not efficiently enumerable or add custom code to overrule the default behavior otherwise.
:::
Starting with CAP Java `4.0`, the reject behaviour is active by default.
It can be disabled by setting cds.security.authorization.instance-based.reject-selected-unauthorized-entity.enabled: false.
## Limitations {.node}
Currently, the security annotations **are only evaluated on the target entity of the request**.
Restrictions on associated entities touched by the operation are not regarded.
This has the following implications:
- Restrictions of (recursively) expanded or inlined entities of a `READ` request aren't checked.
- Deep inserts and updates are checked on the root entity only.
See [solution sketches](#limitation-deep-authorization) for information about how to deal with that.
## Deep Authorizations { #deep-auth .java}
### Associations
Queries to Application Services are not only authorized by the target entity that has a `@restrict` or `@requires` annotation, but also for all __associated entities__ that are used in the statement.
For instance, consider the following model:
```cds
@(restrict: [{ grant: 'READ', to: 'Manager' }])
entity Books {...}
@(restrict: [{ grant: 'READ', to: 'Manager' }])
entity Orders {
key ID: String;
items: Composition of many {
key book: Association to Books;
quantity: Integer;
}
}
```
For the following OData request `GET Orders(ID='1')/items?$expand=book`, authorizations for `Orders` and for `Books` are checked.
If the entity `Books` has a `where` clause for instance-based authorization, it will be added as a filter to the sub-request with the expand.
Custom CQL statements submitted to the [Application Service](../../java/cqn-services/application-services) instances are also authorized by the same rules including the path expressions and subqueries used in them.
For example, the following statement checks role-based authorizations for both `Orders` and `Books`,
because the association to `Books` is used in the select list.
```java
Select.from(Orders_.class,
f -> f.filter(o -> o.ID().eq("1")).items())
.columns(c -> c.book().title());
```
For modification statements with associated entities used in infix filters or where clauses,
role-based authorizations are checked as well.
Associated entities require `READ` authorization, in contrast to the target of the statement itself.
The following statement requires `UPDATE` authorization on `Orders` and `READ` authorization on `Books`
because an association from `Orders.items` to the book is used in the where condition.
```java
Update.entity(Orders_.class, f -> f.filter(o -> o.ID().eq("1")).items())
.data("quantity", 2)
.where(t -> t.book().ID().eq(1));
```
Starting with CAP Java `4.0`, deep authorization is active by default.
It can be disabled by setting cds.security.authorization.deep.enabled: false.
### Compositions
Restrictions on associated composition entities touched by the request are **not** regarded by the runtime.
The rational behind that is that authorization rules are [implicitly defined by the root entity of the document](#autoexposed-restrictions) and therefore security annotations **of the composition root entity are evaluated**.
This has the following implications:
- Restrictions of (recursively) expanded or inlined entities of a `READ` request aren't checked.
- Deep `INSERT`s and `UPDATE`s are checked on the root entity only.
::: warning
**Restrictions on compositions are not checked by the runtime**.
If you model dedicated restriction rules on child entity level, you need to add custom authorization handlers accordingly.
:::
## Best Practices
CAP authorization allows you to control access to your business data on a fine granular level. But keep in mind that the high flexibility can end up in security vulnerabilities if not applied appropriately. In this perspective, lean and straightforward models are preferred. When modeling your access rules, the following recommendations can support you to design such models.
### Choose Conceptual Roles
When defining user roles, one of the first options could be to align roles to the available *operations* on entities, which results in roles such as `SalesOrders.Read`, `SalesOrders.Create`, `SalesOrders.Update`, and `SalesOrders.Delete`.
What is the problem with this approach? Think about the resulting number of roles that the user administrator has to handle when assigning them to business users. The administrator would also have to know the domain model precisely and understand the result of combining the roles. Similarly, assigning roles to operations only (`Read`, `Create`, `Update`, ...) typically doesn't fit your business needs.
We strongly recommend defining roles that describe **how a business user interacts with the system**. Roles like `Vendor`, `Customer`, or `Accountant` can be appropriate. With this approach, you as the application developer define the set of accessible resources in the CDS model for each role - and not the user administrator.
### Prefer Single-Purposed, Use-Case Specific Services { #dedicated-services}
Have a closer look at this example:
```cds
service CatalogService @(requires: 'authenticated-user') {
entity Books @(restrict: [
{ grant: 'READ' },
{ grant: 'WRITE', to: 'Vendor', where: ($user.publishers = publisher) },
{ grant: 'WRITE', to: 'Admin' } ])
as projection on db.Books;
action doAccounting @(requires: ['Accountant', 'Admin']) ();
}
```
Four different roles (`authenticated-user`, `Vendor`, `Accountant`, `Admin`) *share* the same service - `CatalogService`. As a result, it's confusing how a user can use `Books` or `doAccounting`. Considering the complexity of this small example (4 roles, 1 service, 2 resources), this approach can introduce a security risk, especially if the model is larger and subject to adaptation. Moreover, UIs defined for this service will likely appear unclear as well.
The fundamental purpose of services is to expose business data in a specific way. Hence, the more straightforward way is to **use a service for each role**:
```cds
@path:'browse'
service CatalogService @(requires: 'authenticated-user') {
@readonly entity Books
as select from db.Books { title, publisher, price };
}
@path:'internal'
service VendorService @(requires: 'Vendor') {
entity Books @(restrict: [
{ grant: 'READ' },
{ grant: 'WRITE', to: 'vendor', where: ($user.publishers = publisher) } ])
as projection on db.Books;
}
@path:'internal'
service AccountantService @(requires: 'Accountant') {
@readonly entity Books as projection on db.Books;
action doAccounting();
}
/*...*/
```
::: tip
You can tailor the exposed data according to the corresponding role, even on the level of entity elements like in `CatalogService.Books`.
:::
### Prefer Dedicated Actions for Specific Use-Cases { #dedicated-actions}
In some cases it can be helpful to restrict entity access as much as possible and create actions with dedicated restrictions for specific use cases, like in the following example:
```cds
service GitHubRepositoryService @(requires: 'authenticated-user') {
@readonly entity Organizations as projection on GitHub.Organizations actions {
@(requires: 'Admin') action rename(newName : String);
@(requires: 'Admin') action delete();
};
}
```
This service allows querying organizations for all authenticated users. In addition, `Admin` users are allowed to rename or delete.
Granting `UPDATE` to `Admin` would allow administrators to change organization attributes that are not meant to change.
### Think About Domain-Driven Authorization { #domain-driven-authorization}
Static roles often don't fit into an intuitive authorization model. Instead of making authorization dependent on static properties of the user, it's often more appropriate to derive access rules from the business domain. For instance, all users assigned to a department (in the domain) are allowed to access the data of the organization comprising the department. Relationships in the entity model (for example, a department assignment to organization) influence authorization rules at runtime. In contrast to static user roles, **dynamic roles** are fully domain-driven.
Revisit the [ProjectService example](#exists-predicate), which demonstrates how to leverage instance-based authorization to induce dynamic roles.
Advantages of dynamic roles are:
- The most flexible way to define authorizations
- Authorizations induced according to business domain
- Application-specific authorization model and intuitive UIs
- Decentralized role management for application users (no central user administrator required)
Drawbacks to be considered are:
- Additional effort for modeling and designing application-specific role management (entities, services, UI)
- Potentially higher security risk due to lower use of framework functionality
- Sharing authorization management with other (non-CAP) applications is harder to achieve
- Dynamic role enforcement can introduce a performance penalty
### Control Exposure of Associations and Compositions { #limitation-deep-authorization}
Note that exposed associations (and compositions) can disclose unauthorized data. Consider the following scenario:
```cds
namespace db;
entity Employees : cuid { // autoexposed!
name: String(128);
team: Association to Teams;
contract: Composition of Contracts;
}
entity Contracts @(requires:'Manager') : cuid { // autoexposed!
salary: Decimal;
}
entity Teams : cuid {
members: Composition of many Employees on members.team = $self;
}
service ManageTeamsService @(requires:'Manager') {
entity Teams as projection on db.Teams;
}
service BrowseEmployeesService @(requires:'Employee') {
@readonly entity Teams as projection on db.Teams; // navigate to Contracts!
}
```
A team (entity `Teams`) contains members of type `Employees`. An employee refers to a single contract (entity `Contracts`) that contains sensitive information that should be visible only to `Manager` users.
`Employee` users should be able to browse the teams and their members but are not allowed to read or even edit their contracts.
As `db.Employees` and `db.Contracts` are auto-exposed, managers can navigate to all instances through the `ManageTeamsService.Teams` service entity (for example, OData request `/ManageTeamsService/Teams?$expand=members($expand=contract)`).
It's important to note that this also holds for an `Employee` user, as **only the target entity** `BrowseEmployeesService.Teams` **has to pass the authorization check in the generic handler, and not the associated entities**.
To solve this security issue, introduce a new service entity `BrowseEmployeesService.Employees` that removes the navigation to `Contracts` from the projection:
```cds
service BrowseEmployeesService @(requires:'Employee') {
@readonly entity Employees
as projection on db.Employees excluding { contracts }; // hide contracts!
@readonly entity Teams as projection on db.Teams;
}
```
Now, an `Employee` user cannot expand the contracts as the composition is not reachable anymore from the service.
::: tip
Associations without navigation links (for example, when you don't expose an associated entity) are still critical with regard to security.
:::
### Design Authorization Models from the Start
As shown before, defining an adequate authorization strategy has a deep impact on the service model. Apart from the fundamental decision of whether you want to build your authorizations on [dynamic roles](#domain-driven-authorization), authorization requirements can result in completely rearranging service and entity definitions.
For this reason, it's *strongly* recommended to take security design into consideration at an early stage of your project.
### Keep it as Simple as Possible
* If different authorizations are needed for different operations, it's easier to have them defined at the service level. If you start defining them at the entity level, all possible operations must be specified; otherwise, the operations not mentioned are automatically forbidden.
* If possible, try to define your authorizations either on the service or on the entity level. Mixing both variants increases complexity, and not all combinations are supported either.
### Separation of Concerns
Consider using [CDS Aspects](../../cds/cdl#aspects) to separate the actual service definitions from authorization annotations as follows:
::: code-group
```cds [services.cds]
service ReviewsService {
/*...*/
}
service CustomerService {
entity Orders {/*...*/}
entity Approval {/*...*/}
}
```
:::
::: code-group
```cds [services-auth.cds]
annotate ReviewsService with @(requires: 'authenticated-user');
annotate CustomerService with @(requires: 'authenticated-user');
annotate CustomerService.Orders with @(restrict: [
{ grant: ['READ','WRITE'], to: 'admin' },
{ grant: 'READ', where: 'buyer = $user' },
]);
annotate CustomerService.Approval with @(restrict: [
{ grant: 'WRITE', where: '$user.level > 2' }
]);
```
:::
This keeps your actual service definitions concise and focused on structure only. It also allows you to give authorization models separate ownership and lifecycle.