XSUAA Troubleshooting on SAP BTP Cloud Foundry: A Practitioner’s Token‑Level Field Guide

Dr. Sarah Chen breaks down the diagnostic process that separates hours of frustration from a ten‑minute fix.

You deploy the application, the route comes up, but every request to a protected endpoint returns 401 Unauthorized or, maddeningly, 403 Forbidden with a tiny insufficient_scope payload. The XSUAA service itself shows green, and the trust to your corporate IdP appears “configured.” You already re‑pushed and re‑bound the service instance. Now what? After 16 years of untangling SAP authorization architectures, I can tell you the difference between a one‑hour resolution and a day‑long war room is having a token‑centric diagnostic chain rather than prodding configuration screens at random.

The Diagnostic Framework: Reconstruct the OAuth 2.0 Flow

Every Cloud Foundry application that relies on XSUAA participates in a precise chain:

User Agent → IdP (e.g., Azure AD, IAS) → XSUAA → App

A break at any link produces an opaque HTTP error. My approach is to walk the chain backwards from what the application actually receives:

1. Inspect the application logs for the raw XSUAA trace. With cf logs <app> --recent look for lines that contain XSUAA or JWT. A common signature of a missing scope is:

   "error":"insufficient_scope","error_description":"Insufficient scope for this resource"
   

   If you see this, the token itself was accepted, but the scopes encoded in the JWT do not match the roles required by the endpoint.

2. Pull the actual JWT out of your browser’s developer tools or from a dedicated debug endpoint you build (never in production, of course). Decode it with jwt.io or cf curl against the token‑key endpoint. Look for:

   • "iss" – must match the XSUAA identity‑zone URL exactly.
   • "aud" – the audience must include your application_id!t<tenant> pattern.
   • "scope" – verify that it includes, for example, $XSAPPNAME.display if your endpoint requires that scope.

   An issuer mismatch is almost always a trust configuration error between the subaccount and the identity provider – and it won’t show up as a blocked trust in the cockpit if the SAML metadata is merely stale.

3. Verify the XSUAA service instance binding at the platform level:

   cf service-key <xsuaa-instance> <key-name>
   

   Compare the xsuaa.url and xsuaa.uaadomain with the issuer in the token. In multi‑landscape scenarios, I’ve seen developers inadvertently use a trial‑landscape token against a production service instance.

Common Pitfalls and What Their Logs Actually Say

Role Collection Misassignment

The role-collections section in the xs-security.json maps role template names to role collection names. If a user is assigned the role collection but the mapping is missing, the token will not include the expected scope. The cockpit’s “Role Collections” screen can look correct while the mapping is broken. Check:

"scopes": [{
  "name": "$XSAPPNAME.read",
  "description": "Read access"
}],
"role-templates": [{
  "name": "Reader",
  "scope-references": ["$XSAPPNAME.read"]
}],
"role-collections": [{
  "name": "ReaderRoleCollection",
  "role-template-references": ["$XSAPPNAME.Reader"]
}]

A typo in role-template-references (like "reader" instead of "Reader") will silently fail. I validate auto‑generation by diffing the xs-security.json with the XSUAA dashboard after update.

Clock Skew Between the Application Container and XSUAA

Tokens contain iat and exp claims. If the Cloud Foundry container’s clock drifts by more than the XSUAA tolerance (default 60 seconds), validation fails with invalid_token in the application logs even though the token looks correct. Use cf ssh and check date. In one case, a custom buildpack had an incorrect NTP configuration; the fix was instantaneous after the container restarted.

Trust to IdP Unidirectional

The subaccount trust configuration defines a SAML 2.0 relationship. The IdP must also accept the XSUAA service provider. If the IdP side is misconfigured (e.g., missing the ACS URL that XSUAA expects), users experience a redirect loop. The cockpit’s “Test Connection” button does not test the IdP’s acceptance of the SP metadata. My rule: always manually hit the IdP‑initiated endpoint and trace the SAML response.

Monitoring and Prevention: Build Lightweight Guardrails

Rather than waiting for production incidents, I embed a minimal health‑check endpoint inside the app container that, given a valid bearer token, returns the decoded JWT claims. This lets a CI/CD pipeline verify that critical scopes appear for a test user right after deployment. The BTP cockpit’s Subaccount → Security → Trust Configuration also shows recent authentication events; correlate those timestamps with your application log entries.

For deeper platform‑side visibility, use:

cf curl /v2/info
cf curl /v2/service_instances/<guid>/parameters

The XSUAA service does not expose a dedicated debug log, but you can often spot configuration drift by exporting the xs-security.json from the service instance and comparing it with your version‑controlled master.

Action Items for Practitioners

• Token‑first diagnosis: Always decode the JWT before touching trust configuration. It tells you exactly what the app sees.
• Centralize role collection validation: Automate a diff between the deployed xs-security.json and the live service instance after every binding update.
• Inject a health endpoint: Return protected claims for a known test user so your build pipeline can assert scope presence.
• Monitor clock sync: Include a NTP drift check in your container readiness probe.
• Double‑check IdP‑initiated flow: Manually test an IdP‑first login to catch silent SP‑side metadata rejections.

Bottom Line

XSUAA troubleshooting isn’t magic — it’s a deterministic chain that most often breaks inside the JSON payloads, not inside the platform. If you stop chasing vague cockpit “green” indicators and start reading the tokens and the logs as your primary source of truth, you’ll resolve 90% of your authorization issues before you ever need to open a support ticket. The rest are usually just typos.

Source: SAP Help – Monitoring and Troubleshooting for Authorization and Trust Management Service Dr. Sarah Chen is Lead SAP Architect at Flagship Research and has been designing and debugging BTP authentication architectures for more than a decade.

References

• SAP AI Core Documentation
• SAP Community Hub

References

• Monitoring and Troubleshooting
• SAP AI Core Documentation
• SAP Community Hub