[review] Security Guide

guides/security/authentication.md

@@ -39,15 +39,15 @@ As access control relies on verified claims, authentication is a mandatory prere
 According to key concept [Pluggable Building Blocks](./overview#key-concept-pluggable), the authentication method can be configured freely. 
 CAP [leverages platform services](overview#key-concept-platform-services) to provide proper authentication strategies to cover all relevant scenarios:
 
-- For _local development_ and _unit testing_, [Mock User Authentication](#mock-user-auth) is an appropriate built-in authentication feature.
+- For _local development_ and _unit testing_, [Mock User Authentication](#mock-user-authentication) is an appropriate built-in authentication feature.
 
 - For _cloud deployments_, in particular deployments for production, CAP provides integration of several identity services out of the box:  
   - [Identity Authentication Service (IAS)](#ias-auth) provides a full-fledged [OpenId Connect](https://openid.net/connect/) compliant, cross-landscape identity management as first choice for applications. 
   - [XS User Authentication and Authorization Service (XSUAA)](https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG) is an [OAuth 2.0](https://oauth.net/2/)-based authorization server to support existing applications and services in the scope of individual BTP landscapes.
   - CAP applications can run IAS and XSUAA in [hybrid mode](#hybrid-auth) to support a smooth migration from XSUAA to IAS.
 
 
-## Mock User Authentication { #mock-user-auth }
+## Mock User Authentication
 
 In non-production profile, by default, CAP creates a security configuration which accepts _mock users_.
 As this authentication strategy is a built-in feature which does not require any platform service, it is perfect for **unit testing and local development scenarios**.
@@ -140,9 +140,9 @@ curl http://localhost:4004/odata/v4/admin/Books --verbose
 results in a `401` error response from the server indicating that the anonymous user has been rejected due to missing authentication.
 This is true for all endpoints including the web application page at `/index.html`.
 
-Mock users require **basic authentication**, hence sending the same request on behalf of mock user `alice` (password: `basic`) with
+Mock users require **basic authentication**, hence sending the same request on behalf of mock user `alice` (no password) with
 ```sh
-curl http://alice:basic@localhost:4004/odata/v4/admin/Books
+curl http://alice:@localhost:4004/odata/v4/admin/Books
 ```
 returns successfully (HTTP response `200`).
 
@@ -309,7 +309,7 @@ Integration tests running in production profile should verify that unauthenticat
  - cross-landscape user propagation (including on-premise)
  - streamlined SAP and non-SAP system [integration](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/integrating-service) (due to [OpenId Connect](https://openid.net/connect/) compliance)
 
-IAS authentication is best configured and tested in the Cloud, so let's enhance the started bookshop sample application with a deployment descriptor for SAP BTP, Cloud Foundry Runtime (CF).
+IAS authentication is best configured and tested in the Cloud, so let's enhance the [previously started bookshop sample application](#mock-user-authentication) with a deployment descriptor for SAP BTP, Cloud Foundry Runtime (CF).
 
 
 ### Get Ready with IAS { #ias-ready }
@@ -324,7 +324,7 @@ towards your IAS tenant to use it as identity provider for applications in your
 - Ensure your development environment is [prepared for deploying](../deploy/to-cf#prerequisites) on CF, 
 in particular you require a `cf` CLI session targeting a CF space in the test subaccount (test with `cf target`).
 
-You can continue with the sample [already created](#mock-user-auth). In the project root folder, execute
+You can continue with the sample [already created](#mock-user-authentication). In the project root folder, execute
 
 ```sh
 cds add mta
@@ -417,6 +417,7 @@ and wait until the application is up and running.
 You can test the status with `cf apps` on CLI level or in BTP Cockpit, alternatively.
 
 The startup log should confirm the activated IAS authentication:
+
 <div class="java">
 
 ```sh
@@ -426,7 +427,11 @@ The startup log should confirm the activated IAS authentication:
 </div>
 
 <div class="node">
+
+```sh
 TODO
+```
+
 </div>
 
 ::: tip
@@ -677,14 +682,15 @@ The same is true for the logout flow.
 :::
 
 
-Now re-deploy the solution by running 
+Now re-deploy the solution:
 
 ```sh
 cds up
 ```
 
-and test the application via URL provided in the Cockpit.
-The Application Router should redirect to a login flow where you can enter the credentials of a [test user](#ias-admin) created before.
+Test the application using the URL provided in the Cockpit.
+
+The Application Router should redirect to a login flow where you can enter the credentials of a [test user](#ias-admin) you created before in the Administration Console for IAS.
 
 
 ## XSUAA Authentication { #xsuaa-auth }
@@ -706,34 +712,32 @@ XSUAA authentication is best configured and tested in the Cloud, so let's enhanc
 Before working with XSUAA on CF, you need to ensure your development environment is [prepared for deploying](../deploy/to-cf#prerequisites) to CF.
 In particular, you require a `cf` CLI session targeting a CF space in the test subaccount (test with `cf target`).
 
-You can continue with the bookshop sample create for the [mock users](#mock-user-auth) or, alternatively, you can also enhance the [IAS-based](#ias-auth) application. 
+:::details If you haven't prepared a sample yet...
 
-If there is no deployment descriptor yet, execute in the project root folder
+You can create a bookshop sample as described in [Mock User Authentication](#mock-user-authentication).
+
+Execute the following two commands in the project root folder, only if you haven't prepared your sample for IAS in the previous section already.
+
+To make your application ready for deployment to CF:
 
 ```sh
 cds add mta
 ```
 
-<div class="impl java">
-
-::: tip
-Command `add mta` will enhance the project with `cds-starter-cloudfoundry` and therefore all [dependencies required for security](../../java/security#maven-dependencies) are added transitively.
-:::
-
-</div>
-
-to make your application ready for deployment to CF.
-
 You also need to configure DB support:
 
 ```sh [SAP HANA]
 cds add hana
 ```
 
+::: tip For Java
+Command `add mta` will enhance the project with `cds-starter-cloudfoundry` and therefore all [dependencies required for security](../../java/security#maven-dependencies) are added transitively.
+
+:::
 
 ### Adding XSUAA { #adding-xsuaa }
 
-Now the application is ready for enhancing with XSUAA-support:
+Enhance your [sample application](#mock-user-authentication) with XSUAA-support:
 
 <div class="impl java">
 
@@ -1278,7 +1282,7 @@ With `cds.security.authentication.authenticateMetadataEndpoints: false` you can
 
 <div class="node">
 
-Automatic authentication enforcement can be disabled via feature flag <Config>cds.requires.auth.restrict_all_services: false</Config>, or by using [mocked authentication](#mock-user-auth) explicitly in production.
+Automatic authentication enforcement can be disabled via feature flag <Config>cds.requires.auth.restrict_all_services: false</Config>, or by using [mocked authentication](#mock-user-authentication) explicitly in production.
 
 </div>
 
@@ -1337,7 +1341,9 @@ In such architectures, CAP authentication is obsolete and can be deactivated ent
 </div>
 
 <div class="node">
+
 TODO
+
 </div>
 
 

guides/security/authorization.md

@@ -105,12 +105,12 @@ context db {
     ...
   }
 
-  entity Issues : cuid { // implicitly auto-exposed (by composition)
+  entity Issues : cuid { // implicitly auto-exposed (by composition in Components)
     category: Association to Categories;
     ...
   }
 
-  entity Components : cuid { // explicitly exposed (by projection)
+  entity Components : cuid { // explicitly exposed (by projection in IssuesService)
     issues: Composition of many Issues;
     ...
   }
@@ -262,21 +262,35 @@ Restrictions can be defined on different types of CDS resources, but there are s
 | entity          |  <Y/>   | <Y/> | <Y/><sup>1</sup>  |               |
 | action/function |  <Na/>  | <Y/> | <Na/><sup>2</sup> | = `@requires` |
 
-> <sup>1</sup>For bound actions and functions that are not bound against a collection, Node.js supports instance-based authorization at the entity level. For example, you can use `where` clauses that *contain references to the model*, such as `where: CreatedBy = $user`. For all bound actions and functions, Node.js supports simple static expressions at the entity level that *don't have any reference to the model*, such as `where: $user.level = 2`.
+> <sup>1</sup>For bound actions and functions that are not bound against a collection, Node.js supports instance-based authorization at the entity level, see [link] (somewhere in Node.js docs)<br>
 > <sup>2</sup> For unbound actions and functions, Node.js supports simple static expressions that *don't have any reference to the model*, such as `where: $user.level = 2`.
 
 Unsupported privilege properties are ignored by the runtime. Especially, for bound or unbound actions, the `grant` property is implicitly removed (assuming `grant: '*'` instead). The same also holds for functions:
 
-```cds
+::: code-group
+```cds [Model w/ unsupported privilege properties]
 service CatalogService {
   entity Products as projection on db.Products { ... }
   actions {
     @(requires: 'Admin')
     action addRating (stars: Integer);
   }
-  function getViewsCount @(restrict: [{ to: 'Admin' }]) () returns Integer;
+  function getViewsCount @(restrict: [{ grant: 'READ' to: 'Admin' }]) () returns Integer;
+}
+```
+```cds [Resulting model]
+service CatalogService {
+  entity Products as projection on db.Products { ... }
+  actions {
+    @(requires: 'Admin') // is already in implicit {grant: '*'}
+    action addRating (stars: Integer);
+  }
+   //unsupported property is removed, means implicit { grant: '*'}
+  function getViewsCount @(restrict: [{ to: 'Admin' }]) () returns Integer; 
 }
+
 ```
+:::
 
 
 ### Combined Restrictions { #combined-restrictions}
@@ -413,7 +427,25 @@ The [restrict annotation](#restrict-annotation) for an entity allows you to enfo
 In addition, you can define a `where`-condition that further limits the set of accessible instances. 
 This condition, which acts like a filter, establishes *instance-based authorization*.
 
-### Filter Conditions { #filter-consitions }
+### 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*. 
@@ -444,24 +476,6 @@ You can define filter conditions in the `where`-clause of restrictions based on
 </div>
 
 
-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.
-:::
-
 At runtime you'll find filter predicates attached to the appropriate CQN queries matching the instance-based condition.
 
 :::warning Modification of Statements

guides/security/cap-users.md

@@ -1746,22 +1746,23 @@ Prefer using [Remote Services](#remote-services) built on Cloud SDK rather than
 
 ## Pitfalls
 
-- **Don't write custom code against concrete user types of a specific identity service (e.g. XSUAA or IAS)**. 
-Instead, if required at all, use CAP's user abstraction layer (`UserInfo` in Java or `req.user` in Node.js) to handle user-related logic.
+- **Don't write custom code against user types of an identity service (XSUAA / IAS)**. 
+
+  Instead, if it is required at all to code against user types, use CAP's user abstraction layer (`UserInfo` in Java or `req.user` in Node.js) to handle user-related logic.
 
-- **Don't try to propagate named user context in asynchronous requests**, such as when using the Outbox pattern or Messaging. 
-Asynchronous tasks are typically executed outside the scope of the original request context, after successful authorization. 
-Propagating the named user context can lead to inconsistencies or security issues. Instead, use technical users for such scenarios.
+- **Don't try to propagate named user context in asynchronous requests**.
+  
+  This can happen when using the Outbox pattern or Messaging. Asynchronous tasks are typically executed outside the scope of the original request context, after successful authorization. Propagating the named user context can lead to inconsistencies or security issues. Instead, use technical users for such scenarios.
 
-- **Don't mix CAP Roles for business and technical users**. CAP roles should be clearly separated based on their purpose: Business user roles are designed to reflect how end users interact with the application.
-Technical user roles are intended for system-level operations, such as background tasks or service-to-service communication. Mixing these roles can lead to confusion and unintended access control issues.
+- **Don't mix CAP Roles for business and technical users**. 
+
+  CAP roles should be clearly separated based on their purpose: Business user roles are designed to reflect how end users interact with the application. Technical user roles are intended for system-level operations, such as background tasks or service-to-service communication. Mixing these roles can lead to confusion and unintended access control issues.
 
 - **Don't mix AMS Policy level with CAP Role level**.
-AMS policies operate at the business level, while CAP roles are defined at the technical domain level. 
-Avoid mixing these two layers, as this could undermine the clarity and maintainability of your authorization model.
+  
+  AMS policies operate at the business level, while CAP roles are defined at the technical domain level. Avoid mixing these two layers, as this could undermine the clarity and maintainability of your authorization model.
 
-- **Don't choose non-cross-sectional entity attributes as AMS Attributes**.
-Such attributes should have a broad, domain-wide relevance and be applicable across multiple entities. 
-Typically, only a limited number of attributes (less than 10) meet this criterion. 
-Exposing entity-specific attributes as AMS attributes can lead to unnecessary complexity and reduced reusability.
+- **Don't choose entity attributes as AMS Attributes whose relevance is too small**.
+
+  Such attributes should have a broad, domain-wide relevance and be applicable across multiple entities. Typically, only a limited number of attributes (less than 10) meet this criterion. Exposing entity-specific attributes as AMS attributes can lead to unnecessary complexity and reduced reusability.
 

guides/security/overview.md

@@ -172,10 +172,13 @@ Security not only plays a crucial role in [cloud environments](#cloud), but also
 Apparently the security requirements are different from cloud scenario as local endpoints are typically not exposed for remote clients.
 But there are still a few things to consider because exploited vulnerabilities could be the basis for attacks on productive cloud services:
 
+#### DO:{.good}
+
 - Make sure that locally started HTTP endpoints are bound to `localhost`.
-- In case you run your service in hybrid mode with bindings to cloud service instances,
-use [cds bind](../../tools/cds-bind) instead of copying bindings manually to `default-env.json` file.
-`cds bind` avoids materialization of secrets to local disc, which is inherently dangerous.
+- Use [cds bind](../../tools/cds-bind) to run your service in hybrid mode with bindings to cloud service instances. `cds bind` avoids materialization of secrets to local disc, which is inherently dangerous. The opposite is consequently a **Don't**.
+
+#### DON'T:{.bad}
+- Don't copy bindings manually to `default-env.json` file or otherwise on your local disc.
 - Don't write sensitive data to application logs, also not via debug logging.
 - Don't test with real business data, for example, copied from a productive system.
 
@@ -234,32 +237,32 @@ The Identity Authentication service defines the user base for (CAP) applications
 Customers can integrate their third-party or on-premise identity provider (IdP) and harden security by defining multifactor authentication or by narrowing client IP ranges.
 This service helps to introduce a strict separation between platform users (provider) and business users (subscribers), a requirement of CAP. It supports various authentication methods, including SAML 2.0 and [OpenID Connect](https://openid.net/connect/), and allows for the configuration of single sign-on access.
 
-[Learn more in the security guide.](https://help.sap.com/docs/IDENTITY_AUTHENTICATION?#discover_task-security){.learn-more}
+[Learn more in the SAP Cloud Identity - Security Guide.](https://help.sap.com/docs/IDENTITY_AUTHENTICATION?#discover_task-security){.learn-more}
 
 #### [SAP Authorization and Trust Management Service](https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG)
 
 The service allows customers to manage user authorizations in technical roles at the application level, which can be aggregated into business-level role collections for large-scale cloud scenarios.
 Developers must define application roles carefully as they form the basic access rules for business data.
 
-[Learn more in the security guide.](https://help.sap.com/docs/btp/sap-business-technology-platform/btp-security){.learn-more}
+[Learn more in the SAP Authorization and Trust Management service guide.](https://help.sap.com/docs/btp/sap-business-technology-platform/btp-security){.learn-more}
 
 #### [SAP BTP Connectivity](https://help.sap.com/docs/CP_CONNECTIVITY)
 
 The connectivity service allows SAP BTP applications to securely access remote services that run on the Internet or on-premise.
 It provides a way to establish a secure communication channel between remote endpoints that are connected via an untrusted network infrastructure.
 
-[Learn more in the security guide.](https://help.sap.com/docs/CP_CONNECTIVITY/cca91383641e40ffbe03bdc78f00f681/cb50b6191615478aa11d2050dada467d.html){.learn-more}
+[Learn more in the SAP BTP Connectivity guide.](https://help.sap.com/docs/CP_CONNECTIVITY/cca91383641e40ffbe03bdc78f00f681/cb50b6191615478aa11d2050dada467d.html){.learn-more}
 
 #### [SAP Malware Scanning Service](https://help.sap.com/docs/MALWARE_SCANNING)
 
 This service scans transferred business documents for malware and viruses.
 Currently, there is no CAP integration. A scan must be triggered explicitly by the business application.
 
-[Learn more in the security guide.](https://help.sap.com/docs/btp?#operate_task-security){.learn-more}
+[Learn more in the SAP Malware Scanning service guide.](https://help.sap.com/docs/btp?#operate_task-security){.learn-more}
 
 #### [SAP Credential Store](https://help.sap.com/docs/CREDENTIAL_STORE)
 
 Credentials managed by applications must be stored securely.
 This service provides a REST API for (CAP) applications to store and retrieve credentials at runtime.
 
-[Learn more in the security guide.](https://help.sap.com/docs/CREDENTIAL_STORE?#discover_task-security){.learn-more}
+[Learn more in the SAP Credential Store guide.](https://help.sap.com/docs/CREDENTIAL_STORE?#discover_task-security){.learn-more}