Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs-js/features/connectivity/destination.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 `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.

```ts
Expand Down
80 changes: 74 additions & 6 deletions docs-js/features/connectivity/ias.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,14 @@ 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 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.

For IAS-specific convenience functions, see [Convenience Functions](#convenience-functions).

#### Technical User Authentication

For service-to-service communication with client credentials:
Expand Down Expand Up @@ -121,11 +123,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.
Expand Down Expand Up @@ -246,3 +243,74 @@ const destination = await getDestinationFromServiceBinding({
});
// Token request is automatically routed to the subscriber's IAS tenant
```

## Convenience Functions

The SAP Cloud SDK provides the following convenience functions for working with IAS tokens directly:

- [`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 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.

:::

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

:::

:::note

The `targetUrl` property is ignored if the `getTokenFromIasService()` function is used.

:::

```typescript
import {
createDestinationFromIasService,
getTokenFromIasService
} from '@sap-cloud-sdk/connectivity';

// 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 getTokenFromIasService() to retrieve an IAS token (business user)
const token = await getTokenFromIasService('identity', {
authenticationType: 'OAuth2JWTBearer',
assertion: JWT_ASSERTION,
resource: { name: 'backend-api' }
});
```

If the `VCAP_SERVICES` environment variable is not available (e.g. outside SAP BTP), pass service credentials directly instead:

```typescript
const destination = await createDestinationFromIasService(
{
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` value returned from the `createDestinationFromIasService()` function can be passed directly to any SAP Cloud SDK request builder or HTTP client.
Loading