Cannot/update create xsuaa instance with role-template-references

[Jakob-Rufcbs]

Hi,

we are running into an error when trying to deploy our xs-security.json with the mentioned role-template-references from the documentation with the following message:

Updating service "myapp-auth" failed: Error updating application null (Error parsing xs-security.json data: Unrecognized field "role-template-references" (class com.sap.xs2.security.authorization.XSRoleTemplate), not marked as ignorable (9 known properties: "scope-references", "attributeReferences", "default-role-name", "attribute-references", "attributeReferencesFromNames", "name", "appId", "description", "scopeReferences"]) at [Source: REDACTED (StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION disabled); line: 1, column: 276] (through reference chain: com.sap.xs2.security.authorization.XSApp["role-templates"]->java.util.ArrayList[0]->com.sap.xs2.security.authorization.XSRoleTemplate["role-template-references"]))

It worked a few weeks ago when we deployed to production but apparently something has changed in xsuaa service which invalidated role-template-references as an attribute which is why we can't deploy our xsuaa with the documented configuration anymore. When deploying without the configuration, we are getting a 403 when trying to upload the content of the file.

Please advise on how to solve this

[github-actions]

🧪 Initial Analysis & Proposed Remediation

Summary & Root Cause Hypothesis
The issue describes an error encountered during the deployment of an xs-security.json configuration, specifically when attempting to update or create an XSUAA instance. The core error message Unrecognized field "role-template-references" (class com.sap.xs2.security.authorization.XSRoleTemplate) strongly indicates a schema validation failure. The XSUAA service or the deployment tooling no longer recognizes role-template-references as a valid field within an XSRoleTemplate definition. The user notes that this configuration "worked a few weeks ago," suggesting a recent breaking change or deprecation in the XSUAA service API or its underlying schema. The subsequent 403 error when attempting to deploy without this configuration reinforces that the role-template-references were critical for defining necessary permissions, which are now missing without a proper replacement.

Root Cause Hypothesis: The most likely root cause is a breaking change in the SAP BTP XSUAA service's schema for xs-security.json definitions. The role-template-references field within role-templates has likely been deprecated, removed, or replaced by an alternative mechanism, leading to schema validation failures during deployment. This change could have been introduced through an automatic update of the XSUAA service itself on the Cloud Foundry environment.

---

🥇 Prioritized Remediation Steps (with Code Fixes)

1. Consult SAP XSUAA Documentation & Release Notes (High Priority):

   • Rationale: This is the most direct approach to confirm the root cause. SAP regularly updates its services, and breaking changes or deprecations are typically announced in release notes or updated documentation. Verifying this will provide official guidance on the new recommended approach or alternative syntax.
   • Action & Expected State:
     • Search the official SAP BTP documentation for XSUAA service, focusing on xs-security.json schema definitions for role-templates and any recent release notes or migration guides.
     • Specifically look for information regarding role-template-references or similar concepts that might have replaced it.
     • Expected State: Confirmation of the field's deprecation or a new recommended approach to achieve the desired authorization structure. No direct code change is provided here as the outcome of this step will inform subsequent code changes.

2. Migrate role-template-references to explicit scope-references (High Priority):

   • Rationale: The error explicitly states role-template-references is unrecognized, while scope-references is listed as a known, valid property for XSRoleTemplate. The primary purpose of role-template-references within a role-template would typically be to aggregate permissions (scopes) from another template. By explicitly listing all necessary scopes directly in the scope-references array of the current role template, we can achieve the same functional outcome while adhering to the updated schema. This also addresses the follow-up 403 error by ensuring all required permissions are still granted.

   • Action & Required Change: Identify the role-template definitions in your xs-security.json that contain role-template-references. For each such role-template, remove the role-template-references array and instead, consolidate all scopes implied by those referenced templates directly into the scope-references array of the primary role-template.

     Example xs-security.json Snippet (Before & After):

     Let's assume your original xs-security.json snippet had a structure similar to this, where MyRoleTemplate was intended to inherit scopes from AdminRoleTemplate.

     // Original (problematic) xs-security.json snippet
     {
       "xsappname": "myapp",
       "scopes": [
         { "name": "$XSAPPNAME.read", "description": "Read access" },
         { "name": "$XSAPPNAME.admin", "description": "Admin access" }
       ],
       "role-templates": [
         {
           "name": "MyRoleTemplate",
           "description": "My Application Role Template",
           "scope-references": [ "$XSAPPNAME.read" ],
           "role-template-references": [ // <-- THIS FIELD IS NO LONGER RECOGNIZED
             { "name": "AdminRoleTemplate" }
           ]
         },
         {
           "name": "AdminRoleTemplate",
           "description": "Administrator Role Template",
           "scope-references": [ "$XSAPPNAME.admin" ]
         }
       ],
       "role-collections": [
         {
           "name": "MyRoleCollection",
           "description": "Collection for my app roles",
           "role-template-references": [
             { "name": "MyRoleTemplate" }
             // Note: role-template-references is valid here for role-collections,
             // the error was specifically for XSRoleTemplate.
           ]
         }
       ]
     }

     To resolve the issue, remove the role-template-references from MyRoleTemplate and explicitly add the scopes provided by AdminRoleTemplate (i.e., $XSAPPNAME.admin) to MyRoleTemplate's scope-references.

     // Fixed xs-security.json snippet
     {
       "xsappname": "myapp",
       "scopes": [
         { "name": "$XSAPPNAME.read", "description": "Read access" },
         { "name": "$XSAPPNAME.admin", "description": "Admin access" }
       ],
       "role-templates": [
         {
           "name": "MyRoleTemplate",
           "description": "My Application Role Template",
           "scope-references": [ "$XSAPPNAME.read", "$XSAPPNAME.admin" ] // <-- CONSOLIDATED SCOPES
           // The "role-template-references" field is removed from here
         },
         {
           "name": "AdminRoleTemplate",
           "description": "Administrator Role Template",
           "scope-references": [ "$XSAPPNAME.admin" ]
         }
       ],
       "role-collections": [
         {
           "name": "MyRoleCollection",
           "description": "Collection for my app roles",
           "role-template-references": [
             { "name": "MyRoleTemplate" }
           ]
         }
       ]
     }

3. Update Cloud Foundry CLI & Tooling (Medium Priority):

   • Rationale: While the error message points to a backend schema validation, ensuring that your local Cloud Foundry CLI and any related plugins (like the MTA deployer plugin) are up-to-date is a good practice. Older versions might not correctly interact with newer service APIs or could be using outdated internal schemas themselves.

   • Action & Required Change: Update your Cloud Foundry CLI and any relevant plugins to their latest stable versions. This can typically be done via the cf command itself.

     # Update the Cloud Foundry CLI
     cf update-cli
     
     # Check and update CF CLI plugins (e.g., MTA plugin if used directly)
     cf plugins # To list installed plugins
     # If an update is available or required for a specific plugin, use:
     # cf install-plugin <plugin-name> -f
     # or remove and reinstall if update doesn't work.

---

Risk Assessment
Applying these fixes carries a moderate risk.

• Step 1 (Documentation Review): Low risk. This is an informational gathering step and carries no deployment risk.
• Step 2 (Code Change in xs-security.json): Moderate risk. Directly modifying xs-security.json has the potential to alter application permissions. If the scopes derived from role-template-references are not fully or correctly identified and added to scope-references, it could lead to incorrect authorization issues (e.g., users gaining too many or too few permissions, resulting in 403 errors or security vulnerabilities). Careful validation of permissions after deployment is critical.
• Step 3 (CLI/Tooling Update): Low to Moderate risk. Updating CLI tools is generally safe, but compatibility issues with specific environments or custom scripts could occasionally arise. This is generally a transient risk and can often be resolved by rolling back the CLI version if necessary.

It is highly recommended to test these changes in a non-production (e.g., development or staging) environment first, thoroughly verifying all authorization flows before deploying to production.

Next Step: Reply with confirm remediation to approve moving forward (e.g., drafting a PR or creating task list). Reply with refine analysis for a deeper pass, or discard recommendations to remove them.