diff --git a/docs-java/features/connectivity/003-service-bindings.mdx b/docs-java/features/connectivity/003-service-bindings.mdx index 80b38a0c27a..aa075cb4d8f 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 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 SAP BTP Destinations + +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 +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 SAP 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..8b09b772e25 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,38 @@ 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 SAP 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, 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). + +### Connecting to other Systems using Destinations + +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(); +// 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.