From 04403769669f80c1f69ef54d80ac2317c9f03209 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 10:22:51 +0100 Subject: [PATCH 01/13] Example first --- guides/security/authorization.md | 38 ++++++++++++++++---------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/guides/security/authorization.md b/guides/security/authorization.md index 7912c05aaf..ca929bf9dd 100644 --- a/guides/security/authorization.md +++ b/guides/security/authorization.md @@ -413,7 +413,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 +462,6 @@ You can define filter conditions in the `where`-clause of restrictions based on -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 From af9c5d842bbc2e60d979beb25444c07f9657151b Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 12:11:43 +0100 Subject: [PATCH 02/13] use standard link target and add link --- guides/security/authentication.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index aa0ea414a6..752015c47a 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -39,7 +39,7 @@ 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. @@ -47,7 +47,7 @@ CAP [leverages platform services](overview#key-concept-platform-services) to pro - 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**. @@ -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 @@ -706,7 +706,7 @@ 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. +You can continue with the bookshop sample create for the [mock users](#mock-user-authentication) or, alternatively, you can also enhance the [IAS-based](#ias-auth) application. If there is no deployment descriptor yet, execute in the project root folder @@ -1278,7 +1278,7 @@ With `cds.security.authentication.authenticateMetadataEndpoints: false` you can
-Automatic authentication enforcement can be disabled via feature flag cds.requires.auth.restrict_all_services: false, or by using [mocked authentication](#mock-user-auth) explicitly in production. +Automatic authentication enforcement can be disabled via feature flag cds.requires.auth.restrict_all_services: false, or by using [mocked authentication](#mock-user-authentication) explicitly in production.
From b4aa6e8601815ea714b12b05884532504c1431a8 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 12:16:32 +0100 Subject: [PATCH 03/13] todo marker --- guides/security/authentication.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index 752015c47a..f6ddc78cff 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -426,7 +426,11 @@ The startup log should confirm the activated IAS authentication:
+ +```sh TODO +``` +
::: tip @@ -1337,7 +1341,9 @@ In such architectures, CAP authentication is obsolete and can be deactivated ent
+ TODO +
From 83ce6d5d175a381df02a3464a73cea7e760e20e1 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 12:48:30 +0100 Subject: [PATCH 04/13] move repeating information in details block --- guides/security/authentication.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index f6ddc78cff..433a70f424 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -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: +
```sh @@ -710,34 +711,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-authentication) or, alternatively, you can also enhance the [IAS-based](#ias-auth) application. +:::details If you haven't prepared a sample yet... + +You can create a bookshop sample as described in [Mock User Authentication](#mock-user-authentication). -If there is no deployment descriptor yet, execute in the project root folder +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 ``` -
- -::: 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. -::: - -
- -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:
From f11482fc2a6e653f175d001bce27c083113395dc Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 13:19:44 +0100 Subject: [PATCH 05/13] alice without password --- guides/security/authentication.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index 433a70f424..e62ca76bb2 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -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`). @@ -682,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 } From 797356744e43e9ca05a430fb629a158ba0e96f4d Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 14:27:45 +0100 Subject: [PATCH 06/13] introduce do don't pattern, better texts for links --- guides/security/overview.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/guides/security/overview.md b/guides/security/overview.md index ce585b638d..2eb397262e 100644 --- a/guides/security/overview.md +++ b/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} From abcf040ebb6feb5e2cd028ac140f0f4c904c738f Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 14:41:18 +0100 Subject: [PATCH 07/13] edit pitfalls section --- guides/security/cap-users.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/guides/security/cap-users.md b/guides/security/cap-users.md index 2702725241..a6c06c6ed7 100644 --- a/guides/security/cap-users.md +++ b/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. From 44a9aa4526f419583b57e937b2c8ca0f7166a6b1 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 15:01:02 +0100 Subject: [PATCH 08/13] add example for unsupported privileges --- guides/security/authorization.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/guides/security/authorization.md b/guides/security/authorization.md index ca929bf9dd..a4416a8ca0 100644 --- a/guides/security/authorization.md +++ b/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; ... } @@ -267,16 +267,30 @@ Restrictions can be defined on different types of CDS resources, but there are s 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} From 68a83822de53b09199069db4b286433af97a9235 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 16 Jan 2026 15:19:50 +0100 Subject: [PATCH 09/13] reduce text --- guides/security/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/security/authorization.md b/guides/security/authorization.md index a4416a8ca0..46f343f2cc 100644 --- a/guides/security/authorization.md +++ b/guides/security/authorization.md @@ -262,7 +262,7 @@ Restrictions can be defined on different types of CDS resources, but there are s | entity | | | 1 | | | action/function | | | 2 | = `@requires` | -> 1For 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`. +> 1For 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)
> 2 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: From 766a6cb24017a8db11db4af2c7ddd184e946b4ce Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Mon, 19 Jan 2026 12:36:18 +0100 Subject: [PATCH 10/13] ai review --- guides/security/overview.md | 38 ++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/guides/security/overview.md b/guides/security/overview.md index 2eb397262e..51b3b62443 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. ![Overview Customizable Components with CAP](./assets/security-customizable.drawio.svg){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 ![This TAM graphic is explained in the accompanying text.](./assets/cap-security-architecture-overview.png){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. @@ -190,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. @@ -219,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). @@ -227,15 +227,15 @@ 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 SAP Cloud Identity - Security Guide.](https://help.sap.com/docs/IDENTITY_AUTHENTICATION?#discover_task-security){.learn-more} From 8034555a2ef697394250524ff24654f9d2472dcd Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Tue, 20 Jan 2026 14:32:48 +0100 Subject: [PATCH 11/13] AI-supported review --- guides/security/authentication.md | 60 ++++++++++++------------ guides/security/authorization.md | 26 +++++----- guides/security/cap-users.md | 50 ++++++++++---------- guides/security/remote-authentication.md | 28 +++++------ 4 files changed, 81 insertions(+), 83 deletions(-) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index e62ca76bb2..c8cd6287fe 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -159,8 +159,8 @@ Mock users are deactivated in production profile by default ❗ ### Preconfigured Mock Users { #preconfigured-mock-users } -For convenience, the runtime creates default mock users to cover typical test scenarios, e.g. privileged users passing all security checks or users which pass authentication but do not have additional claims. -The predefined users are added to [custom mock users](#custom-mock-users) defined by the application. +For convenience, the runtime creates default mock users to cover typical test scenarios, such as privileged users passing all security checks or users that pass authentication but don't have additional claims. +The runtime adds the predefined users to [custom mock users](#custom-mock-users) you define in the application. You can opt out the preconfigured mock users by setting `cds.security.mock.defaultUsers = false`. { .java } @@ -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 [previously started bookshop sample application](#mock-user-authentication) with a deployment descriptor for SAP BTP, Cloud Foundry Runtime (CF). +You can best configure and test IAS authentication 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 } @@ -466,10 +466,10 @@ In the [Administrative Console for Cloud Identity Services](https://help.sap.com you can see and manage the deployed IAS application. You need a user with administrative privileges in the IAS tenant to access the services at `.accounts400.ondemand.com/admin`. In the Console you can manage the IAS tenant and IAS applications, for example: -- Create (test) users in `Users & Authorizations` -> `User Management` -- Deactivate users -- Configure the authentication strategy (password policies, MFA etc.) in `Applications & Resources` -> `Applications` (IAS instances listed with their display-name) -- Inspect logs in `Monitoring & Reporting` -> `Troubleshooting` +- Create (test) users in `Users & Authorizations` -> `User Management`. +- Deactivate users. +- Configure the authentication strategy (password policies, multifactor authentication, and similar) in `Applications & Resources` -> `Applications` (IAS instances listed with their display-name). +- Inspect logs in `Monitoring & Reporting` -> `Troubleshooting`. ::: tip In BTP Cockpit, service instance `bookshop-ias` appears as a link that allows direct navigation to the IAS application in the Administrative Console for IAS. @@ -510,7 +510,7 @@ The overall setup with CLI client and the Cloud services is sketched in the diag ![CLI-level Testing of IAS Endpoints](./assets/ias-cli-setup.drawio.svg){width="500px"} As IAS requires mTLS-protected channels, **client certificates are mandatory** for all of the following requests: -- Token request to IAS in order to fetch a valid IAS token (1) +- Token request to IAS to fetch a valid IAS token (1) - Business request to the CAP application presenting the token (2) - Initial proof token request to IAS - not required for all business requests (3) @@ -625,8 +625,8 @@ cf delete-service-key bookshop-ias bookshop-ias-key ### UI Level Testing -In the UI scenario, adding an Application Router as an ingress proxy to the deployment simplifies testing a lot. -It will take care of fetching the required IAS tokens when forwarding requests to the backend service. +In the UI scenario, adding an Application Router as an ingress proxy to the deployment simplifies testing significantly. +It fetches the required IAS tokens when forwarding requests to the backend service. Enhancing the project with [SAP Cloud Portal](../deploy/to-cf#option-a-sap-cloud-portal) configuration adds an Application Router component as well as HTML5 Application Repository: @@ -662,7 +662,7 @@ In addition, property `forwardAuthCertificates` needs to be `true` to support th ::: As the login flow is based on an HTTP redirect between the CAP application and IAS login page, -IAS needs to know a valid callback URI which is offered by the AppRouter out-of-the-box. +IAS needs to know a valid callback URI that the AppRouter offers out of the box. The same is true for the logout flow. ::: details Redirect URIs for login and logout @@ -704,7 +704,7 @@ The Application Router should redirect to a login flow where you can enter the c In contrast to [IAS](#ias-auth), XSUAA does not allow cross-landscape user propagation out of the box. ::: -XSUAA authentication is best configured and tested in the Cloud, so let's enhance the sample with a deployment descriptor for SAP BTP, Cloud Foundry Runtime (CF). +You can best configure and test XSUAA authentication in the Cloud, so let's enhance the sample with a deployment descriptor for SAP BTP, Cloud Foundry Runtime (CF). ### Get Ready with XSUAA { #xsuaa-ready } @@ -731,7 +731,7 @@ 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. +Command `add mta` enhances the project with `cds-starter-cloudfoundry` and therefore adds all [dependencies required for security](../../java/security#maven-dependencies) transitively. ::: @@ -811,7 +811,7 @@ There are some mandatory configuration parameters: ::: warning Upgrading the `service-plan` from type `application` to `broker` is not supported. -Hence, start with plan `broker` in case you want to provide technical APIs in future. +Start with plan `broker` if you want to provide technical APIs in future. ::: [Learn more about XSUAA application security descriptor configuration syntax](https://help.sap.com/docs/btp/sap-business-technology-platform/application-security-descriptor-configuration-syntax){.learn-more} @@ -855,9 +855,9 @@ For convenience, when adding the XSUAA facet, these artifacts are initially deri At runtime, after successful authentication, the scope prefix `$XSAPPNAME`is removed by the CAP integration to match the corresponding CAP role. -In the [deplyoment descriptor](#adding-xsuaa), the optional property `role-collections` contains a list of preconfigured role collections. -In general, role collections are [created manually](./cap-users#xsuaa-assign) at runtime by user administrators. -But in case the underlying role template has no reference to an attribute, a corresponding role collection can be prepared already for sake of convenience. +In the [deployment descriptor](#adding-xsuaa), the optional property `role-collections` contains a list of preconfigured role collections. +In general, user administrators [create role collections manually](./cap-users#xsuaa-assign) at runtime. +However, if the underlying role template has no reference to an attribute, you can prepare a corresponding role collection for convenience. In the example, role collection `admin (bookshop -)` containing the role template `admin` is defined and can be directly assigned to users. @@ -1017,7 +1017,7 @@ The request returns with a valid XSUAA token which is suitable to pass authentic {"access_token":"", "token_type":"bearer","expires_in":43199, [...]} ``` -With the token for the technical user, you should be able to access endpoints, which has no specific role requirements: +With the token for the technical user, you should be able to access endpoints that have no specific role requirements:
@@ -1039,8 +1039,8 @@ curl -H "Authorization: Bearer " \
-If you also want to access the `AdminService` which requires the role `admin`, -you need to fetch the token for the named user instead. That is the user which you have assigned the `admin (bookshop -)` role collection to. +If you also want to access the `AdminService` that requires the role `admin`, +you need to fetch the token for the named user instead. That is the user to whom you assigned the `admin (bookshop -)` role collection. With the token for the named user, the following request should succeed: @@ -1081,8 +1081,8 @@ cf delete-service-key bookshop-auth bookshop-auth-key ### UI Level Testing -In the UI scenario, adding an Application Router as an ingress proxy to the deployment simplifies testing a lot. -It will take care of fetching the required XSUAA tokens when forwarding requests to the backend service. +In the UI scenario, adding an Application Router as an ingress proxy to the deployment simplifies testing significantly. +It fetches the required XSUAA tokens when forwarding requests to the backend service. Enhancing the project with [SAP Cloud Portal](../deploy/to-cf#option-a-sap-cloud-portal) configuration adds an Application Router component as well as HTML5 Application Repository: @@ -1121,7 +1121,7 @@ modules: ::: As the login flow is based on an HTTP redirect between the CAP application and XSUAA login page, -XSUAA needs to know a valid callback URI which is offered by the Application Router out of the box. +XSUAA needs to know a valid callback URI that the Application Router offers out of the box. The same is true for the logout flow. ::: details Redirect URIs for login and logout @@ -1170,9 +1170,9 @@ will come soon
There are multiple reasons why customization might be required: -1. Endpoints for non-business requests often require specific authentication methods (e.g. health check, technical services). -2. The application is deployed in the context of a service mesh with ingress authentication (e.g. Istio). -3. The application needs to integrate with a 3rd party authentication service. +1. Endpoints for non-business requests often require specific authentication methods (for example, health check, technical services). +2. The application is deployed in the context of a service mesh with ingress authentication (for example, Istio). +3. The application needs to integrate with a third-party authentication service. ![Endpoints with different authentication strategy](./assets/custom-auth.drawio.svg){width="380px"} @@ -1181,9 +1181,9 @@ There are multiple reasons why customization might be required: - For CAP endpoints you are fine to go with the [automatic authentication](#model-auth) fully derived from the CAP model. -- For custom endpoints that should be protected by the same authentication strategy you are also fine with automatc authentication as CAP will cover these endpoints by default. -- For custom endpoints that should have a different kind of authentication strategy (e.g. X.509, basic or none) you can add a security configuration that [partially overrules](#partially-auth) the CAP integration partially for exactly these endpoints. -- In case the authentiaction is delegated to a different component, just [fully overrule](#fully-auth) CAP authentication and replace by any suitable strategy. +- For custom endpoints that should be protected by the same authentication strategy you are also fine with automatic authentication as CAP will cover these endpoints by default. +- For custom endpoints that should have a different kind of authentication strategy (for example, X.509, basic or none) you can add a security configuration that [partially overrules](#partially-auth) the CAP integration for exactly these endpoints. +- If the authentication is delegated to a different component, just [fully overrule](#fully-auth) CAP authentication and replace it with any suitable strategy. ::: tip Secure by Default **By default, CAP authenticates all endpoints of the microservice, including the endpoints which are not served by CAP itself**. @@ -1352,7 +1352,7 @@ TODO Endpoints of (CAP) applications deployed on SAP BTP are, by default, accessible from the public network. Without security middleware configured, CDS services are exposed to the public. -- **Don't rely on Application Router authentication**. Application Router as a frontend proxy does not shield the backend from incoming traffic. Therefore, the backend must be secured independently. +- **Don't rely on Application Router authentication**. Application Router as a frontend proxy does not shield the backend from incoming traffic. Therefore, you must secure the backend independently. - **Don't deviate from security defaults**. Only when absolutely necessary should experts make the decision to add modifications or replace parts of the standard authentication mechanisms. diff --git a/guides/security/authorization.md b/guides/security/authorization.md index 46f343f2cc..0768c90ae0 100644 --- a/guides/security/authorization.md +++ b/guides/security/authorization.md @@ -21,7 +21,7 @@ uacp: Used as link target from SAP Help Portal at https://help.sap.com/products/ -This guide explains how to restrict access to data by adding respective declarations to CDS models, which are then enforced by CAP's generic service providers. +This guide explains how to restrict access to data by adding respective declarations to CDS models, that are then enforced by CAP's generic service providers. [[toc]] @@ -56,7 +56,7 @@ Finally, according to the key concept [Customizable Security](./overview#key-con ### Internal Services CDS services that are only meant for *internal* usage shouldn't be exposed via protocol adapters. -In order to prevent access from *any* external clients, annotate those services with `@protocol: 'none'`: +To prevent access from *any* external clients, annotate those services with `@protocol: 'none'`: ```cds @protocol: 'none' @@ -398,9 +398,9 @@ annotate IssuesService.Components with @(restrict: [ { grant: '*', to: 'Supporter' }, { grant: 'READ', to: 'authenticated-user' } ]); ``` -Basically, users with the `Supporter` role aren't restricted, whereas authenticated users can only read the `Components`. But what about the auto-exposed entities such as `IssuesService.Issues` and `IssuesService.Categories`? They could be a target of an (indirect) request as outlined in [Events to Auto-Exposed Entities](#events-and-auto-expose), but none of them are annotated with a concrete restriction. In general, the same also holds for service entities, which are generated by the compiler, for example, for localization or draft support. +Basically, users with the `Supporter` role aren't restricted, whereas authenticated users can only read the `Components`. But what about the auto-exposed entities such as `IssuesService.Issues` and `IssuesService.Categories`? They could be a target of an (indirect) request as outlined in [Events to Auto-Exposed Entities](#events-and-auto-expose), but none of them are annotated with a concrete restriction. In general, the same also holds for service entities that are generated by the compiler, for example, for localization or draft support. -To close the gap with auto-exposed and generated entities, the authorization of such entities is delegated to a so-called **authorization entity**, which is the last entity in the request path, which bears authorization information, that means, which fulfills at least one of the following properties: +To close the gap with auto-exposed and generated entities, the authorization of such entities is delegated to a so-called **authorization entity**, which is the last entity in the request path, that bears authorization information, that means, that fulfills at least one of the following properties: - Explicitly exposed in the service - Annotated with a concrete restriction - Annotated with `@cds.autoexpose` @@ -425,7 +425,7 @@ So, the authorization for the requests in the example is delegated as follows: 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, which acts like a filter, establishes *instance-based authorization*. +This condition, that acts like a filter, establishes *instance-based authorization*. ### Filter Conditions @@ -633,7 +633,7 @@ Paths on 1:n associations (`Association to many`) evaluate to `true`, _if the co 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` which restricts access to users classified by assigned accounting areas: +Let's assume an entity `Orders` that restricts access to users classified by assigned accounting areas: ```cds annotate Orders with @(restrict: [ @@ -653,11 +653,11 @@ Entities that have an instance-based authorization condition, that is [`@restric 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 may affect performance. +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 to disclosure 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 behaviour otherwise. +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. @@ -680,7 +680,7 @@ See [solution sketches](#limitation-deep-authorization) for information about ho ### Associations -Queries to Application Services are not only authorized by the target entity which has a `@restrict` or `@requires` annotation, but also for all __associated entities__ that are used in the statement. +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 @@ -753,7 +753,7 @@ CAP authorization allows you to control access to your business data on a fine g 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, the application developers define the set of accessible resources in the CDS model for each role - and not the user administrator. +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} @@ -863,7 +863,7 @@ service BrowseEmployeesService @(requires:'Employee') { } ``` -A team (entity `Teams`) contains members of type `Employees`. An employee refers to a single contract (entity `Contracts`), which contains sensitive information that should be visible only to `Manager` users. +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**.
@@ -881,7 +881,7 @@ service BrowseEmployeesService @(requires:'Employee') { 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 an associated entity is not exposed) are still critical with regard to security. +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 diff --git a/guides/security/cap-users.md b/guides/security/cap-users.md index a6c06c6ed7..d34e05f8c8 100644 --- a/guides/security/cap-users.md +++ b/guides/security/cap-users.md @@ -2,7 +2,7 @@ # layout: cookbook label: CAP Users synopsis: > - This guide introduces to CAP user abstraction and role assignments. + This guide introduces CAP user abstraction and role assignments. status: released --- @@ -23,7 +23,7 @@ status: released -This guide introduces to CAP user abstraction and role assignments. +This guide introduces CAP user abstraction and role assignments. [[toc]] @@ -38,8 +38,8 @@ It contains static information about the user such as name, ID, and tenant. Addi After _successful_ authentication, a **CAP user** is mainly represented by the following properties: - **_Logon name_** identifying the user uniquely -- **_Tenant_** describes the tenant of the user (subscriber or provider) which implies the CDS model and business data container. -- **_Roles_** the user has been assigned by a user administrator (business [user roles](#roles)) or roles which are derived by the authentication level ([pseudo roles](#pseudo-roles)). +- **_Tenant_** describes the tenant of the user (subscriber or provider) that implies the CDS model and business data container. +- **_Roles_** the user has been assigned by a user administrator (business [user roles](#roles)) or roles that are derived by the authentication level ([pseudo roles](#pseudo-roles)). - **_Attributes_** the user has been assigned, for example, for instance-based authorization.
@@ -64,8 +64,8 @@ CAP users can be classified in multiple dimensions: - Technical users operate on behalf of an entire tenant at a technical API level. **Authenticated users vs. anonymous users** -- Authenticated users have successfully completed authentication by presenting valid credentials (e.g., a token). -- Anonymous users are unidentifiable in general, as they usually do not present any credentials. +- Authenticated users have successfully completed authentication by presenting valid credentials (for example, a token). +- Anonymous users are unidentifiable in general, as they usually don't present any credentials. **Provider vs. subscriber tenant** - The provider tenant includes all users of the application owner. @@ -104,12 +104,12 @@ Find more details about how to [switch the user context](#switching-users) durin ### Roles { #roles} CAP roles, which are defined on CDS resources such as services and entities, down to the events allowed on them, form the basis of [static access control](authorization#role-based-access-control). -Technically, the request user is restricted to the resources for which an appropriate CAP role is assiged. +Technically, the request user is restricted to the resources for which an appropriate CAP role is assigned. **Such roles should reflect basic operations performed by users interacting with the application**. In the following example, there are two different basic operations defined on domain level: -- `ReportIssues` describes users which view existing issues, report new issues and confirm provided solutions. -- `ProcessIssues` describes users which process issues. They also write notes for customers. +- `ReportIssues` describes users who view existing issues, report new issues and confirm provided solutions. +- `ProcessIssues` describes users who process issues. They also write notes for customers. ```cds annotate Issues with @(restrict: [ @@ -127,8 +127,8 @@ CAP roles represent basic building blocks of authorization rules that are define Independently of that, user administrators combine CAP roles in higher-level policies and assign them to business users in the platform's central authorization management solution _at runtime_. Dynamic assignments of roles to users can be done by -- [AMS roles](#roles-assignment-ams) in case of [IAS authentication](./authentication#ias-auth). -- [XSUAA roles](#xsuaa-roles) in case of [XSUAA authentication](./authentication#xsuaa-auth). +- [AMS roles](#roles-assignment-ams) for [IAS authentication](./authentication#ias-auth). +- [XSUAA roles](#xsuaa-roles) for [XSUAA authentication](./authentication#xsuaa-auth). ::: info CDS-based authorization deliberately avoids technical concepts, such as _scopes_ in _OAuth_, in favor of user roles, which are closer to the business domain of applications. @@ -137,7 +137,7 @@ CDS-based authorization deliberately avoids technical concepts, such as _scopes_ #### Pseudo Roles { #pseudo-roles} -Often it is useful to define access rules that aren't based on an application-specific user role, but rather on the _technical authentication level_ of the request which can be mapped to a pre-defined CAP role. +Often it is useful to define access rules that aren't based on an application-specific user role, but rather on the _technical authentication level_ of the request that can be mapped to a pre-defined CAP role. For instance, a service should be accessible only for technical users, with or without user propagation. Such roles are called pseudo roles as they aren't assigned by user administrators, but are added by the runtime automatically on successful authentication, reflecting the technical level: @@ -181,7 +181,7 @@ All technical clients that have access to the application's XSUAA or IAS service The object representation of the resolved CAP user is attached to the current request context and has an impact on the request flow, for instance with regard to - [authorizations](./authorization#restrictions) - [enriching business data](../domain/#managed-data) with user data -- setting DB session variables +- setting database session variables In the CDS model, some of the user properties can be referenced in annotations or static views: @@ -497,7 +497,7 @@ annotate AdminService.Books with @ams.attributes: { In general, the `@ams` annotation operates on the entity level. The value of the AMS attribute needs to point to a single-value property of the target entity (paths are supported). -You need to make use of a compiler expression in order to ensure validity of the value reference. +You need to make use of a compiler expression to ensure validity of the value reference. ::: tip @@ -699,7 +699,7 @@ You can now verify that the assigned policies enforce the expected access rules: - mock user `content-manager` has full access to `Books` and `Authors`. - mock user `stock-manager` can _read_ `Books` and `Authors` and can _edit_ `Books` (but _not_ `Authors`). -For the advanced test scenario, you can define custom policies in pre-defined package `local` which is ignored during [deployment of the policies](#ams-deployment) to the Cloud service and hence will not show up in production. +For the advanced test scenario, you can define custom policies in pre-defined package `local` that is ignored during [deployment of the policies](#ams-deployment) to the Cloud service and hence will not show up in production. Let's add a custom policy `StockManagerFiction` which is based on base policy `cap.StockManager` restricting the assigned users to the genres `Mystery` and `Fantasy`: @@ -813,7 +813,7 @@ Enhancing the project by `cds add ams` automatically adds task e.g. in the MTA f Note that the policy deployer task requires a path to a directory structure containing the `ams` root folder with the policies to be deployed. -By default, the path points to `srv/src/gen/policies` which is prepared automatically during build step with the appropriate policy-content copied from `srv/src/main/resources/ams`. +By default, the path points to `srv/src/gen/policies` that is prepared automatically during build step with the appropriate policy-content copied from `srv/src/main/resources/ams`. In addition, `@sap/ams` needs to be referenced to add the deployer logic.
@@ -859,7 +859,7 @@ In addition, `@sap/ams` needs to be referenced to add the deployer logic. Note that the policy deployer task requires a path to a directory structure containing the `ams/dcl` root folder with the policies to be deployed. -By default, the path points to `gen/policies` which is prepared automatically during build step with the appropriate policy-content copied from `ams/dcl`. +By default, the path points to `gen/policies` that is prepared automatically during build step with the appropriate policy-content copied from `ams/dcl`. In addition, `@sap/ams` needs to be referenced to add the deployer logic.
@@ -883,7 +883,7 @@ Afterwards, you can now perform the following tasks in the Administrative Consol To create a custom policy with filter restrictions, follow these steps: 1. Select **Applications & Resources** > **Applications**. Pick the IAS application of your project from the list. -2. In **Authorization Policies** select **Create** > **Create Restriction**. Choose an appropriate policy name, e.g. `StockManagerFiction`. +2. In **Authorization Policies** select **Create** > **Create Restriction**. Choose an appropriate policy name, for example, `StockManagerFiction`. 3. Customize the filter conditions for the available AMS attributes. 4. Confirm with **Save**. @@ -1138,9 +1138,9 @@ Next, you create a role collection that assigns these roles to your users. 8. Choose *Save* -If a user attribute isn't set for a user in the IdP of the SAP BTP Cockpit, this means that the user has no restriction for this attribute. +If a user attribute isn't set for a user in the identity provider of the SAP BTP Cockpit, this means that the user has no restriction for this attribute. For example, if a user has no value set for an attribute "Country", they're allowed to see data records for all countries. -In the _xs-security.json_, the `attribute` entity has a property `valueRequired` where the developer can specify whether unrestricted access is possible by not assigning a value to the attribute. +In the _xs-security.json_, the `attribute` entity has a property `valueRequired` where you as the developer can specify whether unrestricted access is possible by not assigning a value to the attribute. @@ -1265,7 +1265,7 @@ Depending on the configured [authentication](./authentication) strategy, CAP der In most cases, CAP's default mapping to the CAP user matches your requirements, but CAP also allows you to customize the mapping according to specific needs. -For instance, the logon name as injected by standard XSUAA integration might not be unique if several customer IdPs are connected to the underlying identity service. +For instance, the logon name as injected by standard XSUAA integration might not be unique if several customer identity providers are connected to the underlying identity service. Here a combination of `user_name` and `origin` mapped to `$user` might be a feasible solution that you can implement in a custom adaptation. This is done by means of a custom [UserInfoProvider](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/runtime/UserInfoProvider.html) interface that can be implemented as Spring bean as demonstrated in [Registering Global Parameter Providers](../../java/event-handlers/request-contexts#global-providers): @@ -1317,10 +1317,9 @@ Also consider data protection and privacy regulations when storing user data. There are multiple reasonable use cases in which user modification is a suitable approach: -- Injecting or mixing user roles by calling `modifiableUserInfo.addRole(String role)` (In fact this is the base for [AMS plugin](#roles-assignment-ams) injecting user specifc roles). +- Injecting or mixing user roles by calling `modifiableUserInfo.addRole(String role)` (In fact this is the base for [AMS plugin](#roles-assignment-ams) injecting user-specific roles). - Providing calculated attributes used for [instance-based authorization](./authorization#user-attrs) by invoking `modifiableUserInfo.setAttributeValues(String attribute, List values)`. - Constructing a request user based on forwarded (and trusted) header information, completely replacing default authentication. -- etc. [See more examples for custom UserInfoProvider](https://pages.github.tools.sap/cap/docs/java/event-handlers/request-contexts#global-providers){.learn-more} @@ -1359,7 +1358,6 @@ There are multiple reasonable use cases in which user modification is a suitable - Overriding user roles by calling `user.roles(roles)`. - Overriding user attributes and providing calculated attributes used for [instance-based authorization](./authorization#user-attrs) by invoking `user.attr(attributes)`. -- etc. ::: warning Be very careful when redefining `$user` and customizing `cds.middlewares` The user name is frequently stored with business data (for example, `managed` aspect) and might introduce migration efforts. @@ -1589,7 +1587,7 @@ Call application services on behalf of the privileged user only in case the serv
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 => { diff --git a/guides/security/remote-authentication.md b/guides/security/remote-authentication.md index 33e5cecf83..73c9a274ed 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 ![External services](./assets/external-services.drawio.svg){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. From 8c61d06d2a059a0711f368bbda7c3a48f75e52ee Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Tue, 20 Jan 2026 16:44:07 +0100 Subject: [PATCH 12/13] avoid sentences running over code blocks --- guides/security/authentication.md | 81 ++++++++++++++++--------------- 1 file changed, 42 insertions(+), 39 deletions(-) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index c8cd6287fe..d13a472277 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -117,8 +117,8 @@ As the mock user authentication is active, all (CAP) endpoints are [authenticate To simplify the development scenario, you can set cds.security.authentication.mode = "model-relaxed" to deactivate authentication of endpoints derived from unrestricted CDS services. ::: -Sending OData request `curl http://localhost:8080/odata/v4/CatalogService/Books --verbose` -results in a `401` error response from the server indicating that the anonymous user has been rejected due to missing authentication. +If you stay with the standard authentication mode, sending the OData request `curl http://localhost:8080/odata/v4/CatalogService/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 the case 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 `admin` (password: `admin`) with `curl http://admin:admin@localhost:8080/odata/v4/CatalogService/Books` returns successfully (HTTP response `200`). @@ -127,17 +127,17 @@ Mock users require **basic authentication**, hence sending the same request on b
-::: info +::: tip In non-production profile, endpoints derived from unrestricted CDS services are not authenticated to simplify the development scenario. ::: -Sending OData request +Send an OData request through the restricted `AdminService` as follows: ```sh 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 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` (no password) with @@ -314,7 +314,7 @@ You can best configure and test IAS authentication in the Cloud, so let's enhanc ### Get Ready with IAS { #ias-ready } -Before working with IAS on CF, you need to +Before working with IAS on CF, you need to do all of the following: - Prepare an IAS (test) tenant. If not available yet, you need to [create](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/get-your-tenant) it now. @@ -324,14 +324,12 @@ 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-authentication). In the project root folder, execute +You can continue with the sample [already created](#mock-user-authentication). In the project root folder, execute the following command to make your application ready for deployment to CF. ```sh cds add mta ``` -to make your application ready for deployment to CF. -
::: info @@ -340,9 +338,9 @@ Command `add mta` will enhance the project with `cds-starter-cloudfoundry` and t
-You also need to configure DB support: +You also need to configure database support: -```sh [SAP HANA] +```sh cds add hana ``` @@ -350,13 +348,13 @@ cds add hana ### Adding IAS -Now the application is ready to be enhanced with IAS-support by executing +Now the application is ready to be enhanced with IAS-support: ```sh cds add ias ``` -which automatically adds a service instance named `bookshop-ias` of type `identity` (plan: `application`) and binds the CAP application to it. +This command automatically adds a service instance named `bookshop-ias` of type `identity` (plan: `application`) and binds the CAP application to it in the _mta.yaml_. ::: details Generated deployment descriptor for IAS instance and binding ```yaml [mta.yaml] @@ -404,16 +402,16 @@ Service instance and binding offer the following crucial configuration propertie | `app-identifier` | _binding_ | _Ensures stable subject in generated certificate (required for credential rotation)_ | -[Lean more about IAS service instance and binding configuration](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/reference-information-for-identity-service-of-sap-btp){.learn-more} +[Learn more about IAS service instance and binding configuration.](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/reference-information-for-identity-service-of-sap-btp){.learn-more}
-Now let's pack and deploy the application with +Now let's pack and deploy the application: + ```sh cds up ``` -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: @@ -434,7 +432,7 @@ TODO
-::: tip +::: tip Local at this point? The local setup is still runnable on basis of mock users as there is no IAS binding in the environment. ::: @@ -480,7 +478,7 @@ In BTP Cockpit, service instance `bookshop-ias` appears as a link that allows di Due to CAP's autoconfiguration, all CAP endpoints are authenticated and expect valid OAuth tokens created for the IAS application. -Sending the test request +The following request as anonymous user without a token results in a `401 Unauthorized`:
@@ -500,9 +498,7 @@ curl https://--bookshop-srv. \
-as anonymous user without a token results in a `401 Unauthorized` as expected. - -Now let's fetch a token as basis for a fully authenticated test request. +This is expected. Now let's fetch a token as basis for a fully authenticated test request. For doing so, you need to interact with IAS service which requires an authenticated client itself. The overall setup with CLI client and the Cloud services is sketched in the diagram: @@ -718,13 +714,21 @@ You can create a bookshop sample as described in [Mock User Authentication](#moc 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: +If there is no deployment descriptor yet, execute the following in the project root folder: ```sh cds add mta ``` -You also need to configure DB support: +
+ +::: 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. +::: + +
+ +You also need to configure database support: ```sh [SAP HANA] cds add hana @@ -877,7 +881,7 @@ If you modify the _xs-security.json_ manually, make sure that the scope names in #### Start and Check the Deployment -Now let's pack and deploy the application with +Now let's pack and deploy the application:
@@ -928,7 +932,7 @@ The local setup is still runnable on basis of mock users as there is no IAS bind Due to CAP's autoconfiguration, all CAP endpoints are [authenticated automatically](#model-auth) and expect valid XSUAA tokens. -Sending the test request +The following request as anonymous user without a token results in a `401 Unauthorized`:
@@ -948,24 +952,22 @@ curl https://--bookshop-srv. \
-as anonymous user without a token the request results in a `401 Unauthorized` as expected. - -Now let's fetch an XSUAA token to prepare an authenticated test request. -To do so, you need to interact with XSUAA service which requires a valid authentication as well. +This is expected. Now let's fetch an XSUAA token to prepare an authenticated test request. +Here, you need to interact with XSUAA service which requires a valid authentication as well. -As first step add a new client for XSUAA by creating an appropriate service key with +As first step add a new client for XSUAA by creating an appropriate service key: ```sh cf create-service-key bookshop-auth bookshop-auth-key ``` -You can inspect the service key credentials by executing +You can inspect the service key credentials as follows: ```sh cf service-key bookshop-auth bookshop-auth-key ``` -which prints the information to the console: +This command prints the information to the console: ```json { @@ -1141,22 +1143,23 @@ The same is true for the logout flow. ::: -Now update the Cloud deployment with +Now update the Cloud deployment: ```sh cds up ``` -and verify it by running `cf apps` in the targeted space: +Verify it by running `cf apps` in the targeted space: ```sh -name requested state processes routes -bookshop-potal started web:1/1 --bookshop. -bookshop-potal-db-deployer stopped web:0/1 -bookshop-potal-srv started web:1/1 --bookshop-srv. +> $ cf apps +name requested state processes routes +bookshop-portal started web:1/1 --bookshop. +bookshop-portal-db-deployer stopped web:0/1 +bookshop-portal-srv started web:1/1 --bookshop-srv. ``` -and open the route exposed by the `bookshop` UI application in a new browser session. +Open the route exposed by the `bookshop` UI application in a new browser session. From 95a50af949fbfc22b5704fcb9c8aa2c99f4c0726 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Tue, 20 Jan 2026 17:09:10 +0100 Subject: [PATCH 13/13] fix --- guides/security/authentication.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/guides/security/authentication.md b/guides/security/authentication.md index d13a472277..17f90e99eb 100644 --- a/guides/security/authentication.md +++ b/guides/security/authentication.md @@ -383,7 +383,7 @@ resources:
::: info -The [binding](../../java/security#bindings) to service instance of type `identity` is the trigger to automatically enforce IAS authentiaction at runtime ❗ +The [binding](../../java/security#bindings) to service instance of type `identity` is the trigger to automatically enforce IAS authentication at runtime ❗ :::
@@ -720,14 +720,6 @@ If there is no deployment descriptor yet, execute the following in the project r cds add mta ``` -
- -::: 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. -::: - -
- You also need to configure database support: ```sh [SAP HANA]