From a6e6723c31d3817e3486a007a5fe81d8cf69aee1 Mon Sep 17 00:00:00 2001 From: Matthias Kuhr Date: Tue, 28 Oct 2025 15:59:41 +0100 Subject: [PATCH 1/5] Updates to mTLS and bound services --- .../connectivity/003-service-bindings.mdx | 85 +++++++++++++------ docs-java/features/connectivity/007-mtls.mdx | 44 +++++++--- 2 files changed, 91 insertions(+), 38 deletions(-) diff --git a/docs-java/features/connectivity/003-service-bindings.mdx b/docs-java/features/connectivity/003-service-bindings.mdx index 80b38a0c27a..1dc633a4479 100644 --- a/docs-java/features/connectivity/003-service-bindings.mdx +++ b/docs-java/features/connectivity/003-service-bindings.mdx @@ -52,6 +52,25 @@ This is an example where the service offers multiple API endpoints and you need Explore the [BtpServiceOptions](pathname:///java-api/v5/com/sap/cloud/sdk/cloudplatform/connectivity/BtpServiceOptions.html) class to find the options relevant for your service and your use-case. +### Supported Credential Types + +The SAP Cloud SDK supports various credential types for XSUAA- and IAS-based services: + +* Client secret (`instance-secret`, `binding-secret` (XSUAA) or `binding-secret` (IAS)) +* Client certificate + * Certificate generated by the platform, present in the binding (`x509` (XSUAA) or `X509_GENERATED` (IAS)) + * Certificate attested by the Zero Trust Identity Service (ZTIS) (`x509_attested` (XSUAA) or `X509_ATTESTED` (IAS)) + +If the service binding contains no explicit credential type, the SAP Cloud SDK defaults to using a client secret. +The credential type `X509_PROVIDED` (IAS), as well as `x509` with a custom provided certificate (XSUAA), are currently not supported. + +:::info ZTIS Integration + +To use the `X509_ATTESTED` or `x509_attested` credential type, additional setup is required. +Read more about how to configure your app for this credential type on the documentation for [using certificates from the Zero Trust Identity Service (ZTIS)](/docs/java/features/connectivity/mtls#using-automated-certificate-rotation-using-the-zero-trust-identity-service-sap-internal). + +::: + ### List of Supported Services The SAP Cloud SDK supports a variety of services out of the box. @@ -131,6 +150,14 @@ ServiceBindingDestinationOptions .build(); ``` +:::note Principal Propagation with IAS + +For IAS-based applications and services, principal propagation the grant type `jwt-bearer` needs to be enabled. +This can be enabled in the IAS admin console, or by setting the `grant-types` parameter on the identity service instance. +Refer to the documentation [here](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/reference-information-for-identity-service-of-sap-btp?version=Cloud). + +::: + ## Using the Extended Service for User and Account Authentication (XSUAA) Communicating with SAP provided services secured by the SAP XSUAA service usually requires explicit support by the SAP Cloud SDK (see [list of supported services](#list-of-supported-services)). @@ -154,35 +181,11 @@ The code above instructs the SAP Cloud SDK to This configuration results in a destination that uses the XSUAA instance of your application to authenticate against, but communicates with the system reachable under the provided URI. Without the option specified in line 3, the destination would target the XSUAA instance itself. -:::note Principal Propagation with IAS - -For IAS-based applications and services principal propagation requires additional configuration. -When creating the IAS service binding an additional parameter needs to be passed to enable the `jwt-bearer` grant type. -Refer to the documentation [here](https://github.wdf.sap.corp/CPSecurity/Knowledge-Base/blob/master/08_Tutorials/iasbroker/README.md#parameters) (SAP-internal). - -::: - ## Using the Identity and Authentication Service (IAS) -:::warning Beta API - -The API for connecting to services secured by the SAP Identity and Authentication Service (IAS) is currently in beta and subject to change. - -::: - In case your application is bound to an instance of the SAP Identity and Authentication Service (IAS) you can use the SAP Cloud SDK to connect to other applications and services that are secured using IAS. Effectively, the SAP Cloud SDK implements the OAuth flows described [here](https://help.sap.com/docs/identity-authentication/identity-authentication/consume-apis-from-other-applications). -:::info Supported Credential Types - -The SAP Cloud SDK supports the credential types `binding-secret`, `X509_GENERATED` and `X509_ATTESTED` for IAS service bindings. - -If you want to use the `X509_ATTESTED` credential type, you need to add the `connectivity-ztis` dependency to your project. -Read more about how to configure your app for this credential type on the documentation for [using certificates from the Zero Trust Identity Service (ZTIS)](/docs/java/features/connectivity/mtls#using-automated-certificate-rotation-using-the-zero-trust-identity-service-sap-internal). - -The type `X509_PROVIDED` is currently not supported. -::: - ### Connecting to Services If your service is secured using IAS and is using the dedicated [service binding format](#service-binding-format) supported by the SAP Cloud SDK, you can obtain a destination by passing the service label as the `ServiceIdentifier`: @@ -236,6 +239,40 @@ var options = ServiceBindingDestinationOptions .build(); ``` +In case the application URL, dependency name or other properties are dynamic or tenant-specific, you may want to use a BTP destination to hold this information. +Check the example below for how to combine BTP destinations with an IAS App2App flow. + +
+Example for an IAS-based App2App Flow using BTP Destinations + +Define a destination in BTP cockpit and set the target system URL, a property to hold the App2App dependency name, as well as any further properties you might need for your use case (e.g. additional headers, query parameters, etc.). + +```plaintext +name: myDestination +url: https://my-target-system.com/api +authenticationType: NoAuthentication +myPropertyForApp2AppDependencyName: myApp2AppDependency +``` + +You can now use the following code to obtain a destination that will execute the IAS App2App token flow using the certificate provided by ZTIS: + +```java +var btpDestination = DestinationAccessor.getDestination("myDestination"); +var dependency = btpDestination.get("myPropertyForApp2AppDependencyName", String.class).get(); +var uri = btpDestination.getUri(); + +var opts = ServiceBindingDestinationOptions.forService(ServiceIdentifier.IDENTITY_AUTHENTICATION) + .withOption(BtpServiceOptions.IasOptions.withApplicationName(dependency)) + .withOption(BtpServiceOptions.IasOptions.withTargetUri(uri)) + .build(); + +var destination = ServiceBindingDestinationLoader.defaultLoaderChain().getDestination(opts); +``` + +Effectively, the destination from BTP destination service serves as a config map and has to be merged with the destination created locally for the App2App flow. + +
+ ### Calling Back Applications If you received an incoming request from an application using IAS you can use the following options to create a destination for calling back the application: diff --git a/docs-java/features/connectivity/007-mtls.mdx b/docs-java/features/connectivity/007-mtls.mdx index 4a39c7268e4..e9e355489b8 100644 --- a/docs-java/features/connectivity/007-mtls.mdx +++ b/docs-java/features/connectivity/007-mtls.mdx @@ -166,11 +166,14 @@ This guide covers how you can configure and use the SAP Cloud SDK to use certifi The following prerequisites are required to use ZTIS: -- You are deploying an application on Cloud Foundry -- You have assigned the required entitlement for using ZTIS to your subaccount -- You have created a service instance of `zero-trust-identity` in your Cloud Foundry space -- You have bound the ZTIS service instance to your application -- You have added the `zero_trust_sidecar_buildpack` as an additional buildpack for your application +- You have assigned the required entitlement for using ZTIS to your subaccount. +- You have created a service instance of `zero-trust-identity`. +- You have bound the ZTIS service instance to your application. +- For Cloud Foundry: You have added the `zero_trust_sidecar_buildpack` as an additional buildpack for your application. +- For Kubernetes (Kyma, Gardener): + - You have installed the [ZTIS Operator](https://github.tools.sap/pse/ztis-operator?tab=readme-ov-file) in your cluster. + - On Kyma, this is available as the [ZTIS Agent Kyma Module](https://pages.github.tools.sap/pse/pse-docs/docs/identity-k8s/references/ztis-agent-kyma-module). + - Your application has the [`SPIFFE_ENDPOINT_SOCKET` environment variable](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_Endpoint.md#4-locating-the-endpoint) set, pointing to the workload attestation API of the ZTIS agent. Head over to the [official documentation](https://pages.github.tools.sap/pse/pse-docs/docs/identity/), the [reference manual](https://github.tools.sap/pse/blueprints/blob/main/examples/cf/ZTIS_Reference.md) and [sample code](https://github.tools.sap/pse/blueprints/tree/main/examples/cf/java/ztis-identity/cf-manifest) to learn more about how to use ZTIS. @@ -185,26 +188,39 @@ To enable support by SAP Cloud SDK for certificates provided by ZTIS in your app ``` -With this dependency you can create a new or modify an existing `HttpDestination` to use the certificate provided by ZTIS. +### Integration with BTP Services + +The SAP Cloud SDK supports using certificates provided by ZTIS to authenticate to BTP services. +For example: + +- Identity Authentication Service (IAS) +- Authorization and Trust Management Service (XSUAA) +- Destination Service, Connectivity Service, ... + + +The SAP Cloud SDK automatically recognizes the credential type `X509_ATTESTED` and uses the certificates provided by ZTIS in that case. +Consequently, any BTP service supporting this credential type can be accessed using ZTIS. +For more details please refer to the documentation on [connecting to services](/docs/java/features/connectivity/service-bindings). + +### Connecting to other Systems using Destinations + +Aside from connecting to BTP services, you can also obtain or enhance any `HttpDestination` to use the certificate provided by ZTIS. ```java var ks = ZeroTrustIdentityService.getInstance().getOrCreateKeyStore(); +// create a new destination var newDestination = DefaultHttpDestination.builder("https://foo.com") .keyStore(ks) .build(); -var enhancedDestination = DefaultHttpDestination.fromDestination(DestinationAccessor.getDestination("myDestination")) + +// enhance an existing destination, e.g. from BTP destination service +var existingDestination = DestinationAccessor.getDestination("myDestination"); +var enhancedDestination = DefaultHttpDestination.fromDestination(existingDestination) .keyStore(ks) .build(); ``` -### Integration with Identity Authentication Service (IAS) - -The SAP Cloud SDK also supports using certificates provided by ZTIS to authenticate to the Identity Authentication Service (IAS). - -This works fully out of the box if you have an instance of IAS with the corresponding credential type `X509_ATTESTED` configured. -For more details please refer to the documentation on [connecting to services](/docs/java/features/connectivity/service-bindings). - ### Developing Locally On Cloud Foundry the `zero_trust_sidecar_buildpack` adds a sidecar to your application that fetches the certificates from ZTIS. From ba6ad842c3c18c28c9fefc368ca07cd968f5ab7e Mon Sep 17 00:00:00 2001 From: Matthias Kuhr Date: Tue, 28 Oct 2025 16:03:34 +0100 Subject: [PATCH 2/5] review dog fixes --- docs-java/features/connectivity/003-service-bindings.mdx | 8 ++++---- docs-java/features/connectivity/007-mtls.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs-java/features/connectivity/003-service-bindings.mdx b/docs-java/features/connectivity/003-service-bindings.mdx index 1dc633a4479..5e2ecf8066c 100644 --- a/docs-java/features/connectivity/003-service-bindings.mdx +++ b/docs-java/features/connectivity/003-service-bindings.mdx @@ -239,11 +239,11 @@ var options = ServiceBindingDestinationOptions .build(); ``` -In case the application URL, dependency name or other properties are dynamic or tenant-specific, you may want to use a BTP destination to hold this information. -Check the example below for how to combine BTP destinations with an IAS App2App flow. +In case the application URL, dependency name or other properties are dynamic or tenant-specific, you may want to use a SAP BTP destination to hold this information. +Check the example below for how to combine SAP BTP destinations with an IAS App2App flow.
-Example for an IAS-based App2App Flow using BTP Destinations +Example for an IAS-based App2App Flow using SAP BTP Destinations Define a destination in BTP cockpit and set the target system URL, a property to hold the App2App dependency name, as well as any further properties you might need for your use case (e.g. additional headers, query parameters, etc.). @@ -269,7 +269,7 @@ var opts = ServiceBindingDestinationOptions.forService(ServiceIdentifier.IDENTIT var destination = ServiceBindingDestinationLoader.defaultLoaderChain().getDestination(opts); ``` -Effectively, the destination from BTP destination service serves as a config map and has to be merged with the destination created locally for the App2App flow. +Effectively, the destination from SAP BTP destination service serves as a config map and has to be merged with the destination created locally for the App2App flow.
diff --git a/docs-java/features/connectivity/007-mtls.mdx b/docs-java/features/connectivity/007-mtls.mdx index e9e355489b8..7b21229469c 100644 --- a/docs-java/features/connectivity/007-mtls.mdx +++ b/docs-java/features/connectivity/007-mtls.mdx @@ -188,14 +188,14 @@ To enable support by SAP Cloud SDK for certificates provided by ZTIS in your app ``` -### Integration with BTP Services +### Integration with SAP BTP Services -The SAP Cloud SDK supports using certificates provided by ZTIS to authenticate to BTP services. +The SAP Cloud SDK supports using certificates provided by ZTIS to authenticate to SAP BTP services. For example: - Identity Authentication Service (IAS) - Authorization and Trust Management Service (XSUAA) -- Destination Service, Connectivity Service, ... +- Destination Service, Connectivity Service, etc. The SAP Cloud SDK automatically recognizes the credential type `X509_ATTESTED` and uses the certificates provided by ZTIS in that case. @@ -204,7 +204,7 @@ For more details please refer to the documentation on [connecting to services](/ ### Connecting to other Systems using Destinations -Aside from connecting to BTP services, you can also obtain or enhance any `HttpDestination` to use the certificate provided by ZTIS. +Aside from connecting to SAP BTP services, you can also obtain or enhance any `HttpDestination` to use the certificate provided by ZTIS. ```java var ks = ZeroTrustIdentityService.getInstance().getOrCreateKeyStore(); From dbd8d4d4a6ef517a2319c49c4bf1f6019a7c7b5c Mon Sep 17 00:00:00 2001 From: Matthias Kuhr Date: Tue, 28 Oct 2025 16:05:15 +0100 Subject: [PATCH 3/5] review dog fixes --- docs-java/features/connectivity/003-service-bindings.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-java/features/connectivity/003-service-bindings.mdx b/docs-java/features/connectivity/003-service-bindings.mdx index 5e2ecf8066c..10bcc3175f0 100644 --- a/docs-java/features/connectivity/003-service-bindings.mdx +++ b/docs-java/features/connectivity/003-service-bindings.mdx @@ -245,7 +245,7 @@ Check the example below for how to combine SAP BTP destinations with an IAS App2
Example for an IAS-based App2App Flow using SAP BTP Destinations -Define a destination in BTP cockpit and set the target system URL, a property to hold the App2App dependency name, as well as any further properties you might need for your use case (e.g. additional headers, query parameters, etc.). +Define a destination in SAP BTP cockpit and set the target system URL, a property to hold the App2App dependency name, as well as any further properties you might need for your use case (e.g. additional headers, query parameters, etc.). ```plaintext name: myDestination From 1169a02fc94e9a9cbdb3f6b00b2c7666c5a00c8b Mon Sep 17 00:00:00 2001 From: Matthias Kuhr Date: Tue, 28 Oct 2025 16:05:41 +0100 Subject: [PATCH 4/5] review dog fixes --- docs-java/features/connectivity/007-mtls.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-java/features/connectivity/007-mtls.mdx b/docs-java/features/connectivity/007-mtls.mdx index 7b21229469c..fe4f973b920 100644 --- a/docs-java/features/connectivity/007-mtls.mdx +++ b/docs-java/features/connectivity/007-mtls.mdx @@ -199,7 +199,7 @@ For example: The SAP Cloud SDK automatically recognizes the credential type `X509_ATTESTED` and uses the certificates provided by ZTIS in that case. -Consequently, any BTP service supporting this credential type can be accessed using ZTIS. +Consequently, any SAP BTP service supporting this credential type can be accessed using ZTIS. For more details please refer to the documentation on [connecting to services](/docs/java/features/connectivity/service-bindings). ### Connecting to other Systems using Destinations From d4ea8a2dbf57515d64c55d85edba45e166115fce Mon Sep 17 00:00:00 2001 From: Matthias Kuhr Date: Tue, 28 Oct 2025 16:07:42 +0100 Subject: [PATCH 5/5] formatting --- docs-java/features/connectivity/003-service-bindings.mdx | 8 ++++---- docs-java/features/connectivity/007-mtls.mdx | 9 ++++----- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs-java/features/connectivity/003-service-bindings.mdx b/docs-java/features/connectivity/003-service-bindings.mdx index 10bcc3175f0..aa075cb4d8f 100644 --- a/docs-java/features/connectivity/003-service-bindings.mdx +++ b/docs-java/features/connectivity/003-service-bindings.mdx @@ -56,10 +56,10 @@ Explore the [BtpServiceOptions](pathname:///java-api/v5/com/sap/cloud/sdk/cloudp The SAP Cloud SDK supports various credential types for XSUAA- and IAS-based services: -* Client secret (`instance-secret`, `binding-secret` (XSUAA) or `binding-secret` (IAS)) -* Client certificate - * Certificate generated by the platform, present in the binding (`x509` (XSUAA) or `X509_GENERATED` (IAS)) - * Certificate attested by the Zero Trust Identity Service (ZTIS) (`x509_attested` (XSUAA) or `X509_ATTESTED` (IAS)) +- Client secret (`instance-secret`, `binding-secret` (XSUAA) or `binding-secret` (IAS)) +- Client certificate + - Certificate generated by the platform, present in the binding (`x509` (XSUAA) or `X509_GENERATED` (IAS)) + - Certificate attested by the Zero Trust Identity Service (ZTIS) (`x509_attested` (XSUAA) or `X509_ATTESTED` (IAS)) If the service binding contains no explicit credential type, the SAP Cloud SDK defaults to using a client secret. The credential type `X509_PROVIDED` (IAS), as well as `x509` with a custom provided certificate (XSUAA), are currently not supported. diff --git a/docs-java/features/connectivity/007-mtls.mdx b/docs-java/features/connectivity/007-mtls.mdx index fe4f973b920..8b09b772e25 100644 --- a/docs-java/features/connectivity/007-mtls.mdx +++ b/docs-java/features/connectivity/007-mtls.mdx @@ -170,10 +170,10 @@ The following prerequisites are required to use ZTIS: - You have created a service instance of `zero-trust-identity`. - You have bound the ZTIS service instance to your application. - For Cloud Foundry: You have added the `zero_trust_sidecar_buildpack` as an additional buildpack for your application. -- For Kubernetes (Kyma, Gardener): - - You have installed the [ZTIS Operator](https://github.tools.sap/pse/ztis-operator?tab=readme-ov-file) in your cluster. - - On Kyma, this is available as the [ZTIS Agent Kyma Module](https://pages.github.tools.sap/pse/pse-docs/docs/identity-k8s/references/ztis-agent-kyma-module). - - Your application has the [`SPIFFE_ENDPOINT_SOCKET` environment variable](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_Endpoint.md#4-locating-the-endpoint) set, pointing to the workload attestation API of the ZTIS agent. +- For Kubernetes (Kyma, Gardener): + - You have installed the [ZTIS Operator](https://github.tools.sap/pse/ztis-operator?tab=readme-ov-file) in your cluster. + - On Kyma, this is available as the [ZTIS Agent Kyma Module](https://pages.github.tools.sap/pse/pse-docs/docs/identity-k8s/references/ztis-agent-kyma-module). + - Your application has the [`SPIFFE_ENDPOINT_SOCKET` environment variable](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_Endpoint.md#4-locating-the-endpoint) set, pointing to the workload attestation API of the ZTIS agent. Head over to the [official documentation](https://pages.github.tools.sap/pse/pse-docs/docs/identity/), the [reference manual](https://github.tools.sap/pse/blueprints/blob/main/examples/cf/ZTIS_Reference.md) and [sample code](https://github.tools.sap/pse/blueprints/tree/main/examples/cf/java/ztis-identity/cf-manifest) to learn more about how to use ZTIS. @@ -197,7 +197,6 @@ For example: - Authorization and Trust Management Service (XSUAA) - Destination Service, Connectivity Service, etc. - The SAP Cloud SDK automatically recognizes the credential type `X509_ATTESTED` and uses the certificates provided by ZTIS in that case. Consequently, any SAP BTP service supporting this credential type can be accessed using ZTIS. For more details please refer to the documentation on [connecting to services](/docs/java/features/connectivity/service-bindings).