From fdc2b5569a16ef945975a5d7e3e9d2c6c07e4836 Mon Sep 17 00:00:00 2001 From: David Knaack Date: Tue, 24 Mar 2026 09:38:18 +0100 Subject: [PATCH 1/6] chore: [js] Document IAS token and destination helper functions --- docs-js/features/connectivity/destination.mdx | 3 + docs-js/features/connectivity/ias.mdx | 71 +++++++++++++++++-- 2 files changed, 68 insertions(+), 6 deletions(-) diff --git a/docs-js/features/connectivity/destination.mdx b/docs-js/features/connectivity/destination.mdx index 9d89bcd198..973c103eff 100644 --- a/docs-js/features/connectivity/destination.mdx +++ b/docs-js/features/connectivity/destination.mdx @@ -275,6 +275,9 @@ Note, that if your `serviceBindingTransformFn()` function does not provide a nam More advanced examples with service token fetching can be found in [service-binding-to-destination.ts](https://github.com/SAP/cloud-sdk-js/blob/main/packages/connectivity/src/scp-cf/destination/service-binding-to-destination.ts). +For the `identity` service type, the SAP Cloud SDK also provides the standalone convenience functions `getIasToken()` and `getIasDestination()`, which can also work with bare `ServiceCredentials` outside of a `VCAP_SERVICES` binding. +See the [Identity Authentication Service](./ias#convenience-functions) documentation for details. + If you want to skip the destination lookup and consider only the service bindings, call the [getDestinationFromServiceBinding()](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) function with the service name and options. ```ts diff --git a/docs-js/features/connectivity/ias.mdx b/docs-js/features/connectivity/ias.mdx index d61e1e8815..953e0434bb 100644 --- a/docs-js/features/connectivity/ias.mdx +++ b/docs-js/features/connectivity/ias.mdx @@ -81,12 +81,16 @@ sequenceDiagram ### Creating Destinations -Use [`getDestinationFromServiceBinding()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) to connect to a system that is registered as an application within IAS. +Use [`getDestinationFromServiceBinding()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) or [`transformServiceBindingToDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.transformServiceBindingToDestination.html) to connect to a system that is registered as an application within IAS. The parameter `iasOptions` contains: - `targetUrl`: The URL of the system where the target application resides. - `resource`: The dependency identified by its name or identifier configured in IAS (see [App2App Resources](#app2app-resources)) section. +In addition to these standard functions for destination retrieval and transformation, the SAP Cloud SDK provides two convenience functions, [`getIasDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasDestination.html) and [`getIasToken()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasToken.html), which fetch an IAS token and return a destination or token result respectively. +These functions are useful when you need direct access to the IAS token or destination, for example outside SAP BTP environments with pre-populated `VCAP_SERVICES` or when constructing a destination manually. +Refer to the [Convenience Functions](#convenience-functions) section below for more details. + #### Technical User Authentication For service-to-service communication with client credentials: @@ -121,11 +125,6 @@ const destination = await getDestinationFromServiceBinding({ #### Business User Authentication -:::warning - -When using business user authentication, token requests are not cached. - -::: :::info Setting `authenticationType` to `OAuth2JWTBearer` is required to trigger Business User authentication. @@ -246,3 +245,63 @@ const destination = await getDestinationFromServiceBinding({ }); // Token request is automatically routed to the subscriber's IAS tenant ``` + +## Convenience Functions + +The SAP Cloud SDK provides two convenience functions for working with IAS tokens directly. +These are useful when you need access to the IAS token or destination, for example outside SAP BTP environments with pre-populated `VCAP_SERVICES` or when constructing a destination manually. + +Both functions accept a service as `Service | string | ServiceCredentials`, unlike `getDestinationFromServiceBinding()` they also accept bare `ServiceCredentials` (e.g., just `clientid`, `clientsecret`, and `url`). + +- **[`getIasDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasDestination.html)** fetches an IAS token and builds a ready-to-use [`Destination`](pathname:///api/v4/interfaces/sap-cloud-sdk_connectivity.Destination.html) with the token, the target URL, and the mTLS key pair from the service binding credentials (if present). +- **[`getIasToken()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasToken.html)** fetches an IAS token and returns an [`IasTokenResult`](pathname:///api/v4/interfaces/sap-cloud-sdk_connectivity.IasTokenResult.html) with the access token string, its expiration, and an optional refresh token. + +:::note + +`getIasToken()` returns the access token as a raw string rather than a decoded JWT, as IAS tokens may not always be in JWT format. + +::: + +:::note + +The `targetUrl` is ignored if `getIasToken()` is used. + +::: + +```typescript +import { getIasDestination, getIasToken } from '@sap-cloud-sdk/connectivity'; + +// Use getIasDestination() to build a destination (technical user) +const destination = await getIasDestination( + { + clientid: 'CLIENT_ID', + clientsecret: 'CLIENT_SECRET', + url: 'https://my-ias.accounts.ondemand.com' + }, + { + targetUrl: 'https://backend-provider.example.com', + jwt: JWT_PAYLOAD, + requestAs: 'current-tenant', + resource: { name: 'backend-api' } + } +); + +// Use getIasToken() to retrieve an IAS token (business user) +const token = await getIasToken( + { + clientid: 'CLIENT_ID', + clientsecret: 'CLIENT_SECRET', + url: 'https://my-ias.accounts.ondemand.com' + }, + { + authenticationType: 'OAuth2JWTBearer', + assertion: JWT_ASSERTION, + resource: { name: 'backend-api' } + } +); +``` + +The `Destination` returned by `getIasDestination()` can be passed directly to any SAP Cloud SDK request builder or HTTP client. + +For the full set of options both functions accept the same [`IasTokenOptions`](pathname:///api/v4/types/sap-cloud-sdk_connectivity.IasTokenOptions.html) which includes `iasOptions` properties as available in [`getDestinationFromServiceBinding()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) or [`transformServiceBindingToDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.transformServiceBindingToDestination.html). +See the [App2App Authentication](#app2app-authentication) section above for details. From d5367580d23da7cc7dfadeb4b6750d6ae794367d Mon Sep 17 00:00:00 2001 From: David Knaack Date: Tue, 24 Mar 2026 10:13:28 +0100 Subject: [PATCH 2/6] chore: fix link --- docs-js/features/connectivity/destination.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-js/features/connectivity/destination.mdx b/docs-js/features/connectivity/destination.mdx index 973c103eff..7a30b67e6a 100644 --- a/docs-js/features/connectivity/destination.mdx +++ b/docs-js/features/connectivity/destination.mdx @@ -276,7 +276,7 @@ Note, that if your `serviceBindingTransformFn()` function does not provide a nam More advanced examples with service token fetching can be found in [service-binding-to-destination.ts](https://github.com/SAP/cloud-sdk-js/blob/main/packages/connectivity/src/scp-cf/destination/service-binding-to-destination.ts). For the `identity` service type, the SAP Cloud SDK also provides the standalone convenience functions `getIasToken()` and `getIasDestination()`, which can also work with bare `ServiceCredentials` outside of a `VCAP_SERVICES` binding. -See the [Identity Authentication Service](./ias#convenience-functions) documentation for details. +See the [Identity Authentication Service](./ias.mdx#convenience-functions) documentation for details. If you want to skip the destination lookup and consider only the service bindings, call the [getDestinationFromServiceBinding()](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) function with the service name and options. From ff34af97a374e8efeaf33bf0aafddd9ee9aad2bd Mon Sep 17 00:00:00 2001 From: David Knaack Date: Wed, 25 Mar 2026 14:46:52 +0100 Subject: [PATCH 3/6] chore: update IAS helpers to document 'identity' as preferred service argument --- docs-js/features/connectivity/ias.mdx | 53 ++++++++++++++------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/docs-js/features/connectivity/ias.mdx b/docs-js/features/connectivity/ias.mdx index 953e0434bb..85e6b453db 100644 --- a/docs-js/features/connectivity/ias.mdx +++ b/docs-js/features/connectivity/ias.mdx @@ -251,7 +251,13 @@ const destination = await getDestinationFromServiceBinding({ The SAP Cloud SDK provides two convenience functions for working with IAS tokens directly. These are useful when you need access to the IAS token or destination, for example outside SAP BTP environments with pre-populated `VCAP_SERVICES` or when constructing a destination manually. -Both functions accept a service as `Service | string | ServiceCredentials`, unlike `getDestinationFromServiceBinding()` they also accept bare `ServiceCredentials` (e.g., just `clientid`, `clientsecret`, and `url`). +Both functions accept either the string `'identity'` (preferred, resolves the binding from `VCAP_SERVICES`) or bare `ServiceCredentials` (e.g., just `clientid`, `clientsecret`, and `url`). + +:::tip + +Pass `'identity'` whenever possible to let the SAP Cloud SDK resolve the IAS service binding from the environment, avoiding manual handling of credentials. + +::: - **[`getIasDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasDestination.html)** fetches an IAS token and builds a ready-to-use [`Destination`](pathname:///api/v4/interfaces/sap-cloud-sdk_connectivity.Destination.html) with the token, the target URL, and the mTLS key pair from the service binding credentials (if present). - **[`getIasToken()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasToken.html)** fetches an IAS token and returns an [`IasTokenResult`](pathname:///api/v4/interfaces/sap-cloud-sdk_connectivity.IasTokenResult.html) with the access token string, its expiration, and an optional refresh token. @@ -272,32 +278,29 @@ The `targetUrl` is ignored if `getIasToken()` is used. import { getIasDestination, getIasToken } from '@sap-cloud-sdk/connectivity'; // Use getIasDestination() to build a destination (technical user) -const destination = await getIasDestination( - { - clientid: 'CLIENT_ID', - clientsecret: 'CLIENT_SECRET', - url: 'https://my-ias.accounts.ondemand.com' - }, - { - targetUrl: 'https://backend-provider.example.com', - jwt: JWT_PAYLOAD, - requestAs: 'current-tenant', - resource: { name: 'backend-api' } - } -); +// Preferred: pass 'identity' to resolve the binding from VCAP_SERVICES +const destination = await getIasDestination('identity', { + targetUrl: 'https://backend-provider.example.com', + jwt: JWT_PAYLOAD, + requestAs: 'current-tenant', + resource: { name: 'backend-api' } +}); // Use getIasToken() to retrieve an IAS token (business user) -const token = await getIasToken( - { - clientid: 'CLIENT_ID', - clientsecret: 'CLIENT_SECRET', - url: 'https://my-ias.accounts.ondemand.com' - }, - { - authenticationType: 'OAuth2JWTBearer', - assertion: JWT_ASSERTION, - resource: { name: 'backend-api' } - } +// Preferred: pass 'identity' to resolve the binding from VCAP_SERVICES +const token = await getIasToken('identity', { + authenticationType: 'OAuth2JWTBearer', + assertion: JWT_ASSERTION, + resource: { name: 'backend-api' } +}); +``` + +If `VCAP_SERVICES` is not available (e.g. outside SAP BTP), pass `ServiceCredentials` directly instead: + +```typescript +const destination = await getIasDestination( + { clientid: 'CLIENT_ID', clientsecret: 'CLIENT_SECRET', url: 'https://my-ias.accounts.ondemand.com' }, + { targetUrl: 'https://backend-provider.example.com', resource: { name: 'backend-api' } } ); ``` From 17720f1a0ca5059d92323f83425651ce429cbaeb Mon Sep 17 00:00:00 2001 From: cloud-sdk-js Date: Thu, 26 Mar 2026 12:10:18 +0000 Subject: [PATCH 4/6] fix: Changes from lint --- docs-js/features/connectivity/ias.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs-js/features/connectivity/ias.mdx b/docs-js/features/connectivity/ias.mdx index 85e6b453db..4017d345ea 100644 --- a/docs-js/features/connectivity/ias.mdx +++ b/docs-js/features/connectivity/ias.mdx @@ -299,8 +299,15 @@ If `VCAP_SERVICES` is not available (e.g. outside SAP BTP), pass `ServiceCredent ```typescript const destination = await getIasDestination( - { clientid: 'CLIENT_ID', clientsecret: 'CLIENT_SECRET', url: 'https://my-ias.accounts.ondemand.com' }, - { targetUrl: 'https://backend-provider.example.com', resource: { name: 'backend-api' } } + { + clientid: 'CLIENT_ID', + clientsecret: 'CLIENT_SECRET', + url: 'https://my-ias.accounts.ondemand.com' + }, + { + targetUrl: 'https://backend-provider.example.com', + resource: { name: 'backend-api' } + } ); ``` From 6ac7072a5d1312d57d5bfa408fdc7a613fb4fdcb Mon Sep 17 00:00:00 2001 From: David Knaack Date: Thu, 7 May 2026 16:47:56 +0200 Subject: [PATCH 5/6] address review feedback --- docs-js/features/connectivity/destination.mdx | 2 +- docs-js/features/connectivity/ias.mdx | 47 +++++++++---------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/docs-js/features/connectivity/destination.mdx b/docs-js/features/connectivity/destination.mdx index 7a30b67e6a..b537611b0a 100644 --- a/docs-js/features/connectivity/destination.mdx +++ b/docs-js/features/connectivity/destination.mdx @@ -275,7 +275,7 @@ Note, that if your `serviceBindingTransformFn()` function does not provide a nam More advanced examples with service token fetching can be found in [service-binding-to-destination.ts](https://github.com/SAP/cloud-sdk-js/blob/main/packages/connectivity/src/scp-cf/destination/service-binding-to-destination.ts). -For the `identity` service type, the SAP Cloud SDK also provides the standalone convenience functions `getIasToken()` and `getIasDestination()`, which can also work with bare `ServiceCredentials` outside of a `VCAP_SERVICES` binding. +For the `identity` service type, the SAP Cloud SDK also provides the standalone convenience functions `getTokenFromIasService()` and `createDestinationFromIasService()`, which can also work with bare service credentials outside of a `VCAP_SERVICES` binding. See the [Identity Authentication Service](./ias.mdx#convenience-functions) documentation for details. If you want to skip the destination lookup and consider only the service bindings, call the [getDestinationFromServiceBinding()](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) function with the service name and options. diff --git a/docs-js/features/connectivity/ias.mdx b/docs-js/features/connectivity/ias.mdx index 4017d345ea..b21de15d4b 100644 --- a/docs-js/features/connectivity/ias.mdx +++ b/docs-js/features/connectivity/ias.mdx @@ -81,15 +81,13 @@ sequenceDiagram ### Creating Destinations -Use [`getDestinationFromServiceBinding()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) or [`transformServiceBindingToDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.transformServiceBindingToDestination.html) to connect to a system that is registered as an application within IAS. +Use [`getDestinationFromServiceBinding()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) or [`transformServiceBindingToDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.transformServiceBindingToDestination.html) to create a destination for a system that is registered as an application within IAS. The parameter `iasOptions` contains: - `targetUrl`: The URL of the system where the target application resides. - `resource`: The dependency identified by its name or identifier configured in IAS (see [App2App Resources](#app2app-resources)) section. -In addition to these standard functions for destination retrieval and transformation, the SAP Cloud SDK provides two convenience functions, [`getIasDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasDestination.html) and [`getIasToken()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasToken.html), which fetch an IAS token and return a destination or token result respectively. -These functions are useful when you need direct access to the IAS token or destination, for example outside SAP BTP environments with pre-populated `VCAP_SERVICES` or when constructing a destination manually. -Refer to the [Convenience Functions](#convenience-functions) section below for more details. +For IAS-specific convenience functions, see [Convenience Functions](#convenience-functions). #### Technical User Authentication @@ -248,57 +246,59 @@ const destination = await getDestinationFromServiceBinding({ ## Convenience Functions -The SAP Cloud SDK provides two convenience functions for working with IAS tokens directly. -These are useful when you need access to the IAS token or destination, for example outside SAP BTP environments with pre-populated `VCAP_SERVICES` or when constructing a destination manually. +The SAP Cloud SDK provides the following convenience functions for working with IAS tokens directly: -Both functions accept either the string `'identity'` (preferred, resolves the binding from `VCAP_SERVICES`) or bare `ServiceCredentials` (e.g., just `clientid`, `clientsecret`, and `url`). +- [`getTokenFromIasService()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getTokenFromIasService.html) fetches an IAS token. +- [`createDestinationFromIasService()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.createDestinationFromIasService.html) creates a destination with an IAS token. + +These are useful when you need access to the IAS token or service, for example outside SAP BTP environments with pre-populated `VCAP_SERVICES` environment variable or when constructing a destination manually. + +Both functions accept either the string `'identity'` (preferred, resolves the binding from `VCAP_SERVICES`) or bare service credentials, for example `clientid`, `clientsecret`, and `url`. + +The `targetUrl` option is only relevant for the `createDestinationFromIasService()` function. :::tip -Pass `'identity'` whenever possible to let the SAP Cloud SDK resolve the IAS service binding from the environment, avoiding manual handling of credentials. +Pass the string `'identity'` as the first argument whenever possible to let the SAP Cloud SDK resolve the IAS service binding from the environment, avoiding manual handling of credentials. ::: -- **[`getIasDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasDestination.html)** fetches an IAS token and builds a ready-to-use [`Destination`](pathname:///api/v4/interfaces/sap-cloud-sdk_connectivity.Destination.html) with the token, the target URL, and the mTLS key pair from the service binding credentials (if present). -- **[`getIasToken()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getIasToken.html)** fetches an IAS token and returns an [`IasTokenResult`](pathname:///api/v4/interfaces/sap-cloud-sdk_connectivity.IasTokenResult.html) with the access token string, its expiration, and an optional refresh token. :::note -`getIasToken()` returns the access token as a raw string rather than a decoded JWT, as IAS tokens may not always be in JWT format. +The `getTokenFromIasService()` function returns the access token as a raw string rather than a decoded JWT, as IAS tokens may not always be in JWT format. ::: :::note -The `targetUrl` is ignored if `getIasToken()` is used. +The `targetUrl` property is ignored if the `getTokenFromIasService()` function is used. ::: ```typescript -import { getIasDestination, getIasToken } from '@sap-cloud-sdk/connectivity'; +import { createDestinationFromIasService, getTokenFromIasService } from '@sap-cloud-sdk/connectivity'; -// Use getIasDestination() to build a destination (technical user) -// Preferred: pass 'identity' to resolve the binding from VCAP_SERVICES -const destination = await getIasDestination('identity', { +// Use createDestinationFromIasService() to build a destination (technical user) +const destination = await createDestinationFromIasService('identity', { targetUrl: 'https://backend-provider.example.com', jwt: JWT_PAYLOAD, requestAs: 'current-tenant', resource: { name: 'backend-api' } }); -// Use getIasToken() to retrieve an IAS token (business user) -// Preferred: pass 'identity' to resolve the binding from VCAP_SERVICES -const token = await getIasToken('identity', { +// Use getTokenFromIasService() to retrieve an IAS token (business user) +const token = await getTokenFromIasService('identity', { authenticationType: 'OAuth2JWTBearer', assertion: JWT_ASSERTION, resource: { name: 'backend-api' } }); ``` -If `VCAP_SERVICES` is not available (e.g. outside SAP BTP), pass `ServiceCredentials` directly instead: +If the `VCAP_SERVICES` environment variable is not available (e.g. outside SAP BTP), pass service credentials directly instead: ```typescript -const destination = await getIasDestination( +const destination = await createDestinationFromIasService( { clientid: 'CLIENT_ID', clientsecret: 'CLIENT_SECRET', @@ -311,7 +311,6 @@ const destination = await getIasDestination( ); ``` -The `Destination` returned by `getIasDestination()` can be passed directly to any SAP Cloud SDK request builder or HTTP client. +The `Destination` value returned from the `createDestinationFromIasService()` function can be passed directly to any SAP Cloud SDK request builder or HTTP client. + -For the full set of options both functions accept the same [`IasTokenOptions`](pathname:///api/v4/types/sap-cloud-sdk_connectivity.IasTokenOptions.html) which includes `iasOptions` properties as available in [`getDestinationFromServiceBinding()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.getDestinationFromServiceBinding.html) or [`transformServiceBindingToDestination()`](pathname:///api/v4/functions/sap-cloud-sdk_connectivity.transformServiceBindingToDestination.html). -See the [App2App Authentication](#app2app-authentication) section above for details. From 39aed0c5adf5fd59afc872f57920bb9687a7d59e Mon Sep 17 00:00:00 2001 From: "sap-cloud-sdk-bot[bot]" <274190970+sap-cloud-sdk-bot[bot]@users.noreply.github.com> Date: Thu, 7 May 2026 14:52:12 +0000 Subject: [PATCH 6/6] fix: Changes from lint --- docs-js/features/connectivity/ias.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs-js/features/connectivity/ias.mdx b/docs-js/features/connectivity/ias.mdx index b21de15d4b..1ea1e2eb74 100644 --- a/docs-js/features/connectivity/ias.mdx +++ b/docs-js/features/connectivity/ias.mdx @@ -263,7 +263,6 @@ Pass the string `'identity'` as the first argument whenever possible to let the ::: - :::note The `getTokenFromIasService()` function returns the access token as a raw string rather than a decoded JWT, as IAS tokens may not always be in JWT format. @@ -277,7 +276,10 @@ The `targetUrl` property is ignored if the `getTokenFromIasService()` function i ::: ```typescript -import { createDestinationFromIasService, getTokenFromIasService } from '@sap-cloud-sdk/connectivity'; +import { + createDestinationFromIasService, + getTokenFromIasService +} from '@sap-cloud-sdk/connectivity'; // Use createDestinationFromIasService() to build a destination (technical user) const destination = await createDestinationFromIasService('identity', { @@ -312,5 +314,3 @@ const destination = await createDestinationFromIasService( ``` The `Destination` value returned from the `createDestinationFromIasService()` function can be passed directly to any SAP Cloud SDK request builder or HTTP client. - -