Skip to Content
Technical Articles

Creating Role Collections in SAP BTP Using the New ‘role-collections’ Property

Setting up ready-to-use role collections in the Cloud Foundry environment of SAP Business Technology Platform is cumbersome.

I bet it bothered you that there is no quick way of creating role collections right away? It would be handy to push role collections directly into the SAP BTP cockpit. So, admins could immediately use them and assign them to users.

Good news: A quick shortcut is available now (Release Notes and Quick Start: Create Role Collections (with Predefined Roles)).

How do I do that?

You directly define the role collections in the xs-security.json using the new role-collections property.

These defined role collections reference role templates. The role templates can be in the same application or in other applications, but within the same subaccount. As soon as you’ve deployed your application, the SAP BTP cockpit displays the role collections. They contain the roles you predefined in the referenced role templates.

What you need to do?

1. Deploy an application you want to use for creating role collections.

2. Edit the xs-security.json file and add the role-collections property. For details see the role-collections section in Application Security Descriptor Syntax.

"role-templates": [
        "name": "Viewer",
        "description": "View Users",
        "scope-references": [
        "name": "Manager",
        "description": "Maintain Users",
        "scope-references": [
"role-collections": [
        "name": "UserManagerRC",
        "description": "User Manager Role Collection",
        "role-template-references": [

3. Go to the folder where the xs-security.json file is stored.

4. To deploy the security information, create a service using your file.

cf create-service xsuaa application <service_name> -c xs-security.json


cf create-service xsuaa application rolecoll-serv -c xs-security.json 

5. (If you do not use a manifest file) Bind your application to the service.

cf bind-service <application_name> <service_name>


cf bind-service rcpropertyapp rolecoll-serv

Now, you have created a role collection.

6. Log on to the SAP BTP cockpit.

7. Navigate to your subaccount. The Role Collections menu item displays the role collection you defined during this procedure. Admins can now log on to the SAP BTP cockpit and assign this role collection to users.



There is a tutorial with an xs-security.json file that includes role collections. You may use this as an example.

You find the tutorial here: Tutorials for Authorization and Trust Management

You must be Logged on to comment or reply to a post.
  • Very helpful blog ! The issue of not having a quick way of creating role collections right away was a huge obstacle. This really does simplify things.

    • Hi Martin Blust

      how can I avoid errors like "Bad Gateway: Service broker error: Service broker xsuaa failed with: Role Collection XYZ already exists in this subaccount.", when I'm using the CF MTA Plugin for deployment of MTAR?

      ? live long and prosper


      • Hi Martin,

        we do have the same issue (Role Collection already exists).

        If we built the role collectios already, the new deployment within a new space (Prod) will fail, because the role collections already exist.

        Of course, I can remove the role-collections property from the xs-security file, but this is not at nice at all.





        • And an other issue was that I was not able to assign the roles to this generated role collections.

          In the end I had to create the role collections manually and could assign them to the roles.



  • Hi Martin,

    It would be great if you could also add the usergroup.
    So the IDP en the usergroupname. Do you know if this is possible?

    regards Erik

  • Hello,

    as far as I know it is only possible to include attributes that come with groups. See Application Security Descriptor Configuration Syntax. I guess this is not what you want to do.

    To add user groups to role collection, use the SAP BTP cockpit. <global_account> -> <subaccount> -> Security -> Users brings you to the screen where you can manage users' permissions. See Working with Users.

    Of course, you must have administrator rights to do so.