Now accepting guest editorial from SAP, Oracle, Workday and ServiceNow practitioners.Pitch a guide
The Sign-Off Table

Lesson 2 of 5

Scopes, roles and role collections

9 min

Listen to this lesson

0:00 / 8:07

Authentication says who you are; authorization says what you may do. For applications that use the SAP Authorization and Trust Management service (often called XSUAA), the model has a few layers that developers and administrators share. Developers define what can be granted; administrators decide who gets it. Mixing up the layers is the root of many "it works for me" defects.

ScopeA single permission the app checks, such as $XSAPPNAME.FleetAgent. Defined by the developer.
AttributeA user-specific value used to restrict data, such as customer. Defined by the developer; values come from the role or the identity provider.
Role templateA bundle of scopes and attribute references in the app's security descriptor (xs-security.json)
RoleAn instance of a role template. Created automatically when no attributes are needed; otherwise by an administrator who sets attribute values.
Role collectionA group of roles, possibly from several apps, assigned to users or mapped to identity provider groups
The authorization layers of SAP Authorization and Trust Management, from developer-defined to administrator-assigned.
The Sign-Off Table · thesignofftable.com/academy/sap-btp-204

The security descriptor

The app declares its authorization artifacts in xs-security.json. The xsappname names the application; every scope is prefixed with the placeholder $XSAPPNAME, which the service replaces with the real, unique name. scopes list the permissions, attributes list restricting attributes with a value type, and role-templates bundle scope references and attribute references. Optionally, role-collections define ready-made collections that reference role templates. tenant-mode is dedicated for a single-tenant app and shared for a multitenant one. When the app's XSUAA service instance is created or updated with this file, its role templates appear in the subaccount.

ElementFleet app content
xsappnamefleet-order-status (with the org and space appended at deployment)
scopes$XSAPPNAME.FleetAgent, $XSAPPNAME.FleetSupervisor, $XSAPPNAME.FleetCustomer
attributescustomer (string): business partner number of a fleet customer contact
role-templatesFleetAgent, FleetSupervisor, FleetCustomer (references the customer attribute)
role-collections (predefined)Fleet Agent and Fleet Supervisor; Fleet Customer is created by the administrator because it needs an attribute source

The fleet app's security descriptor in outline.

The XSUAA model: developers define scopes, attributes and role templates; administrators create roles and role collections; and only role collections reach users or groups.
The Sign-Off Table · thesignofftable.com/academy/sap-btp-204

Roles and attributes

SAP's documentation explains that roles for purely functional role templates are generated automatically, while roles that use attributes must be created by an administrator, who decides where each attribute's value comes from: a static value stored in the role, a value taken from the identity provider's assertion (by its exact attribute name), or unrestricted, meaning the attribute imposes no limit. For the fleet customer role, Contoso sources customer from the identity provider, so each Great Lakes Fleet Services contact carries their own business partner number in their token.

For an attribute-based role the administrator picks the value source; the Fleet Customer role takes customer from the identity provider so each contact carries their own number.
The Sign-Off Table · thesignofftable.com/academy/sap-btp-204

Role collections are where business language meets technical roles. A role collection can combine roles from several applications, so the Fleet Supervisor collection might hold the supervisor role of the fleet app and a viewer role of an analytics app the supervisors also use. Name collections after the business role, not the app, and keep their contents documented: when a new app adds a role, the question "which business role should hold it?" must be answered by the process owner, not decided silently by whoever deploys the app. The security descriptor can predefine role collections for convenience, but only for role templates without attributes, since attribute values have to be set per customer landscape.

Developer (in the app)Administrator (in the subaccount)
DefinesScopes, attributes, role templates, optional predefined role collectionsRoles with attribute values, role collections
Changes throughxs-security.json, deployed with the appSAP BTP cockpit or APIs
Assigns to peopleNeverUsers and identity provider groups, per subaccount
Test evidenceDescriptor in source control; automated authorization testsExported role collection assignments; access review
Who owns which part of the authorization model.
The Sign-Off Table · thesignofftable.com/academy/sap-btp-204

What would you do?

A developer asks the subaccount administrator to "assign the FleetSupervisor scope to Grace". What should the administrator explain?

Key points
  • Scopes are permissions; attributes restrict data; role templates bundle them in xs-security.json.
  • Roles are instances of role templates; attribute-based roles are created by administrators.
  • Role collections group roles and are the only thing assigned to users or groups.
  • Attribute values can be static, from the identity provider, or unrestricted.
  • Check whether your app uses XSUAA or Authorization Management policies; the evidence differs.

Check your understanding · not graded

Lesson check

  1. 1. What is assigned to users or identity provider groups in a subaccount?

  2. 2. What does $XSAPPNAME stand for in xs-security.json?

  3. 3. When must an administrator create a role manually?

  4. 4. Which attribute source lets each fleet customer contact carry their own business partner number?