Skip to content

Principal Propagation Setup

Authenticate each MCP user to SAP with their own identity via BTP Destination Service and Cloud Connector. No shared SAP passwords. Full per-user audit trail.

When to Use

  • Enterprise environments requiring per-user SAP authorization
  • Compliance/audit requirements (who did what in SAP)
  • When different users should have different SAP permissions
  • Zero shared credentials architecture

Architecture

MCP Client (JWT)
  │
  ▼
ARC-1 (/mcp)
  │  validates JWT (OIDC or XSUAA)
  │  passes X-User-Token to Destination Service
  ▼
BTP Destination Service
  │  resolves per-user destination (PrincipalPropagation type)
  ▼
Connectivity Proxy
  │
  ▼
Cloud Connector
  │  propagates user identity via client certificate
  ▼
SAP ICM
  │  CERTRULE / VUSREXTID maps certificate to SAP user
  ▼
SAP user session (per-user)

Prerequisites

  • JWT-based MCP auth working (OIDC setup or XSUAA setup)
  • ARC-1 deployed on BTP Cloud Foundry
  • Destination + Connectivity service instances bound to ARC-1 app
  • Cloud Connector connected to your BTP subaccount
  • SAP system reachable from Cloud Connector

Step 1: Create Two BTP Destinations

Create a dual-destination setup in BTP Cockpit (Connectivity → Destinations):

Shared destination (fallback)

Property Value
Name SAP_TRIAL (your choice)
Type HTTP
URL http://<sap-host>:<sap-port>
Authentication BasicAuthentication
User Technical SAP user
Password Technical SAP password

Per-user destination (principal propagation)

Property Value
Name SAP_TRIAL_PP (your choice)
Type HTTP
URL http://<sap-host>:<sap-port>
Authentication PrincipalPropagation

Step 2: Configure Cloud Connector

  1. Open Cloud Connector Admin UI
  2. Add the SAP system mapping (Cloud to On-Premise → Add)
  3. Enable Principal Propagation in the access control for the mapping
  4. Configure the system certificate for signing principal propagation certificates

Required Cloud Connector Resource Paths

If you use restrictive Cloud Connector resource whitelisting, expose at least these paths:

URL Path Access Policy Purpose
/sap/bc/adt Path and all sub-paths ADT API used by ARC-1 core read/write operations
/sap/opu/odata/UI2/PAGE_BUILDER_CUST Path and all sub-paths FLP launchpad management via SAPManage FLP actions
/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV Path and all sub-paths UI5 ABAP Repository OData (BSP deploy metadata)

The trial setup guide uses / (all paths), which implicitly includes these routes. For production, explicit path allowlists are recommended for defense in depth.

Step 3: Configure SAP System

The SAP system must trust Cloud Connector's certificates and map them to SAP users.

Certificate trust (STRUST)

  1. Import the Cloud Connector system certificate into STRUST (SSL Server Standard PSE → Certificate List)

Certificate mapping (CERTRULE or VUSREXTID)

Configure how the certificate's subject is mapped to a SAP user:

  • CERTRULE (transaction /nCERTRULE): Rule-based mapping (e.g., Subject CN → SAP User ID)
  • VUSREXTID (table VUSREXTID via SM30): Explicit user-to-certificate subject mapping

ICM parameters

Verify these profile parameters (transaction /nRZ10):

Parameter Value Purpose
icm/HTTPS/verify_client 1 Accept client certificates
login/certificate_mapping_rulebased 1 Enable CERTRULE mapping

Step 4: Configure ARC-1

export SAP_BTP_DESTINATION=SAP_TRIAL
export SAP_BTP_PP_DESTINATION=SAP_TRIAL_PP
export SAP_PP_ENABLED=true
export SAP_PP_STRICT=true

Behavior

  • JWT request → ARC-1 uses the per-user destination (SAP_BTP_PP_DESTINATION), passing the JWT as X-User-Token
  • PP failure + SAP_PP_STRICT=false (default) → falls back to shared destination
  • PP failure + SAP_PP_STRICT=true → returns error, no fallback
  • API key / non-JWT request → uses shared destination

Set SAP_PP_STRICT=true on any multi-user instance

With the default SAP_PP_STRICT=false, a per-user PP failure (destination error, missing CERTRULE mapping, untrusted JWT issuer) silently falls back to the shared service account. The request then runs with the technical user's full authorizations and SAP audits it as that technical user — not the real caller. An attacker who can force PP to fail escalates to the shared account and defeats the per-user audit trail this setup exists to provide. Keep the fallback only for mixed API-key deployments; for a per-user instance set SAP_PP_STRICT=true.

Flag Env Var Default Description
--pp-enabled SAP_PP_ENABLED false Enable principal propagation
--pp-strict SAP_PP_STRICT false Fail on PP errors (no fallback)
--pp-allow-shared-cookies SAP_PP_ALLOW_SHARED_COOKIES false Escape hatch — allow cookies to coexist with PP (cookies stay on shared client only)
— SAP_BTP_DESTINATION — Shared (fallback) destination name
— SAP_BTP_PP_DESTINATION — Per-user PP destination name

Auth safety (SEC-09): ARC-1 fails fast at startup if SAP_PP_ENABLED=true is combined with SAP_COOKIE_FILE / SAP_COOKIE_STRING — per-user sessions must not inherit a shared cookie. Set SAP_PP_ALLOW_SHARED_COOKIES=true only if you accept that the cookie stays on the shared-fallback client. Per-user auth never inherits shared Basic/cookie credentials. See Coexistence Matrix.

Step 5: Test

  1. Check logs after a JWT-authenticated request: 

    cf logs arc1-mcp-server --recent | grep -E "Principal propagation|per-user|BTP destination"

  2. Check SAP for per-user identity:

  3. Transaction SM20 (security audit log) — verify the individual SAP user appears
  4. Transaction SM04 (user sessions) — check for per-user sessions

Troubleshooting

PP always falls back to shared user

  1. Verify SAP_PP_ENABLED=true is set
  2. Verify SAP_BTP_PP_DESTINATION authentication type is PrincipalPropagation in BTP Cockpit
  3. Check Cloud Connector logs for principal propagation errors
  4. Verify the JWT contains a valid user identity

SAP returns 401 for propagated user

  1. Check STRUST: Is the Cloud Connector system cert in the certificate list?
  2. Check ICM: Is icm/HTTPS/verify_client = 1?
  3. Check certificate mapping: Does CERTRULE or VUSREXTID map the certificate subject to a valid SAP user?
  4. Check user exists: Does the SAP user exist and is it unlocked?

Cloud Connector issues

  1. Check Cloud Connector logs (All/Payload trace)
  2. Verify icm/trusted_reverse_proxy parameter matches Cloud Connector system certificate
  3. Ensure principal propagation is enabled in Cloud Connector access control

What's NOT supported

ARC-1 does not support local ephemeral X.509 certificate generation. The following flags do not exist:

  • --pp-ca-key, --pp-ca-cert, --pp-cert-ttl
  • --client-cert, --client-key
  • --oidc-username-claim, --oidc-user-mapping

Principal propagation is exclusively via BTP Destination Service + Cloud Connector.

SAP Documentation References

This page covers on-premise principal propagation via Cloud Connector. For a cloud-to-cloud BTP ABAP Environment (no Cloud Connector), see btp-abap-environment.md — including the cross-subaccount caveat.