Demystifying the OAuth2 SAML Bearer Assertion usage in SAP Integration Suite

1. Introduction:

In the rapidly evolving landscape of enterprise integration, authentication and authorization are no longer mere checkpoints — they are the guardians of trust between systems. Within SAP Integration Suite, the OAuth 2.0 SAML Bearer Assertion & JWT Bearer grant types stand out as a powerful yet often less-understood mechanisms for secure API access, especially in hybrid enterprise landscapes where user identity is federated across multiple systems.

If you have ever stared at an urn:ietf:params:oauth:grant-type:saml2-bearer or urn:ietf:params:oauth:grant-type:jwt-bearer parameter as a supported grant type and wondered how this elegant string actually translates into a trusted access token, you are not alone. Many integration developers and security practitioners have encountered it — often through trial, error, and a bit of documentation spelunking.

In this article, we’ll go beyond the surface. We’ll explore:

What OAuth2.0 SAML Bearer Assertion is really doing under the hood — and why it exists in the first place.How this plays into SAP Integration Suite’s XSUAA and the broader BTP security model, particularly in securing IFlows and APIs within SAP Integration Suite.Practical configuration patterns and gotchas that can save you hours of troubleshooting.A few examples of exchanging a signed SAML assertion for an OAuth access token, demystifying the process step by step.

2. When is the OAuth2.0 SAML Bearer Assertion relevant for an Integration Developer?

Traditionally, most communication handled by Cloud Integration has been system-to-system, where a technical client or application authenticates itself, and the user context is irrelevant. In such scenarios, the Client Credentials grant type has been sufficient, since all that mattered was verifying that the calling system was trusted.

But this picture is evolving. Today, IFlows and APIs are two sides of the same coin: while IFlows orchestrate integration logic, APIs expose functionality that must often act on behalf of a specific user. Increasingly, organizations expect end-user identity and authorizations established in one system (e.g., via a corporate IdP or another SAP application) to be seamlessly propagated into Cloud Integration and carried forward all the way to the backend system.

This is exactly where the OAuth 2.0 SAML Bearer Assertion grant type becomes relevant. It provides a standards-based mechanism to exchange a trusted user identity assertion for an access token in Cloud Integration. That access token can then be forwarded downstream, ensuring that the original user’s context — along with their authorizations — is preserved across system boundaries.

For the integration developer, this means that Cloud Integration is no longer just a technical middleware layer. It becomes an active participant in identity propagation, enabling end-to-end security models that align with enterprise zero-trust principles and modern API-driven architectures.

📌To demonstrate the concepts required for achieving identity propagation, this article utilizes the SAP Cloud Connector, X.509 certificates, and backend configurations that I have already explained in detail in my earlier blog post on technical user propagation. While that post specifically focuses on technical user propagation, the configuration steps are not very different for the user propagation scenario described here. I therefore recommend that readers familiarize themselves with those concepts first, as they provide a solid foundation for this discussion.

📌One of the scenarios in this blog post will also refer back to the earlier article to highlight the applicability of the authorization code grant type in Cloud Integration—particularly when authorizing users from a corporate IdP such as Entra ID, using OpenID Connect–based federation in conjunction with SAP Cloud Identity Services (SAP IAS). For a broader perspective, I also suggest referring to my linked blog post, which explains single sign-on to SAP Cloud Integration runtime from an external application.

Taken together, these resources provide a complete 360-degree view of securing and implementing user-linked flows in SAP Integration Suite.

3. Full support for OAuth2.0 SAML Bearer Assertion in Cloud Integration

It is important to emphasize that SAP Cloud Integration fully supports the OAuth2 SAML Bearer Assertion flow both at the ‘sender’ and at the ‘receiver’ side.

On the inbound side, Cloud Integration can authenticate and authorize incoming requests based on the user’s identity, ensuring that calls made to IFlows are evaluated not just at the technical client level but also with the context of the end user. This enables developers to enforce fine-grained authorization rules and maintain auditability of user actions.
The following simplified illustration shows how OAuth2 SAML and JWT Bearer grants act as the enablers that make this flow possible.

You can specify these grant types while creating a service instance for the Process Integration Runtime.
Here’s an example snippet to create a service instance with the SAMLBearer and JWTBearer grant types On the outbound side, Cloud Integration can establish an OAuth2 SAML Bearer Assertion when calling downstream systems such as SAP SuccessFactors, SAP S/4HANA Cloud, S/4HANA On-Premise (wrapped under the familiar Principal Propagation pattern), etc.
Note: This capability is not new. Even in the days of Neo, Cloud Integration has supported the OAuth2 SAML Bearer flow for connecting to SAP SuccessFactors — both through technical credentials and via user-based assertions using an email identifier. The topic has been well covered in the community, including several blog posts authored by my colleague, Deepak Deshpande. (here and here)
Beyond this, any system within the BTP ecosystem that leverages the BTP Connectivity Service—including S/4HANA Cloud—can take part in the identity propagation chain. In the sections that follow, we will explore some of the possibilities this enables, such as chaining into another iFlow (within the same or a different subaccount) or invoking a service exposed through OData Provisioning.

This dual capability positions Cloud Integration as a true enabler of end-to-end user identity propagation, bridging the gap between modern identity-aware APIs and enterprise backend systems, while ensuring security models remain consistent across landscapes.

**4. Understanding the “SAML” in OAuth2 SAML Bearer Assertion**

The term OAuth2 SAML Bearer Assertion (RFC: RFC 7522) can often feel confusing at first glance, particularly with the placement of the word ‘SAML‘.

“Where is SAML in this picture?”, you may ask, as practitioners know for a fact that SAP BTP is based on OAuth2.0 and OIDC-based security standards. Let’s unpack this.

Fundamentally, classical Identity Providers (IdP) like Entra ID, SAP IAS, or corporate ADFS are designed to issue signed assertions asserting a user’s identity and attributes. These assertions are trusted pieces of information that downstream systems can use to authenticate a user without requiring them to re-enter credentials. In addition, in an enterprise integration landscape, the Identity Provider role is not limited to classical IdPs. Connectivity and middleware components themselves can also act as an Identity Provider and trusted issuers of SAML assertions. The process of SAML to OAuth2 token exchange sequence is as follows :

The SAML assertion issued by the assumed Identity Provider acts as a ‘credential wrapper‘ — it carries the authenticated user identity, roles, and authorizations.The Authorization Server (in BTP Integration Suite tenant, i.e., XSUAA) consumes this signed assertion and, if trusted and valid, exchanges it for an OAuth 2.0 access token, per the RFC spec (RFC 7522).This access token, representing the user identity, can then be presented to the target system, which, based on its security directive, can authenticate and authorize the identity from the token.

Let’s look at a few notable examples where this process is at play:

The classical approach to setting up a SAML trust between an Identity Provider and a Service Provider lends itself to setting up for the OAuth2 bearer exchange flow, particularly between Entra ID and SAP BTP, based on the ‘on-behalf-of‘ directive. Explained so elegantly in these two blog posts authored by Martin and Niklas, respectively, applicable for services secured by the BTP XSUAA Service.
Note that this classical ‘trust’ setup also equally applies between, say, Entra ID and SAP NetWeaver ABAP AS. Martin Pankraz and I demonstrated the setup in this blog post.SAP BTP Connectivity Service can generate signed SAML assertions when bridging secure connections to backend systems. For example, the BTP Destination type ‘OAuth2SAMLBearerAssertion‘ leverages this principal. See example below:
API Management’s gateway acts as an identity provider that injects a user’s authenticated identity into a signed assertion to downstream services. Customers frequently use policy templates like this one listed in the API Business Accelerator Hub.Cloud Integration itself uses the BTP Connectivity Services’ principles by providing out-of-the-box Security Materials that support OAuth2 SAML Bearer exchange. We’ll get to more of this bit in this very blog post.

This means that within the BTP ecosystem, the ability to mint a signed SAML assertion is not confined to a single component but distributed across the connectivity and security services that are orchestrating secure communication flows.

Put simply, the “SAML” in OAuth2 SAML Bearer Assertion is the trusted identity assertion format that enables one system to confidently vouch for a user’s identity to another. When combined with OAuth 2.0, it bridges the gap between user-centric authentication (SAML) and token-based authorization (OAuth).

On that note, you may have come across the OAuth2 JWT Bearer grant type as well. Let’s weave that into our context.

5. The OAuth2 JWT Bearer grant type

While the OAuth2 SAML Bearer grant type leverages a SAML 2.0 assertion to obtain an access token, its close cousin — the OAuth2 JWT Bearer grant type — follows a similar token exchange pattern but uses a signed JSON Web Token (JWT) instead of SAML. In the context of SAP BTP XSUAA, the JWT Bearer flow is often chosen when the identity assertion is already in JWT format, such as when integrating with systems that natively issue JWTs (e.g., other BTP applications, certain identity providers, or trusted microservices).

However, for the purposes of this article, we will not be focusing on the JWT Bearer approach. The reason is that SAP Cloud Integration only partially supports it — JWT Bearer can be used when authenticating inbound requests to an iFlow, but it is not available as a selectable option in the “Security Material” when making outbound calls from Cloud Integration to a target system. As such, its utility is currently more limited in end-to-end integration scenarios compared to the SAML Bearer flow.

6. Configurations needed to achieve OAuth2 SAML Bearer exchange

Since we are on the topic of the role of Identity Providers (actual or assumed) during an OAuth2 SAML Bearer handshake, let us weave in the role of the Trust Configuration setting in the BTP Cockpit — a subject that is often less understood in the context of SAP Integration Suite.

Why is this less understood?

In BTP landscapes, the Trust Configuration in the cockpit is primarily associated with browser-based BTP applications that require coupling between an Identity Provider (IdP) (such as SAP IAS or a corporate IdP) and the Service Provider (SP) role of the application. This trust relationship governs how users log in interactively to applications and how their identities are federated.

This implies that at the design time (UI) level, configuring the Trust relationship ensures that developers and administrators can access the Integration Suite tools via their corporate IDP.

However, customers often struggle to apply the same concept when it comes to the runtime — where iFlows and APIs need to be authenticated and authorized via user identities. This is precisely where dialing in the correct runtime configurations for OAuth2 SAML Bearer exchange becomes critical.

To keep this practical, let’s break the discussion into multiple scenarios and examine the configurations required for each. Here is a table that captures the different scenarios covered in this blog post :

Scenario 1 [INBOUND] Invoking an IFlow via BTP Destination / Connectivity ServiceScenario 2 variant 1

Scenario 1 + [OUTBOUND] Using Security Material to make an outbound OAuth2 SAML Bearer call

Scenario 2 variant 2 Authorization Code grant type + [OUTBOUND] Using Security Material to make an outbound OAuth2 SAML Bearer call

6.1. Scenario 1: [INBOUND] Invoking an IFlow via a BTP Destination:

There are use cases where a Fiori/UI5 application deployed on BTP uses a destination to call an IFlow, ensuring the user’s identity (via OAuth2 SAML Bearer) is securely propagated into the integration layer. Similarly, SAP Build Process Automation can leverage destinations in its Actions framework to trigger IFlows as part of an automated workflow, often requiring identity propagation so that downstream systems know which user initiated the process. Beyond these, other scenarios include SAP Work Zone or SAP Launchpad extensions invoking integration services, as well as custom applications running in the Cloud Foundry runtime consuming iFlows via destinations.

In practice, customers often face challenges in identifying the correct configurations to make this scenario work. Below is a detailed cluster of the configurations involved.

OAuth token endpoint address: Customers often assume the default ‘…/oauth/token‘ endpoint applies universally, but this is not the case. OAuthSAMLBearer looks for the ‘…/oauth/token/alias/‘ endpoint. Exchange of trust between subaccounts where the services reside.Implicit trust within the same subaccount: Even if both services are in the same subaccount, an implicit trust relationship must still be established. This small step can save hours of troubleshooting.BTP Destination and Integration Flow settings to support OAuth2 SAML Bearer handshake.A quick walkthrough of the SAP Business Application Studio template wizard building blocks, enabling an SAP Fiori application to validate everything completed so far.

Here is a solution blueprint of what we will put together:

Let’s review these configurations step by step.

1. OAuth token alias endpoint.

Step No

Description

Screenshot

1.Download the ‘SAML Metadata‘ from the ‘Trust Configuration‘ section of your BTP Cockpit2.Locate and copy the value of the ‘entityID‘ element from the downloaded XML file3.

Locate and copy the ‘Location‘ element. There are multiple attributes present; make sure you copy the one that contains the ‘…/oauth/token/alias/…‘ URL pattern.

This will be the token endpoint we will use in subsequent configuration screens.

2. & 3. Exchange of Trust between subaccount / Implicit trust within the same subaccount.

Follow the instructions in this BTP help guide: construct the EntityDescriptor metadata exactly as specified and upload it as Trusted Metadata in your target subaccount—namely, the subaccount hosting the Integration Suite.

Step No.

Description

Screenshot

Identify your source and target subaccounts, and carefully construct the EntityDescriptor snippet using the settings provided in the User Propagation between Cloud Foundry Applications guide.

💡Note: As mentioned earlier, this step is required even if the source and target services reside within the same BTP subaccount. In such cases, the configuration establishes a self-trust relationship.

2.Go to the Destination Trust section in your BTP Cockpit of the source subaccount and import the Active Trust Certificate. In addition, follow the recommended best practices to set up a Passive Trust Certificate as well, ensuring a smooth switchover and preventing disruptions when the active certificate approaches expiry.3.Here is a snapshot of the EntityDescriptor file taken from my account configuration.4.

Upload the prepared file by clicking on the ‘New SAML Trust Configuration‘ button in your target subaccount.

💡Disable the Available for User Logon and Create Shadow User options. Disabling the latter ensures that only pre-onboarded users are propagated, which is more secure than allowing all users to be automatically created and propagated.

5.Because we disabled shadow user creation, go to the Users section and explicitly create the users that need to be propagated. 6.Once the user has been created, we still need to ensure that the necessary roles and scopes from the source token are available for propagation. There are two ways to achieve this. The simplest approach is to assign the newly created user to a Role Collection that includes the MessagingSend role.7. Rather than explicitly assigning individual users to a role collection, a more elegant approach is to map a group from the identity provider to the desired role collection. This ensures that the corresponding scopes from the original token are automatically granted to the user principal in the target token as well.

4. BTP Destination and IFlow settings:

Step No.

Description

Screenshot

1.Create a service instance of the Process Integration Runtime, selecting only the saml2-bearer grant type. This configuration strengthens IFlow security by preventing the use of other grant types (such as client credentials or password).2.

Make sure to create a BTP Destination in the ‘source’ subaccount (i.e., the subaccount that hosts the client app). I’ve highlighted the key settings.

URL – The target IFlow’s runtime host alias.
Audience – the entityID captured in step 6.1.1.2.
Token Service URL – the ‘/oauth/token/alias‘ endpoint as explained above.
includeAttributes = true. This is needed to support the Identity Provider group assignment demonstrated in step 6.1.2.7.
nameIDFromat = ‘urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress’ to support the propagation of email address

To demonstrate an end-to-end flow, I’ve created an IFlow that uses an OData V2 adapter at both the Sender and Receiver. This approach was chosen because SAP Business Application Studio makes it straightforward to build a Fiori app that consumes an OData service.

This first variant of the receiver adapter connects to an S/4HANA On-premise backend using principal propagation. It demonstrates how an inbound OAuth2 SAML Bearer assertion grant type carries the full user context, which can then be propagated downstream.

4.The second receiver adapter variant connects to an S/4HANA Cloud system using OAuth2 SAML Bearer security material. While we will cover this approach in the next scenario, the detailed configuration within the S/4HANA backend lies outside the scope of this blog post.5.To test the settings, let’s shift focus to SAP Business Application Studio (BAS) in the source subaccount, where we’ll build a small app that connects through the BTP Destination to the IFlow running in the target subaccount, using the OAuth2 SAML Bearer bridge. Note that we are using the BAS only as a means to simulate the user login experience.6.If you encounter an error code 500 and notice no entries showing that the IFlow was invoked (for example, in the HTTP Access Log), it most likely indicates that the token exchange failed. In this case, review the configuration steps carefully to ensure accuracy.7.

When all configurations are correctly set, the Next button becomes enabled. This confirms that the system successfully retrieved the OData metadata by querying the backend through the configured destination type. In the Application Wizard template block’s Output console, you can see the call dispatched to the Integration Flow, which can also be verified in the Message Processing Logs (MPL)

While this successfully concludes our demonstration, feel free to complete the Wizard and run/deploy the generated application to see the end-to-end response light up.

✅This completes one successful round-trip.

6.2. Scenario 2: [OUTBOUND] Using Security Material to make an outbound OAuth2 SAML Bearer call

As described in section 3.b.2, we will now focus on leveraging Cloud Integration’s capability to use the generic OAuth2 SAML Bearer security material, rather than the ones targeting SuccessFactors, as they are already well covered in the community.

One might ask: how do we set up an environment that makes it simple to simulate and test the user flow? The good news is that Scenario 1 has already given us the user interaction layer. All we need to do now is chain the IFlow we created earlier with another one, letting the outbound of the first serve as the inbound of the second. This allows us to validate the flow end-to-end in both directions.

To keep the discourse engaging, we will explore yet another variant for testing the outbound OAuth2 SAML Bearer setup. Here, we’ll use Cloud Integration’s capability to trigger an Authorization Code grant type exchange, simulating a real user login, and then build on that to invoke the OAuth2 SAML Bearer method.

6.2.1. Scenario 2 – Variant 1:
Here’s the solution blueprint of the first variant, where we extend scenario 1 and chain an intermediate IFlow with the main IFlow.

The sequence of events from the client to Business Application Studio follows the same pattern as in Scenario 1. The difference here is that instead of directly calling the main IFlow, we have intentionally introduced an intermediate IFlow (step callout 1 in the blueprint above), which is configured with OAuth2 SAML Bearer security material to eventually connect with the main IFlow. Since the main IFlow accepts only the OAuth2 SAML grant type (step callout 2), this setup allows the connection to be seamlessly extended to the backend using Principal Propagation.

Regardless of whether the intermediate and main IFlows are in the same or separate subaccounts, a SAML trust between the source and target is mandatory, as highlighted in Procedure 2 of Scenario 1.

Let’s take a look at the key configuration steps:

Step No.

Description

Screenshot

1.Notice that I’ve created a metadata called ‘self-trust‘ with the entityDescriptor for the subaccount. In my case, both the intermediate and main IFlow are on the same Integration Suite tenant, hence the ‘self’ trust.2.Create a security material of type OAuth2 SAML Bearer. Set the target system type as ‘SAP BTP (CF)‘. For the attributes, use the same settings as the ones we used in step 6.1.4.2 of the previous scenario. 3.💡You may notice that under the hood, this internally generates a BTP Destination in the subaccount with OAuth2SAMLBearer.4.Notice the change here on the IFlow we built in scenario 1 (step 3 of 6.1.4). Instead of directly calling the backend URL, we have turned this into an Intermediate IFlow that chains into the final main IFlow, with the authentication set to the OAuth2 SAML Bearer security material created in step 2.4.As you can verify in the screenshot, the main IFlow is the one that invokes the backend with principal propagation.5.Let’s go back to the app we built in scenario 1 and refresh the page. We should see the UI populate with the expected recordset after successfully negotiating the flows across the chained intermediate and main IFlows all the way to the backend.6. As a confirmation step, look up the activity in the message processing logs (MPL) section, and you will see that both the intermediate and final IFlows were executed and in the right sequence.

6.2.2. Scenario 2 – Variant 2:
Rather than using Business Application Studio as the user-centric app to trigger the intermediate IFlow, we will instead leverage the Authorization Code grant type. From a technical perspective, the Authorization Code flow differs from the OAuth2 SAML Bearer grant; however, in principle, both achieve the same outcome: propagating a user session within an OAuth access token.

This raises the question—how do we introduce the Authorization Code grant flow?

Cloud Integration natively supports the Authorization Code grant type as security material. While it was originally introduced to support adapters such as Dropbox and Microsoft 365, which rely on this flow, we can extend its utility further. By attaching this security material to any outbound call through the HTTP Receiver adapter—and applying a small amount of scripting (see step 6.2.2.3)—we can retrieve an access token from the authorization code using the SecureStoreService API.

Here is a solution blueprint of what we aim to achieve:
For simplicity, a timer-based IFlow will initiate an outbound call to the intermediate IFlow, attaching an access token extracted from the security material (constructed via the authorization code exchange) that represents an authenticated user. This user may either be provisioned through the default Cloud Identity Service or authenticated via a corporate IdP such as Entra ID, as outlined in one of my earlier blog posts. The interaction sequence between the intermediate IFlow and the final IFlow remains unchanged.

6.2.2.1 First, let’s go over the configuration steps to establish the authorization code:

Step No.

Description

Screenshot

1.In your source subaccount, create a new OAuth2 Authorization Code security material. During setup, a Redirect URL will be generated—make sure to note this URL, as it will be required in the next step when configuring a service key with the Authorization Code grant type.2.In the BTP Cockpit, when creating a new instance of the Process Integration Runtime service, select both the Refresh Token and Authorization Code grant types. Then, paste the Redirect URL captured in Step 1 into the Redirect URI field.3.After creating the service key, make sure to note the client credentials, along with the authorization and token URL endpoints, as these will be required in a later step.4.

Go back to the security material creation screen and enter the parameters copied from the previous step.

You may specify a user name for the user entity you want to create, but this value will be overridden by the actual user identity provided during browser logon step.

5.After the security material is created, click on the ‘Authorize‘ button under the … column. This will kick off the authorization code flow process in a new browser window. and will present the auth code to the specified redirect_uri. 6.You will be asked to authenticate yourself to an identity provider of your choosing, depending on the IDP settings as enabled in BTP’s ‘Trust Configuration’. Note that I’ll be authenticating into SAP Identity Service, which in turn is configured to federate with multiple corporate IDPs via OIDC settings, as explained in my linked blog.7.I’m being led into authenticating against Entra ID and my *.outlook.com email is being propagated as the authenticated user context into Cloud Integration.8.

After successfully logging the user in, the browser redirects to the specified ‘redirect_uri’ with the negotiated ‘code‘.

✅This completes our authentication process.

6.2.2.2 Next step, let’s review the time-triggered IFlow that kicks off the entire process. The first sequence in the flow is a ‘timer’ step. To keep things simple, it just triggers off upon deployment.

6.2.2.3. In the second step, we add a Groovy script that taps into the SecureStoreService API to read the Authorization Code security material defined in the previous step. The script then exchanges the authorization code with the token endpoint to fetch a valid access token.

import com.sap.gateway.ip.core.customdev.util.Message
import com.sap.it.api.securestore.SecureStoreService
import com.sap.it.api.ITApiFactory

def Message processData(Message message) {

// Name of your OAuth2 Authorization Code credential (as defined in Security Material)
def credentialName = “auth-code-demo”

// Get an instance of SecureStoreService
def secureStoreService = ITApiFactory.getApi(SecureStoreService.class, null)

if (secureStoreService == null) {
throw new IllegalStateException(“SecureStoreService not available”)
}

// Fetch the access token
def tokenResponse = secureStoreService.getAccesTokenForOauth2AuthorizationCodeCredential(credentialName)

if (tokenResponse == null) {
throw new IllegalStateException(“Failed to retrieve access token for credential: ${credentialName}”)
}

// Extract access token string
def accessToken = tokenResponse.getAccessToken()

// Optional: log for debug (mask in production!)
//messageLogFactory.getMessageLog(message).addAttachmentAsString(“OAuth2 Access Token”, accessToken, “text/plain”)

// Store token in message header for downstream adapters
message.setHeader(“Authorization”, “Bearer ” + accessToken)

return message
}

6.2.2.4 The third step in the sequence is to call the OData entity set through the intermediate IFlow. Note that the authorization setting is explicitly configured as None, since the bearer token is already applied in the preceding Groovy script step. Also, do note that the intermediate IFlow eventually calls the final IFlow, as we studied in step 4 of 6.2.1.

6.2.2.5 The final step in the sequence is to log the response returned after the final IFlow executes, which is handled by a simple Groovy script.

6.2.2.6. After triggering the process, you can verify the outcome in the Message Processing Logs (MPL). You should see an entry in the Completed state, with the Attachments section containing a text representation of the backend response.

🏆Congratulations on reaching this stage!

Closing summary:

In this blog, we explored how OAuth2 SAML Bearer assertion support in SAP Cloud Integration serves as a powerful mechanism for securing IFlows and APIs. By leveraging trust configurations, user propagation, and the integration of identity providers, we demonstrated how this grant type enables secure end-to-end flows while maintaining user context. Along the way, we also highlighted related patterns—such as the use of Authorization Code grant type in specific scenarios—and showed how these capabilities extend the flexibility of SAP Integration Suite when working with corporate identity providers and SAP Cloud Identity Services.

As integration landscapes continue to evolve, adopting OAuth2 SAML Bearer assertion not only strengthens security but also ensures compliance with modern identity federation standards. With the concepts and examples covered here, you now have a foundation to design flows that are both secure and user-aware—critical ingredients for enterprise-grade integrations.

1. Introduction:In the rapidly evolving landscape of enterprise integration, authentication and authorization are no longer mere checkpoints — they are the guardians of trust between systems. Within SAP Integration Suite, the OAuth 2.0 SAML Bearer Assertion & JWT Bearer grant types stand out as a powerful yet often less-understood mechanisms for secure API access, especially in hybrid enterprise landscapes where user identity is federated across multiple systems.If you have ever stared at an urn:ietf:params:oauth:grant-type:saml2-bearer or urn:ietf:params:oauth:grant-type:jwt-bearer parameter as a supported grant type and wondered how this elegant string actually translates into a trusted access token, you are not alone. Many integration developers and security practitioners have encountered it — often through trial, error, and a bit of documentation spelunking.In this article, we’ll go beyond the surface. We’ll explore:What OAuth2.0 SAML Bearer Assertion is really doing under the hood — and why it exists in the first place.How this plays into SAP Integration Suite’s XSUAA and the broader BTP security model, particularly in securing IFlows and APIs within SAP Integration Suite.Practical configuration patterns and gotchas that can save you hours of troubleshooting.A few examples of exchanging a signed SAML assertion for an OAuth access token, demystifying the process step by step.2. When is the OAuth2.0 SAML Bearer Assertion relevant for an Integration Developer?Traditionally, most communication handled by Cloud Integration has been system-to-system, where a technical client or application authenticates itself, and the user context is irrelevant. In such scenarios, the Client Credentials grant type has been sufficient, since all that mattered was verifying that the calling system was trusted.But this picture is evolving. Today, IFlows and APIs are two sides of the same coin: while IFlows orchestrate integration logic, APIs expose functionality that must often act on behalf of a specific user. Increasingly, organizations expect end-user identity and authorizations established in one system (e.g., via a corporate IdP or another SAP application) to be seamlessly propagated into Cloud Integration and carried forward all the way to the backend system.This is exactly where the OAuth 2.0 SAML Bearer Assertion grant type becomes relevant. It provides a standards-based mechanism to exchange a trusted user identity assertion for an access token in Cloud Integration. That access token can then be forwarded downstream, ensuring that the original user’s context — along with their authorizations — is preserved across system boundaries.For the integration developer, this means that Cloud Integration is no longer just a technical middleware layer. It becomes an active participant in identity propagation, enabling end-to-end security models that align with enterprise zero-trust principles and modern API-driven architectures.📌To demonstrate the concepts required for achieving identity propagation, this article utilizes the SAP Cloud Connector, X.509 certificates, and backend configurations that I have already explained in detail in my earlier blog post on technical user propagation. While that post specifically focuses on technical user propagation, the configuration steps are not very different for the user propagation scenario described here. I therefore recommend that readers familiarize themselves with those concepts first, as they provide a solid foundation for this discussion.📌One of the scenarios in this blog post will also refer back to the earlier article to highlight the applicability of the authorization code grant type in Cloud Integration—particularly when authorizing users from a corporate IdP such as Entra ID, using OpenID Connect–based federation in conjunction with SAP Cloud Identity Services (SAP IAS). For a broader perspective, I also suggest referring to my linked blog post, which explains single sign-on to SAP Cloud Integration runtime from an external application.Taken together, these resources provide a complete 360-degree view of securing and implementing user-linked flows in SAP Integration Suite.3. Full support for OAuth2.0 SAML Bearer Assertion in Cloud IntegrationIt is important to emphasize that SAP Cloud Integration fully supports the OAuth2 SAML Bearer Assertion flow both at the ‘sender’ and at the ‘receiver’ side.On the inbound side, Cloud Integration can authenticate and authorize incoming requests based on the user’s identity, ensuring that calls made to IFlows are evaluated not just at the technical client level but also with the context of the end user. This enables developers to enforce fine-grained authorization rules and maintain auditability of user actions. The following simplified illustration shows how OAuth2 SAML and JWT Bearer grants act as the enablers that make this flow possible.You can specify these grant types while creating a service instance for the Process Integration Runtime.Here’s an example snippet to create a service instance with the SAMLBearer and JWTBearer grant types On the outbound side, Cloud Integration can establish an OAuth2 SAML Bearer Assertion when calling downstream systems such as SAP SuccessFactors, SAP S/4HANA Cloud, S/4HANA On-Premise (wrapped under the familiar Principal Propagation pattern), etc.Note: This capability is not new. Even in the days of Neo, Cloud Integration has supported the OAuth2 SAML Bearer flow for connecting to SAP SuccessFactors — both through technical credentials and via user-based assertions using an email identifier. The topic has been well covered in the community, including several blog posts authored by my colleague, Deepak Deshpande. (here and here)Beyond this, any system within the BTP ecosystem that leverages the BTP Connectivity Service—including S/4HANA Cloud—can take part in the identity propagation chain. In the sections that follow, we will explore some of the possibilities this enables, such as chaining into another iFlow (within the same or a different subaccount) or invoking a service exposed through OData Provisioning.This dual capability positions Cloud Integration as a true enabler of end-to-end user identity propagation, bridging the gap between modern identity-aware APIs and enterprise backend systems, while ensuring security models remain consistent across landscapes.4. Understanding the “SAML” in OAuth2 SAML Bearer AssertionThe term OAuth2 SAML Bearer Assertion (RFC: RFC 7522) can often feel confusing at first glance, particularly with the placement of the word ‘SAML’.”Where is SAML in this picture?”, you may ask, as practitioners know for a fact that SAP BTP is based on OAuth2.0 and OIDC-based security standards. Let’s unpack this.Fundamentally, classical Identity Providers (IdP) like Entra ID, SAP IAS, or corporate ADFS are designed to issue signed assertions asserting a user’s identity and attributes. These assertions are trusted pieces of information that downstream systems can use to authenticate a user without requiring them to re-enter credentials. In addition, in an enterprise integration landscape, the Identity Provider role is not limited to classical IdPs. Connectivity and middleware components themselves can also act as an Identity Provider and trusted issuers of SAML assertions. The process of SAML to OAuth2 token exchange sequence is as follows :The SAML assertion issued by the assumed Identity Provider acts as a ‘credential wrapper’ — it carries the authenticated user identity, roles, and authorizations.The Authorization Server (in BTP Integration Suite tenant, i.e., XSUAA) consumes this signed assertion and, if trusted and valid, exchanges it for an OAuth 2.0 access token, per the RFC spec (RFC 7522).This access token, representing the user identity, can then be presented to the target system, which, based on its security directive, can authenticate and authorize the identity from the token.Let’s look at a few notable examples where this process is at play:The classical approach to setting up a SAML trust between an Identity Provider and a Service Provider lends itself to setting up for the OAuth2 bearer exchange flow, particularly between Entra ID and SAP BTP, based on the ‘on-behalf-of’ directive. Explained so elegantly in these two blog posts authored by Martin and Niklas, respectively, applicable for services secured by the BTP XSUAA Service.Note that this classical ‘trust’ setup also equally applies between, say, Entra ID and SAP NetWeaver ABAP AS. Martin Pankraz and I demonstrated the setup in this blog post.SAP BTP Connectivity Service can generate signed SAML assertions when bridging secure connections to backend systems. For example, the BTP Destination type ‘OAuth2SAMLBearerAssertion’ leverages this principal. See example below: API Management’s gateway acts as an identity provider that injects a user’s authenticated identity into a signed assertion to downstream services. Customers frequently use policy templates like this one listed in the API Business Accelerator Hub.Cloud Integration itself uses the BTP Connectivity Services’ principles by providing out-of-the-box Security Materials that support OAuth2 SAML Bearer exchange. We’ll get to more of this bit in this very blog post. This means that within the BTP ecosystem, the ability to mint a signed SAML assertion is not confined to a single component but distributed across the connectivity and security services that are orchestrating secure communication flows.Put simply, the “SAML” in OAuth2 SAML Bearer Assertion is the trusted identity assertion format that enables one system to confidently vouch for a user’s identity to another. When combined with OAuth 2.0, it bridges the gap between user-centric authentication (SAML) and token-based authorization (OAuth).On that note, you may have come across the OAuth2 JWT Bearer grant type as well. Let’s weave that into our context.5. The OAuth2 JWT Bearer grant typeWhile the OAuth2 SAML Bearer grant type leverages a SAML 2.0 assertion to obtain an access token, its close cousin — the OAuth2 JWT Bearer grant type — follows a similar token exchange pattern but uses a signed JSON Web Token (JWT) instead of SAML. In the context of SAP BTP XSUAA, the JWT Bearer flow is often chosen when the identity assertion is already in JWT format, such as when integrating with systems that natively issue JWTs (e.g., other BTP applications, certain identity providers, or trusted microservices).However, for the purposes of this article, we will not be focusing on the JWT Bearer approach. The reason is that SAP Cloud Integration only partially supports it — JWT Bearer can be used when authenticating inbound requests to an iFlow, but it is not available as a selectable option in the “Security Material” when making outbound calls from Cloud Integration to a target system. As such, its utility is currently more limited in end-to-end integration scenarios compared to the SAML Bearer flow.6. Configurations needed to achieve OAuth2 SAML Bearer exchangeSince we are on the topic of the role of Identity Providers (actual or assumed) during an OAuth2 SAML Bearer handshake, let us weave in the role of the Trust Configuration setting in the BTP Cockpit — a subject that is often less understood in the context of SAP Integration Suite.Why is this less understood?In BTP landscapes, the Trust Configuration in the cockpit is primarily associated with browser-based BTP applications that require coupling between an Identity Provider (IdP) (such as SAP IAS or a corporate IdP) and the Service Provider (SP) role of the application. This trust relationship governs how users log in interactively to applications and how their identities are federated.This implies that at the design time (UI) level, configuring the Trust relationship ensures that developers and administrators can access the Integration Suite tools via their corporate IDP.However, customers often struggle to apply the same concept when it comes to the runtime — where iFlows and APIs need to be authenticated and authorized via user identities. This is precisely where dialing in the correct runtime configurations for OAuth2 SAML Bearer exchange becomes critical.To keep this practical, let’s break the discussion into multiple scenarios and examine the configurations required for each. Here is a table that captures the different scenarios covered in this blog post :Scenario 1 [INBOUND] Invoking an IFlow via BTP Destination / Connectivity ServiceScenario 2 variant 1Scenario 1 + [OUTBOUND] Using Security Material to make an outbound OAuth2 SAML Bearer callScenario 2 variant 2 Authorization Code grant type + [OUTBOUND] Using Security Material to make an outbound OAuth2 SAML Bearer call6.1. Scenario 1: [INBOUND] Invoking an IFlow via a BTP Destination:There are use cases where a Fiori/UI5 application deployed on BTP uses a destination to call an IFlow, ensuring the user’s identity (via OAuth2 SAML Bearer) is securely propagated into the integration layer. Similarly, SAP Build Process Automation can leverage destinations in its Actions framework to trigger IFlows as part of an automated workflow, often requiring identity propagation so that downstream systems know which user initiated the process. Beyond these, other scenarios include SAP Work Zone or SAP Launchpad extensions invoking integration services, as well as custom applications running in the Cloud Foundry runtime consuming iFlows via destinations.In practice, customers often face challenges in identifying the correct configurations to make this scenario work. Below is a detailed cluster of the configurations involved.OAuth token endpoint address: Customers often assume the default ‘…/oauth/token’ endpoint applies universally, but this is not the case. OAuthSAMLBearer looks for the ‘…/oauth/token/alias/’ endpoint. Exchange of trust between subaccounts where the services reside.Implicit trust within the same subaccount: Even if both services are in the same subaccount, an implicit trust relationship must still be established. This small step can save hours of troubleshooting.BTP Destination and Integration Flow settings to support OAuth2 SAML Bearer handshake.A quick walkthrough of the SAP Business Application Studio template wizard building blocks, enabling an SAP Fiori application to validate everything completed so far.Here is a solution blueprint of what we will put together:Let’s review these configurations step by step.1. OAuth token alias endpoint.Step NoDescriptionScreenshot1.Download the ‘SAML Metadata’ from the ‘Trust Configuration’ section of your BTP Cockpit2.Locate and copy the value of the ‘entityID’ element from the downloaded XML file3.Locate and copy the ‘Location’ element. There are multiple attributes present; make sure you copy the one that contains the ‘…/oauth/token/alias/…’ URL pattern.This will be the token endpoint we will use in subsequent configuration screens. 2. & 3. Exchange of Trust between subaccount / Implicit trust within the same subaccount.Follow the instructions in this BTP help guide: construct the EntityDescriptor metadata exactly as specified and upload it as Trusted Metadata in your target subaccount—namely, the subaccount hosting the Integration Suite.Step No.DescriptionScreenshot1Identify your source and target subaccounts, and carefully construct the EntityDescriptor snippet using the settings provided in the User Propagation between Cloud Foundry Applications guide.💡Note: As mentioned earlier, this step is required even if the source and target services reside within the same BTP subaccount. In such cases, the configuration establishes a self-trust relationship.2.Go to the Destination Trust section in your BTP Cockpit of the source subaccount and import the Active Trust Certificate. In addition, follow the recommended best practices to set up a Passive Trust Certificate as well, ensuring a smooth switchover and preventing disruptions when the active certificate approaches expiry.3.Here is a snapshot of the EntityDescriptor file taken from my account configuration.4.Upload the prepared file by clicking on the ‘New SAML Trust Configuration’ button in your target subaccount.💡Disable the Available for User Logon and Create Shadow User options. Disabling the latter ensures that only pre-onboarded users are propagated, which is more secure than allowing all users to be automatically created and propagated.5.Because we disabled shadow user creation, go to the Users section and explicitly create the users that need to be propagated. 6.Once the user has been created, we still need to ensure that the necessary roles and scopes from the source token are available for propagation. There are two ways to achieve this. The simplest approach is to assign the newly created user to a Role Collection that includes the MessagingSend role.7. Rather than explicitly assigning individual users to a role collection, a more elegant approach is to map a group from the identity provider to the desired role collection. This ensures that the corresponding scopes from the original token are automatically granted to the user principal in the target token as well.4. BTP Destination and IFlow settings:Step No.DescriptionScreenshot1.Create a service instance of the Process Integration Runtime, selecting only the saml2-bearer grant type. This configuration strengthens IFlow security by preventing the use of other grant types (such as client credentials or password).2. Make sure to create a BTP Destination in the ‘source’ subaccount (i.e., the subaccount that hosts the client app). I’ve highlighted the key settings. URL – The target IFlow’s runtime host alias.Audience – the entityID captured in step 6.1.1.2.Token Service URL – the ‘/oauth/token/alias’ endpoint as explained above.includeAttributes = true. This is needed to support the Identity Provider group assignment demonstrated in step 6.1.2.7.nameIDFromat = ‘urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress’ to support the propagation of email address3. To demonstrate an end-to-end flow, I’ve created an IFlow that uses an OData V2 adapter at both the Sender and Receiver. This approach was chosen because SAP Business Application Studio makes it straightforward to build a Fiori app that consumes an OData service.This first variant of the receiver adapter connects to an S/4HANA On-premise backend using principal propagation. It demonstrates how an inbound OAuth2 SAML Bearer assertion grant type carries the full user context, which can then be propagated downstream.4.The second receiver adapter variant connects to an S/4HANA Cloud system using OAuth2 SAML Bearer security material. While we will cover this approach in the next scenario, the detailed configuration within the S/4HANA backend lies outside the scope of this blog post.5.To test the settings, let’s shift focus to SAP Business Application Studio (BAS) in the source subaccount, where we’ll build a small app that connects through the BTP Destination to the IFlow running in the target subaccount, using the OAuth2 SAML Bearer bridge. Note that we are using the BAS only as a means to simulate the user login experience.6.If you encounter an error code 500 and notice no entries showing that the IFlow was invoked (for example, in the HTTP Access Log), it most likely indicates that the token exchange failed. In this case, review the configuration steps carefully to ensure accuracy.7.When all configurations are correctly set, the Next button becomes enabled. This confirms that the system successfully retrieved the OData metadata by querying the backend through the configured destination type. In the Application Wizard template block’s Output console, you can see the call dispatched to the Integration Flow, which can also be verified in the Message Processing Logs (MPL) 8.While this successfully concludes our demonstration, feel free to complete the Wizard and run/deploy the generated application to see the end-to-end response light up.✅This completes one successful round-trip. 6.2. Scenario 2: [OUTBOUND] Using Security Material to make an outbound OAuth2 SAML Bearer callAs described in section 3.b.2, we will now focus on leveraging Cloud Integration’s capability to use the generic OAuth2 SAML Bearer security material, rather than the ones targeting SuccessFactors, as they are already well covered in the community.One might ask: how do we set up an environment that makes it simple to simulate and test the user flow? The good news is that Scenario 1 has already given us the user interaction layer. All we need to do now is chain the IFlow we created earlier with another one, letting the outbound of the first serve as the inbound of the second. This allows us to validate the flow end-to-end in both directions.To keep the discourse engaging, we will explore yet another variant for testing the outbound OAuth2 SAML Bearer setup. Here, we’ll use Cloud Integration’s capability to trigger an Authorization Code grant type exchange, simulating a real user login, and then build on that to invoke the OAuth2 SAML Bearer method.6.2.1. Scenario 2 – Variant 1:Here’s the solution blueprint of the first variant, where we extend scenario 1 and chain an intermediate IFlow with the main IFlow.The sequence of events from the client to Business Application Studio follows the same pattern as in Scenario 1. The difference here is that instead of directly calling the main IFlow, we have intentionally introduced an intermediate IFlow (step callout 1 in the blueprint above), which is configured with OAuth2 SAML Bearer security material to eventually connect with the main IFlow. Since the main IFlow accepts only the OAuth2 SAML grant type (step callout 2), this setup allows the connection to be seamlessly extended to the backend using Principal Propagation.Regardless of whether the intermediate and main IFlows are in the same or separate subaccounts, a SAML trust between the source and target is mandatory, as highlighted in Procedure 2 of Scenario 1.Let’s take a look at the key configuration steps:Step No.DescriptionScreenshot1.Notice that I’ve created a metadata called ‘self-trust’ with the entityDescriptor for the subaccount. In my case, both the intermediate and main IFlow are on the same Integration Suite tenant, hence the ‘self’ trust.2.Create a security material of type OAuth2 SAML Bearer. Set the target system type as ‘SAP BTP (CF)’. For the attributes, use the same settings as the ones we used in step 6.1.4.2 of the previous scenario. 3.💡You may notice that under the hood, this internally generates a BTP Destination in the subaccount with OAuth2SAMLBearer.4.Notice the change here on the IFlow we built in scenario 1 (step 3 of 6.1.4). Instead of directly calling the backend URL, we have turned this into an Intermediate IFlow that chains into the final main IFlow, with the authentication set to the OAuth2 SAML Bearer security material created in step 2.4.As you can verify in the screenshot, the main IFlow is the one that invokes the backend with principal propagation.5.Let’s go back to the app we built in scenario 1 and refresh the page. We should see the UI populate with the expected recordset after successfully negotiating the flows across the chained intermediate and main IFlows all the way to the backend.6. As a confirmation step, look up the activity in the message processing logs (MPL) section, and you will see that both the intermediate and final IFlows were executed and in the right sequence. 6.2.2. Scenario 2 – Variant 2: Rather than using Business Application Studio as the user-centric app to trigger the intermediate IFlow, we will instead leverage the Authorization Code grant type. From a technical perspective, the Authorization Code flow differs from the OAuth2 SAML Bearer grant; however, in principle, both achieve the same outcome: propagating a user session within an OAuth access token.This raises the question—how do we introduce the Authorization Code grant flow? Cloud Integration natively supports the Authorization Code grant type as security material. While it was originally introduced to support adapters such as Dropbox and Microsoft 365, which rely on this flow, we can extend its utility further. By attaching this security material to any outbound call through the HTTP Receiver adapter—and applying a small amount of scripting (see step 6.2.2.3)—we can retrieve an access token from the authorization code using the SecureStoreService API.Here is a solution blueprint of what we aim to achieve:For simplicity, a timer-based IFlow will initiate an outbound call to the intermediate IFlow, attaching an access token extracted from the security material (constructed via the authorization code exchange) that represents an authenticated user. This user may either be provisioned through the default Cloud Identity Service or authenticated via a corporate IdP such as Entra ID, as outlined in one of my earlier blog posts. The interaction sequence between the intermediate IFlow and the final IFlow remains unchanged.6.2.2.1 First, let’s go over the configuration steps to establish the authorization code:Step No.DescriptionScreenshot1.In your source subaccount, create a new OAuth2 Authorization Code security material. During setup, a Redirect URL will be generated—make sure to note this URL, as it will be required in the next step when configuring a service key with the Authorization Code grant type.2.In the BTP Cockpit, when creating a new instance of the Process Integration Runtime service, select both the Refresh Token and Authorization Code grant types. Then, paste the Redirect URL captured in Step 1 into the Redirect URI field.3.After creating the service key, make sure to note the client credentials, along with the authorization and token URL endpoints, as these will be required in a later step.4.Go back to the security material creation screen and enter the parameters copied from the previous step.You may specify a user name for the user entity you want to create, but this value will be overridden by the actual user identity provided during browser logon step.5.After the security material is created, click on the ‘Authorize’ button under the … column. This will kick off the authorization code flow process in a new browser window. and will present the auth code to the specified redirect_uri. 6.You will be asked to authenticate yourself to an identity provider of your choosing, depending on the IDP settings as enabled in BTP’s ‘Trust Configuration’. Note that I’ll be authenticating into SAP Identity Service, which in turn is configured to federate with multiple corporate IDPs via OIDC settings, as explained in my linked blog.7.I’m being led into authenticating against Entra ID and my *.outlook.com email is being propagated as the authenticated user context into Cloud Integration.8.After successfully logging the user in, the browser redirects to the specified ‘redirect_uri’ with the negotiated ‘code’.✅This completes our authentication process.6.2.2.2 Next step, let’s review the time-triggered IFlow that kicks off the entire process. The first sequence in the flow is a ‘timer’ step. To keep things simple, it just triggers off upon deployment.6.2.2.3. In the second step, we add a Groovy script that taps into the SecureStoreService API to read the Authorization Code security material defined in the previous step. The script then exchanges the authorization code with the token endpoint to fetch a valid access token.import com.sap.gateway.ip.core.customdev.util.Message
import com.sap.it.api.securestore.SecureStoreService
import com.sap.it.api.ITApiFactory