Skip to content

Commit 1ea543b

Browse files
MatKuhrMatKuhr
authored
Updates to mTLS and bound services (#2291)
* Updates to mTLS and bound services * review dog fixes * review dog fixes * review dog fixes * formatting
1 parent 4048e70 commit 1ea543b

File tree

2 files changed

+90
-38
lines changed

2 files changed

+90
-38
lines changed

‎docs-java/features/connectivity/003-service-bindings.mdx‎

Lines changed: 61 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,25 @@ This is an example where the service offers multiple API endpoints and you need
5252

5353
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.
5454

55+
### Supported Credential Types
56+
57+
The SAP Cloud SDK supports various credential types for XSUAA- and IAS-based services:
58+
59+
- Client secret (`instance-secret`, `binding-secret` (XSUAA) or `binding-secret` (IAS))
60+
- Client certificate
61+
- Certificate generated by the platform, present in the binding (`x509` (XSUAA) or `X509_GENERATED` (IAS))
62+
- Certificate attested by the Zero Trust Identity Service (ZTIS) (`x509_attested` (XSUAA) or `X509_ATTESTED` (IAS))
63+
64+
If the service binding contains no explicit credential type, the SAP Cloud SDK defaults to using a client secret.
65+
The credential type `X509_PROVIDED` (IAS), as well as `x509` with a custom provided certificate (XSUAA), are currently not supported.
66+
67+
:::info ZTIS Integration
68+
69+
To use the `X509_ATTESTED` or `x509_attested` credential type, additional setup is required.
70+
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).
71+
72+
:::
73+
5574
### List of Supported Services
5675

5776
The SAP Cloud SDK supports a variety of services out of the box.
@@ -131,6 +150,14 @@ ServiceBindingDestinationOptions
131150
.build();
132151
```
133152

153+
:::note Principal Propagation with IAS
154+
155+
For IAS-based applications and services, principal propagation the grant type `jwt-bearer` needs to be enabled.
156+
This can be enabled in the IAS admin console, or by setting the `grant-types` parameter on the identity service instance.
157+
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).
158+
159+
:::
160+
134161
## Using the Extended Service for User and Account Authentication (XSUAA)
135162

136163
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
154181
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.
155182
Without the option specified in line 3, the destination would target the XSUAA instance itself.
156183

157-
:::note Principal Propagation with IAS
158-
159-
For IAS-based applications and services principal propagation requires additional configuration.
160-
When creating the IAS service binding an additional parameter needs to be passed to enable the `jwt-bearer` grant type.
161-
Refer to the documentation [here](https://github.wdf.sap.corp/CPSecurity/Knowledge-Base/blob/master/08_Tutorials/iasbroker/README.md#parameters) (SAP-internal).
162-
163-
:::
164-
165184
## Using the Identity and Authentication Service (IAS)
166185

167-
:::warning Beta API
168-
169-
The API for connecting to services secured by the SAP Identity and Authentication Service (IAS) is currently in beta and subject to change.
170-
171-
:::
172-
173186
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.
174187
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).
175188

176-
:::info Supported Credential Types
177-
178-
The SAP Cloud SDK supports the credential types `binding-secret`, `X509_GENERATED` and `X509_ATTESTED` for IAS service bindings.
179-
180-
If you want to use the `X509_ATTESTED` credential type, you need to add the `connectivity-ztis` dependency to your project.
181-
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).
182-
183-
The type `X509_PROVIDED` is currently not supported.
184-
:::
185-
186189
### Connecting to Services
187190

188191
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
236239
.build();
237240
```
238241

242+
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.
243+
Check the example below for how to combine SAP BTP destinations with an IAS App2App flow.
244+
245+
<details>
246+
<summary>Example for an IAS-based App2App Flow using SAP BTP Destinations</summary>
247+
248+
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.).
249+
250+
```plaintext
251+
name: myDestination
252+
url: https://my-target-system.com/api
253+
authenticationType: NoAuthentication
254+
myPropertyForApp2AppDependencyName: myApp2AppDependency
255+
```
256+
257+
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:
258+
259+
```java
260+
var btpDestination = DestinationAccessor.getDestination("myDestination");
261+
var dependency = btpDestination.get("myPropertyForApp2AppDependencyName", String.class).get();
262+
var uri = btpDestination.getUri();
263+
264+
var opts = ServiceBindingDestinationOptions.forService(ServiceIdentifier.IDENTITY_AUTHENTICATION)
265+
.withOption(BtpServiceOptions.IasOptions.withApplicationName(dependency))
266+
.withOption(BtpServiceOptions.IasOptions.withTargetUri(uri))
267+
.build();
268+
269+
var destination = ServiceBindingDestinationLoader.defaultLoaderChain().getDestination(opts);
270+
```
271+
272+
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.
273+
274+
</details>
275+
239276
### Calling Back Applications
240277

241278
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:

‎docs-java/features/connectivity/007-mtls.mdx‎

Lines changed: 29 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -166,11 +166,14 @@ This guide covers how you can configure and use the SAP Cloud SDK to use certifi
166166

167167
The following prerequisites are required to use ZTIS:
168168

169-
- You are deploying an application on Cloud Foundry
170-
- You have assigned the required entitlement for using ZTIS to your subaccount
171-
- You have created a service instance of `zero-trust-identity` in your Cloud Foundry space
172-
- You have bound the ZTIS service instance to your application
173-
- You have added the `zero_trust_sidecar_buildpack` as an additional buildpack for your application
169+
- You have assigned the required entitlement for using ZTIS to your subaccount.
170+
- You have created a service instance of `zero-trust-identity`.
171+
- You have bound the ZTIS service instance to your application.
172+
- For Cloud Foundry: You have added the `zero_trust_sidecar_buildpack` as an additional buildpack for your application.
173+
- For Kubernetes (Kyma, Gardener):
174+
- You have installed the [ZTIS Operator](https://github.tools.sap/pse/ztis-operator?tab=readme-ov-file) in your cluster.
175+
- 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).
176+
- 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.
174177

175178
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.
176179

@@ -185,26 +188,38 @@ To enable support by SAP Cloud SDK for certificates provided by ZTIS in your app
185188
</dependency>
186189
```
187190

188-
With this dependency you can create a new or modify an existing `HttpDestination` to use the certificate provided by ZTIS.
191+
### Integration with SAP BTP Services
192+
193+
The SAP Cloud SDK supports using certificates provided by ZTIS to authenticate to SAP BTP services.
194+
For example:
195+
196+
- Identity Authentication Service (IAS)
197+
- Authorization and Trust Management Service (XSUAA)
198+
- Destination Service, Connectivity Service, etc.
199+
200+
The SAP Cloud SDK automatically recognizes the credential type `X509_ATTESTED` and uses the certificates provided by ZTIS in that case.
201+
Consequently, any SAP BTP service supporting this credential type can be accessed using ZTIS.
202+
For more details please refer to the documentation on [connecting to services](/docs/java/features/connectivity/service-bindings).
203+
204+
### Connecting to other Systems using Destinations
205+
206+
Aside from connecting to SAP BTP services, you can also obtain or enhance any `HttpDestination` to use the certificate provided by ZTIS.
189207

190208
```java
191209
var ks = ZeroTrustIdentityService.getInstance().getOrCreateKeyStore();
192210

211+
// create a new destination
193212
var newDestination = DefaultHttpDestination.builder("https://foo.com")
194213
.keyStore(ks)
195214
.build();
196-
var enhancedDestination = DefaultHttpDestination.fromDestination(DestinationAccessor.getDestination("myDestination"))
215+
216+
// enhance an existing destination, e.g. from BTP destination service
217+
var existingDestination = DestinationAccessor.getDestination("myDestination");
218+
var enhancedDestination = DefaultHttpDestination.fromDestination(existingDestination)
197219
.keyStore(ks)
198220
.build();
199221
```
200222

201-
### Integration with Identity Authentication Service (IAS)
202-
203-
The SAP Cloud SDK also supports using certificates provided by ZTIS to authenticate to the Identity Authentication Service (IAS).
204-
205-
This works fully out of the box if you have an instance of IAS with the corresponding credential type `X509_ATTESTED` configured.
206-
For more details please refer to the documentation on [connecting to services](/docs/java/features/connectivity/service-bindings).
207-
208223
### Developing Locally
209224

210225
On Cloud Foundry the `zero_trust_sidecar_buildpack` adds a sidecar to your application that fetches the certificates from ZTIS.

0 commit comments

Comments
 (0)