Skip to main content

Identity Authentication Service

warning

Only IAS App2App authentication is supported by the SAP Cloud SDK. Other scenarios such as App2Service are not fully supported yet.

The SAP Cloud SDK supports the Identity Authentication Service (IAS) for App2App authentication scenarios. In this scenario, a consumer application requests tokens scoped to specific provider applications through pre-configured dependencies in IAS.

App2App Authentication​

App2App authentication allows secure service-to-service communication where tokens are scoped to specific provider applications. The consumer and provider applications must have a pre-configured dependency relationship in IAS.

At runtime, the consumer requests a token using the resource parameter, which references the provider dependency. The IAS broker validates the relationship and issues a scoped token that only works for the specified provider.

Configuration​

note

The destination includes mtlsKeyPair with x509 credentials from the IAS service binding, if present. The SAP Cloud SDK uses these credentials for mTLS communication with the provider system.

The SAP Cloud SDK supports IAS service bindings with the following credential types:

  • X509_GENERATED: automatically generated X.509 certificates.
  • SECRET: client secret credentials.

Provider applications register a "provides" configuration on the IAS broker service, defining which APIs are exposed. Consumer applications create a service binding to IAS with dependencies on the required provider resources.

The dependency name configured in IAS is used as resource.name in the SAP Cloud SDK.

Creating Destinations​

Use getDestinationFromServiceBinding() or transformServiceBindingToDestination() 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) section.

For IAS-specific convenience functions, see Convenience Functions.

Technical User Authentication​

For service-to-service communication with client credentials:

import { getDestinationFromServiceBinding } from '@sap-cloud-sdk/connectivity';

const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  iasOptions: {
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' }
  }
});

For multi-tenant scenarios, see the Multi-Tenant Support section.

Technical user token requests will be cached by default. To disable caching, set the useCache option to false in the destination request:

const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  useCache: false,
  iasOptions: {
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' }
  }
});

Business User Authentication​

info

Setting authenticationType to OAuth2JWTBearer is required to trigger Business User authentication.

For user context propagation, provide the JWT and set the authentication type. When you provide a JWT to the function, it automatically uses it as the assertion for token exchange. This will happen when no explicit assertion is provided in iasOptions:

const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  jwt: userToken,
  iasOptions: {
    authenticationType: 'OAuth2JWTBearer',
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' }
    // assertion is automatically set to userToken
  }
});

Multi-tenant scenarios are supported as well, refer to the JWT-Based Tenant Extraction section for more details.

App2App Resources​

The IasResource type identifies provider dependencies configured in IAS. It can be specified by dependency name or provider client identifier:

type IasResource =
  | {
      name: string;
    }
  | {
      providerClientId: string;
      providerTenantId?: string;
    };

The name property refers to the dependency name configured in IAS and is the recommended way to identify resources. Alternatively, the providerClientId property can be used to specify the provider application's client identifier. Providing providerClientId grants access to all dependencies associated with that provider.

Multi-Tenant Support​

In multi-tenant scenarios, you can control the tenant context using the requestAs parameter or explicitly provide the tenant identifier.

Current Tenant and Provider Tenant options​

warning

The requestAs parameter only affects technical user authentication (client credentials flow).

The requestAs parameter determines which tenant (app_tid) context is used for the token request:

  • 'current-tenant' (default): Uses the tenant from the provided JWT (if any), otherwise falls back to the service binding credentials' app_tid
  • 'provider-tenant': Always uses the tenant from the service binding credentials
// Request as current tenant (uses JWT's app_tid)
const jwt = '<user-jwt>'; // Placeholder for user JWT
const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  jwt, // JWT's app_tid will be used
  iasOptions: {
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' },
    requestAs: 'current-tenant' // default
  }
});
// Request as provider tenant (uses service binding's app_tid)
const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  iasOptions: {
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' },
    requestAs: 'provider-tenant'
  }
});

Explicit Tenant Identifier​

For client credentials flows in multi-tenant scenarios, you can explicitly specify the consumer tenant identifier using appTid:

const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  iasOptions: {
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' },
    appTid: 'subscriber-tenant-id'
  }
});

JWT-Based Tenant Extraction​

When a JWT is supplied in the options, the SAP Cloud SDK automatically extracts the tenant information from the JWT assertion and routes token requests to the correct IAS tenant. JWT-Based tenant extraction is enabled for technical user authentication (OAuth2ClientCredentials) as the current tenant (default) and business user authentication (OAuth2JWTBearer):

const destination = await getDestinationFromServiceBinding({
  destinationName: 'my-identity-service',
  jwt: subscriberUserJwt,
  iasOptions: {
    authenticationType: 'OAuth2JWTBearer',
    targetUrl: 'https://backend-provider.example.com',
    resource: { name: 'backend-api' }
  }
});
// 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:

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 getIasToken() 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 getIasToken() function is used.

import {
  createDestinationFromIasService,
  getIasToken
} 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 getIasToken() to retrieve an IAS token (business user)
const token = await getIasToken('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:

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.