diff --git a/java/cqn-services/remote-services.md b/java/cqn-services/remote-services.md index 1158b6b6e..c74f5abaa 100644 --- a/java/cqn-services/remote-services.md +++ b/java/cqn-services/remote-services.md @@ -147,8 +147,8 @@ The class `SomeReuseServiceOAuth2PropertySupplier` needs to be provided by you e #### Binding to a Service with Shared Identity -If the remote API is available within the same SaaS application and using the same (shared) XSUAA service instance for authentication, no service broker-based reuse service is required. -The _Remote Service_ can be configured using the shared XSUAA service instance as binding (here: `shared-xsuaa`): +If the remote API is available within the same SaaS application and using the same (shared) service instance of XSUAA or Identity (IAS) for authentication, no service broker-based reuse service is required. +The _Remote Service_ can be configured using the shared service instance as binding (here: `shared-xsuaa`): ::: code-group ```yaml [srv/src/main/resources/application.yaml] @@ -162,9 +162,14 @@ cds: ``` ::: -The plain XSUAA service binding does not contain the URL of the remote API. Therefore it needs to be explicitly configured in the `options` section. +The plain service binding of XSUAA or IAS does not contain the URL of the remote API. Therefore it needs to be explicitly configured in the `options` section. As the URL is typically not known at development time, it can be alternatively defined as an environment variable `CDS_REMOTE_SERVICES__OPTIONS_URL`. +:::tip +Remote APIs which require IAS-based authentication might expect certificate based client authentication in addition to the IAS-based JWT token (ie. [proof-of-possession](https://github.com/SAP/cloud-security-services-integration-library/tree/main/java-security#proofofpossession-validation)). +CAP _Remote Services_ automatically takes care of this by initiating a mutual TLS handshake with the remote API. +::: + #### Configuring the Authentication Strategy While service bindings typically provide authentication details, they don't predetermine the user propagation and authentication strategy, for example, technical user or named user flow. @@ -193,6 +198,20 @@ cds: ``` ::: +If your CAP application is using IAS and you want to call a _remote API_ that is provided by another IAS-based application (ie. Application2Application scenario), you can utilize a simplified security configuration in the destination. +As a pre-requisite, your CAP application and the called application need to trust the same IAS tenant and you need to define a dependency in IAS to consume the respective API provided by the _remote API_. + +Create a destination configuration with the following parameters: + +- _URL_: `` +- _Authentication_: `NoAuthentication` +- Additional Properties: + - _cloudsdk.ias-dependency-name_: `` + +At runtime, this destination configuration will use the bound `identity` service instance's credentials to request a token for the _remote API_. + +[Learn more about consuming APIs from Other IAS-Appications in the **SAP Cloud Identity Services documentation**.](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications){.learn-more} + The CAP Java SDK obtains the destination for a _Remote Service_ from the `DestinationAccessor` using the name that is configured in the _Remote Service_'s destination configuration. If you're using the SAP BTP Destination Service, this is the name you used when you defined the destination there. To properly resolve the destination from SAP BTP Destination Service [additional Cloud SDK dependencies](#cloud-sdk-dependencies) are required. diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 6f3eceeb6..352434e5f 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -28,10 +28,10 @@ Now, that you're familiar with how to configure your application, start to creat When running your application in production, it makes sense to strictly disable some development-oriented features. The production profile configures a set of selected property defaults, recommended for production deployments, at once. -To specify the production profile, set `cds.environment.production.profile` to a Spring profile used in production deployments. +By default the production profile is set to `cloud`. To specify a custom production profile, set `cds.environment.production.profile` to a Spring profile used in your production deployments. ::: tip Production profile = `cloud` -It is recommended to set `cds.environment.production.profile` to `cloud`. The Java Buildpacks set the `cloud` profile for applications by default. +The Java Buildpacks set the `cloud` profile for applications by default. Other active profiles for production deployments are typically set using the environment variable `SPRING_PROFILES_ACTIVE` on your application in your deployment descriptors (`mta.yaml`, Helm charts, etc.). ::: diff --git a/java/messaging.md b/java/messaging.md index ec0794914..2a6854451 100644 --- a/java/messaging.md +++ b/java/messaging.md @@ -755,7 +755,7 @@ Besides these kinds of topic manipulations, additional topic manipulations might The configuration property `structured` determines if messages are represented as a plain String (`false`) or always structured as two separate maps, representing data and headers (`true`). Setting this property enables handling of message headers, like `cloudevents` headers, separately from the message itself. This works for all messaging brokers supported by CAP. If using a message broker that supports native headers, e.g. Kafka, the headers are separated from the business data. On incoming messages the flag determines the internal representation of the message either as a plain string or two maps of message data and message headers. Having header data separated, avoids adding extra information or metadata as part of the business data when sending them to the message broker. Additionally the header data is clearly separated on the consumer side, because they provided by different data and headers maps. -The default value for the configuration property `structured` is `false`. +The default value for the configuration property `structured` is `true`. Configuration example: ::: code-group diff --git a/java/migration.md b/java/migration.md index 6423573af..1c9e0e508 100644 --- a/java/migration.md +++ b/java/migration.md @@ -23,8 +23,203 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/ [[toc]] +## CAP Java 2.10 to CAP Java 3.0 { #two-to-three } -## CAP Java 1.34 to CAP Java 2.0 { #one-to-two} +### Minimum Versions + +CAP Java 3.0 increased some minimum required versions: + +| Dependency | Minimum Version | +| --- | --- | +| @sap/cds-dk | ^7 | +| Maven | 3.6.3 | +| Cloud SDK | 5.9.0 | + +CAP Java 3.0 no longer supports @sap/cds-dk ^6. + +### Production Profile `cloud` + +The Production Profile now defaults to `cloud`. This ensures that various property defaults suited for local development are changed to recommended secure values for production. + +One of the effects of the production profile is that the index page is disabled by default. +If you are using the root path `/` for readiness or liveness probing in Kyma you will need to adjustment them, in this case +it is recommended to use Spring Boot actuator's `/actuator/health` endpoint instead. + +[Learn more about the Production Profile.](developing-applications/configuring#production-profile){.learn-more} + +### Removed feature `cds-feature-xsuaa` + +The feature `cds-feature-xsuaa` has been removed. Support for XSUAA and IAS has been unified under the umbrella of `cds-feature-identity`. + +It utilizes [SAP´s `spring-security` library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security) instead of the deprecated [`spring-xsuaa` library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-xsuaa). + +If your application relies on the standard security configuration by CAP Java and depend on one of the CAP starter bundles, it is expected that you won't need to adapt code. + +If you have customized the security configuration, you need to adapt it to the new library. If your application had a direct dependency to `cds-feature-xsuaa`, we recommend using one of our starter bundles `cds-starter-cloudfoundry` or `cds-starter-k8s`. + +[Learn more about the security configuration.](./security#xsuaa-ias){.learn-more} +[Learn more about migration to SAP´s `spring-security` library.](https://github.com/SAP/cloud-security-services-integration-library/blob/main/spring-security/Migration_SpringXsuaaProjects.md) + +### Removed MTX Classic Support + +Support for classic MTX (@sap/cds-mtx) has been removed. Using streamlined MTX (@sap/cds-mtxs) is mandatory for multitenancy. +If you're still using MTX Classic refer to the [multitenancy migration guide](../guides/multitenancy/old-mtx-migration). + +In addition, the deprecated `MtSubscriptionService` API, has been removed. It has now been superseeded by the `DeploymentService` API. +As part of this change the compatibility mode for the `MtSubscriptionService` API has been removed. Besides the removal of the Java APIs this includes the following behavioural changes: + +- During unsubscribe the tenant's content (e.g. HDI container) is now deleted by default when using the new `DeploymentService` API. +- The HTTP-based tenant upgrade APIs provided by the CAP Java app have been removed. This includes the following endpoints: + - `/mt/v1.0/subscriptions/deploy/**` (GET & POST) + - `/messaging/v1.0/em/` (PUT) + +### Lazy Localization by default + +EDMX resources served by the OData V4 `/$metadata` endpoints are now localized lazily by default. +This significantly reduces EDMX cache memory consumption when many languages are used. +Note, that this requires at least `@sap/cds-mtxs` in version `1.12.0`. + +The cds build no longer generates localized EDMX files by default anymore, but instead generates templated EDMX files and a `i18n.json` containing text bundles. +If you need localized EDMX files to be generated, set `--opts contentLocalizedEdmx=true` when calling `cds build`. + +### Star-expand and inline-all are no longer permitted + +Previously, you could not use expand or inline without explicit paths on draft-enabled entities. Now they are rejected for all entities on application service level. + +For example, following statement will not be executed when submitted to an instance of [`ApplicationService`](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/cds/ApplicationService.html). + +```java +Select.from(BOOKS).columns(b -> b.expand()); +``` + +This does not impact OData where `expand=*` is transformed into expands for all associations. + +### Adjusted POJO class generation + +Some parameter defaults of the goal `generate` have been adjusted: + +| Parameter | Old Value | New Value | Explanation | +| --- | --- | --- | --- | +| `sharedInterfaces` | `false` | `true` | Interfaces for global arrayed types with inline anonymous type are now generated exactly once. `sharedInterfaces` ensures such types are not generated as inline interfaces again, if used in events, actions or functions. | +| `uniqueEventContexts` | `false` | `true` | Determines whether the event context interfaces should be unique for bound actions and functions. | + +Both these changes result in the generation of incompatible POJOs. To get the former POJOs, the new defaults can be overwritten by setting the parameters to the old values. + +### Adjusted Property Defaults + +Some property defaults have been adjusted: + +| Property | Old Value | New Value | Explanation | +| --- | --- | --- | --- | +| `cds.remote.services..http.csrf.enabled` | `true` | `false` | Most APIs don't require CSRF tokens. | +| `cds.sql.hana.optimizationMode` | `legacy` | `hex` | SQL for SAP HANA is optimized for the HEX engine. | +| `cds.odataV4.lazyI18n.enabled` | `null` | `true` | Lazy localization is now enabled by default in multitenant scenarios. | +| `cds.auditLog.personalData.throwOnMissingDataSubject` | `false` | `true` | Raise errors for incomplete personal data annotations by default. | +| `cds.messaging.services..structured` | `false` | `true` | [Enhanced message representation](./messaging.md#enhanced-messages-representation) is now enabled by default. | + +### Adjusted Property Behavior + +| Property | New Behavior | +| --- | --- | +| `cds.outbox.persistent.enabled` | When set to `false`, all persistent outboxes are disabled regardless of their specific configuration. | + +### Deprecated Session Context Variables + +| Old Variable | Replacement | +| --- | --- | +| `$user.tenant` | `$tenant` | +| `$at.from` | `$valid.from` | +| `$at.to` | `$valid.to` | + +### Removed Properties + +The following table gives an overview about the removed properties: + +| Removed Property | Replacement | Explanation | +| --- | --- | --- | +| `cds.auditlog.outbox.persistent.enabled` | `cds.auditlog.outbox.name` | | +| `cds.dataSource.csvFileSuffix` | `cds.dataSource.csv.fileSuffix` | | +| `cds.dataSource.csvInitializationMode` | `cds.dataSource.csv.initializationMode` | | +| `cds.dataSource.csvPaths` | `cds.dataSource.csv.paths` | | +| `cds.dataSource.csvSingleChangeset` | `cds.dataSource.csv.singleChangeset` | | +| `cds.identity.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | +| `cds.messaging.services..outbox.persistent.enabled` | `cds.messaging.services..outbox.name` | | +| `cds.multiTenancy.compatibility.enabled` | | MtSubscriptionService API [has been removed](#removed-mtx-classic-support) and compatibility mode is no longer available. | +| `cds.multiTenancy.healthCheck.intervalMillis` | `cds.multiTenancy.healthCheck.interval` | | +| `cds.multiTenancy.mtxs.enabled` | | MTXS is enabled [by default](#removed-mtx-classic-support). | +| `cds.multiTenancy.security.deploymentScope` | | HTTP-based tenant upgrade endpoints [have been removed](#removed-mtx-classic-support). | +| `cds.odataV4.apply.inCqn.enabled` | `cds.odataV4.apply.transformations.enabled` | | +| `cds.odataV4.serializer.enabled` | | The legacy serializer has been removed. | +| `cds.outbox.persistent.maxAttempts` | `cds.outbox.services..maxAttempts` | | +| `cds.outbox.persistent.storeLastError` | `cds.outbox.services..storeLastError` | | +| `cds.outbox.persistent.ordered` | `cds.outbox.services..ordered` | | +| `cds.remote..destination.headers` | `cds.remote.services..http.headers` | | +| `cds.remote..destination.queries` | `cds.remote.services..http.queries` | | +| `cds.remote..destination.service` | `cds.remote.services..http.service` | | +| `cds.remote..destination.suffix` | `cds.remote.services..http.suffix` | | +| `cds.remote..destination.type` | `cds.remote.services..type` | | +| `cds.security.mock.users..unrestricted` | | Special handling of unrestricted attributes has been removed, in favor of [explicit modelling](../guides/security/authorization#unrestricted-xsuaa-attributes). | +| `cds.sql.search.useLocalizedView` | `cds.sql.search.model` | | +| `cds.sql.supportedLocales` | | All locales are supported by default for localized entities, as session variables can now be leveraged on all databases. | +| `cds.xsuaa.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | + +### Removed Java APIs + +- Removed deprecated classes: + - `com.sap.cds.services.environment.ServiceBinding` + - `com.sap.cds.services.environment.ServiceBindingAdapter` + - `com.sap.cds.services.mt.MtAsyncDeployEventContext` + - `com.sap.cds.services.mt.MtAsyncDeployStatusEventContext` + - `com.sap.cds.services.mt.MtAsyncSubscribeEventContext` + - `com.sap.cds.services.mt.MtAsyncSubscribeFinishedEventContext` + - `com.sap.cds.services.mt.MtAsyncUnsubscribeEventContext` + - `com.sap.cds.services.mt.MtAsyncUnsubscribeFinishedEventContext` + - `com.sap.cds.services.mt.MtDeployEventContext` + - `com.sap.cds.services.mt.MtGetDependenciesEventContext` + - `com.sap.cds.services.mt.MtSubscribeEventContext` + - `com.sap.cds.services.mt.MtSubscriptionService` + - `com.sap.cds.services.mt.MtUnsubscribeEventContext` + +- Removed deprecated methods: + - `com.sap.cds.services.request.ModifiableUserInfo.addUnrestrictedAttribute` + - `com.sap.cds.services.request.ModifiableUserInfo.setUnrestrictedAttributes` + - `com.sap.cds.services.request.ModifiableUserInfo.removeUnrestrictedAttribute` + - `com.sap.cds.services.request.UserInfo.getUnrestrictedAttributes` + - `com.sap.cds.services.request.UserInfo.isUnrestrictedAttribute` + - `com.sap.cds.ql.Insert.cqn(String)` + - `com.sap.cds.ql.Update.cqn(String)` + - `com.sap.cds.ql.Upsert.cqn(String)` + +- Deprecations: + - `com.sap.cds.ql.cqn.CqnSearchPredicate`, instead use `CqnSearchTermPredicate` + - `com.sap.cds.ql.cqn.Modifier.search(String)`, instead use `searchTerm(CqnSearchTermPredicate)` + +### Removed goals in `cds-maven-plugin` + +The goal `addSample` from the `cds-maven-plugin` has been removed. Use the new goal `add` with the property `-Dfeature=TINY_SAMPLE` instead. + +### Proof-Of-Possession enforced for IAS-based authentication + +In IAS scenarios, the [Proof-Of-Possession](https://github.com/SAP/cloud-security-services-integration-library/tree/main/java-security#proofofpossession-validation) is now enforced by default for incoming requests for versions starting from `3.5.1` of the [SAP BTP Spring Security Client](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security). + +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} + +## Cloud SDK 4 to 5 { #cloudsdk5 } + +CAP Java `2.6.0` and higher is compatible with Cloud SDK in version 4 and 5. For reasons of backward compatibility, CAP Java assumes Cloud SDK 4 as the default. However, we highly recommend that you use at least version `5.7.0` of Cloud SDK. If you relied on the Cloud SDK integration package (`cds-integration-cloud-sdk`), you won't need to adapt any code to upgrade your CAP Java application to Cloud SDK 5. In these cases, it's sufficient to add the following maven dependency to your CAP Java application: + +```xml + + com.sap.cloud.sdk.cloudplatform + connectivity-apache-httpclient4 + +``` + +If you are using Cloud SDK APIs explicitly in your code consider the migration guide for Cloud SDK 5 itself: https://sap.github.io/cloud-sdk/docs/java/guides/5.0-upgrade-steps + +## CAP Java 1.34 to CAP Java 2.0 { #one-to-two } This section describes the changes in CAP Java between the major versions 1.34 and 2.0. It provides also helpful information how to migrate a CAP Java application to the new major version 2.0. @@ -1042,16 +1237,3 @@ After rebuilding and restarting your application, your Application Services are - -## Cloud SDK 4 to 5 { #cloudsdk5 } - -CAP Java `2.6.0` and higher is compatible with Cloud SDK in version 4 and 5. For reasons of backward compatibility, CAP Java assumes Cloud SDK 4 as the default. However, we highly recommend to use at least version `5.2.0` of Cloud SDK. To upgrade your CAP Java application to Cloud SDK 5, in most cases, you don't need to adapt any code if you rely on the Cloud SDK integration package (`cds-integration-cloud-sdk`). In these cases, it's sufficient to add the following maven dependency to your CAP Java application: - -```xml - - com.sap.cloud.sdk.cloudplatform - connectivity-apache-httpclient4 - -``` - - diff --git a/java/security.md b/java/security.md index eb3d416b3..df62dec24 100644 --- a/java/security.md +++ b/java/security.md @@ -63,52 +63,19 @@ CAP Java picks only a single binding of each type. If you have multiple XSUAA or 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`. ::: -### Transition from `cds-feature-xsuaa` to `cds-feature-identity` { #transition-xsuaa-ias} -CAP also provides support for XSUAA-based authentication via the maven dependency `cds-feature-xsuaa` which is based on the [spring-xsuaa library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-xsuaa). -We recommend to move to `cds-feature-identity`, as the spring-xsuaa library is deprecated. When moving to `cds-feature-identity`, please keep the following in mind: +#### Proof-Of-Possession for IAS { #proof-of-possession} -- As `cds-feature-xsuaa` still takes priority over `cds-feature-identity` for backward compatibility, remove all existing dependencies to `cds-feature-xsuaa` and `xsuaa-spring-boot-starter`. -- If you are using the `cds-starter-cloudfoundry` or the `cds-starter-k8s` starter bundle, make sure to **explicitly** exclude the mentioned dependencies using `...`. +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. -::: code-group +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. -```xml [srv/pom.xml (cds-starter-cloudfoundry)] - - com.sap.cds - cds-starter-cloudfoundry - - - com.sap.cds - cds-feature-xsuaa - - - com.sap.cloud.security.xsuaa - xsuaa-spring-boot-starter - - - -``` +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 utilizing the `.cert.` domain. -```xml [srv/pom.xml (cds-starter-k8s)] - - com.sap.cds - cds-starter-k8s - - - com.sap.cds - cds-feature-xsuaa - - - com.sap.cloud.security.xsuaa - xsuaa-spring-boot-starter - - - -``` +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. This can be achieved by setting `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)). -::: +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. -Now follow the description in [Configure XSUAA and IAS Authentication](#xsuaa-ias). +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. ### Automatic Spring Boot Security Configuration { #spring-boot} diff --git a/java/versions.md b/java/versions.md index fd0832b1b..82ff50dd3 100644 --- a/java/versions.md +++ b/java/versions.md @@ -66,12 +66,12 @@ The following table lists these minimum versions for various common dependencies | Dependency | Minimum Version | Recommended Version | | --- | --- | --- | | JDK | 17 | 211 | -| Maven | 3.5.0 | 3.9.6 | -| @sap/cds-dk | 6 | latest | -| @sap/cds-compiler | 3 | latest | +| Maven | 3.6.3 | 3.9.8 | +| @sap/cds-dk | 7 | latest | +| @sap/cds-compiler | 4 | latest | | Spring Boot | 3.0 | latest | | XSUAA | 3.0 | latest | -| SAP Cloud SDK | 4.24 | latest | +| SAP Cloud SDK | 5.9 | latest | | Java Logging | 3.7 | latest | 1 When using the SAP Business Application Studio JDK 17 is recommended.