In rare situations you might want to call a public service without sharing information of the current request user.
-In this case, user propagation is explicitly prevented.
+In this case, you explicitly prevent user propagation.
Such service calls can be executed on behalf of the anonymous user, acting as a public user without personal user claims:
```java
@@ -1604,7 +1602,7 @@ cdsRuntime.requestContext().anonymousUser().run(privilegedContext -> {
In rare situations you might want to call a public service without sharing information about the current request user.
-In this case, user propagation can explicitly be prevented by running in a context whose principal is the `anonymous` user.
+In this case, you can explicitly prevent user propagation by running in a context whose principal is the `anonymous` user.
```js
cds.tx({ user: cds.User.anonymous }, async tx => {
@@ -1746,22 +1744,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.
diff --git a/guides/security/overview.md b/guides/security/overview.md
index 34cdab3e9..1365a4eb1 100644
--- a/guides/security/overview.md
+++ b/guides/security/overview.md
@@ -36,14 +36,14 @@ For example, authentication can be delegated to a [separate ingress component](.
### Customizable { #key-concept-customizable }
-Due to the plugin-based architecture, **CAP allows standard functions to be modified as required or, if necessary, completely replaced**.
-This flexibility is crucial for scenarios where the default methods do not fully meet the requirements of the application.
+Due to the plugin-based architecture, **you can modify CAP's standard functions as required or, if necessary, completely replace them**.
+This flexibility is crucial for scenarios where the default methods do not fully meet your application's requirements.
Moreover, this integration helps to easily incorporate non-CAP and even non-BTP services, thereby providing a flexible and interoperable environment.
{width="600px" }
-For instance, it is possible to define specific endpoints with a [custom authentication strategy](./authentication#custom-auth).
-Likewise, the CAP representation of the request user can be overruled to match additional, application-specific requirements.
+For instance, you can define specific endpoints with a [custom authentication strategy](./authentication#custom-auth).
+Likewise, you can override the CAP representation of the request user to match additional, application-specific requirements.
### Built on Best of Breed { #key-concept-platform-services }
@@ -59,7 +59,7 @@ Likewise, TLS termination is offered by the [platform infrastructure](#platform-
### Decoupled from Business Logic { #key-concept-decoupled-coding }
-As security functions are factorized into independent components, **application code is entirely decoupled** and hence is not subject to change in case of any security-related adaptations.
+As security functions are factorized into independent components, **application code is entirely decoupled** and hence is not subject to change for any security-related adaptations.
This ensures that business logic remains independent of platform services, which are often subject to security-hardening initiatives.
As a welcome side effect, this also allows testing application security in a **local test or development setup in a self-contained way**.
@@ -85,7 +85,7 @@ The application is responsible for coordinated overall configuration.
## Security Architecture
CAP applications run in a specific context that has a major impact on the security [architecture](#architecture-overview).
-CAP requires a dedicated [platform environment](#platform-environment) to integrate with, in order to ensure end-to-end security.
+CAP requires a dedicated [platform environment](#platform-environment) to integrate with to ensure end-to-end security.
### Architecture Overview { #architecture-overview }
@@ -93,7 +93,7 @@ The following diagram provides a high-level overview of the security-relevant co
{width="600px"}
-To serve a business request, different runtime components are involved: a request, issued by a UI or technical client ([public zone](#public-zone)), is forwarded by a gateway or ingress router to the CAP application. In case of a UI request, an [Application Router](https://help.sap.com/docs/btp/sap-business-technology-platform/application-router) instance acts as a proxy to manage the login flow and the browser session. The CAP application can have additional services such as a CAP sidecar. All application components ([application zone](#application-zone)) might make use of platform services such as database or identity service ([platform zone](#platform-zone)).
+To serve a business request, different runtime components are involved: a request, issued by a UI or technical client ([public zone](#public-zone)), is forwarded by a gateway or ingress router to the CAP application. For a UI request, an [Application Router](https://help.sap.com/docs/btp/sap-business-technology-platform/application-router) instance acts as a proxy to manage the login flow and the browser session. The CAP application can have additional services such as a CAP sidecar. All application components ([application zone](#application-zone)) might make use of platform services such as database or identity service ([platform zone](#platform-zone)).
#### Public Zone { #public-zone }
@@ -107,17 +107,17 @@ Ideally, you should limit the number of exposed endpoints to a minimum, perhaps
The platform zone contains all platform components and services that are *configured and maintained* by the application provider.
CAP applications consume these low-level [platform services](#btp-services) to handle more complex business requests.
-For instance, persistence service to store business data and identity service to authenticate the business user play a fundamental role.
+For instance, the persistence service stores business data and the identity service authenticates the business user. Both play a fundamental role.
The platform zone also includes the gateway, which is the main entry point for external requests. Additionally, it may contain extra ingress routers.
#### Application Zone { #application-zone}
-The application zone comprises all microservices that represent a CAP application. They are tightly integrated and form a **unit of trust**. The application provider is responsible to *develop, deploy and operate* these services:
+The application zone comprises all microservices that represent a CAP application. They are tightly integrated and form a **unit of trust**. The application provider is responsible for *developing, deploying, and operating* these services:
- The [Application Router](https://help.sap.com/docs/btp/sap-business-technology-platform/application-router) acts as an optional reverse proxy wrapping the application service and providing business-independent functionality required for UIs.
This includes serving UI content, providing a login flow as well as managing the session with the browser.
-It can be deployed as an application (reusable module) or alternatively consumed as a [service](https://help.sap.com/docs/btp/sap-business-technology-platform/managed-application-router).
+You can deploy it as an application (reusable module) or alternatively consume it as a [service](https://help.sap.com/docs/btp/sap-business-technology-platform/managed-application-router).
- The CAP application service exposes the API to serve business requests. Usually, it makes use of lower-level platform services. As built on CAP, a significant number of security requirements is covered either out of the box or by adding minimal configuration.
@@ -144,7 +144,7 @@ This **frees CAP applications from the need to manage trust certificates**. The
3. **Secrets** that are required to protect the application or to consume other platform services **are injected by the platform** into the application microservices in a secure way.
-All supported [environments](#cloud) fulfill the given requirements. Additional requirements could be added in future.
+All supported [environments](#cloud) fulfill the given requirements. Additional requirements may be added in future.
::: tip
Custom domain certificates must be signed by a trusted certificate authority.
@@ -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.
@@ -187,12 +190,12 @@ Currently, CAP supports to run on two cloud runtimes of [SAP Business Technology
- [SAP BTP, Cloud Foundry Runtime](https://help.sap.com/docs/btp/sap-business-technology-platform/cloud-foundry-environment)
- [SAP BTP, Kyma Runtime](https://help.sap.com/docs/btp/sap-business-technology-platform/kyma-environment)
-Application providers are responsible to ensure a **secure platform environment**.
+Application providers are responsible for ensuring a **secure platform environment**.
In particular, this includes *configuring* [platform services](#btp-services) the application consumes.
-For instance, the provider (user) administrator needs to configure the [identity service](#identity-service) to separate platform users from business users that come from different identity providers.
+For instance, you as the provider (user) administrator need to configure the [identity service](#identity-service) to separate platform users from business users that come from different identity providers.
Likewise, login policies (for example, multifactor authentication or single-sign-on) must be aligned with company-specific requirements.
-Note, that achieving production-ready security requires to meet all relevant aspects of the **development process** as well.
+Note that achieving production-ready security requires meeting all relevant aspects of the **development process** as well.
For instance, source code repositories must be protected and must not contain any secrets or personal data.
Likewise, the **deployment process** must be secured. This includes not only setting up CI/CD pipelines running on technical platform users, but also defining integration tests to ensure properly secured application endpoints.
@@ -216,7 +219,7 @@ Find more about BTP platform security here:
### Security Platform Services { #btp-services }
-SAP BTP provides a range of platform services that your CAP applications can utilize to meet production-grade security requirements. To ensure the security of your CAP applications, it's crucial to comply with the service level agreement (SLA) of these platform services. *As the provider of the application, you play a key role in meeting these requirements by correctly configuring and using these services.*
+SAP BTP provides a range of platform services that your CAP applications can use to meet production-grade security requirements. To ensure the security of your CAP applications, comply with the service level agreement (SLA) of these platform services. *As the provider of the application, you play a key role in meeting these requirements by correctly configuring and using these services.*
::: tip
SAP BTP services and the underlying platform infrastructure hold various certifications and attestations, which can be found under the naming of SAP Cloud Platform in the [SAP Trust Center](https://www.sap.com/about/trust-center/certification-compliance/compliance-finder.html?search=SAP%20Business%20Technology%20Platform%20ISO).
@@ -224,42 +227,42 @@ SAP BTP services and the underlying platform infrastructure hold various certifi
[Webcast SAP BTP Cloud Identity and Security Services](https://assets.dm.ux.sap.com/webinars/sap-user-groups-k4u/pdfs/221117_sap_security_webcast_series_sap_btp_cloud_identity_and_security_services.pdf){.learn-more}
-The CAP framework offers flexible APIs that you can integrate with various services, including your custom services. If you replace platform services with your custom ones, it's important to ensure that the service level agreements (SLAs) CAP depends on are still met.
+The CAP framework offers flexible APIs that you can integrate with various services, including your custom services. If you replace platform services with your custom ones, ensure that the service level agreements (SLAs) CAP depends on are still met.
The most important services for security offered by the platform:
#### [SAP Cloud Identity Services - Identity Authentication](https://help.sap.com/docs/IDENTITY_AUTHENTICATION) { #identity-service }
-The Identity Authentication service defines the user base for (CAP) applications and services, and allows to control access.
-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.
+The Identity Authentication service defines the user base for (CAP) applications and services, and allows you to control access.
+You can integrate your third-party or on-premise identity provider (IdP) and harden security by defining multifactor authentication or by narrowing client IP ranges.
+This service helps 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 you to configure 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}
diff --git a/guides/security/remote-authentication.md b/guides/security/remote-authentication.md
index 33e5cecf8..73c9a274e 100644
--- a/guides/security/remote-authentication.md
+++ b/guides/security/remote-authentication.md
@@ -29,7 +29,7 @@ This guide explains how to authenticate remote services.
## Remote Service Abstraction { #remote-services }
-According to the key concept of [pluggable building blocks](./overview#key-concept-pluggable), the architecture of CAP's [Remote Services](../services/consuming-services#consuming-services) decouples protocol level (i.e., exchanged content) from connection level (i.e., established connection channel).
+According to the key concept of [pluggable building blocks](./overview#key-concept-pluggable), the architecture of CAP's [Remote Services](../services/consuming-services#consuming-services) decouples protocol level (that is, exchanged content) from connection level (that is, established connection channel).
While the business context of the application impacts the protocol, the connectivity of the service endpoints is independent of it and mainly depends on platform-level capabilities.
The latter is frequently subject to change and therefore should not introduce application dependencies.
@@ -45,15 +45,15 @@ All three service scenarios can be addressed through configuration variants of t
CAP supports out-of-the-box consumption of various types of [remote services]( #remote-services):
-* [Co-located services](#co-located-services) as part of the same deployment and bound to the same identity instance (i.e., belong to the same trusted [application zone](./overview#application-zone)).
-* [External services](#app-to-app) which can be running on non-BTP platforms.
+* [Co-located services](#co-located-services) as part of the same deployment and bound to the same identity instance (that is, belong to the same trusted [application zone](./overview#application-zone)).
+* [External services](#app-to-app) that can be running on non-BTP platforms.
* [BTP reuse services](#ias-reuse) consumed via service binding.
## Co-located Services {#co-located-services}
Co-located services do not run in the same microservice, but are typically part of the same deployment unit and hence reside within the same trust boundary of the [application zone](./overview#application-zone).
-Logically, such co-located services contribute to the application equally and could run as integrated services in the same microservice, but for technical reasons (e.g., different runtime or scaling requirements) they are separated physically, often as a result of a [late-cut microservice approach](../deploy/microservices#late-cut-microservices).
+Logically, such co-located services contribute to the application equally and could run as integrated services in the same microservice, but for technical reasons (for example, different runtime or scaling requirements) they are separated physically, often as a result of a [late-cut microservice approach](../deploy/microservices#late-cut-microservices).
Technically, **they share the same identity instance, which allows direct token forwarding**:
@@ -200,7 +200,7 @@ xtravels-ias identity application xtravels, xtravels-srv, xflights-srv, ..
:::
You can test the valid setup of the xtravels application by accessing the UI and logging in with an authorized test user of the IAS tenant.
-To do so, assign a proper AMS policy (e.g., `admin`) to the test user as described [earlier](./cap-users#ams-deployment).
+To do so, assign a proper AMS policy (for example, `admin`) to the test user as described [earlier](./cap-users#ams-deployment).
::: tip
@@ -215,7 +215,7 @@ As a consequence, external services can run cross-regionally; even non-BTP syste
A prerequisite for external service calls is a trust federation between the consumer and the provider system.
A seamless integration experience for external service communication is provided by [IAS App-2-App](#app-to-app) flows, which are offered by CAP via remote services.
-Alternatively, remote services can be configured on top of [BTP HTTP Destinations](../services/consuming-services#using-destinations) which offer [various authentication strategies](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/http-destinations) such as SAML 2.0 as required by many S/4 system endpoints.
+Alternatively, remote services can be configured on top of [BTP HTTP Destinations](../services/consuming-services#using-destinations) that offer [various authentication strategies](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/http-destinations) such as SAML 2.0 as required by many S/4 system endpoints.
### IAS App-2-App { #app-to-app }
@@ -226,7 +226,7 @@ Prerequisites are identity instances on both consumer and provider sides, plus a
{width="500px" }
CAP supports communication between arbitrary IAS endpoints and remains transparent for applications as it builds on the same architectural pattern of [remote services](#remote-services).
-Technically, the connectivity component uses [IAS App-2-App flows](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications) in this scenario which requires a token exchange from a consumer token into a token for the provider.
+Technically, the connectivity component uses [IAS App-2-App flows](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications) in this scenario that requires a token exchange from a consumer token into a token for the provider.
The latter is issued by IAS only if the consumer is configured with a valid IAS dependency pointing to the provider accordingly.
:::tip
@@ -273,7 +273,7 @@ The description helps administrators to configure the consumer application with
How can proper authorization be configured for _technical clients without user propagation_?
OAuth tokens presented by valid consumer requests from an App-2-App flow will have API claim `DataConsumer`, which is automatically mapped to a CAP role by the runtime.
-Therefore, the corresponding CDS service can be protected by CAP role `DataConsumer` to authorize requests thoroughly:
+Therefore, you can protect the corresponding CDS service by CAP role `DataConsumer` to authorize requests thoroughly:
::: code-group
```cds [/srv/authorization.cds]
@@ -298,16 +298,16 @@ The API identifiers exposed by the IAS instance in list `provided-apis` are gran
::: warning Use different roles for technical and business users
Use different CAP roles for technical clients without user propagation and for named business users.
-Instead of using the same role, expose dedicated CDS services to technical clients which aren't accessible to business users and vice versa.
+Instead of using the same role, expose dedicated CDS services to technical clients that are not accessible to business users and vice versa.
:::
#### 2. Prepare and deploy the consumer application { #consumer }
Like with xflights, clone [`xtravels-java`](https://github.com/capire/xtravels-java/tree/main) or, if already cloned and modified locally, reset to remote branch.
-First, a BTP destination needs to be added that points to the provider service endpoint to be called (`URL`) and that contains the information about the IAS dependency to be called (`cloudsdk.ias-dependency-name`).
+First, you need to add a BTP destination that points to the provider service endpoint to be called (`URL`) and that contains the information about the IAS dependency to be called (`cloudsdk.ias-dependency-name`).
The name for the IAS dependency is flexible but **needs to match the chosen name in the next step** when [connecting consumer and provider in IAS](#connect).
-The destination is required by the connectivity component to prepare the HTTP call accordingly. Also note that the authentication type of the destination is `NoAuthentication`, as the destination itself does not contribute to the authentication process.
+The connectivity component requires the destination to prepare the HTTP call accordingly. Also note that the authentication type of the destination is `NoAuthentication`, as the destination itself does not contribute to the authentication process.
::: code-group
@@ -390,7 +390,7 @@ cds up
Remote HCQL service responded with HTTP status code '401', ...
```
-Technically, the remote service implementation will delegate the HTTP connection setup to the connectivity component, which can recognize by the type of destination that it needs to initiate an App-2-App flow.
+Technically, the remote service implementation will delegate the HTTP connection setup to the connectivity component that can recognize by the type of destination that it needs to initiate an App-2-App flow.
It then takes the token from the request and triggers an IAS token exchange for the target [IAS dependency](#connect) according to the user propagation strategy (technical communication here).
As the IAS dependency is not created yet, IAS rejects the token exchange request and the call to the provider fails with `401` (not authenticated).
@@ -438,10 +438,10 @@ To do so, assign a proper AMS policy (e.g., `admin`) to the test user as describ
- **Don't write custom integration logic** for consumed services.
Leverage CAP's remote service architecture instead to ensure a seamless integration experience.
-- **Don't implement connectivity layer code** (e.g., to fetch or exchange tokens).
+- **Don't implement connectivity layer code** (for example, to fetch or exchange tokens).
Instead, rely on the shared connectivity component, which ensures centralized and generic processing of outbound requests.
- **Don't treat co-located services as external services**.
-This introduces unnecessary communication overhead and increases total cost of ownership (TCO).
+This introduces unnecessary communication overhead and increases total cost of ownership.