Troubleshoot SAP BTP Principal Propagation Through Cloud Connector

A BTP application works with a technical account but fails when switched to principal propagation. Cloud Connector shows a connected tunnel. The backend service works directly. Where should you look next?

My architectural rule is simple: prove each identity boundary separately. Network reachability, user authentication, certificate trust, and backend authorization are different controls. A green connection indicator does not validate all four.

This tutorial follows an HTTP-based flow from a Cloud Foundry application through SAP Cloud Connector to an on-premise ABAP service. Other runtimes and protocols require corresponding configuration changes.

Prerequisites

• A BTP Cloud Foundry application authenticated through UAA/XSUAA.
• Destination and Connectivity service bindings available to the application.
• Cloud Connector connected to the intended BTP subaccount.
• An exposed on-premise HTTP service, preferably a read-only test endpoint.
• Access to application logs, Cloud Connector diagnostics, and backend logs.
• Backend administration support for certificate trust, user mapping, and authorization.
• A test user with a known backend account.

Use a nonproduction environment for configuration changes. Never include bearer tokens, private keys, or complete certificate subjects containing personal information in support tickets.

Overview: Understand the Identity Flow

SAP’s troubleshooting article starts with the essential sequence: a user authenticates through UAA, and the application attempts to reach an on-premise service.

For an X.509-based HTTP principal-propagation flow, inspect these boundaries:

User
  → UAA/XSUAA authentication
  → BTP application receives validated user context
  → Destination and Connectivity services
  → Cloud Connector receives propagated identity
  → Cloud Connector creates a short-lived user certificate
  → Backend trusts the certificate and maps it to a local user
  → Backend evaluates that user's authorizations

The backend does not normally authenticate this flow by directly accepting the application’s UAA access token. Cloud Connector translates the propagated identity into the configured backend authentication mechanism.

The supplied SAP sample guide adds useful implementation context: the backend must see the actual user rather than a generic technical account, and certificate-to-user mapping is essential. This tutorial extends that setup perspective with a boundary-by-boundary diagnostic method.

Step 1: Establish One Reproducible Failure

Choose one user, one destination, and one read-only request. Record:

• UTC timestamp and application request ID.
• Destination name and requested path.
• Expected backend user and SAP client.
• HTTP status, response headers, and a sanitized response excerpt.
• Whether the request appears in Cloud Connector and backend logs.

For example:

Destination: ERP_PP
Request: GET /sap/opu/odata/sap/Z_READONLY_SRV/$metadata
Expected backend user: TEST_USER
Observed response: HTTP 401

These are illustrative values, not required SAP configuration names.

Avoid testing different users and endpoints simultaneously. You need to compare the same request across layers.

A successful Basic Authentication test proves some combination of routing, service availability, and technical-user access. It does not prove certificate trust or propagated-user mapping.

Step 2: Verify the Application Retains User Context

First confirm that the application receives and validates a user access token. Successful browser login alone is insufficient: a scheduled task or downstream application call may execute without that user context.

Check that:

• Authentication middleware validates the token’s signature, issuer, audience, and lifetime.
• The outbound call uses the authenticated user’s context.
• The application has not replaced it with a client-credentials token.
• The user token belongs to the intended tenant and trust configuration.

For a Node.js application using SAP Cloud SDK, this illustrates a user-context-aware call:

import { executeHttpRequest } from '@sap-cloud-sdk/http-client';

export async function readMetadata(req, res, next) {
  try {
    // Assumes upstream middleware already validated this bearer token.
    const authorization = req.headers.authorization;
    if (!authorization?.startsWith('Bearer ')) {
      return res.sendStatus(401);
    }

    const userJwt = authorization.slice('Bearer '.length);

    const response = await executeHttpRequest(
      {
        destinationName: 'ERP_PP',
        jwt: userJwt
      },
      {
        method: 'GET',
        url: '/sap/opu/odata/sap/Z_READONLY_SRV/$metadata'
      }
    );

    res.status(response.status).send(response.data);
  } catch (error) {
    next(error);
  }
}

Adapt this to your SDK version and authentication framework. Extracting a header is not token validation.

For custom connectivity clients, distinguish two credentials:

• Proxy-Authorization: authorizes access to the Connectivity proxy.
• SAP-Connectivity-Authentication: carries the user token for principal propagation.

They serve different purposes. Prefer supported SDK handling rather than manually implementing token exchange and proxy headers.

Step 3: Check the Destination and Connector Route

Inspect the destination actually resolved by the application—not merely a similarly named cockpit entry.

An illustrative destination is:

Name=ERP_PP
Type=HTTP
URL=http://erp-virtual:8000
ProxyType=OnPremise
Authentication=PrincipalPropagation

Its hostname and port must match Cloud Connector’s virtual system mapping. They need not match the physical backend hostname and port.

Also verify:

• The destination is visible in the application’s effective tenant context.
• Any configured Cloud Connector location ID matches the intended connector.
• No destination override changes the authentication method.
• The application is not adding a conflicting Basic Authentication header.

The destination URL above represents the virtual route. It does not imply that the connector-to-backend connection should be unencrypted. For certificate-based backend authentication, configure the appropriate HTTPS backend connection.

In Cloud Connector, verify:

1. The connector is registered to the correct subaccount.
2. The virtual host and port match the destination.
3. The internal host, port, and protocol identify the intended backend endpoint.
4. The requested resource path is allowed.
5. The mapping’s principal type supports the intended X.509 flow.

Use the official principal-propagation configuration documentation for release-specific controls.

Do not expose / broadly just to eliminate an access-denied error. Allow only the service paths the application requires.

A cockpit connection check may establish reachability without reproducing an authenticated end-user request. Always repeat the application test.

Step 4: Inspect Certificate Generation and Backend Trust

Once routing works, inspect the identity Cloud Connector receives and the certificate identity it produces.

Verify:

• The expected identity provider and user attributes are available.
• The configured subject pattern uses a supported attribute.
• The resulting certificate subject represents the intended person.
• Certificates are valid, and system clocks are synchronized.

For example, the supplied SAP sample illustrates:

CN=${name}

Do not assume ${name} equals the ABAP username. It could represent a login name that your backend mapping does not recognize. Inspect a diagnostic certificate or trace using approved procedures.

Separate the certificate roles:

• Cloud Connector’s backend-facing system identity.
• The signing CA used for short-lived propagated user certificates.
• The generated user certificate.
• The backend server certificate trusted by Cloud Connector.

These are not interchangeable. Importing an unrelated subaccount certificate does not establish every required trust relationship. Verify the actual certificate chain and the backend’s configured trust model.

Where an intermediary terminates TLS, confirm that the supported certificate-forwarding and trusted-proxy configuration preserves authentication securely. Never trust arbitrary client-supplied certificate headers.

Step 5: Prove Backend Mapping and Authorization

On an ABAP backend, inspect the relevant SSL trust configuration in STRUST. Then examine certificate-to-user mapping through the mechanism supported by your release, such as rule-based certificate mapping in CERTRULE.

Confirm that:

• The presented certificate chain is trusted.
• Mapping rules match the actual issuer and subject.
• The resulting account exists in the intended SAP client.
• The account is usable and has the required service authorizations.
• The service’s logon configuration permits the intended certificate authentication.

A common mismatch is:

Propagated identity: alex@example.com
Backend account:    ALEX01

That requires an explicit, controlled mapping. Similar-looking names do not establish identity equivalence.

Avoid broad rules that map many certificate subjects to one privileged account. Such rules defeat individual accountability.

After authentication succeeds, investigate authorization separately. Use the backend’s available authorization tracing, such as STAUTHTRACE, under controlled conditions. A 403 may indicate authorization failure, but status codes alone cannot establish the failing layer.

Step 6: Correlate Logs to Find the First Broken Boundary

Collect evidence for one timed reproduction:

For ABAP OData, /IWFND/ERROR_LOG and, where applicable, /IWBEP/ERROR_LOG help inspect service errors. TLS failures may occur before either log receives an entry.

Use this triage sequence:

• No connector evidence: inspect application destination resolution and proxy access.
• Connector access denied: inspect virtual mapping and resource allowlists.
• Certificate-generation failure: inspect propagated attributes and connector configuration.
• Backend handshake failure: inspect TLS trust and certificate chains.
• Backend logon failure: inspect certificate mapping and account status.
• Successful logon, rejected operation: inspect service authorization.

Enable detailed tracing briefly. Restore normal levels afterward and protect diagnostic files.

Conclusion

Principal propagation succeeds only when every boundary preserves and accepts the intended identity.

My recommended order is: establish a reproducible request, verify application user context, validate destination routing, inspect certificate generation, prove backend mapping, and finally test authorization.

Finish by confirming that the backend records the expected individual user—not merely that the HTTP request returns successfully. That is the evidence that principal propagation works end to end.

References

• Principal Propagation failing between BTP Mobile S…