In today’s world, hardly any application is built in which there is no distinction between different users, roles or rights. Of course, the same also applies to SAP UI5 applications that are to run on the  SAP Business Technology Platform. In this small post I would like to go into more detail about the configuration of an application for role-based access.

Let’s start with the target scenario: the starting point is a SAP UI5 application, which was developed using a tool of your choice and runs in the BTP. Only users who have a specific role should have access to this application. The users with their groups are maintained in an own IAS tenant and the application itself is made available via a launchpad (or SAP Build Workzone). The following figure shows the scenario schematically. A team leader shall have access to the application and a normal team member has no access.

Role-based access scenario

Disclaimer: I describe the individual steps required and refer to other sources of information if necessary. This blog post is not a complete click-through guide to securing your own application.

Role restriction in UI5 application

First, the UI5 application must be secured. A good start for creating the application and setting up the security aspects can be found at:

• Good introduction to developing a user interface in CAP: https://developers.sap.com/tutorials/hana-cloud-cap-create-ui.html
• Add authentication: https://developers.sap.com/tutorials/hana-cloud-cap-add-authentication.html
• Deep dive: SAP Authorization and Trust Management Service in the Cloud Foundry Environment

The xs-security.json file is used to map your own role. This file is created automatically when generating the AppRouter (managed or standalone) for the application.

Adjustments in xs-security.json

The finest unit for controlling permissions is the scope. This must be created in xs-security.json. In our case, we define the team leader there. The name of the scope contains a reference to the name of the application, so that in the end the scope is specific to the application.

"scopes": [
    ...,
    {
      "name": "$XSAPPNAME.Teamlead",
      "description": "Teamlead"
    }
  ],

An application can define any number of scopes. The scopes can then be grouped into roles. This enables fine-grained authorization control.

Next, the template for the corresponding role is created. This role is then available in the BTP cockpit for assignment to role collections. The role template refers to all scopes for which the role should be authorized.

"role-templates": [
    ...,
    {
      "name": "Teamlead",
      "description": "Teamlead within the project",
      "scope-references": [
        "$XSAPPNAME.Teamlead"
      ],
      "attribute-references": []
    }
  ]

Attention: role collections can also be defined in xs-security.json. If you do this, the role-collections created with it cannot be used in the launchpad. So it’s best to do without this feature.

Adjustments in xs-app.json

Now the scope and the role template for the team leader are defined. Now it has to be ensured that the application can only be used by the team leader. To do this, the xs-app.json must be adapted. This file defines which routes are served by the application and how they are to be protected.

{
  "welcomeFile": "/index.html",
  "authenticationMethod": "route",
  "routes": [
    ...,   
    {
      "source": "^(.*)$",
      "target": "$1",
      "service": "html5-apps-repo-rt",
      "authenticationType": "xsuaa",
      "scope": [ "$XSAPPNAME.Teamlead" ]
    }
  ]
}

Now only the team leader can use the application. The scope thus submits access to the path in the application. If several routes are defined, you can also act there with restrictions based on the scope.

Note: If the application uses data from third-party systems, access to this data and the corresponding roles should also be restricted there. This means that checking whether a user is allowed to see data should not only be left to the UI5 application. In the case of the Cloud Application Programming Model, I recommend taking a look at the relevant cookbook: https://cap.cloud.sap/docs/guides/authorization

IAS configuration

The application is now self-secured. Next, a group must be created in the IAS that bundles the necessary rights. Theoretically, the groups can be defined completely independently in the IAS without having a specific reference to roles/scopes in the UI5 application. The easiest way is to map group names directly to role-collection names in BTP. This makes it easier to keep track of which group has which rights.

In the IAS, the group definition is very simple under the tile User & Authorizations => User Groups, all user groups can be managed. This is where you create the new group for the application.

Group definition in IAS

The group can now be assigned to the users who should have access to the application. The administration of groups and users is very well documented in the help: User Groups

Launchpad configuration

The next step is to configure the required roles in the launchpad. Assumption: the application has already been configured and is available for use. A new role can be stored via the Site Manager => Content Manager. The role has a name and a unique ID. As with the group setup in the IAS, the name can be freely assigned and does not necessarily have to be related to existing groups/role configurations. It is of course easier to use the same names again. Don’t forget to assign the application(s) accessable by an user with the new role.

Role configuration in launchpad

The new role has now been defined generically in the Launchpad Service and is therefore available for all specific sites. In order for the site to be able to use the role, it must still be added. This is done via the site settings. Editing this allows the role to be added to the site.

Assign role to site

Final configuration in SAP BTP cockpit

All services and applications involved now know the new role. In order for these to work together, a few things still have to be done in the SAP BTP cockpit. When the role was created in the launchpad, a corresponding role collection was created in the cockpit. The Role Collection is now expanded:

The necessary role of the SAPUI5 application is added in the Roles area. This means that anyone who has access to the Role Collection also has access to the corresponding application. The IAS user group must then be added to the User Groups area. Each user with the corresponding IAS user group is now automatically assigned to the Role Collection.

IAS user group mapping

If all steps have been carried out accordingly, only users with the necessary role will now see the application, regardless of whether they access it directly or via the launchpad.

Summary

With a few simple steps, a scenario can be set up in which access to a SAPUI5 application is controlled via the IAS and then taken into account at all relevant points. It is important that all steps are carried out and not too much is configured. As mentioned before, if the role collection is created directly in xs-security.json, it cannot be easily configured in the launchpad. The launchpad will show an exception if a role is added with the same name of an existing role collection.

If you now need additional attributes from the IAS in the application, I can recommend the following blog post: Mapping of SAML attributes with XSUAA JWT in Cloud Foundry It is also essential to think about the necessary attributes at an early stage. If you create role templates without attribute references in the UI5 application, roles are created automatically with the deployment. If you then add attributes afterwards, the roles in the SAP BTP Cockpit cannot be automatically adjusted accordingly, so that manual intervention is necessary here.

Another important aspect when defining the security settings is the credential type. Here you can find some interesting aspects: Why developers should care about credential-types for xsuaa?.

What are your experiences and tricks when configuring roles/rights in the SAPUI5, BTP, launchpad/workzone universe?