From fdc2b5569a16ef945975a5d7e3e9d2c6c07e4836 Mon Sep 17 00:00:00 2001 From: David Knaack Date: Tue, 24 Mar 2026 09:38:18 +0100 Subject: [PATCH 1/4] 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/4] 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/4] 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/4] 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' } + } ); ```