Title here
Summary here
Role Collection Design: Patterns and Principles
TL;DR
- SAP BTP authorization follows a three-tier hierarchy: Role Template (application-defined) → Role (instance with attribute values) → Role Collection (assignable bundle). Each tier is owned by a different persona and must be designed before the first user is onboarded.
- Group-based assignment via SAP Cloud Identity Services is production-ready and the only scalable approach for enterprise landscapes — individual user-to-role-collection mapping breaks beyond 20 users and creates permanent audit debt.
- The hardest design failure is not a technical one: treating role collections as an afterthought, assigning Global Account Administrator to developers, and omitting xs-security.json predefined role collections from application design are all requirements-stage decisions with long operational consequences.
Where This Article Sits
| ID | Category | Component | Scope |
|---|---|---|---|
| BTP-F01 | Overview | BTP Architecture Design | Overview and Key Decisions |
| BTP-F02 | Account Design (1) | Subaccount Design | Patterns and Principles |
| BTP-F03 | Account Design (2) | Entitlement and Quota Management | Patterns and Principles |
| BTP-F04 | Authorization (1) | Role Collection Design | Patterns and Principles (this article) |
| BTP-F05 | Authorization (2) | Naming Conventions | Patterns and Principles |
| BTP-F06 | Dev & Transport | CI/CD and Transport Management | Patterns and Principles |
| BTP-F07 | Use Cases | BTP Architecture Design | Use Cases and Decision Patterns |
References
| Resource | URL |
|---|---|
| Role Collections and Roles in Global Accounts, Directories, and Subaccounts | help.sap.com → |
| User and Member Management | help.sap.com → |
| Security Administration: Managing Authentication and Authorization | help.sap.com → |
| Application Security Descriptor Configuration Syntax | help.sap.com → |
| SAP BTP Security Best Practices | help.sap.com → |
1) The BTP Authorization Landscape
The BTP authorization model has five distinct components that work together. Understanding the boundaries between them is the prerequisite for any role collection design decision.
| Domain | What it does | Primary user |
|---|---|---|
| Role Template | Application-defined blueprint declaring permission scopes and attribute references | Application Developer |
| Role | An instance of a role template; holds resolved scope references and optional attribute values | Platform Administrator |
| Role Collection | A named bundle of roles assigned as a unit to users or user groups | Platform/Subaccount Administrator |
| Trust Configuration | Establishes federation between SAP BTP and an external identity provider | Platform Administrator |
| User Group (IdP) | Logical grouping inside the identity provider used for bulk role collection assignment | Identity Provider Administrator |
They are not substitutes. A role template without a role collection is never assignable. A role collection without a trust configuration cannot reach enterprise users. A trust configuration without defined user groups forces individual user management at scale. Each component is independently necessary. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/role-collections-and-roles-in-global-accounts-directories-and-subaccounts]
2) How It Connects to S/4HANA
BTP role collections and SAP S/4HANA authorization objects are parallel systems. They share an identity provider but govern entirely different access layers.
Corporate IdP (Azure AD / Okta)
|
| SAML federation
|
SAP Cloud Identity Services (IAS)
/ \
/ \
S/4HANA Cloud SAP BTP
PFCG Roles Role Collections
| |
Authorization Application access
Objects (Integration Suite,
(FI, MM, SD...) BAS, Build Apps, etc.)When a user logs into an SAP Build Apps application backed by SAP S/4HANA data, they need two independent authorization grants: a BTP role collection granting access to the Build Apps runtime, and an S/4HANA authorization object granting access to the underlying business data via OData APIs. Designing one without the other produces a go-live blocker — the application opens, but data requests return 403s or empty results.
The identity provider is the bridge: a corporate IdP federates through SAP Cloud Identity Services into both systems. The same group membership can trigger both S/4HANA role assignment (via Identity Provisioning Service) and BTP role collection assignment (via group mapping). [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/security-administration-managing-authentication-and-authorization]
Key point: Do not design BTP role collections in isolation from S/4HANA authorization requirements. The IAM design for any BTP–S/4HANA integration must address both layers before the first sprint begins.
3) Maturity Map
| Domain | Maturity | Notes |
|---|---|---|
| BTP cockpit role collection management | ✅ Production-ready | Stable and fully supported. Available via cockpit UI, btp CLI, and Terraform BTP provider. |
| Group-based role assignment (IdP group mapping) | ✅ Production-ready | Requires custom IdP. Default SAP ID service supports individual assignment only. SAP Cloud Identity Services is the standard choice. |
| xs-security.json pre-defined role collections | ✅ Production-ready | Shipped with application deployment. Immediately assignable post-deployment. Reduces Day 1 setup risk. |
| Cloud Foundry org/space roles | ⚠️ Ready with prerequisites | Separate role management model from BTP cockpit role collections. Requires deliberate governance separation between cockpit Members tab and cf CLI. |
| Kyma environment authorization | ⚠️ Ready with prerequisites | Kubernetes RBAC runs in parallel with BTP role collections. Requires Kubernetes-literate platform administrators. |
| ABAP environment authorization | ⚠️ Ready with prerequisites | PFCG-style authorization objects managed independently. Coordination between Basis team and BTP admin team is required; gaps here cause service-to-service call failures. |
SAP Cloud Identity Services group mapping and xs-security.json predefined role collections together form the production-ready baseline for enterprise BTP deployments. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/user-and-member-management]
4) Requirements Checklist
Identity Provider Foundation
| Checklist item | Why it matters |
|---|---|
| Confirm whether the default SAP ID service or a custom IdP will be used | Default SAP ID service supports only individual user assignment; group mapping requires a custom identity provider |
| Identify and provision the SAP Cloud Identity Services tenant | SAP BTP enterprise agreements include an IAS tenant; confirm it is provisioned before IAM design begins |
| Define the corporate IdP federation path (Azure AD / Okta → IAS → BTP) | Federation must be designed end-to-end; gaps in the chain prevent group mapping from working at runtime |
| Document the trust configuration settings for each subaccount | Trust configurations are subaccount-scoped; each subaccount requires its own configuration pointing to the correct IAS tenant |
| Establish who owns user lifecycle in the corporate IdP | If HR owns the IdP group structures, the BTP admin team must coordinate with HR before designing group mappings |
Role Collection Architecture
| Checklist item | Why it matters |
|---|---|
| Map business personas to role collections (not to individual permissions) | Role collections should represent job functions — assigning raw roles to users bypasses the role collection model and creates audit complexity |
| Define the permission band for each role collection: Administrator / Viewer / Auditor | SAP BTP default role collections follow this three-band model; custom collections should match the same pattern |
| Identify which subaccounts require custom role collections vs. relying on defaults | Default role collections (Subaccount Administrator, Subaccount Viewer) cover most platform access; application access requires custom collections |
| Confirm whether xs-security.json will ship pre-defined role collections | Applications that ship with pre-defined role collections reduce post-deployment setup time and misconfiguration risk |
| Verify that Service Credentials Viewer is included when developers need service binding access | Subaccount Viewer alone does not expose service credentials; a custom role collection combining Subaccount Viewer and Service Credentials Viewer is required |
| Document role collection names before creation | Role collections are immutable after assignment; renaming requires deleting and recreating, breaking existing user assignments |
Assignment Strategy
| Checklist item | Why it matters |
|---|---|
| Decide between individual user assignment and group-based mapping before go-live | Individual assignment is acceptable for < 20 users or for emergency access scenarios; group mapping is mandatory at enterprise scale |
| Define IdP user group naming convention aligned with BTP role collections | Group names are the mapping key; inconsistent naming between IdP and BTP produces missed assignments |
| Identify which identity provider tenant owns each user group | Multiple IAS tenants or corporate IdP namespaces require explicit mapping documentation |
| Plan for user offboarding: group removal vs. manual role collection revocation | Group-based assignment automatically revokes access when a user is removed from the IdP group; individual assignment requires a manual removal step |
| Confirm platform user vs. business user assignment scope | Platform users (administrators, developers) receive BTP-level role collections; business users receive application-level role collections |
Enterprise Governance
| Checklist item | Why it matters |
|---|---|
| Define role collection change management process | Role collection modifications affect all assigned users immediately; an unreviewed change can grant unintended access or break a go-live |
| Assign an owner per role collection | Ownerless role collections accumulate unreviewed users over time (shadow user accumulation) |
| Schedule a quarterly access review cadence | Role collection assignments drift as personnel change; periodic review is the control that prevents access creep |
| Document the exception process for emergency access (break-glass accounts) | Break-glass access via Global Account Administrator must be time-limited and logged; absence of this process leads to permanent over-provisioning |
| Confirm that Global Account Administrator is NOT assigned to application developers | Global Account Administrator grants read-write access to commercialization operations including entitlement and subaccount management — not a developer-level permission |
These requirements apply regardless of BTP commercial model. The governance items (change management, access review, exception handling) are organizational commitments that tooling alone cannot enforce. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/security-administration-managing-authentication-and-authorization]
5) Decision Criteria
The three questions to ask first
Q1. Can you identify all current and future users who need access, and is the number under 20?
If yes, individual user assignment is viable for the initial phase. If the number exceeds 20, or if you cannot enumerate all users at requirements time (typical for enterprise rollouts where access is determined by job function rather than by name), group-based assignment is the correct baseline from day one. Retrofitting group mapping after individual assignment has been in production is possible but requires a complete re-design of the assignment structure.
Q2. Who owns user lifecycle data — the corporate HR/IT organization or the project team?
If HR or a central IT team owns Active Directory or another corporate IdP, the BTP project team cannot unilaterally manage user group membership. The group naming convention and group lifecycle process must be agreed with the IdP owner before the trust configuration is created. Without this agreement, the BTP team will be blocked at the moment they try to map a group.
Q3. Is there a named platform administrator with budget authority to provision SAP Cloud Identity Services and configure trust settings?
SAP Cloud Identity Services tenant provisioning and trust configuration are platform-level operations. If no one with platform authority is identified, role collection design cannot be completed — the assignment mechanism has no valid foundation.
Role collection approach by project context
| Project context | Recommended approach |
|---|---|
| Small project, fewer than 20 named users, no corporate IdP | Individual user assignment directly in BTP cockpit |
| Enterprise project with Azure AD, Okta, or similar corporate IdP | Group mapping via SAP Cloud Identity Services (IAS) trust configuration |
| Multi-subaccount landscape shared across teams | Shared IAS tenant per global account; group mapping per subaccount with standardized naming |
| SaaS application shipped to multiple customer tenants | xs-security.json pre-defined role collections for default access baseline |
| Regulatory environment requiring audit trails (SOX, GDPR) | Auditor role collections mandatory; Viewer-only is insufficient for compliance reporting |
| No clear user base or persona definition yet | Stop. Go back to Q1. |
The assignment method selected here determines the operational model for the life of the subaccount. Group-based assignment via SAP Cloud Identity Services is the only approach that enforces automatic access revocation when a user leaves the organization. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/user-and-member-management]
Licensing and cost
| Component | Licensing model | Key question to ask |
|---|---|---|
| SAP BTP role collections | Included in all BTP subscription tiers | No incremental cost; governance effort is the investment |
| SAP Cloud Identity Services (IAS) | Included with BTP enterprise agreements (BTPEA, CPEA) | Confirm your BTP contract includes IAS tenant provisioning — not all legacy agreements do |
| Corporate IdP federation (Azure AD, Okta, Ping) | Governed by existing corporate IdP license | Does your Azure AD P1/P2 license support SAML/OIDC federation with external services? Confirm before designing the federation path |
6) Common Failures
Failure 1: Individual assignment at scale
The BTP cockpit supports direct user-to-role-collection assignment without any IdP group mapping requirement. This is appropriate for small teams and emergency scenarios. Projects that use individual assignment for 50+ users discover the maintenance cost at the first personnel change: departed employees retain access until manually removed, new hires wait days for manual provisioning, and access review requires exporting and auditing every assignment individually. The cost is not visible at go-live; it accumulates silently over the first six months.
Failure 2: Global Account Administrator assigned to developers
Global Account Administrator grants read-write access to entitlements, subaccount creation, and commercialization operations — a set of capabilities that no application developer requires. Projects assign it because it “unblocks” developers during a sprint. The unintended consequence is that a developer can now delete subaccounts, modify entitlement assignments, or alter trust configurations. Subaccount Administrator is the correct permission band for developer administrative needs. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/role-collections-and-roles-in-global-accounts-directories-and-subaccounts]
Failure 3: Confusing Cloud Foundry roles with BTP cockpit role collections
Cloud Foundry org roles (Org Manager, Org Auditor, Org User) and space roles (Space Manager, Space Developer, Space Auditor, Space Supporter) are managed separately from BTP cockpit role collections. A user who holds Subaccount Administrator in the cockpit does not automatically have CF org or space permissions. Projects that assume the BTP cockpit role collection cascades into the CF environment find that their developers cannot deploy applications despite holding what appears to be full administrative access. CF role assignment must be explicitly completed in the Members tab or via the cf CLI.
Failure 4: No pre-defined role collections in xs-security.json
Applications that do not ship with pre-defined role collections in xs-security.json force the platform administrator to manually build role collections from raw role templates after deployment. In multi-tenant or multi-environment deployments, this manual step is repeated for every subaccount and is prone to omission. Shipping pre-defined role collections in xs-security.json gives administrators a ready-made starting point and reduces Day 1 configuration errors. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/application-security-descriptor-configuration-syntax]
Failure 5: Shadow user accumulation
Every user who logs into SAP BTP and triggers a trust configuration creates a shadow user entry in that subaccount. Without an owner per role collection and a periodic access review, shadow users accumulate over months. The audit finding is not just cosmetic — shadow users with valid role collection assignments retain access even after the underlying IdP account is deactivated, because BTP does not automatically synchronize with IdP lifecycle events unless SAP Cloud Identity Services Identity Provisioning is configured to push deprovisioning events.
Failure 6: Role collection naming sprawl
Without a naming convention defined at requirements stage, each team creates role collections with ad hoc names. A landscape that starts with Developer_RC_TEST grows to include DevRC-prod, RC_DEV_FINAL, and TEST-developer-full. Auditing which role collections are active, which are redundant, and which map to which business function becomes a project in itself. Naming conventions for role collections belong in the BTP architecture decision record alongside subaccount naming conventions (covered in BTP-F05).
Failure 7: Missing Service Credentials Viewer for developer operations
Developers who need to inspect service binding credentials (API keys, OAuth client credentials) in the SAP BTP cockpit require a custom role collection that combines Subaccount Viewer with Service Credentials Viewer. Subaccount Viewer alone does not expose credentials. Projects that discover this at the first service binding inspection delay the integration sprint while a custom role collection is created, reviewed, and assigned. This is a requirements-stage item, not an operational workaround.
FAQ
Q: What is the difference between S/4HANA PFCG roles and SAP BTP role collections?
They are parallel authorization systems. PFCG roles in SAP S/4HANA control access to ABAP transactions, reports, and business objects. BTP role collections control access to BTP services, applications, and cockpit operations. They share an identity provider through federation but do not share roles, templates, or management tooling. An employee correctly provisioned in S/4HANA with PFCG roles still requires a separate BTP role collection assignment before accessing any BTP application. Both must be addressed in the IAM design. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/role-collections-and-roles-in-global-accounts-directories-and-subaccounts]
Q: Does SAP Cloud Identity Services cost extra?
SAP Cloud Identity Services is included in SAP BTP enterprise agreements (BTPEA and CPEA). Projects running on legacy subscription agreements should verify whether IAS tenant provisioning is included or requires an add-on order. The IAS administration console is at https://<tenant>.accounts.ondemand.com/admin. If the tenant has not been provisioned, raise a request with SAP during the BTP onboarding phase — IAS provisioning can take several business days and should not be deferred to the sprint when group mapping is first needed. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/user-and-member-management]
Q: When should we descope role collection complexity from a BTP project?
When you cannot answer Q1 (user count and persona definition), descope the group mapping effort and design for individual assignment with a documented upgrade path. Group mapping is the right end state, but it depends on IdP group structures that a corporate IT organization must create and own. If that organizational dependency cannot be resolved within the project timeline, shipping with individual assignment for a named set of administrators and creating a backlog item for the group mapping transition is the pragmatic choice. Never descope the role collection architecture itself — operating without defined role collections means operating with over-provisioned users.
Q: How do I document the role collection requirement for the business?
Use a role-collection matrix: one row per persona, columns for subaccount scope, role collection name, permission band (Administrator / Viewer / Auditor), assignment method (individual / group), IdP group name, and owner. This matrix is the single source of truth for IAM handover to operations. It belongs in the solution design document alongside the subaccount design and entitlement matrix. Present it to the business sponsor before go-live — undocumented access grants produce audit findings and escalations at the first compliance review.
Q: Can one role collection span multiple subaccounts?
No. Role collections are scoped to the account level where they are created — a role collection in Subaccount A does not exist in Subaccount B. In a multi-subaccount landscape, administrators must create equivalent role collections in each subaccount individually, or use the btp CLI or Terraform to automate the provisioning. This is a frequent source of confusion when teams assume that a centrally-created role collection applies globally. The subaccount boundary is a hard isolation boundary for role collections, not a governance preference. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/sap-business-technology-platform/role-collections-and-roles-in-global-accounts-directories-and-subaccounts]
Summary
SAP BTP role collections are not a deployment step — they are an architectural decision made at requirements stage. The three-tier hierarchy (role template → role → role collection) is fully production-ready. The choice of assignment method determines whether the IAM design scales: group mapping via SAP Cloud Identity Services is the only enterprise-viable approach for landscapes with more than 20 users or multiple subaccounts. The failure modes that appear in go-live reviews — over-provisioned Global Account Administrators, missing Service Credentials Viewer custom collections, CF role confusion, shadow user accumulation — are all traceable to requirements decisions made too late or not made at all. The role-collection matrix, defined before the first sprint, is the document that prevents them. [Confidence: high — SAP Help Portal, https://help.sap.com/docs/btp/best-practices/security]