+
+After the application is built, check the *srv/src/main/resources/ams* folder to see the generated AMS *schema* and a *basePolicies* DCL file in a package called *cap*:
+
+::: code-group
+
+``` [srv/src/main/resources]
+└─ ams
+ ├─ cap
+ │ └─ basePolicies.dcl
+ └─ schema.dcl
+```
+
+:::
+
+
+
+
+After the application is built, check the *ams/dcl* folder to see the generated AMS *schema* and a *basePolicies* DCL file in a package called *cap*:
+
+::: code-group
+
+``` [./ams]
+└─ dcl
+ ├─ cap
+ │ └─ basePolicies.dcl
+ └─ schema.dcl
+```
+
+:::
+
+
+[Learn more about policy generation](https://sap.github.io/cloud-identity-developer-guide/CAP/cds-Plugin.html#dcl-generation){.learn-more}
+
+
+The generated policies are a good starting point to add manual modifications.
+
+The generated DCL schema includes all AMS attributes exposed for filtering basically:
+
+```yaml [/ams/schema.dcl]
+SCHEMA {
+ Genre : String
+}
+```
+
+In the schema you may configure [value help](https://sap.github.io/cloud-identity-developer-guide/Authorization/ValueHelp.html) for the attributes in the [Cockpit UI for AMS](#ams-deployment).
+
+The generated policies are usually subject to change.
+For example, you can rename the policies to reflect appropriate job functions and adjust the referenced CAP roles according to your needs:
+
+```yaml [/ams/cap/basePolicies.dcl]
+POLICY StockManager {
+ ASSIGN ROLE ManageBooks WHERE Genre IS NOT RESTRICTED;
+}
+
+POLICY ContentManager {
+ ASSIGN ROLE ManageAuthors;
+ ASSIGN ROLE ManageBooks;
+}
+```
+
+In contrast to a `StockManager` who is responsible for the books offering, a `ContentManager` additionally makes the author selection.
+Optionally, a `StockManager` with CAP role `ManageBooks` may be restricted to specific genres by applying filters prepared in [customized policies](#local-testing).
+As a `ContentManager` there is no genre-based restriction based on genres is prepared.
+
+There are several options for the attribute declarations that have an impact on the effect of filters:
+
+| Attribute Statement | Description | Attribute Filter |
+|:-----------------------:|:--------------------:|:---------------:|
+| `WHERE Genre IS NOT RESTRICTED` | Offers `Genre` as filterable attribute in the scope of the role | Filter restriction could be provided in a custom policy, but no filter applied by default (potentially restricted) |
+| `WHERE Genre IS RESTRICTED` | Enforces `Genre` as filtered attribute in the scope for the role | Filter restriction must be provided in a custom policy and is applied (restricted) |
+| - no defintion - | The role does not offer any attribute for filtering | No restriction filter is applied (unrestricted) |
+
+::: tip
+The attribute statement is in the scope of a dedicated CAP role and filters are applied on matching entites only.
+:::
+
+[Learn more about AMS policies](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/configuring-authorization-policies){.learn-more}
+
+
+### Local Testing { #local-testing }
+
+Although the AMS policies are not yet [deployed to the Cloud service](#ams-deployment), you can assign (base) policies to mock users and run locally:
+
+
+
+```yaml
+cds:
+ security:
+ mock:
+ users:
+ content-manager: // [!code ++]
+ policies: // [!code ++]
+ - cap.ContentManager // [!code ++]
+ stock-manager: // [!code ++]
+ policies: // [!code ++]
+ - cap.StockManager // [!code ++]
+```
+
+
+
+
+
+```json [package.json]
+{
+ "cds": {
+ "requires": {
+ "auth": {
+ "[development]": {
+ "kind": "mocked",
+ "users": {
+ "content-manager": { // [!code ++:5]
+ "policies": [
+ "cap.ContentManager"
+ ]
+ },
+ "stock-manager": { // [!code ++:5]
+ "policies": [
+ "cap.StockManager"
+ ]
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+
+
+:::tip
+Don't forget to refer to fully qualified policy names including the package name (`cap` in this example).
+:::
+
+Now (re)start the application with
+
+
+
+and verify in the UI for `AdminService` (`http://localhost:8080/index.html#Books-manage`) that the the assigned policies imply the expected access rules:
+
+
+
+
+
+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 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 no 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`:
+
+```yaml [/ams/local/customPolicies.dcl]
+POLICY StockManagerFiction {
+ USE cap.StockManager RESTRICT Genre IN ('Mystery', 'Fantasy');
+}
+```
+
+[Learn more about DCL operators](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/condition-operators){.learn-more}
+
+
+
+::: tip
+Don't miss to add the policy files in sub folders of `ams` reflecting the namespace properly: Policy `local.StockManagerFiction` is expected to be in a file within directory `/ams/local/`.
+:::
+
+```yaml
+cds:
+ security:
+ mock:
+ users:
+ stock-manager-fiction: // [!code ++]
+ policies: // [!code ++]
+ - local.StockManagerFiction // [!code ++]
+```
+
+You can verify in the UI that mock user `stock-manager-fiction` is restricted to books of genres `Mystery` and `Fantasy`.
+
+
+
+
+
+::: tip
+Don't miss to add the policy files in sub folders of `ams/dcl` reflecting the namespace properly: Policy `local.StockManagerFiction` is expected to be in a file within directory `./ams/dcl/local/`.
+:::
+
+```json [package.json]
+{
+ "cds": {
+ "requires": {
+ "auth": {
+ "[development]": {
+ "kind": "mocked",
+ "users": {
+ "stock-manager-fiction": { // [!code ++:5]
+ "policies": [
+ "local.StockManagerFiction"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+
+
+[Learn more about AMS attribute filters with CAP](https://sap.github.io/cloud-identity-developer-guide/CAP/InstanceBasedAuthorization.html#instance-based-authorization){.learn-more}
+
+
+### Cloud Deployment { #ams-deployment }
+
+If not done yet, prepare your project Cloud deployment [as eplained before](./authentication#ias-ready).
+
+Policies can be automatically deployed to the AMS server during deployment of the application by means of AMS deployer script available in `@sap/ams`.
+
+Enhancing the project with by `cds add ams` automatically adds task e.g. in the MTA for AMS policy deyployment.
+
+
+
+::: details AMS policy deployer task in the MTA
+
+::: code-group
+```yaml [mta.yaml- deployer task]
+- name: bookshop-ams-policies-deployer
+ type: javascript.nodejs
+ path: srv/src/gen/policies # Node.js: gen/policies
+ parameters:
+ buildpack: nodejs_buildpack
+ no-route: true
+ no-start: true
+ tasks:
+ - name: deploy-dcl
+ command: npm start
+ memory: 512M
+ requires:
+ - name: bookshop-ias
+ [...]
+```
+
+
+```json [srv/src/gen/policies/package.json - deyployer module]
+{
+ "name": "ams-dcl-content-deployer",
+ "version": "3.0.0",
+ "dependencies": {
+ "@sap/ams": "^3"
+ },
+ [...]
+ "scripts": {
+ "start": "npx --package=@sap/ams deploy-dcl"
+ }
+}
+```
+
+:::
+
+
+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`.
+In addition, `@sap/ams` needs to be referenced to add the deployer logic.
+
+
+
+
+
+::: details AMS policy deployer task in the MTA
+
+::: code-group
+```yaml [mta.yaml - deployer task]
+- name: bookshop-ams-policies-deployer
+ type: javascript.nodejs
+ path: gen/policies
+ parameters:
+ buildpack: nodejs_buildpack
+ no-route: true
+ no-start: true
+ tasks:
+ - name: deploy-dcl
+ command: npm start
+ memory: 512M
+ requires:
+ - name: bookshop-ias
+ [...]
+```
+
+
+```json [gen/policies/package.json - deyployer module]
+{
+ "name": "ams-dcl-content-deployer",
+ "version": "3.0.0",
+ "dependencies": {
+ "@sap/ams": "^3"
+ },
+ [...]
+ "scripts": {
+ "start": "npx --package=@sap/ams deploy-dcl"
+ }
+}
+```
+
+:::
+
+
+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`.
+In addition, `@sap/ams` needs to be referenced to add the deployer logic.
+
+
+
+::: tip
+Several microservices sharing the same IAS instance need a common folder structure the deployer task operates on.
+It contains the common view of policies applied to all services.
+:::
+
+[Learn more about AMS deployer](https://sap.github.io/cloud-identity-developer-guide/Authorization/DeployDCL.html#ams-policies-deployer-app){.learn-more}
+
+Now let's deploy and start the application with
+
+```sh
+cds up
+```
+
+You can now perform the following tasks in the Administrative Console for the IAS tenant (see prerequisites [here](./authentication#ias-admin)):
+- Assign (base or custom) policies to IAS users
+- Create custom policies
+
+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`.
+3. Customize the filter conditions for the available AMS attributes
+4. Confirm with **Save**
+
+::: details Create custom AMS policy with filter condition
+
+
+
+
+
+:::
+
+[Learn more about how to create custom AMS policies](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/create-authorization-policy){.learn-more}
+
+
+To assign a policy to an IAS user, follow these steps:
+1. Select **Applications & Resources** > **Applications**. Pick the IAS application of your project from the list.
+2. Switch to tab **Authorization Policies** and select the policy you want to assign
+3. In **Assignments**, add the IAS user of the tenant to which the policy should be assigned (you can review the policy definition in **Rules**).
+
+[Learn more about how to edit custom AMS policies](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/edit-authorization-policy){.learn-more}
+
+::: details Assign AMS policy to an IAS user
+
+
+
+
+
+:::
+
+
+You can log on to the bookshop test application with the test user and check that only books of dedicated genres can be modified.
+
+[Learn more about AMS policy assignment](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/assign-authorization-policies) {.learn-more}
+
+
+
+### Tracing
+
+You can verify a valid configfuration of the AMS plugin by the following log output:
+
+
+
+```sh
+c.s.c.s.a.c.AmsRuntimeConfiguration : Configured AmsUserInfoProvider
+```
+
+
+
+
+
+```sh
+[ams] - AMS Plugin loaded.
+[ams] - Added AMS middleware after 'auth' middleware.
+```
+
+
+
+In addition, for detailed analysis of issues, you can set AMS logger to `DEBUG` level:
+
+
+
+```yaml
+logging:
+ level:
+ com.sap.cloud.security.ams: DEBUG
+```
+
+
+
+
+
+```json
+{
+ "cds": {
+ "log": {
+ "levels": {
+ "ams": "DEBUG"
+ }
+ }
+ }
+}
+```
+
+
+
+which gives you more information about the policy evaluation at request time:
+
+
+
+```sh
+c.s.c.s.a.l.PolicyEvaluationSlf4jLogger : Policy evaluation result: {...,
+"unknowns":"[$app.Genre]", "$dcl.policies":"[local.StockManagerFiction]",
+ ...
+"accessResult":"or( eq($app.Genre, "Mystery") eq($app.Genre, "Fantasy") )"}.
+```
+
+
+
+
+
+```sh
+[ams] - Determined potential actions for resource '$SCOPES': stock-manager {
+ potentialActions: Set(1) { 'stock-manager' },
+ policies: [ 'local.StockManagerFiction' ],
+ ...
+ }
+[ams] - AMS user roles added to user.is: [ 'stock-manager' ]
+[ams] - Privilege check for 'stock-manager' on '$SCOPES' was conditional. {
+ result: 'conditional',
+ dcn: "$app.genre IN ['Fantasy', 'Mystery']",
+ policies: [ 'local.StockManagerFiction' ],
+ ...
+ }
+[ams] - Resulting privileges for READ on AdminService.Books : [
+ {
+ grant: 'READ',
+ to: [ 'stock-manager' ],
+ where: "genre.name IN ('Fantasy', 'Mystery')"
+ }
+ ]
+```
+
+
+
+You can add general user information by applying [user tracing](#user-tracing).
+
+::: tip
+It might be useful to investiagte the injected filter conditions by activating the query-trace (logger `com.sap.cds.persistence.sql`).
+:::
+
+
+## Role Assignment with XSUAA { #xsuaa-roles }
+
+Information about roles and attributes can be made available to the XSUAA platform service.
+This information enables the respective JWT tokens to be constructed and sent with the requests for authenticated users.
+
+In particular, the following happens automatically behind-the-scenes upon build:
+
+
+### Generate Security Descriptor
+
+Derive scopes, attributes, and role templates from the CDS model:
+
+`) to the *Roles* list.
+7. Add the email addresses for your users to the *Users* list.
+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.
+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.
+
+
+
+## Developing with CAP Users { #developing-with-users }
+
+CAP is not tied to any specific authentication method, nor to concrete user information such as that provided by IAS or XSUAA.
+Instead, an abstract [user representation](cap-users#claims) is attached to the request which can be used to influence request processing.
+For example, both authorization enforcement and domain logic can depend on properties of the the current user.
+
+::: warning
+Avoid writing custom code based on the raw authentication info, as this undermines the decoupling between authentication strategy and your business logic.
+:::
+
+::: tip
+**In most casese, there is no need to write custom code dependent on the CAP user - leverage CDS modelling whenever possible**.
+:::
+
+
+### Reflection { #reflection }
+
+
+
+In CAP Java, The CAP user of a request is represented by a [UserInfo](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/UserInfo.html) object that can be retrieved from the [RequestContext](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/RequestContext.html) of a handler in different ways:
+
+```java
+@Before(entity = Books_.CDS_NAME)
+public void beforeReadBooks(CdsReadEventContext context) {
+ UserInfo userInfo = context.getUserInfo();
+ String name = userInfo.getName();
+ // [...]
+}
+```
+
+or by Spring dependency injection within a handler bean:
+
+```java
+@Autowired
+UserInfo userInfo;
+
+@After(event = CqnService.EVENT_READ)
+public void discountBooks(Stream
books) {
+ String name = userInfo.getName();
+ // [...]
+}
+```
+
+There is always an `UserInfo` attached to the current `RequestContext`, reflecting any type of [users](#user-types).
+The `UserInfo` object is not modifyable, but during request processing, a new `RequestContext` can be spawned and may be accompanied by a [switch of the current user](#switching-users).
+
+
+Depending on the configured [authentication](./authentication) strategy, CAP derives a *default set* of user claims containing the user's name, tenant, attributes and assigned roles:
+
+| User Property | UserInfo Getter | XSUAA JWT Property | IAS JWT Property | `@restrict`-annotation |
+|---------------|-----------------------------------------|-----------------------------|-------------------------|------------------------|
+| _Logon name_ | `getName()` | `user_name` | `sub` | `$user` |
+| _Tenant_ | `getTenant()` | `zid` | `app_tid` | `$user.tenant` |
+| _Attributes_ | `getAttributeValues(String attr)` | `xs.user.attributes.` | All non-meta attributes | `$user.` |
+| _Roles_ | `getRoles()` and `hasRole(String role)` | `scopes` | n/a - injected via AMS | String in `to`-clause |
+
+::: tip
+CAP does not make any assumptions on the presented claims given in the token. String values are copied as they are.
+:::
+
+In addition, there are getters to retrieve information about [pseudo-roles](#pseudo-roles):
+
+| UserInfo method | Description | CAP Role |
+|:--------------------|:-------------------------------------------------------------------------------------------------------------------|----------------------|
+| `isAuthenticated()` | True if the current user has been authenticated. | `authenticated-user` |
+| `isSystemUser()` | Indicates whether the current user has pseudo-role `system-user`. | `system-user` |
+| `isInternalUser()` | Indicates whether the current user has pseudo-role `internal-user`. | `internal-user` |
+| `isPrivileged()` | Returns `true` if the current user runs in [privileged mode](#switching-to-privileged-user), i.e. is unrestricted. | n/a |
+
+
+
+In CAP Node.js, the CAP user of a request is represented by a [`cds.User`](../../node.js/authentication#cds-user) object.
+An instance of `cds.User` representing the current principal is available from the current request context in `req.user`.
+Similarly, the identifier of the user's tenant is available from `req.tenant`.
+
+```js
+srv.before('READ', srv.entities.Books, req => {
+ const { user, tenant } = req
+ // [...]
+})
+```
+
+In addition to the request context, information about the current user can similarly be retrieved from the global [`cds.context`](../../node.js/events#cds-context), which provides access to the current [`cds.EventContext`](../../node.js/events#cds-event-context):
+
+```js
+const cds = require('@sap/cds')
+const { user, tenant } = cds.context
+```
+
+:::tip
+Prefer local req objects in your handlers for accessing event context properties, as each access to `cds.context` happens through [AsyncLocalStorage.getStore()](https://nodejs.org/api/async_context.html#asynclocalstoragegetstore), which induces some minor overhead.
+:::
+
+Setting `cds.context` usually happens in inbound authentication middlewares or in inbound protocol adapters.
+During processing, you can set it programmatically or spawn a new root transaction providing a context argument to achieve a [switch of the current user](#switching-users--switching-users-node).
+
+Depending on the configured [authentication](./authentication) strategy, CAP derives a default set of user claims containing the user's name, tenant, attributes and assigned roles:
+
+| User Property | UserInfo Getter | XSUAA JWT Property | IAS JWT Property | `@restrict`-annotation |
+|---------------|-------------------------------------|-----------------------------|-------------------------|------------------------|
+| _Logon name_ | `user.id` | `user_name` | `sub` | `$user` |
+| _Tenant_ | `req.tenant` / `cds.context.tenant` | `zid` | `app_tid` | `$user.tenant` |
+| _Attributes_ | `attr(attr)` | `xs.user.attributes.
` | All non-meta attributes | `$user.` |
+| _Roles_ | `is(role)` | `scopes` | n/a - injected via AMS | String in `to`-clause |
+
+
+
+In most cases, CAP's default mapping to the CAP user will match 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.
+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):
+
+::: details Sample implementation to override the user name
+
+```java
+@Component
+@Order(1)
+public class UniqeNameUserInfoProvider implements UserInfoProvider {
+
+ private UserInfoProvider defaultProvider;
+
+ @Override
+ public UserInfo get() {
+ ModifiableUserInfo userInfo = UserInfo.create();
+ if (defaultProvider != null) {
+ UserInfo prevUserInfo = defaultProvider.get();
+ if (prevUserInfo != null) {
+ userInfo = prevUserInfo.copy();
+ }
+ }
+ if (userInfo != null) {
+ XsuaaUserInfo xsuaaUserInfo = userInfo.as(XsuaaUserInfo.class);
+ userInfo.setName(xsuaaUserInfo.getEmail() + "/" +
+ xsuaaUserInfo.getOrigin()); // adapt name
+ }
+
+ return userInfo;
+ }
+
+ @Override
+ public void setPrevious(UserInfoProvider prev) {
+ this.defaultProvider = prev;
+ }
+}
+```
+
+:::
+
+In the example, the `UniqeNameUserInfoProvider` defines an overlay on the default XSUAA-based provider (`defaultProvider`) by leveraging chaining technique (`@Order(1)` ensures proper ordering).
+`UserInfo.copy()` returns [`ModifiableUserInfo`](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/ModifiableUserInfo.html) interface which allows arbitrary modifications such as
+overriding the user's name by a combination of email and origin.
+
+::: warning Be very careful when redefining `$user`
+The user name is frequently stored with business data (for example, `managed` aspect) and might introduce migration efforts.
+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).
+- 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}
+
+
+
+
+
+In most cases, CAP's default mapping to the CAP user will match 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.
+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 can be done by modifying `cds.middlewares`.
+To modify the `cds.context.user` while still relying on existing generic middlewares, a new middleware must be registered after the `auth` middleware.
+If you intend to manipulate the `cds.context.tenant` as well, the new middlware must run before `cds.context.model` is set for the current request.
+
+::: details Sample implementation to override the user id
+
+```js
+cds.middlewares.before = [
+ cds.middlewares.context(),
+ cds.middlewares.trace(),
+ cds.middlewares.auth(),
+ function ctx_user (_,__,next) {
+ const ctx = cds.context
+ ctx.user.id = ctx.user.attr('origin') + ctx.user.id
+ next()
+ },
+ cds.middlewares.ctx_model()
+]
+```
+
+:::
+
+There are multiple reasonable use cases in which user modification is a suitable approach:
+
+- 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.
+Also consider data protection and privacy regulations when storing user data.
+:::
+
+:::tip Custom Authentication Middleware
+In case you require even more control, it is possible to replace the authentication middleware with a fully [Custom Authentication](../../node.js/authentication#custom).
+:::
+
+
+
+### Switching Users { #switching-users }
+
+
+
+There are a few typical use cases in a (multitenant) application where switching the current user of the request is required.
+For instance, the business request on behalf of a named subscriber user needs to reach out to a platform service on behalf of the underlying technical user of the subscriber.
+
+These scenarios are identified by a combination of the user (*technical* or *named*) and the tenant (*provider* or *subscriber*):
+
+
+
+In CAP Java, the user context can only be modified by explicitly opening an appropriate Request Context which ensures a well-defined scope for the changed settings.
+Services might, for example, trigger HTTP requests to external services by deriving the target tenant from the current Request Context.
+
+The `RequestContextRunner` API offers convenience methods that allow an easy transition from the current Request Context to a derived one according to the concrete scenario.
+
+| Method | Scenario |
+|----------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `systemUser()` | [Switches](#switching-to-technical-user) to the **technical user** and preserves the tenant from the current user. |
+| `systemUserProvider()` | [Switches](#switching-to-provider-tenant) to the **technical user of the provider account**. |
+| `systemUser(tenant)` | [Switches](#switching-to-subscriber-tenant) to a **technical user targeting a given subscriber account**. |
+| `privilegedUser()` | [Elevates](#switching-to-privileged-user) the current `UserInfo` to by-pass all authorization checks. |
+| `anonymousUser()` | [Switches](#switching-to-anonymous-user) to an anonymous user. |
+
+Named user contexts are only created by the CAP Java framework as initial Request Context based on appropriate authentication information (for example, JWT token) attached to the incoming HTTP request.
+
+:::tip Note
+- It is not possible to switch from technical user to a named user.
+- Asynchronous requests to CAP services are always on behalf of a technical user.
+:::
+
+
+
+
+
+There are a few typical use cases in a (multitenant) application, where switching the current user of the request is required.
+For instance, the business request on behalf of a named subscriber user needs to reach out to a service on behalf of the subscribers technical user.
+
+These scenarios are identified by a combination of the user (*technical* or *named*) and the tenant (*provider* or *subscriber*):
+
+
+
+In CAP Node.js, the `cds.context` allows to access the current `cds.EventContext` and enables updating the principal of the context.
+The prefered method for switching users and executing code in a different context and for a different principal, is to spawn a new root transaction using [`cds/srv.tx()`](../../node.js/cds-tx#srv-tx).
+Providing a `ctx` argument when creating a new root transaction allows switching the user for nested operations.
+The `cds.User` class exposes convenience constructors and accessors for specialized `cds.User` instances that represent typical technical principals you may require.
+
+```js
+const newUser = new cds.User({ id: '...', roles: [...], ...})
+await srv.tx ({ user: newUser, tenant: '' }, async tx => {
+ // Perform operations with a privileged principal
+})
+```
+
+:::tip
+When creating new root transactions in calls to [`cds/srv.tx()`](../../node.js/cds-tx#srv-tx), all properties not specified in the `ctx` argument are inherited from `cds.context`, if set in the current continuation.
+:::
+
+
+
+#### Switching to Technical User {#switching-to-technical-user }
+
+
+
+{width="330px"}
+
+The incoming JWT token triggers the creation of an initial Request Context with a named user.
+Accesses to the database in the OData Adapter as well as the custom `On` handler are executed within tenant1 and authorization checks are performed for user JohnDoe.
+An additionally defined `After` handler wants to call out to an external service using a technical user without propagating the named user JohnDoe.
+To achieve this, it's required to call `requestContext()` on the current `CdsRuntime` and use the `systemUser()` method to remove the named user from the new Request Context:
+
+```java
+@After(entity = Books_.CDS_NAME)
+public void afterHandler(EventContext context){
+ runtime.requestContext().systemUser().run(reqContext -> {
+ // call technical service
+ });
+}
+```
+
+
+
+
+
+{width="330px"}
+
+The incoming JWT token triggers the creation of an initial `cds.EventContext` with a named user.
+Accesses to the database in the OData Adapter as well as the custom `.on` handler are executed within _tenant1_ and authorization checks are performed for user _JohnDoe_.
+
+In addition, there is an `.after` handler that wants to call out to an external service using a technical user without propagating the named user _JohnDoe_.
+To achieve this, you can create a new root transaction using `srv.tx` and use it to connect to the external service from within a new context:
+
+```js
+srv.after('*', srv.entities.Books, async (res, req) => {
+ await srv.tx({ user: cds.User.privileged }, async tx => {
+ // call technical service
+ })
+})
+```
+
+
+
+#### Switching to Technical Provider Tenant {#switching-to-provider-tenant }
+
+
+
+{width="500px"}
+
+The application offers a bound action in a CDS entity. Within the action, the application communicates with a remote CAP service using an internal technical user from the provider account.
+The corresponding `on` handler of the action needs to create a new Request Context by calling `requestContext()`.
+Using the `systemUserProvider()` method, the existing user information is removed and the tenant is automatically set to the provider tenant.
+This allows the application to perform an HTTP call to the remote CAP service, which is secured using the pseudo-role `internal-user`.
+
+```java
+@On(entity = Books_.CDS_NAME)
+public void onAction(AddToOrderContext context){
+ runtime.requestContext().systemUserProvider().run(reqContext -> {
+ // call remote CAP service
+ });
+}
+```
+
+
+
+
+
+{width="500px"}
+
+In this scenario the application offers a bound action in a CDS entity.
+Within the action, the application communicates with a remote CAP service using a privileged user and the provider tenant.
+The corresponding `.on` handler of the action needs to create a new root transaction by calling `srv.tx`.
+The user passed to `srv.tx` in the `ctx` attribute will be used as the prinicpal for requests made within the new root transaction.
+
+```js
+srv.on('action', srv.entities.Books, async req => {
+ const systemUser = new cds.User({ id: 'system', roles: [ 'internal-user' ] })
+ await srv.tx({ user: systemUser , tenant: 'provider-tenant' }, async tx => {
+ // call remote CAP service
+ })
+})
+```
+
+
+
+#### Switching to a Specific Technical Tenant {#switching-to-subscriber-tenant }
+
+
+
+{width="450px"}
+
+The application is using a job scheduler that needs to regularly perform tasks on behalf of a certain tenant.
+By default, background executions (for example in a dedicated thread pool) aren't associated to any subscriber tenant and user.
+In this case, it's necessary to explicitly define a new Request Context based on the subscribed tenant by calling `systemUser(tenantId)`.
+This ensures that the Persistence Service performs the query for the specified tenant.
+
+```java
+runtime.requestContext().systemUser(tenant).run(reqContext -> {
+ return persistenceService.run(Select.from(Books_.class))
+ .listOf(Books.class);
+});
+```
+
+::: warning Resource Bottlenecks in Tenant Looping
+Avoid iterating through all subscriber tenants to perform tenant-specific tasks.
+Instead, prefer a task-based approach which processes specific subscriber tenants selectively.
+:::
+
+
+
+
+
+{width="450px"}
+
+The application is using [`cds.spawn`](../../node.js/cds-tx#cds-spawn) to regularly perform tasks on behalf of a certain tenant.
+By default, operations that are nested within `cds.spawn` will inherit the outer context.
+You can explicitly define the context `cds.spawn` should use by passing relevant information in a `ctx` argument.
+This enables to ensure that the Persistence Service performs the query for the specified tenant.
+
+```js
+cds.spawn({ user: cds.User.privileged, tenant: 'tenant1', every: '1h' }, async tx => {
+ await persistenceService.run(SELECT.from(Books))
+})
+```
+
+::: warning Resource Bottlenecks in Tenant Looping
+Avoid iterating through all subscriber tenants to perform tenant-specific tasks.
+Instead, prefer a task-based approach which processes specific subscriber tenants selectively.
+:::
+
+
+
+
+
+#### Switching to Privileged User { #switching-to-privileged-user }
+
+Application services invoked within custom handlers enforce an authorization on second-layer, which is the preferred behaviour to ensure security by default.
+However, in certain situations, you might want to bypass additional authorization checks if the initial request authorization is deemed sufficient.
+
+Such service calls can be executed on behalf of a privileged user, acting as a superuser without restrictions:
+```java
+cdsRuntime.requestContext().privilegedUser().run(privilegedContext -> {
+ assert privilegedContext.getUserInfo().isPrivileged();
+ // service calls in this scope pass generic authorization handler
+});
+```
+
+::: warning
+Call application services on behalf of the privileged user only in case the service call is fully independent from the business user's actual restrictions.
+:::
+
+
+
+#### Switching to Anonymous User { #switching-to-anonymous-user }
+
+
+
+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.
+
+Such service calls can be executed on behalf of the anonymous user, acting as a public user without personal user claims:
+```java
+cdsRuntime.requestContext().anonymousUser().run(privilegedContext -> {
+ // ... Service calls in this scope pass generic authorization handler
+
+});
+```
+
+
+
+
+
+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.
+
+```js
+cds.tx({ user: cds.User.anonymous }, async tx => {
+ // Perform operations anonymously
+})
+```
+
+
+
+### User Propagation { #user-propagation }
+
+
+
+#### Between Threads
+
+Within the same Request Context, all CAP service calls share the same user information.
+By default, the Request Context of the current thread is not shared with spawned threads and hence user information is lost.
+If you want to avoid this, you can propagate the Request Context to spawned threads as described [here](https://pages.github.tools.sap/cap/docs/java/event-handlers/request-contexts#threading-requestcontext) and hence the same user context is applied.
+
+
+
+#### Non-CAP Libraries { #user-token }
+
+
+
+CAP plugins for IAS and XSUAA store the resolved user information in Spring's [`SecurityContext`](https://docs.spring.io/spring-security/reference/api/java/org/springframework/security/core/context/SecurityContext.html) which contains all relevant authentication information. Hence, library code can rely on standards to fetch the authentication information and restore the user information if needed.
+
+In addition, the [authentication information](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/authentication/AuthenticationInfo.html) is stored in the Request Context and can be fetched as sketched here:
+
+```java
+AuthenticationInfo authInfo = context.getAuthenticationInfo();
+JwtTokenAuthenticationInfo jwtTokenInfo = authInfo.as(JwtTokenAuthenticationInfo.class);
+String jwtToken = jwtTokenInfo.getToken();
+```
+
+
+
+
+
+CAPs generic authentication middlewares for IAS and XSUAA maintain resolved authentication information in the `authInfo` attribute of `cds.context.user`.
+For `@sap/xssec`-based authentication strategies (`ias`, `jwt`, and `xsuaa`), `cds.context.user.authInfo` is an instance of `@sap/xssec`'s [`SecurityContext`](https://www.npmjs.com/package/@sap/xssec#securitycontext).
+You can retrieve available authentication information for use in a non-CAP library from the `SecurityContext`.
+
+```js
+const authInfo = cds.context.user.authInfo // @sap/xssec SecurityContext
+const token = authInfo.token // @sap/xssec Token
+const jwtToken = token.jwt // string
+```
+
+::: warning
+The `cds.User.authInfo` property depends on the authentication library that you use.
+CAP does not guarantee the content of this property. Use it with caution.
+Always pin your dependencies as described in the [best practices](../../node.js/best-practices#deploy).
+:::
+
+
+
+#### Remote Services { #remote-services }
+
+
+
+Remote APIs can be invoked either on behalf of a named user or a technical user, depending on the callee's specification.
+Thus, a client executing a business request within a specific user context might need to explicitly adjust the user propagation strategy.
+CAP's [Remote Services](../using-services) offer an easy and declarative way to define client-side representations of remote service APIs.
+Such services integrate seamlessly with CAP, managing connection setup, including [authentication and user propagation](../../java/cqn-services/remote-services#configuring-the-authentication-strategy):
+
+```yaml
+cds:
+ remote.services:
+ SomeReuseService:
+ binding:
+ name: reuse-service-instance
+ onBehalfOf: systemUserProvider
+```
+
+The parameter `onBehalfOf` in the binding configuration section allows to define the following *user propagation* strategies:
+
+- `currentUser` (default): Propagate the user of the current Request Context.
+- `systemUser`: Propagate the (tenant-specific) technical user, based on the tenant set in the current Request Context.
+- `systemUserProvider`: Propagate the technical user of the provider tenant.
+
+::: tip
+Remote Services configurations with `destination` section support `onBehalfOf` only in case of [IAS App-2-App flows](../../java/cqn-services/remote-services#consuming-apis-from-other-ias-applications).
+:::
+
+[Learn more about Remote Services in CAP Java](../../java/cqn-services/remote-services#remote-services){.learn-more}
+
+
+
+
+
+CAP's [Remote Services](../using-services) offer an easy and declarative way to define client-side representations of remote service APIs.
+Such services integrate seamlessly with CAP, managing connection setup, including [authentication and user propagation](../using-services#authentication-and-authorization-of-remote-services).
+Under the hood CAP utilizes the [BTP Destinations](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/create-destinations-from-scratch) and [`@sap-cloud-sdk/connectivity`](https://www.npmjs.com/package/@sap-cloud-sdk/connectivity) to do most of the heavy lifting.
+
+```json
+{
+ "cds": {
+ "requires": {
+ "SomeReuseService": {
+ "kind": "odata",
+ "model": "srv/external/SomeReuseService",
+ "credentials": {
+ "destination": "some-reuse-service",
+ "path": "/reuse/odata/api",
+ }
+ }
+ }
+ }
+}
+```
+
+
+
+::: tip
+Always prefer using [Remote Services](#remote-services) over natively consuming [Cloud SDK](https://sap.github.io/cloud-sdk/).
+:::
+
+
+
+
+
+#### Cloud SDK { #cloud-sdk }
+
+
+On a programmatic level, the CAP runtime integrates with [Cloud SDK](https://sap.github.io/cloud-sdk/) offering an abstraction for connection setup with remote services, including authentication and user propagation.
+By default,
+- the *tenant* of the current Request Context is propagated under the hood.
+- the *user token* is propagated via Spring's [`SecurityContext`](#user-token).
+- *user propagation strategy* can be specified with parameter values [`OnBehalfOf`](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/service-bindings#multitenancy-and-principal-propagation).
+
+::: tip
+Prefer using [Remote Services](#remote-services) built on Cloud SDK rather than natively consuming the Cloud SDK.
+:::
+
+[Learn more about Cloud SDK integration in CAP Java](../../java/cqn-services/remote-services#cloud-sdk-integration){.learn-more}
+
+
+
+## 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 try to propagate named user context in asynchronous requests**. Do not attempt to propagate the context of a named user 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 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.
+
+- **Don't expose non-cross-sectional entity attributes as AMS Attributes**.
+When defining AMS attributes, ensure that only cross-sectional attributes are exposed.
+These attributes should have a broad, domain-wide relevance and be applicable across multiple entities.
+Typically, only a limited number of attributes (fewer than 5) meet this criterion.
+Exposing entity-specific attributes as AMS attributes can lead to unnecessary complexity and reduced reusability.
+
diff --git a/guides/security/overview.md b/guides/security/overview.md
index 249401071a..34cab58985 100644
--- a/guides/security/overview.md
+++ b/guides/security/overview.md
@@ -1,142 +1,99 @@
---
synopsis: >
- This section provides an overview about the security architecture of CAP applications on different platforms.
+ This section provides an overview about the security concepts and architecture of CAP applications on different platforms.
status: released
uacp: Used as link target from SAP Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/9186ed9ab00842e1a31309ff1be38792.html
---
-# Platform Security
+# Overview
{{ $frontmatter.synopsis }}
[[toc]]
-## Platform Compliance { #platform-compliance }
+## Key Concepts { #key-concepts }
-CAP applications run in a certain environment, that is, in the context of some platform framework that has specific characteristics.
-The underlying framework has a major impact on the security of the application,
-regardless of whether it runs a [cloud](#cloud) environment or [local](#local) environment.
-Moreover, CAP applications are tightly integrated with [platform services](#btp-services), in particular with identity and persistence service.
+CAP's security architecture is built on several fundamental principles that enable flexible, secure, and maintainable applications.
+These concepts work together to provide comprehensive security while maintaining developer productivity and operational efficiency.
-::: warning End-to-end security necessarily requires compliance with all security policies of all involved components.
-CAP application security requires consistent security configuration of the underlying platform and all consumed services. Consult the relevant security documentation accordingly.
-:::
+### Pluggable Building Blocks { #key-concept-pluggable }
-### CAP in Cloud Environment { #cloud }
-
-Currently, CAP supports to run on two cloud runtimes of [SAP Business Technology Platform](https://help.sap.com/docs/btp):
-
-- [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**.
-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.
-Likewise login policies (for example, multifactor authentication or single-sign-on) need to be aligned with company-specific requirements.
-
-Note, that achieving production-ready security requires to meet all relevant aspects of the **development process** as well.
-For instance, source code repositories need to be protected and may not contain any secrets or personal data.
-Likewise, the **deployment process** needs to be secured. That includes not only setting up CI/CD pipelines running on technical platform users, but also defining integration tests to ensure properly secured application endpoints.
-
-As part of **secure operations**, application providers need to establish a patch and vulnerability management, as well as a secure support process. For example, component versions need to be updated and credentials need to be rotated regularly.
-
-::: warning
-The application provider is responsible to **develop, deploy, and operate the application in a secure platform environment**.
-CAP offers seamless integration into platform services and tools to help to meet these requirements.
-:::
-
-Find more about BTP platform security here:
-
-[SAP BTP Security](https://help.sap.com/docs/btp/sap-business-technology-platform/security-e129aa20c78c4a9fb379b9803b02e5f6){.learn-more}
-[SAP BTP Security Recommendations](https://help.sap.com/docs/btp/sap-btp-security-recommendations-c8a9bb59fe624f0981efa0eff2497d7d/sap-btp-security-recommendations){.learn-more}
-[SAP BTP Security (Community)](https://pages.community.sap.com/topics/btp-security){.learn-more}
-
-
-
-
-### CAP in Local Environment { #local }
-
-Security not only plays a crucial role in [cloud](#cloud) environments, but also during local development.
-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:
-
-- 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](../../advanced/hybrid-testing) instead of copying bindings manually to `default-env.json` file.
-`cds bind` avoids materialization of secrets to local disc, which is inherently dangerous.
-- 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.
+CAP divides the different security-related tasks into separate and independent building blocks, each with a standard CAP implementation suitable for most scenarios:
+{width="700px" }
-### SAP BTP Services for Security { #btp-services}
+- [Authentication](./authentication )
+- [CAP Users](./cap-users)
+- [CAP Authorization](./authorization)
+- [Remote Authentication](./remote-authentication)
-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.*
+**By separating these concerns**, CAP ensures that each security function can be configured and customized independently without affecting other parts of the system, providing maximum flexibility.
-::: 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).
-:::
+For example, authentication can be delegated to a [separate ingress component](./authentication#fully-auth), while authorization remains within the application service close to the data.
-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.
+### Customizable { #key-concept-customizable }
-The most important services for security offered by the platform:
+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.
+Moreover, this integration helps to easily incorporate non-CAP and even non-BTP services, thereby providing a flexible and interoperable environment.
-[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}
+{width="600px" }
-#### [SAP Cloud Identity Services - Identity Authentication](https://help.sap.com/docs/IDENTITY_AUTHENTICATION) { #identity-service }
+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.
-The Identity Authentication service defines the user base for (CAP) applications and services, and allows to control access.
-Customers can integrate their 3rd 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.
+### Built on Best of Breed { #key-concept-platform-services }
-[Learn more in the security guide.](https://help.sap.com/docs/IDENTITY_AUTHENTICATION?#discover_task-security){.learn-more}
+CAP does not deal with user login flows, password and credential management, user sessions, or any cryptographic logic - **and applications should definitely not do so!**
+Instead, **CAP seamlessly integrates with battle-tested [platform services](#btp-services)** that handle these critical security topics centrally.
+This approach not only simplifies the implementation but also enhances security by leveraging robust, well-tested mechanisms provided by the platform.
+Built on platform services, CAP allows developers to focus on core application functionality without worrying about the intricacies of security implementation.
-#### [SAP Authorization and Trust Management Service](https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG)
+Most notably, authentication is covered by CAP-integration of [platform's identity services](./authentication#ias-auth).
+Likewise, TLS termination is offered by the [platform infrastructure](#platform-environment).
-The service lets customers manage user authorizations in technical roles at application level, which can be aggregated into business-level role collections for large-scale cloud scenarios.
-Obviously, developers must define application roles carefully as they form basic access rules to business data.
+{width="600px" }
-#### [SAP Malware Scanning Service](https://help.sap.com/docs/MALWARE_SCANNING)
+### Decoupled from Business Logic { #key-concept-decoupled-coding }
-This service can be used to scan transferred business documents for malware and viruses.
-Currently, there is no CAP integration. A scan needs to be triggered by the business application explicitly.
+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 adaptions.
+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**.
-[Learn more in the security guide.](https://help.sap.com/docs/btp?#operate_task-security){.learn-more}
+For instance, CAP allows performing outbound service calls via [Remote Services while handling authentication completely under the hood](./remote-authentication#remote-services).
+This abstraction layer ensures that developers do not need to worry about the details of authentication.
-#### [SAP Credential Store](https://help.sap.com/docs/CREDENTIAL_STORE)
-Credentials managed by applications need to be stored in a secure way.
-This service provides a REST API for (CAP) applications to store and retrieve credentials at runtime.
+### Secure by Default { #key-concept-secure-by-default }
-[Learn more in the security guide.](https://help.sap.com/docs/CREDENTIAL_STORE?#discover_task-security){.learn-more}
+CAP security features are activated by default. If different behaviour is required, you must explicitly reconfigure or add custom code accordingly.
+CAP's security autoconfiguration approach significantly reduces the risk of misconfiguration - **override only when absolutely necessary and when all effects are safely controlled**.
-#### [SAP BTP Connectivity](https://help.sap.com/docs/CP_CONNECTIVITY)
+For instance, endpoints of deployed CAP applications are [automatically authenticated](./authentication#model-auth), providing a secure baseline.
+Making endpoints public requires manual configuration in either the CAP model or the middleware.
-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}
-## Architecture and Platform Requirements
+## Security Architecture
-As [pointed out](#platform-compliance), CAP cloud applications run in a specific context that has a major impact on the security [architecture](#architecture-overview).
+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.
### Architecture Overview { #architecture-overview }
-The following diagram provides a high-level overview about the security-relevant aspects of a deployed CAP application in a cloud environment:
+The following diagram provides a high-level overview about the security-relevant components and interfaces of a deployed CAP application in a cloud environment:
-
{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. The CAP application might make use of 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. 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)).
#### Public Zone { #public-zone }
From CAP's point of view, all components without specific security requirements belong to the public zone.
Therefore, you shouldn't rely on the behavior or structure of consumer components like browsers or technical clients for the security of server components.
The platform's gateway provides a single point of entry for any incoming call and defines the API visible to the public zone.
-As malicious users have free access to the public zone, these endpoints need to be protected carefully.
+Since malicious users have free access to the public zone, you must protect these endpoints carefully.
Ideally, you should limit the number of exposed endpoints to a minimum, perhaps through proper network configuration.
#### Platform Zone { #platform-zone }
@@ -149,30 +106,26 @@ The platform zone also includes the gateway, which is the main entry point for e
#### 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 to *develop, deploy and operate* these services:
-- The [Application Router](https://help.sap.com/docs/btp/sap-business-technology-platform/application-router) acts as as an optional reverse proxy wrapping the application service and providing business-independent functionality required for UIs.
+- 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 application (reusable module) or alternatively consumed as a [service](https://help.sap.com/docs/btp/sap-business-technology-platform/managed-application-router).
+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).
- 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.
- The optional CAP sidecar (reusable module) is used to outsource application-independent tasks such as providing multitenancy and extension support.
-Application providers, that is platform users, have privileged access to the application zone.
-In contrast, application subscribers, that is business users, are restricted to a minimal interface.
+Application providers (platform users) have privileged access to the application zone.
+In contrast, application subscribers (business users) are restricted to a minimal interface.
::: warning
-❗ Application providers **may not share any secrets from the application zone** such as binding information with other components or persons.
-In a productive environment, it is recommended to deploy and operate the application on behalf of a technical user.
-:::
-
-::: tip
-Without limitation of generality, there may be multiple CAP services or sidecars according to common [microservice architecture pattern](https://microservices.io/patterns/microservices.html).
+❗ Application providers **must not share any secrets from the application zone** such as binding information with other components or persons.
+In a production environment, we recommend deploying and operating the application on behalf of a technical user.
:::
-### Required Platform Environment { #platform-environment }
+### Platform Requirements { #platform-environment }
There are several assumptions that a CAP application needs to make about the platform environment it is deployed to:
@@ -180,18 +133,126 @@ There are several assumptions that a CAP application needs to make about the pla
Hence, the **CAP application can offer a pure HTTP endpoint** without having to enforce TLS and to deal with certificates.
2. The server certificates presented by the external endpoints are signed by a trusted certificate authority.
-This **frees CAP applications from the need to manage trust certificates**. The underlying runtimes (Java or Node) can validate the server certificates by default.
+This **frees CAP applications from the need to manage trust certificates**. The underlying runtimes (Java or Node.js VMs) can validate the server certificates by default.
-3. **Secrets** that are required to protect the application or to consume other platform services **are injected by the platform** into the application in a secure way.
+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](overview#cloud) fulfill the given requirements. Additional requirements could be added in future.
::: tip
-Custom domain certificates need to be signed by trusted certificate authority.
+Custom domain certificates must be signed by a trusted certificate authority.
+:::
+
+::: warning
+❗ **In general, application endpoints are visible to public zone**. Hence, CAP applications need to protect all exposed endpoints.
:::
+
+## Platform Compliance { #platform-compliance }
+
+CAP applications run in a certain environment, that is, in the context of some platform framework that has specific characteristics as explained [before](#platform-environment).
+The underlying framework has a major impact on the security of the application,
+regardless of whether it runs a [cloud environment](#cloud) or [local environment](#local).
+Moreover, CAP applications are tightly integrated with [platform services](#btp-services), in particular with identity and persistence service.
+
+::: warning ❗ End-to-end security necessarily requires compliance with all security policies of all involved components
+CAP application security requires consistent security configuration of the underlying platform and all consumed services. Consult the relevant security documentation accordingly.
+:::
+
+### CAP in Local Environment { #local }
+
+Security not only plays a crucial role in [cloud environments](#cloud), but also during local development.
+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:
+
+- 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](../../advanced/hybrid-testing) instead of copying bindings manually to `default-env.json` file.
+`cds bind` avoids materialization of secrets to local disc, which is inherently dangerous.
+- 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.
+
+
+### CAP in Cloud Environment { #cloud }
+
+Currently, CAP supports to run on two cloud runtimes of [SAP Business Technology Platform](https://help.sap.com/docs/btp):
+
+- [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**.
+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.
+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.
+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.
+
+As part of **secure operations**, application providers must establish patch and vulnerability management, as well as a secure support process. For example, component versions must be updated and credentials must be rotated regularly.
+
::: warning
-❗ **In general, application endpoints are visible to public zone**. Hence, CAP can't rely on private endpoints.
-In particular, an application router does not prevent external access to the CAP application service.
-As a consequence, **all CAP endpoints must be protected in an appropriate manner**.
+The application provider is responsible to **develop, deploy, and operate the application in a secure platform environment**.
+CAP offers seamless integration into platform services and tools to help to meet these requirements.
+:::
+
+Find more about BTP platform security here:
+
+[SAP BTP Security](https://help.sap.com/docs/btp/sap-business-technology-platform/security-e129aa20c78c4a9fb379b9803b02e5f6){.learn-more}
+[SAP BTP Security Recommendations](https://help.sap.com/docs/btp/sap-btp-security-recommendations-c8a9bb59fe624f0981efa0eff2497d7d/sap-btp-security-recommendations){.learn-more}
+[SAP BTP Security (Community)](https://pages.community.sap.com/topics/btp-security){.learn-more}
+
+
+
+
+
+
+### 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.*
+
+::: 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).
:::
+[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 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 3rd 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}
+
+#### [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}
+
+#### [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}
+
+#### [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}
+
+#### [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}
diff --git a/guides/security/remote-authentication.md b/guides/security/remote-authentication.md
new file mode 100644
index 0000000000..496a23eea4
--- /dev/null
+++ b/guides/security/remote-authentication.md
@@ -0,0 +1,448 @@
+---
+# layout: cookbook
+label: Remote Authentication
+synopsis: >
+ This guide explains how to authenticate remote services.
+status: released
+---
+
+
+
+
+
+# Remote Authentication { #remote-authentication }
+
+
+
+This guide explains how to authenticate remote services.
+
+[[toc]]
+
+## 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](../using-services#consuming-services) decouples protocol level (i.e., exchanged content) from connection level (i.e., 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.
+
+{width="400px" }
+
+At the connectivity layer, the following basic tasks can be addressed generically:
+- Authentication (_how to set up a trusted channel_)
+- Destination (_how to find the target service_)
+- User propagation (_how to transport user information_)
+
+CAP's connectivity component handles authentication (IAS, XSUAA, X.509, ZTID, ...), destination (local destination, BTP Destination, BTP Service Binding), and user propagation (technical provider, technical subscriber, named user) transparently through configuration.
+All three service scenarios can be addressed through configuration variants of the same remote service concept, as shown in the following sections.
+
+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.
+* [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](../providing-services#late-cut-microservices).
+
+Technically, **they share the same identity instance, which allows direct token forwarding**:
+
+{width="450px" }
+
+[Learn more about how to configure co-located services in CAP Java](/java/cqn-services/remote-services#binding-to-a-service-with-shared-identity) {.learn-more}
+
+You can test CAP's built-in support for co-located services in practice by modifying the [`xflights-java`](https://github.com/capire/xflights-java/tree/main) and [`xtravels-java`](https://github.com/capire/xtravels-java/tree/main) sample applications.
+`xflights-java` acts as a master data provider exposing basic flight data in service [`sap.capire.flights.data`](https://github.com/capire/xflights-java/blob/6fc7c665c63bb6d73e28c11b391b1ba965b8772c/srv/data-service.cds#L24) via different protocols.
+On the client side, `xtravels-java` imports this service as a CAP remote service and fetches data in a [custom handler for data federation](https://github.com/capire/xtravels-java/blob/53a5fa33caf4c9068f2e66fab25bda26f3f450ca/srv/src/main/java/sap/capire/xtravels/handler/FederationHandler.java#L63).
+
+::: tip
+CAP offers a simplified co-located service setup by leveraging remote services that require:
+- Shared identity instance
+- URL for the destination
+- Principal propagation mode (optional)
+:::
+
+
+To combine both applications in a co-located setup, follow these steps:
+
+#### 1. Prepare the CF environment { #prepare }
+
+Make sure that you've prepared a [local environment for CF deployments](../deployment/to-cf#prerequisites) and in addition:
+- A Cloud Foundry (CF) space in a subaccount.
+- [HANA Cloud instance](https://help.sap.com/docs/hana-cloud/sap-hana-cloud-administration-guide/create-sap-hana-database-instance-using-sap-hana-cloud-central) mapped to the CF space.
+- [IAS tenant](./authentication#ias-ready) mapped to the subaccount.
+
+
+#### 2. Prepare and deploy the consumer application { #co-located-consumer }
+
+As client, `xtravels-srv` first needs a valid configuration for the remote service `sap.capire.flights.data`:
+
+::: code-group
+
+```yaml [/srv/src/main/resources/application.yaml]
+---
+spring:
+ config.activate.on-profile: cloud
+cds:
+ remote.services:
+ xflights:
+ type: hcql
+ model: sap.capire.flights.data
+ binding:
+ name: xtravels-ias
+ options:
+ url: https:///hcql
+ onBehalfOf: systemUserProvider
+```
+:::
+
+The `type` property activates the protocol for exchanging business data and must be offered by the provider [CDS service](https://github.com/capire/xflights-java/blob/6fc7c665c63bb6d73e28c11b391b1ba965b8772c/srv/data-service.cds#L24).
+The `model` property needs to match the fully qualified name of the CDS service from the imported model.
+You can find CDS service definition of `sap.capire.flights.data` in file `target/cds/capire/xflight-data/service.cds` resolved during CDS build step.
+The `binding.name` needs to point to the shared identity instance and `option.url` provides the required location of the remote service endpoint.
+Finally, `onBehalfOf: systemUserProvider` specifies that the remote call is invoked on behalf of the technical provider tenant.
+
+
+Now you are ready to deploy the application with
+
+```sh
+cd ./xtravels_java
+cds up
+```
+
+❗Note that CF application `xtravels-srv` will not start successfully as long as `xflights` is not deployed yet (step 3).
+
+::: tip
+For production deployment, it is recommended to combine both services with the shared identity instance in a [single MTA descriptor](../deployment/microservices#all-in-one-deployment).
+:::
+
+
+#### 3. Prepare and deploy the provider application { #co-located-provider }
+
+As server, `xflights-srv` needs to restrict service `sap.capire.flights.data` to the technical client calling from of the same application.
+This can be done by adding pseudo-role [`internal-user`](./cap-users#pseudo-roles) to the service:
+
+::: code-group
+```cds [/srv/authorization.cds]
+using { sap.capire.flights.data as data } from './data-service';
+
+annotate data with @(requires: 'internal-user');
+```
+:::
+
+::: tip
+For different [user propagation](./cap-users#remote-services) modes the remote service can be configured appropriately.
+The provider service authorization needs to align with the configured user propagation.
+:::
+
+Additionally, to establish the co-located setup, the microservice needs to share the same identity instance:
+
+::: code-group
+
+```yaml [/srv/srv/main/resources/application.yaml]
+resources:
+ - name: xflights-ias
+ type: org.cloudfoundry.managed-service // [!code --]
+ type: org.cloudfoundry.existing-service // [!code ++]
+ parameters:
+ service: identity // [!code --]
+ service-name: xflights-ias // [!code --]
+ service-name: xtravels-ias // [!code ++]
+ service-plan: application // [!code --]
+ config: // [!code --]
+ display-name: xflights // [!code --]
+```
+
+:::
+
+Finally, deploy and start the application with
+
+```sh
+cd ./xflights_java
+cds up
+```
+
+#### 4. Verify the deployment { #verify }
+
+First, you can check the overall deployment status at the CF CLI level. Specifically, the application services must be started successfully and the shared identity instance must be verified.
+
+::: details Verify: `cf apps` should show the following lines:
+
+::: code-group
+```sh
+name requested state processes routes
+xflights-db-deployer stopped web:0/1
+xflights-srv started web:1/1 ...
+xtravels started web:1/1 ...
+xtravels-ams-policies-deployer stopped web:0/1
+xtravels-db-deployer stopped web:0/1
+xtravels-srv started web:1/1 ...
+```
+:::
+
+::: details Verify: `cf services` should show the following lines:
+
+::: code-group
+```sh
+xflights-ias identity application
+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).
+
+
+::: tip
+The very same setup could be deployed for XSUAA-based services.
+:::
+
+
+## External Services
+
+In contrast to [co-located services](#co-located-services), external services do not have strong dependencies as they have a fully decoupled lifecycle and are provided by different owners.
+As a consequence, external services can run cross-regionally; even non-BTP systems might be involved.
+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](../using-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.
+
+
+### IAS App-2-App { #app-to-app }
+
+As a first-class citizen, [IAS](./authentication#ias-auth) is positioned to simplify cross-regional requests with user propagation.
+Prerequisites are identity instances on both consumer and provider sides, plus a registered IAS dependency in the consumer instance.
+
+{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.
+The latter is issued by IAS only if the consumer is configured with a valid IAS dependency pointing to the provider accordingly.
+
+:::tip
+CAP offers a simplified App-2-App setup by leveraging remote services that require:
+- Identity instances for provider and consumer
+- Configured IAS dependency from consumer to provider
+- Destination with URL pointing to the provider
+- Principal propagation mode (optional)
+:::
+
+[Learn more about how to consume external application APIs with IAS](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications) {.learn-more}
+
+
+
+#### 1. Prepare and deploy the provider application
+
+Assuming the same local CF environment setup as [here](#prepare), clone [`xflights-java`](https://github.com/capire/xflights-java/tree/main) or, if already cloned and modified locally, reset to the remote branch.
+
+Similar to the [co-located](#co-located-provider) variant, `xflights` needs to expose service `sap.capire.flights.data` to technical clients.
+The difference is that the consumers are not known a priori and are not part of the same application deployment.
+
+To expose service APIs for consumption, you can enhance the identity instance of the provider by defining API identifiers that are listed in property `provided-apis`:
+
+::: code-group
+```yaml [mta.yaml]
+resources:
+ - name: xflights-ias
+ type: org.cloudfoundry.managed-service
+ parameters:
+ [...]
+ config:
+ display-name: xflights
+ provided-apis: [{ # [!code ++:5]
+ name: DataConsumer,
+ description: Grants technical access to data service API
+ }]
+```
+:::
+
+The entry with name `DataConsumer` represents the consumption of service `sap.capire.flights.data` and is exposed as IAS API.
+The description helps administrators to configure the consumer application with the proper provider API if done on UI level.
+
+[Detailed description about identity instance parameters for `provided-apis`](https://github.wdf.sap.corp/pages/CPSecurity/sci-dev-guide/docs/BTP/identity-broker#service-instance-parameters){.learn-more}
+
+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:
+
+::: code-group
+```cds [/srv/authorization.cds]
+using { sap.capire.flights.data as data } from './data-service';
+
+annotate data with @(requires: 'DataConsumer');
+```
+:::
+
+Finally, deploy and start the application with
+
+```sh
+cd ./xflights_java
+cds up
+```
+
+
+::: tip API as CAP role
+The API identifiers exposed by the IAS instance in list `provided-apis` are granted as CAP roles after successful authentication and can be used in @requires annotations.
+:::
+
+::: 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.
+:::
+
+#### 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`).
+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.
+
+
+::: code-group
+
+```yaml [mta.yaml (destination instance)]
+ - name: xtravels-destination
+ type: org.cloudfoundry.managed-service
+ parameters:
+ service: destination
+ service-plan: lite
+ config:
+ init_data:
+ instance:
+ existing_destinations_policy: update
+ destinations:
+ - Name: xtravels-data-consumer
+ Type: HTTP
+ URL: https:///hcql
+ cloudsdk.ias-dependency-name: "DataConsumer"
+ Authentication: NoAuthentication
+ ProxyType: Internet
+ Description: "Data consumer destination for xtravels"
+```
+
+```yaml [mta.yaml (destination binding)]
+modules:
+ - name: xtravels-srv
+ type: java
+ [...]
+ requires:
+ - name: xtravels-destination # [!code ++]
+```
+
+:::
+
+:::tip
+Alternatively, the destination can also be created manually in the [BTP destination editor](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/access-destinations-editor).
+:::
+
+
+Given the destination, the remote service can be configured in a very similar way as with [co-located services](#co-located-consumer).
+Currently, an additional Cloud SDK dependency `scp-cf` is required to support communication with the BTP destination service:
+
+::: code-group
+
+```yaml [/srv/srv/main/resources/application.yaml]
+spring:
+ config.activate.on-profile: cloud
+cds:
+ remote.services:
+ xflights:
+ type: hcql
+ model: sap.capire.flights.data
+ destination:
+ name: xtravels-data-consumer
+ onBehalfOf: systemUserProvider
+```
+
+```xml [/srv/pom.xml]
+
+ com.sap.cloud.sdk.cloudplatform
+ scp-cf
+ runtime
+
+```
+
+:::
+
+[Learn more about simplified Remote Service configuration with destinations](/java/cqn-services/remote-services#destination-based-scenarios) {.learn-more}
+
+Finally, deploy and start the application with
+
+```sh
+cd ./xtravels_java
+cds up
+```
+
+`xtravels-srv` is not expected to start successfully; instead, you should see error log messages like this:
+```yaml
+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.
+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).
+
+Note that property `oauth2-configuration.token-policy.access-token-format: jwt` is set in the identity instance to ensure the exchanged token has JWT format.
+
+#### 3. Connect consumer with provider { #connect }
+
+Now let's create the missing IAS dependency to establish trust for the API service call targeting provided API with id `DataConsumer`.
+
+Open the Administrative Console for the IAS tenant (see prerequisites [here](./authentication#ias-admin)):
+
+1. Select **Applications & Resources** > **Applications**. Choose the IAS application of the `xtravels` consumer from the list.
+2. In **Application APIs** select **Dependencies** and click on **Add**.
+3. Type a dependency name (needs to match property value `cloudsdk.ias-dependency-name`) and pick provided API `DataConsumer` from the provider IAS application `xflights`.
+4. Confirm with **Save**
+
+::: details Create IAS dependency in Administrative Console
+
+ {width="500px" }
+
+ {width="500px" }
+
+:::
+
+:::tip
+Both the BTP destination and the IAS dependency can be automatically created at runtime using [UCL integration](../../java/integrating-applications/ucl#unified-customer-landscape-ucl).
+:::
+
+Now restart the consumer application with
+
+```sh
+cf restart xtravels-srv
+```
+
+to trigger a successful startup with valid flight data retrieved from the provider.
+
+You can now 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).
+
+
+
+
+
+## Pitfalls
+
+- **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).
+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).
+
+
diff --git a/java/_menu.md b/java/_menu.md
index 3baf3672bb..bcd07a0355 100644
--- a/java/_menu.md
+++ b/java/_menu.md
@@ -24,7 +24,6 @@
# [Multitenancy](multitenancy)
## [Multitenancy (Classic)](multitenancy-classic)
# [Security](security)
- ## [IAS and AMS](../../java/ams)
# [Spring Boot Integration](spring-boot-integration)
# [Developing Applications](developing-applications/)
## [Building](developing-applications/building)
diff --git a/java/event-handlers/request-contexts.md b/java/event-handlers/request-contexts.md
index f3d89ed70c..9e234f3b27 100644
--- a/java/event-handlers/request-contexts.md
+++ b/java/event-handlers/request-contexts.md
@@ -116,74 +116,20 @@ For example, if the request is processed by an HTTP-based protocol adapter, `Par
The CAP Java SDK allows you to create new Request Contexts and define their scope. This helps you to control, which set of parameters is used when events are processed by services.
-There are a few typical use cases in a CAP-based, multitenant application on SAP BTP in which creation of new Request Contexts is necessary. These scenarios are identified by a combination of the user (technical or named) and the tenant (provider or subscribed).
-
-
-
-When calling CAP Services, it's important to call them in an appropriate Request Context. Services might, for example, trigger HTTP requests to external services by deriving the target tenant from the current Request Context.
-
-The `RequestContextRunner` API offers convenience methods that allow an easy transition from one scenario to the other.
-
-| Method | Description |
-|----------------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| systemUserProvider() | Switches to a technical user targeting the provider account. |
-| systemUser() | Switches to a technical user and preserves the tenant from the current `UserInfo` (for example downgrade of a named user Request Context). |
-| systemUser(tenant) | Switches to a technical user targeting a given subscriber account. |
-| anonymousUser() | Switches to an anonymous user. |
-| privilegedUser() | Elevates the current `UserInfo` to by-pass all authorization checks. |
-
-::: info Note
-The [RequestContextRunner](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/runtime/RequestContextRunner.html) API does not allow you to create a Request Context based on a named user. Named user contexts are only created by the CAP Java framework as initial Request Context is based on appropriate authentication information (for example, JWT token) attached to the incoming HTTP request.
-:::
-
-In the following a few concrete examples are given:
-- [Switching to Technical User](#switching-to-technical-user)
-- [Switching to Provider Tenant](#switching-to-provider-tenant)
-- [Switching to a Specific Technical Tenant](#switching-to-a-specific-technical-tenant)
-
-### Switching to Technical User
-
-
-
-The incoming JWT token triggers the creation of an initial RequestContext with a named user. Accesses to the database in the OData Adapter as well as the custom `On` handler are executed within tenant1 and authorization checks are performed for user JohnDoe. An additionally defined `After` handler wants to call out to an external service using a technical user without propagating the named user JohnDoe.
-Therefore, the `After` handler needs to create a new Request Context. To achieve this, it's required to call `requestContext()` on the current `CdsRuntime` and use the `systemUser()` method to remove the named user from the new Request Context:
```java
@After(entity = Books_.CDS_NAME)
public void afterHandler(EventContext context){
- runtime.requestContext().systemUser().run(reqContext -> {
- // call technical service
- ...
- });
-}
-```
-### Switching to Technical Provider Tenant {#switching-to-provider-tenant}
-
-
-
-The application offers an action for one of its CDS entities. Within the action, the application communicates with a remote CAP service using an internal technical user from the provider account. The corresponding `on` handler of the action needs to create a new Request Context by calling `requestContext()`. Using the `systemUserProvider()` method, the existing user information is removed and the tenant is automatically set to the provider tenant. This allows the application to perform an HTTP call to the remote CAP service, which is secured using the pseudo-role `internal-user`.
-
-```java
-@On(entity = Books_.CDS_NAME)
-public void onAction(AddToOrderContext context){
- runtime.requestContext().systemUserProvider().run(reqContext -> {
- // call remote CAP service
- ...
+ runtime.requestContext()
+ // [...] prepare the fully context
+ .run(reqContext -> {
+ // do service calls
});
}
```
-### Switching to a Specific Technical Tenant
-
+Most important use case is to switch users, for which CAP Java provides [convenience APIs](../../guides/security/cap-users#switching-users).
-The application is using a job scheduler that needs to regularly perform tasks on behalf of a certain tenant. By default, background executions (for example in a dedicated thread pool) aren't associated to any subscriber tenant and user. In this case, it's necessary to explicitly define a new Request Context based on the subscribed tenant by calling `systemUser(tenantId)`. This ensures that the Persistence Service performs the query for the specified tenant.
-
-```java
-runtime.requestContext().systemUser(tenant).run(reqContext -> {
- return persistenceService.run(Select.from(Books_.class))
- .listOf(Books.class);
-});
-```
## Modifying Request Contexts { #modifying-requestcontext}
Besides the described common use cases, it's possible to modify parts of an existing Request Context. To manually add, modify or reset specific attributes within the scope of a new Request Context, you can use the [RequestContextRunner](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/runtime/RequestContextRunner.html) API.
diff --git a/java/migration.md b/java/migration.md
index 1697c152b1..47650c0484 100644
--- a/java/migration.md
+++ b/java/migration.md
@@ -94,9 +94,9 @@ Some property defaults have been adjusted:
| Property | Old Value | New Value | Explanation |
| --- | --- | --- | --- |
-| `cds.security.authorization.deep.enabled` | false | true | [Deep Authorization](./security#deep-auth) is now enabled by default. |
+| `cds.security.authorization.deep.enabled` | false | true | [Deep Authorization](../guides/security/authorization#deep-auth) is now enabled by default. |
| `cds.security.authorization.instanceBased.rejectSelectedUnauthorizedEntity.enabled` | false | true | Requests that violate instance-based authorization conditions now fail with 403, instead of 404. |
-| `cds.security.authorization.instanceBased.checkInputData.enabled` | false | true | [Authorization Checks On Input Data](./security#input-data-auth) are now enabled by default. |
+| `cds.security.authorization.instanceBased.checkInputData.enabled` | false | true | [Authorization Checks On Input Data](../guides/security/authorization#input-data-auth) are now enabled by default. |
| `cds.errors.defaultTranslations.enabled` | false | true | [Translations for Validation Error Messages](./event-handlers/indicating-errors#ootb-translated-messages) are now enabled by default. |
| `cds.sql.runtimeView.mode` | resolve | cte | [Runtime views](./working-with-cql/query-execution#runtimeviews) are now by default translated into Common Table Expressions |
@@ -190,8 +190,6 @@ In IAS scenarios, the [Proof-Of-Possession](https://github.com/SAP/cloud-securit
Because of this, applications calling a CAP Java application will need to send a valid client certificate in addition to the JWT token. In particular, applications using an Approuter have to set `forwardAuthCertificates: true` on the Approuter destination pointing to your CAP backend.
-[Learn more about Proof-Of-Possession.](./security.md#proof-of-possession){.learn-more}
-
### Lazy Localization by default
EDMX resources served by the OData V4 `/$metadata` endpoints are now localized lazily by default.
@@ -1179,7 +1177,7 @@ With the help of these interfaces, the classic enforcement API can be mapped to
| `getUserAttribute(String attributeName)` | `user.getAttribute(attributeName)` |
| `isContainerSecurityEnabled()` | no substitution required |
-[See section **Enforcement API & Custom Handlers in Java** for more details.](./security#enforcement-api){.learn-more}
+[See section **Developing with CAP Users** for more details.](../guides/security/cap-users#developing-with-users){.learn-more}
diff --git a/java/outbox.md b/java/outbox.md
index 0bd0d0c2a8..1804f1df9a 100644
--- a/java/outbox.md
+++ b/java/outbox.md
@@ -420,7 +420,7 @@ Filters can be applied as for any other CDS defined entity, for example, to filt
It is crucial to make the service `OutboxDeadLetterQueueService` accessible for internal users only as it contains sensitive data that could be exploited for malicious purposes if unauthorized changes are performed.
-[Learn more about pseudo roles](../guides/security/authorization#pseudo-roles){.learn-more}
+[Learn more about pseudo roles](../guides/security/cap-users#pseudo-roles){.learn-more}
:::
diff --git a/java/security.md b/java/security.md
index 0eba8a281f..5d2e5450eb 100644
--- a/java/security.md
+++ b/java/security.md
@@ -1,6 +1,6 @@
---
synopsis: >
- Describes authentication and authorization in CAP Java.
+ Describes authentication and authorization specific for CAP Java.
status: released
uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/9186ed9ab00842e1a31309ff1be38792.html
---
@@ -26,146 +26,87 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/
{ #security}
-## Overview
-
-For Web services, authentication is about controlling _who_ is using the service. It typically involves verifying the user's identity, tenant, and validating claims like granted roles. In contrast, authorization makes sure that the user has the required privileges to access the requested resources. Hence, authorization is about controlling _what_ the user is allowed to handle.
-
-Hence both, authentication and authorization, are essential for application security:
-* [Authentication](#authentication) describes how to configure authentication.
-* [Authorization](#auth) is about resource access control.
-
-[Connecting to IAS Services](#outbound-auth) describes how to authenticate outbound calls.
-
-::: warning
-Without security configured, CDS services are exposed to public. Proper configuration of authentication __and__ authorization is required to secure your CAP application.
+::: info
+This chapter appends CAP Java sepcifc information only.
+Consult the comprehensive [Security Guide](../guides/security/#cap-security-guide) first to learn about CAP Security features in general.
:::
## Authentication { #authentication}
-Authentication rejects user requests with invalid authentication and limits the possible resource impact.
+### Auto Configuration { #xsuaa-ias }
-Rejecting them as soon as possible is one of the reasons why it's not an integral part of the CAP runtime and needs to be configured on the application framework level. In addition, CAP Java is based on a [modular architecture](./developing-applications/building#modular_architecture) and allows flexible configuration of any authentication method.
-By default, it supports the standard BTP platform identity services [out of the box](#xsuaa-ias):
+To enable auto-configuration for authentication based on platform services, following two conditions need to be met:
+1. Required Maven [dependencies](#maven-dependencies) available.
+2. [Binding](#bindings) to a corresponding service instance (XSUAA and/or IAS) is available at runtime.
-- [SAP Cloud Identity Services Identity Authentication (IAS)](https://help.sap.com/docs/cloud-identity-services) - preferred solution integrating endpoints cross SAP-systems
-- [SAP Authorization and Trust Management Service (XSUAA)](https://help.sap.com/docs/authorization-and-trust-management-service) - previous offering scoped to a BTP landscape
+::: warning
+Only **if both, the library dependencies and an XSUAA or IAS service binding are in place**, the CAP Java SDK activates a Spring security configuration, which enforces authentication for all endpoints **automatically**.
+:::
-Which are highly recommended for production usage. For specific use cases, [custom authentication](#custom-authentication) can be configured as well.
-Local development and testing can be done easily with built-in [mock user](#mock-users) support.
+#### Maven Dependencies { #maven-dependencies }
+To ensure the proper maven dependencies, we recommend using the `cds-starter-cloudfoundry` or the `cds-starter-k8s` starter bundle.
+Both can be active for the local scenario.
-### Configure XSUAA and IAS Authentication { #xsuaa-ias}
-To enable your application for XSUAA or IAS-authentication, we recommend using the `cds-starter-cloudfoundry` or the `cds-starter-k8s` starter bundle, which covers all required dependencies.
+:::details Runtime Maven dependencies required for authentication
-:::details Individual Dependencies
-These are the individual dependencies that can be explicitly added in the `pom.xml` file of your service:
- * `com.sap.cloud.security:resourceserver-security-spring-boot-starter` that brings [spring-security library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security)
- * `org.springframework.boot:spring-boot-starter-security`
- * `cds-feature-identity`
+- `cds-feature-identity`
+- `org.springframework.boot:spring-boot-starter-security`
+- `com.sap.cloud.security:resourceserver-security-spring-boot-starter` that brings [spring-security library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security)
:::
-In addition, your application needs to be bound to corresponding service instances depending on your scenario. The following list describes which service needs to be bound depending on the tokens your applications should accept:
- * only accept tokens issued by XSUAA --> bind your application to an [XSUAA service instance](../guides/security/authorization#xsuaa-configuration)
- * only accept tokens issued by IAS --> bind your application to an [IAS service instance](https://help.sap.com/docs/IDENTITY_AUTHENTICATION)
- * accept tokens issued by XSUAA and IAS --> bind your application to service instances of both types.
+#### Service Bindings { #bindings }
+
+Additionally, your application must be bound to corresponding service instances depending on your scenario.
+The following list describes which service must be bound depending on the tokens your application should accept:
+ * only accept tokens issued by XSUAA --> bind your application to an [XSUAA service instance](../guides/security/authentication#xsuaa-auth)
+ * only accept tokens issued by IAS --> bind your application to an [IAS service instance](../guides/security/authentication#ias-auth)
+ * accept tokens issued by XSUAA and IAS --> bind your application to service instances of [both types](../guides/security/authentication#hybrid-auth).
-::: tip Specify Binding
+::: tip Unique Binding
CAP Java picks only a single binding of each type. If you have multiple XSUAA or IAS bindings, choose a specific binding with property `cds.security.xsuaa.binding` respectively `cds.security.identity.binding`.
Choose an appropriate XSUAA service plan to fit the requirements. For instance, if your service should be exposed as technical reuse service, make use of plan `broker`.
:::
-#### Proof-Of-Possession for IAS { #proof-of-possession}
-
-Proof-Of-Possession is a technique for additional security where a JWT token is **bound** to a particular OAuth client for which the token was issued. On BTP, Proof-Of-Possession is supported by IAS and can be used by a CAP Java application.
-
-Typically, a caller of a CAP application provides a JWT token issued by IAS to authenticate a request. With Proof-Of-Possession in place, a mutual TLS (mTLS) tunnel is established between the caller and your CAP application in addition to the JWT token. Clients calling your CAP application need to send the certificate provided by their `identity` service instance in addition to the IAS token.
-
-On Cloud Foundry, the CAP application needs to be exposed under an additional route which accepts client certificates and forwards them to the application as `X-Forwarded-Client-Cert` header (for example, the `.cert.cfapps.` domain).
-
-
-
-On Kyma, it is required to configure an additional component (i.e. a gateway in Istio) which accepts client certificates and forwards them to the application as `X-Forwarded-Client-Cert` header. An example can be found in the Bookshop sample application [here](https://github.com/SAP-samples/cloud-cap-samples-java/tree/ias-ams-kyma/k8s). Besides defining the actual `Gateway` resource, it is required to expose the application under the new domain (see the `values.yaml` [here](https://github.com/SAP-samples/cloud-cap-samples-java/blob/e9c779cb64c0937815910988387b0775d8842765/helm/values.yaml#L47).
-
-The Proof-Of-Possession also affects approuter calls to a CAP Java application. The approuter needs to be configured to forward the certificate to the CAP application. First, set `forwardAuthCertificates: true` on the destination pointing to your CAP backend (for more details see [the `environment destinations` section on npmjs.org](https://www.npmjs.com/package/@sap/approuter#environment-destinations)). Second, configure the destination to use the route of the CAP backend that has been configured to accept client certificates as described previously.
-
-When authenticating incoming requests with IAS, the Proof-Of-Possession is activated by default. This requires using at least version `3.5.1` of the [SAP BTP Spring Security Client](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security) library.
-
-You can disable the Proof-Of-Possession enforcement in your CAP Java application by setting the property `sap.spring.security.identity.prooftoken` to `false` in the `application.yaml` file.
-
-:::tip
-CAP Java requires an AppRouter to be configured with mTLS in case of IAS authentication (`forwardAuthCertificates: true`).
-:::
-
+### Custom Authentication { #spring-boot }
-### Automatic Spring Boot Security Configuration { #spring-boot}
+#### Authenticated Endpoints { #auth-endpoints }
-Only if **both, the library dependencies and an XSUAA/IAS service binding are in place**, the CAP Java SDK activates a Spring security configuration, which enforces authentication for all endpoints **automatically**:
+By default, the [auto-configuration](#xsuaa-ias) covers
* Protocol adapter endpoints (managed by CAP such as OData V4/V2 or custom protocol adapters)
* Remaining custom endpoints (not managed by CAP such as custom REST controllers or Spring Actuators)
-The security auto configuration authenticates all endpoints by default, unless corresponding CDS model is not explicitly opened to public with [pseudo-role](../guides/security/authorization#pseudo-roles) `any` (configurable behaviour).
-Here's an example of a CDS model and the corresponding authentication configuration:
-
-```cds
-service BooksService @(requires: 'any') {
- @readonly
- entity Books @(requires: 'any') {...}
-
- entity Reviews {...}
-
- entity Orders @(requires: 'Customer') {...}
-}
-```
-
-| Path | Authenticated ? |
-|:--------------------------|:----------------:|
-| `/BooksService` | |
-| `/BooksService/$metadata` | |
-| `/BooksService/Books` | |
-| `/BooksService/Reviews` | |
-| `/BooksService/Orders` | |
-
-
-::: tip
-For multitenant applications, it's required to authenticate all endpoints as the tenant information is essential for processing the request.
-:::
-
-There are several application parameters in section `cds.security.authentication` that influence the behaviour of the auto-configuration:
+There are several application parameters in section `cds.security.authentication` that influence the behaviour of the auto-configuration wit hregards to the affected endpoints:
| Configuration Property | Description | Default
| :---------------------------------------------------- | :----------------------------------------------------- | ------------
-| `mode` | Determines the [authentication mode](#auth-mode): `never`, `model-relaxed`, `model-strict` or `always` | `model-strict`
| `authenticateUnknownEndpoints` | Determines, if security configurations enforce authentication for endpoints not managed by protocol-adapters. | `true`
| `authenticateMetadataEndpoints` | Determines, if OData $metadata endpoints enforce authentication. | `true`
-The following properties can be used to switch off automatic security configuration at all:
-
-| Configuration Property | Description | Default
-| :---------------------------------------------------- | :----------------------------------------------------- | ------------
-| `cds.security.xsuaa.enabled` | Whether automatic XSUAA security configuration is enabled. | `true`
-| `cds.security.identity.enabled` | Whether automatic IAS security configuration is enabled. | `true`
-
-#### Setting the Authentication Mode { #auth-mode}
+#### Authentication Modes { #auth-mode}
The property `cds.security.authentication.mode` controls the strategy used for authentication of protocol-adapter endpoints. There are four possible values:
-- `never`: No endpoint requires authentication. All protocol-adapter endpoints are considered public.
-- `model-relaxed`: Authentication is derived from the authorization annotations `@requires` and `@restrict`. If no such annotation is available, the endpoint is considered public.
-- `model-strict`: Authentication is derived from the authorization annotations `@requires` and `@restrict`. If no such annotation is available, the endpoint is authenticated. An explicit `@requires: 'any'` makes the endpoint public.
-- `always`: All endpoints require authentication.
+| Configuration Property | Description |
+| :---------------------------------------------------- | :----------------------------------------------------- |
+| `never` | No endpoint requires authentication. All protocol-adapter endpoints are considered public.
+| `model-relaxed` | Authentication is derived from the authorization annotations `@requires` and `@restrict`. If no such annotation is available, the endpoint is considered public.
+| `model-strict` | Authentication is derived from the authorization annotations `@requires` and `@restrict`. If no such annotation is available, the endpoint is authenticated. An explicit `@requires: 'any'` makes the endpoint public (Default).
+| `always` | All endpoints require authentication.
By default the authentication mode is set to `model-strict` to comply with secure-by-default.
In that case you can use the annotation `@requires: 'any'` on service-level to make the service and its entities public again.
-Please note that it's only possible to make an endpoint public, if the full endpoint path is considered public as well.
+You can only make an endpoint public if the full endpoint path is also considered public.
For example you can only make an entity public, if the service that contains it is also considered public.
+
::: tip
-Please note that the authentication mode has no impact on the *authorization* behaviour.
+The authentication mode has no impact on the *authorization* behaviour.
:::
-#### Customizing Spring Boot Security Configuration { #custom-spring-security-config}
+#### Overrule Partially { #custom-spring-security-config }
If you want to explicitly change the automatic security configuration, you can add an _additional_ Spring security configuration on top that overrides the default configuration by CAP.
-This can be useful, for instance, if an alternative authentication method is required for *specific endpoints* of your application.
+This can be useful if an alternative authentication method is required for *specific endpoints* of your application.
As the default security configurations provided by CAP act as the last line of defense and handle any request by default, you need to ensure that your custom security configurations have higher precedence. At the `SecurityFilterChain` bean method, set the `@Order` annotation with a lower numeric value, for example `1`:
@@ -214,76 +155,70 @@ public class ActuatorSecurityConfig {
}
```
-In case you want to write your own custom security configuration that acts as a last line of defense and handles any request you need to disable the CAP security configurations by setting cds.security.authentication.authConfig.enabled: false, as Spring Security forbids registering multiple security configurations with an any request security matcher.
-
-### Custom Authentication { #custom-authentication}
-You're free to configure any authentication method according to your needs. CAP isn't bound to any specific authentication method or user representation such as introduced with XSUAA, it rather runs the requests based on a [user abstraction](../guides/security/authorization#user-claims). The CAP user of a request is represented by a [UserInfo](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/UserInfo.html) object that can be retrieved from the [RequestContext](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/RequestContext.html) as explained in [Enforcement API & Custom Handlers](#enforcement-api).
-
-Hence, if you bring your own authentication, you have to transform the authenticated user and inject as `UserInfo` to the current request. This is done by means of [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).
-More frequently you might have the requirement to just adapt the request's `UserInfo` which is possible with the same interface:
+#### Overrule Fully { #custom-spring-security-alone }
+In case you want to write your own custom security configuration that acts as a last line of defense and handles any request you need to disable the CAP security configurations by setting cds.security.authentication.authConfig.enabled: false, as Spring Security forbids registering multiple security configurations with an any request security matcher.
-```java
-@Component
-public class CustomUserInfoProvider implements UserInfoProvider {
+If you even want to deactivate OAuth token validation for XSUAA or IAS, e.g. to establish an own authentication strategy,
+the following properties can be used:
- private UserInfoProvider defaultProvider;
+| Configuration Property | Description | Default
+| :---------------------------------------------------- | :----------------------------------------------------- | ------------
+| `cds.security.xsuaa.enabled` | Whether automatic XSUAA security configuration is enabled. | `true`
+| `cds.security.identity.enabled` | Whether automatic IAS security configuration is enabled. | `true`
- @Override
- public UserInfo get() {
- ModifiableUserInfo userInfo = UserInfo.create();
- if (defaultProvider != null) {
- UserInfo prevUserInfo = defaultProvider.get();
- if (prevUserInfo != null) {
- userInfo = prevUserInfo.copy();
- }
- }
- if (userInfo != null) {
- /* any modification of the resolved user goes here: */
- XsuaaUserInfo xsuaaUserInfo = userInfo.as(XsuaaUserInfo.class);
- userInfo.setName(xsuaaUserInfo.getEmail() + "/" +
- xsuaaUserInfo.getOrigin()); // normalizes name
- }
- return userInfo;
- }
- @Override
- public void setPrevious(UserInfoProvider prev) {
- this.defaultProvider = prev;
- }
-}
-```
+## CAP Users { #custom-authentication}
-In the example, the `CustomUserInfoProvider` defines an overlay on the default XSUAA-based provider (`defaultProvider`). The overlay redefines the user's name by a combination of email and origin.
+CAP is not bound to any specific authentication method or user representation such as those introduced with XSUAA or IAS; it runs requests based on a [user abstraction](../guides/security/cap-users#claims).
+The CAP user of a request is represented by a [UserInfo](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/UserInfo.html) object that can be retrieved from the [RequestContext](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/RequestContext.html) as explained in the [authentication guide](../guides/security/cap-users#developing-with-users).
-### Mock User Authentication with Spring Boot { #mock-users}
+### Mock Users { #mock-users}
By default, CAP Java creates a security configuration, which accepts _mock users_ for test purposes.
-::: details Requirement
+::: tip
Mock users are only initialized if the `org.springframework.boot:spring-boot-starter-security` dependency is present in the `pom.xml` file of your service.
:::
-#### Preconfigured Mock Users
+#### Preconfigured Mock Users { #preconfigured-mock-users}
+
+For convenience, the runtime creates default mock users reflecting the [pseudo roles](../guides/security/cap-users#pseudo-roles):
+
+| Name | Role | Password
+| :---------------------------------------------------- | :----------------------------------------------------- | ------------
+| `authenticated` | `authenticated-user` | _empty_
+| `system` |`system-user` | _empty_
+| `privileged` | privileged mode | _empty_
+
+
+For example, requests sent during a Spring MVC unit test with annotation `@WithMockUser("authenticated")` will pass authorization checks that require `authenticated-user`.
+The privileged user will pass any authorization checks.
-For convenience, the runtime creates default mock users reflecting the [pseudo roles](../guides/security/authorization#pseudo-roles). They are named `authenticated`, `system` and `privileged` and can be used with an empty password. For instance, requests sent during a Spring MVC unit test with annotation `@WithMockUser("authenticated")` will pass authorization checks that require `authenticated-user`. The privileged user will pass any authorization checks. `cds.security.mock.defaultUsers = false` prevents the creation of default mock users at startup.
+There are several properties to control behavioud of mock users:
-#### Explicitly Defined Mock Users
+| Configuration Property | Description | Default
+| :---------------------------------------------------- | :----------------------------------------------------- | ------------
+| `cds.security.mock.defaultUsers` | Activates creation of pre-defined mock users at startup. | `true`
+| `cds.security.mock.enabled` | Activates mock users. | `false` in production profile, `true` otherwise.
+
+
+#### Custom Mock Users {#custom-mock-users}
You can also define mock users explicitly. This mock user configuration only applies if:
-* The service runs without an XSUAA service binding (non-productive mode)
+* The service runs without a service binding (non-production mode)
* Mock users are defined in the active application configuration
-Define the mock users in a Spring profile, which may be only active during testing, as in the following example:
+Define the mock users in a Spring profile, which may be only active in local testing, as in the following example:
::: code-group
```yaml [srv/src/main/resources/application.yaml]
---
spring:
- config.activate.on-profile: test
+ config.activate.on-profile: default
cds:
security:
mock:
@@ -307,11 +242,9 @@ cds:
- "*"
```
:::
-- Mock user with name `Viewer-User` is a typical business user with SaaS-tenant `CrazyCars` who has assigned role `Viewer` and user attribute `Country` (`$user.Country` evaluates to value list `[GER, FR]`). This user also has the additional attribute `email`, which can be retrieved with `UserInfo.getAdditionalAttribute("email")`. The [features](../java/reflection-api#feature-toggles) `cruise` and `park` are enabled for this mock user.
+- Mock user with name `Viewer-User` is a typical business user with SaaS tenant `CrazyCars` who has the assigned role `Viewer` and user attribute `Country` (`$user.Country` evaluates to the value list `[GER, FR]`). This user also has the additional attribute `email`, which can be retrieved with `UserInfo.getAdditionalAttribute("email")`. The [features](../java/reflection-api#feature-toggles) `cruise` and `park` are enabled for this mock user.
- `Admin-User` is a user running in privileged mode. Such a user is helpful in tests that bypasses all authorization handlers.
-Property `cds.security.mock.enabled = false` disables any mock user configuration (default in production profile).
-
A setup for Spring MVC-based tests based on the given mock users and the CDS model from [above](#spring-boot) could look like this:
```java
@@ -360,403 +293,43 @@ cds:
The mock user `Alice` is assigned to the mock tenant `CrazyCars` for which the features `cruise` and `park` are enabled.
-## Connecting to IAS Services { #outbound-auth }
-
-CAP Java supports the consumption of IAS-based services of various kinds:
-
-* [Internal Services](#internal-app) bound to the same IAS instance of the provider application.
-* [External IAS](#app-to-app) applications consumed by providing a destination.
-* [BTP reuse services](#ias-reuse) consumed via service binding.
-
-{width="800px" }
-Regardless of the kind of service, CAP provides a [unified integration as Remote Service](/java/cqn-services/remote-services#remote-odata-services).
-Basic communication setup and user propagation is addressed under the hood, for example, an mTLS handshake is performed in case of service-2-service communication.
+### Custom Users { #custom-users}
-### Internal Services {#internal-app}
-
-For communication between adjacent CAP applications, these are CAP applications which are bound to the same identity instance, simplified configuration is explained in [Binding to a Service with Shared Identity](/java/cqn-services/remote-services#binding-to-a-service-with-shared-identity).
-
-### External Services (IAS App-to-App) {#app-to-app}
-
-CAP Java supports technical communication with any IAS-based service deployed to an SAP Cloud landscape. User propagation is supported.
-For connection setup, it uses [IAS App-2-App flows](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications).
-
-#### Provider Application
-
-The CAP Java application as a _provider app_ needs to:
-
-1. Configure [IAS authentication](/java/security#xsuaa-ias).
-2. Expose an API in the IAS service instance.
-
- ::: details Sample IAS instance of provider (mta.yaml)
-
- Add this to your `mta.yaml` resources section:
+Therefore, if you bring your own authentication, you must transform the authenticated user and inject it as `UserInfo` to the current request. This is done by means of [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).
+More frequently you might have the requirement to just adapt the request's `UserInfo` which is possible with the same interface:
- ```yaml
- - name: server-identity
- type: org.cloudfoundry.managed-service
- parameters:
- service: identity
- service-plan: application
- config:
- multi-tenant: true
- provided-apis:
- - name: "review-api"
- ```
- :::
+```java
+@Component
+public class CustomUserInfoProvider implements UserInfoProvider {
-3. Prepare a CDS service endpoint for the exposed API.
+ private UserInfoProvider defaultProvider;
- ::: details Sample CDS Service for the API
+ @Override
+ public UserInfo get() {
+ ModifiableUserInfo userInfo = UserInfo.create();
+ if (defaultProvider != null) {
+ UserInfo prevUserInfo = defaultProvider.get();
+ if (prevUserInfo != null) {
+ userInfo = prevUserInfo.copy();
+ }
+ }
+ if (userInfo != null) {
+ /* any modification of the resolved user goes here: */
+ XsuaaUserInfo xsuaaUserInfo = userInfo.as(XsuaaUserInfo.class);
+ userInfo.setName(xsuaaUserInfo.getEmail() + "/" +
+ xsuaaUserInfo.getOrigin()); // normalizes name
+ }
- ```cds
- service ReviewService @(requires: 'review-api') {
- [...]
+ return userInfo;
}
- ```
-
- :::
-
-::: tip API as CAP role
-The API identifiers exposed by the IAS instance in list `provided-apis` are granted as CAP roles after successful authentication.
-:::
-
-::: 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 verse.
-:::
-
-#### Consumer Application
-
-To set up a connection to such an IAS service, the _consumer app_ requires to do:
-
-1. Create an IAS instance that consumes the required API.
-
- ::: details Sample IAS instance for client (mta.yaml)
-
- Add this to your `mta.yaml` resources section:
-
- ```yaml
- - name: client-identity
- type: org.cloudfoundry.managed-service
- parameters:
- service: identity
- service-plan: application
- config:
- multi-tenant: true
- oauth2-configuration:
- token-policy:
- grant_types:
- - "urn:ietf:params:oauth:grant-type:jwt-bearer"
- ```
-
- :::
-
-2. Create a Remote Service based on the destination (optional).
- ::: details Sample Remote Service configuration
-
- ```yaml
- cds:
- remote.services:
- Reviews:
- destination:
- name: review-service-destination
- ```
-
- :::
-
-To activate the App-2-App connection as a *consumer*, you need to:
-
-1. Create an IAS application dependency in the IAS tenant:
- - Open the Cloud Identity Services admin console
- - Navigate to [Application APIs / Dependencies](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/communicate-between-applications)
- - Create a new dependency pointing to your provider application's API
-
-2. Create a dedicated [destination](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/access-destinations-editor) with the following configuration:
- * The URL pointing to the IAS-endpoint of the application.
- * Authentication type `NoAuthentication`.
- * Attribute `cloudsdk.ias-dependency-name` with the name of the created IAS application dependency in Step 1.
-
-
-
-
-
-[Learn more about how to consume external application APIs with IAS](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications) {.learn-more}
-
-[Learn more about simplified Remote Service configuration with destinations](/java/cqn-services/remote-services#destination-based-scenarios) {.learn-more}
-
-
-### BTP Reuse Services {#ias-reuse}
-
-IAS-based BTP reuse services can be created/consumed with CAP Java even more easily.
-
-The CAP reuse service (provider) needs to:
-
-1. Configure [IAS authentication](/java/security#xsuaa-ias).
-2. Bind an IAS instance that exposes services and service plans.
-
- ::: details Sample IAS instance for provider
-
- ```yaml
- - name: server-identity
- type: org.cloudfoundry.managed-service
- parameters:
- service: identity
- service-plan: application
- config:
- multi-tenant: true
- catalog:
- services:
- - id: "1d5c23ee-1ce6-6130-4af4-26461bc6ef79"
- name: "review-service"
- plans:
- - id: "2d5c23ee-1ce6-6130-4af4-26461bc6ef78"
- name: "review-api"
- ```
-
- :::
-
-3. Prepare a CDS service endpoint for the exposed API.
-
- ::: details Sample CDS Service for the API
-
- ```cds
- service ReviewService @(requires: 'review-api') {
- [...]
+ @Override
+ public void setPrevious(UserInfoProvider prev) {
+ this.defaultProvider = prev;
}
- ```
-
- :::
-
-The CAP consumer application (client) needs to:
-
-1. Create and bind the provided service from the marketplace.
-
- ::: details Create and bind service instance.
- ```sh
- cf create-service review-service review-api review-service-instance
- cf bind-service review-service-instance --binding-name review-service-binding
- ```
- :::
-
-2. Create an IAS instance that consumes the required service.
-
- ::: details Sample IAS instance for client
-
- ```yaml
- - name: client-identity
- type: org.cloudfoundry.managed-service
- parameters:
- service: identity
- service-plan: application
- config:
- multi-tenant: true
- "consumed-services": [ {
- "service-instance-name": "review-service-instance"
- } ]
- ```
-
- :::
-
-3. Create a Remote Service based on the binding (optional).
-
- ::: details Sample Remote Service configuration
-
- ```yaml
- cds:
- remote.services:
- Reviews:
- binding:
- name: review-service-binding
- onBehalfOf: currentUser
- ```
-
- :::
-
-4. Use CQN queries to consume the reuse service (optional)
-
-[Learn more about simplified Remote Service configuration with bindings](/java/cqn-services/remote-services#service-binding-based-scenarios) {.learn-more}
-
-::: tip Service plan name as CAP role
-The service plan names as specified in `consumed-services` in the IAS instance are granted as CAP roles after successful authentication.
-:::
-
-::: 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.
-:::
-
-
-#### How to Authorize Callbacks
-
-For bidirectional communication, callbacks from the reuse service to the CAP service need to be authorized as well.
-Currently, there is no standadized way to achieve this in CAP so that custom codeing is required.
-As a prerequisite*, the CAP service needs to know the clientId of the reuse service's IAS application which should be part of the binding exposed to the CAP service.
-
-::: details Sample Code for Authorization of Callbacks
-
-```java
-private void authorizeCallback() {
- UserInfo userInfo = runtime.getProvidedUserInfo();
- String azp = (String) userInfo.getAdditionalAttributes().get("azp");
- if(!userInfo.isSystemUser() || azp == null || !azp.equals(clientId)) {
- throw new ErrorStatusException(ErrorStatuses.FORBIDDEN);
- }
- }
-```
-:::
-
-
-## Authorization { #auth}
-
-CAP Java SDK provides a comprehensive authorization service. By defining authorization rules declaratively via annotations in your CDS model, the runtime enforces authorization of the requests in a generic manner. Two different levels of authorization can be distinguished:
-
-- [Role-based authorization](../guides/security/authorization#requires) allows to restrict resource access depending on user roles.
-- [Instance-based authorization](../guides/security/authorization#instance-based-auth) allows to define user privileges even on entity instance level, that is, a user can be restricted to instances that fulfill a certain condition.
-
-It's recommended to configure authorization declaratively in the CDS model. If necessary, custom implementations can be built on the [Authorization API](#enforcement-api).
-
-A precise description of the general authorization capabilities in CAP can be found in the [Authorization](../guides/security/authorization) guide.
-
-In addition to standard authorization, CAP Java provides additional out of the box capabilities to reduce custom code:
-
-### Deep Authorization { #deep-auth}
-
-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.
-__Compositions__ are neither checked nor extended with additional filters.
-For instance, consider the following model:
-
-```cds
-@(restrict: [{ grant: 'READ', to: 'Manager' }])
-entity Books {...}
-
-@(restrict: [{ grant: 'READ', to: 'Manager' }])
-entity Orders {
- key ID: String;
- items: Composition of many {
- key book: Association to Books;
- quantity: Integer;
- }
}
```
-For the following OData request `GET Orders(ID='1')/items?$expand=book`, authorizations for `Orders` and for `Books` are checked.
-If the entity `Books` has a `where` clause for [instance-based authorization](/java/security#instance-based-auth),
-it will be added as a filter to the sub-request with the expand.
-
-Custom CQL statements submitted to the [Application Service](/java/cqn-services/application-services) instances
-are also authorized by the same rules including the path expressions and subqueries used in them.
-
-For example, the following statement checks role-based authorizations for both `Orders` and `Books`,
-because the association to `Books` is used in the select list.
-
-```java
-Select.from(Orders_.class,
- f -> f.filter(o -> o.ID().eq("1")).items())
- .columns(c -> c.book().title());
-```
-
-For modification statements with associated entities used in infix filters or where clauses,
-role-based authorizations are checked as well. Associated entities require `READ` authorization, in contrast to the target of the statement itself.
-
-The following statement requires `UPDATE` authorization on `Orders` and `READ` authorization on `Books`
-because an association from `Orders.items` to the book is used in the where condition.
-
-```java
-Update.entity(Orders_.class, f -> f.filter(o -> o.ID().eq("1")).items())
- .data("quantity", 2)
- .where(t -> t.book().ID().eq(1));
-```
-:::tip Modification of Statements
-Be careful when you modify or extend the statements in custom handlers.
-Make sure you keep the filters for authorization.
-:::
-
-Starting with CAP Java `4.0`, deep authorization is on by default.
-It can be disabled by setting cds.security.authorization.deep.enabled: false.
-
-[Learn more about `@restrict.where` in the instance-based authorization guide.](/guides/security/authorization#instance-based-auth){.learn-more}
-
-### Forbidden on Rejected Entity Selection { #reject-403 }
-
-Entities that have an instance-based authorization condition, that is [`@restrict.where`](/guides/security/authorization#restrict-annotation),
-are guarded by the CAP Java runtime by adding a filter condition to the DB query **excluding not matching instances from the result**.
-Hence, if the user isn't authorized to query an entity, requests targeting a *single* entity return *404 - Not Found* response and not *403 - Forbidden*.
-
-To allow the UI to distinguish between *not found* and *forbidden*, CAP Java can detect this situation and rejects`PATCH` and `DELETE` requests to single entities with forbidden accordingly.
-The additional authorization check may affect performance.
-
-::: warning
-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.
-:::
-
-Starting with CAP Java `4.0`, the reject behaviour is on by default.
-It can be disabled by setting cds.security.authorization.instance-based.reject-selected-unauthorized-entity.enabled: false.
-
-[Learn more about `@restrict.where` in the instance-based authorization guide.](/guides/security/authorization#instance-based-auth){.learn-more}
-
-### Authorization Checks On Input Data { #input-data-auth }
-
-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:
-
-```cds
-annotate Orders with @(restrict: [
- { grant: '*', where: 'accountingArea = $user.accountingAreas' } ]);
-```
-
-A user with accounting areas `[Development, Research]` is not able to send an `UPDATE` request, that changes `accountingArea` from `Research` or `Development` to `CarFleet`, for example.
-Note that the `UPDATE` on instances _not matching the request user's accounting areas_ (for example, `CarFleet`) are rejected by standard instance-based authorization checks.
-
-Starting with CAP Java `4.0`, deep authorization is on by default.
-It can be disabled by setting cds.security.authorization.instanceBased.checkInputData: false.
-
-[Learn more about `@restrict.where` in the instance-based authorization guide.](/guides/security/authorization#instance-based-auth){.learn-more}
-
-
-### Enforcement API & Custom Handlers { #enforcement-api}
-
-The generic authorization handler performs authorization checks driven by the annotations in an early Before handler registered to all application services by default. You may override or add to the generic authorization logic by providing custom handlers. The most important piece of information is the [UserInfo](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/request/UserInfo.html) that reflects the authenticated user of the current request. You can retrieve it:
-
-a) from the [EventContext](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/EventContext.html):
- ```java
- EventContext context;
- UserInfo user = context.getUserInfo();
- ```
-
-b) through dependency injection within a handler bean:
-
- ```java
- @Autowired
- UserInfo user;
- ```
-
-The most helpful getters in `UserInfo` are listed in the following table:
-
-| UserInfo method | Description
-| :---------------------------------------------------- | :----------------------------------------------------- |
-| `getName()` | Returns the unique (logon) name of the user as configured in the IdP. Referred by `$user` and `$user.name`. |
-| `getTenant()` | Returns the tenant of the user. |
-| `isSystemUser()` | Indicates whether the request has been initiated by a technical service. Refers to [pseudo-role](../guides/security/authorization#pseudo-roles) `system-user`. |
-| `isAuthenticated()` | True if the current user has been authenticated. Refers to [pseudo-role](../guides/security/authorization#pseudo-roles) `authenticated-user`. |
-| `isPrivileged()` | Returns `true` if the current user runs in privileged (that is, unrestricted) mode |
-| `hasRole(String role)` | Checks if the current user has the given role. |
-| `getRoles()` | Returns the roles of the current user |
-| `getAttributeValues(String attribute)` | Returns the value list of the given user attribute. Referred by `$user.`. |
-
-It's also possible to modify the `UserInfo` object for internal calls. See section [Request Contexts](./event-handlers/request-contexts) for more details.
-For instance, you might want to run internal service calls in privileged mode that bypasses authorization checks:
-
-```java
-cdsRuntime.requestContext().privilegedUser().run(privilegedContext -> {
- assert privilegedContext.getUserInfo().isPrivileged();
- // ... Service calls in this scope pass generic authorization handler
-});
-```
+In the example, the `CustomUserInfoProvider` defines an overlay on the default XSUAA-based provider (`defaultProvider`). The overlay redefines the user's name by a combination of email and origin.
diff --git a/menu.md b/menu.md
index 53a289d38e..7cea86d492 100644
--- a/menu.md
+++ b/menu.md
@@ -76,8 +76,11 @@
## [Security](guides/security/)
- ### [CDS-based Authorization](guides/security/authorization)
- ### [Platform Security](guides/security/overview)
+ ### [Overview](guides/security/overview)
+ ### [Authentication](guides/security/authentication)
+ ### [CAP Users](guides/security/cap-users)
+ ### [CAP Authorization](guides/security/authorization)
+ ### [Remote Authentication](guides/security/remote-authentication)
### [Security Aspects](guides/security/aspects)
### [Data Protection & Privacy](guides/security/data-protection-privacy)
### [Product Standard Compliance](../guides/security/product-standards)
diff --git a/tools/cds-lint/rules/auth-valid-restrict-to/index.md b/tools/cds-lint/rules/auth-valid-restrict-to/index.md
index 6b6c7fe2fa..f22577ccca 100644
--- a/tools/cds-lint/rules/auth-valid-restrict-to/index.md
+++ b/tools/cds-lint/rules/auth-valid-restrict-to/index.md
@@ -14,7 +14,7 @@ status: released
## Rule Details
-The `to` property of a `@restrict` privilege defines one or more [user roles](../../../../guides/security/authorization#roles) or [pseudo roles](../../../../guides/security/authorization#pseudo-roles) that the privilege applies to. This rule checks that the values of `@restrict.to` are valid, that is, roles cannot be missing or misspelled and that roles including `any` should be simplified to just `any`.
+The `to` property of a `@restrict` privilege defines one or more [user roles](../../../../guides/security/cap-users#roles) or [pseudo roles](../../../../guides/security/cap-users#pseudo-roles) that the privilege applies to. This rule checks that the values of `@restrict.to` are valid, that is, roles cannot be missing or misspelled and that roles including `any` should be simplified to just `any`.
## Examples