Integration

Look who's calling. How to identify client in Integration Cell API

Jiri Fridrich

Recently I was building an API artifact on the Integration Cell runtime that should be consumed by several external partners. The goal was one URL for everybody, but each partner may only see its own data. To do that, the API needs to know who is calling.

My first idea: create a BTP service instance (SAP Process Integration Runtime, plan integration-flow), generate a service key per partner and read the caller from the header SapAuthenticatedUserName. It turned out this does not work in an API artifact. In this post I will show why, and how to identify the caller properly with OAuth and an external identity provider (SAP Identity Authentication Service, IAS).

I will not go into details how to build the API artifact. You can refer to this SAP blog to do so.

1. Why Basic Authentication does not tell you who is calling

There are two traps.

Trap 1: service keys share the client ID. All service keys created under one service instance have the same clientid. They differ only in the secret. So Partner A and Partner B look exactly the same to the runtime. If you want to distinguish them, you need a separate instance per partner, not a separate key.

Trap 2: the API artifact does not pass the identity to your logic. Even with a separate instance per partner, the caller’s identity does not reach your logic. The Authorization step in the API artifact swaps the client ID of the user for the client ID of the Destination used by the API artifact for the target call. Look for SapAuthenticatedUserName header in the call.

So with Basic authentication, or with OAuth tokens from BTP’s own authorization server (XSUAA, the default of an API artifact), you can control access with roles, but you cannot identify the partner inside the API artifact.

2. The solution: External OAuth (OIDC) with SAP IAS

The Authentication policy of the API artifact can validate tokens from an external OIDC identity provider. In this mode, the token is passed to the artifact as-is, and that is the key point. The token contains the claim azp with the client ID of the calling application, and we can read it.

The idea is:

  • every partner gets its own IAS application (own client ID = identity)

  • your API is represented by a provider application in IAS

  • partners get access to the API through an IAS dependency

3. IAS configuration

Step 3a: Provider application

In the IAS admin console go to Applications & Resources → Applications → Create. Name it, for example, Logistics-API, protocol OpenID Connect.

Provider application Logistics-API in IASLogistics-API application settings, protocol OpenID Connect

Under Application APIs → Provided APIs add an API, for example logistics_api. This is the permission we will check later in the API artifact.

Provided API logistics_apiClient ID of the Logistics-API application

Note down the Client ID of this application. We need it for the Audience.

Step 3b: Partner applications

Create one application per partner: Logistics-Partner-A, Logistics-Partner-B.

In each of them:

  • Trust → Client Authentication → Secrets → Add. For API Access select only OpenID, and set an expiry date rather than “Never”.

  • Application APIs → Dependencies → Add. Dependency name logistics-api-dependency, application Logistics-API, API logistics_api.

  • Note the Client ID - that is the identification of our partner, which we want to recognize in the integration.

Client ID of the Partner Test A applicationDependency logistics-api-dependency on Logistics-API

Note: all secrets of one IAS application share the same client ID, the same as BTP service keys. One application per partner is a must.

Step 3c: Getting the token

The partner requests the token with the client credentials grant:

POST https://<your-ias-tenant>.accounts.ondemand.com/oauth2/token?resource=urn:sap:identity:application:provider:name:logistics-api-dependency
Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Notice the resource parameter. It tells IAS that the token is meant for our provider application, and its last part is the Dependency Name from step 3b. In my tests, IAS ignored it when sent in the body, and it only worked as part of the URL. Without it you still get a token, but it is issued for the partner application itself and the API will reject it.

Note: the token URL is your IAS tenant (<tenant>.accounts.ondemand.com), not the authentication URL of your BTP subaccount (<subaccount>.authentication.<region>.hana.ondemand.com).

The decoded token then looks like this:

{
  "iss": "https://<your-ias-tenant>.accounts.ondemand.com",
  "aud": "66b0a908-88ed-4930-9b63-adcd00cddaaa",
  "azp": "b99423d8-a098-4435-b97e-1672ce18aadb",
  "ias_apis": ["logistics_api"],
  "sap_id_type": "app"
}

  • aud – the API Application client ID

  • azp – who is calling - the Partner A client ID

  • ias_apis – the partner has the permission

4. API artifact configuration

Create a new API artifact. Again, please refer to existing blogs to guide you through.

Note: a newly created API artifact uses the default XSUAA authentication. Until you switch it to External OAuth (OIDC) and redeploy, every IAS token ends with 401 invalidToken.

Authentication policy configuration

  • External OAuth (OIDC): checked

  • Configuration Type: Well-Known URL

  • Well-Known URL: https://<your-ias-tenant>.accounts.ondemand.com/.well-known/openid-configuration

  • Audience: <LOGISTICS-API-CLIENT-ID>

  • ClientID Key: ${authn.oidc.jwt.azp}

Authentication policy with External OAuth (OIDC)

The Audience is the client ID of the provider application Logistics-API, not the partner’s.

Note: once OIDC is active, Basic authentication, client certificates and XSUAA tokens no longer work on this artifact.

Authorization policy

  • Authorization Type: OAuth Scope

  • Scope Key: ias_apis

  • Scope: logistics_api

Authorization policy with Scope Key ias_apis

Note: the default Scope Key is scope, but the IAS token has no such claim. The granted APIs are in ias_apis. If you forget to change it, every call ends with 403 forbidden. The Scope value must match the Provided API name in IAS exactly.

Don’t forget to redeploy after every policy change.

Reading the caller in Groovy

After Authorization step we insert a Groovy script, which extracts azp value from the JWT token and exports it into a Header partnerClient. As it is a header value, it can be passed further to target iflow.

import groovy.json.JsonSlurper

def processData(message) {
    def headers = message.getHeaders()
    def auth = (headers.get("Authorization") ?: headers.get("authorization"))?.toString()
    if (!auth?.startsWith("Bearer ")) {
        throw new IllegalStateException("401: missing bearer token")
    }
    def payload = auth.substring(7).split("\\.")[1]
    def claims = new JsonSlurper().parseText(
        new String(Base64.getUrlDecoder().decode(payload), "UTF-8"))
    message.setHeader("partnerClient", claims.azp)
    return message
}

API artifact now looks like this

API artifact policy model with the Extract client ID script

Note: If we inserted this script later in the target iflow, the Authorization header would be already the one of the Destination, as described above. That's why it needs to be here in the API artifact already.

Note: The script always overwrites the header, so a value sent by the caller is discarded.

Create and deploy target iflow

API artifact is a proxy for the real iflow target in Cloud Foundry runtime. It is not really necessary for the demonstration in this blog to have it created, but at least your calls from HTTP client will not end up in HTTP/500 error. Nevertheless, it would be this target iflow, which could do the message routing based on the extracted client ID.

Warning: the target iflow trusts the partnerClient header only because no one else can call it. Give the destination its own service instance with a dedicated role and require that role in the iflow’s sender channel. Do not reuse a shared instance whose keys are spread across other integrations.

5. Calling the API and testing

Now let's test our API from Postman, Bruno or any other HTTP client. First obtain the token as described above (ie. you first call the IAS tenant) and with the token call the API artifact (classic 2-step OAuth sequence).

Check the trace

This screenshot is from the target iflow itself, where we can see the partnerclient header, carrying the ID of our partner, and the SapAuthenticatedUserName header, carrying the ID of the Destination, ie. the technical user with which our API authenticates against Cloud Foundry runtime.

Target iflow trace with the partnerclient and SapAuthenticatedUserName headers

Repeat with Partner B and you get a different value.

Note: see that the header changed from partnerClient to partnerclient. Integration Cell converted it to lowercase.

Negative tests

These prove the security works and help us better understand the principles.

  • Token without resource. aud is the partner app itself and ias_apis is missing, so the call is rejected by the Authentication or Authorization policy. You get 401.

  • Expired or random token. Also try to change one character in the token. You get 401.

From here it is just a mapping partnerClient → partner ID and filtering the data in the backend call.

Two more things I recommend:

  • Don't take the partner identity from a header the caller sends, like X-Partner-Id. The caller can put anything there, but doesn't have control over the token content. Tip: allow only relevant headers (Authorization, Content-type) in the API artifact runtime configuration.

  • Remove the Authorization header before calling the backend, so the partner’s token does not travel any further.

Summary

With OAuth tokens from an external IdP (SAP IAS), the API artifact receives the token as-is, and the claim azp tells you exactly which partner is calling. One URL serves all partners. Onboarding a new partner means a new IAS application, a secret and a dependency, and the API artifact does not change at all.

With Basic authentication (and BTP XSUAA tokens), the identity of the caller does not reach your logic in the API artifact. Do not build any partner logic on SapAuthenticatedUserName in an API artifact: it reflects the destination user, not the caller.

If OAuth is not an option for your partner, the alternative is a dedicated endpoint per partner:

  • a separate API artifact (or resource path) per partner, e.g. /logistics/partner-a, /logistics/partner-b

  • a separate BTP service instance per partner, each with its own role, and each endpoint requiring only that partner’s role

The role is checked before your logic runs, so whoever gets through /partner-a is Partner A. The price is one URL and one small artifact per partner.

To sum up the best practice: if you need to know who is calling an API artifact, go for OAuth with an external IdP. Keep Basic authentication with dedicated endpoints only for partners who cannot do OAuth.

SMARTER TECH, SMARTER BUSINESS

Cloud, AI and mates. Integration, development, automation and AI on SAP Business Technology Platform and Microsoft.

Write to us →

RESOURCES

© 2026 CLAIMATE · CLOUD · AI · MATES

SAP PartnerEdge · Microsoft Partner

SMARTER TECH, SMARTER BUSINESS

Cloud, AI and mates. Integration, development, automation and AI on SAP Business Technology Platform and Microsoft.

Write to us →

RESOURCES

© 2026 CLAIMATE · CLOUD · AI · MATES

SAP PartnerEdge · Microsoft Partner

SMARTER TECH, SMARTER BUSINESS

Cloud, AI and mates. Integration, development, automation and AI on SAP Business Technology Platform and Microsoft.

Write to us →

© 2026 CLAIMATE · CLOUD · AI · MATES

SAP PartnerEdge · Microsoft Partner

Integration

Look who's calling. How to identify client in Integration Cell API