diff --git a/docs-js/features/connectivity/destination.mdx b/docs-js/features/connectivity/destination.mdx index 9d89bcd198..7a30b67e6a 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.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. ```ts diff --git a/docs-js/features/connectivity/ias.mdx b/docs-js/features/connectivity/ias.mdx index d61e1e8815..4017d345ea 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,73 @@ 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 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. + +:::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) +// 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) +// 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' } + } +); +``` + +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.