TinyWorld - Part 11
Add authorization
Hello again!
In Introduction to the TinyWorld application we introduced the TinyWorld muti-part tutorial, describing how to develop applications for SAP HANA and XS Advanced, using the SAP Web IDE for SAP HANA (Web IDE).
Our next challenge (and yes, this is not an easy task...) is to enhance the application with authorization checking code.
We will introduce two categories of users: those that can only view the country information, and those that are authorized to add new countries.
The XS Advanced security concept is based on scopes.
Scopes are functional authorization units in the context of an application, e.g. the permission to create a new country could be encapsulated by a scope called CreateCountry. Scopes can be assigned to roles which in turn can be assigned to users. Application can also define a role-template which simplifies the process of creating new roles for administrators.
Enabling authorization includes the following steps:
- Define scopes and role-templates in xs-security.json
- Recreate the UAA service with xs-security.json
- Add authorization checks to the application tinyui and tinyjs
- Create roles, role collections from templates and assign them to users
1. Create the xs-security.json file
The xs-security.json file is a configuration file that defines the scopes used by the application and role-templates that consolidate the scopes into functional roles.
Below is a simple sample xs-security.json for our TinyWorld application. It defines one scope to only view data, and another to also create data, and corresponding role-templates: tinyworldView and tinyworldCreate.
{
"xsappname": "tinyworld",
"scopes": [ { "name": "$XSAPPNAME.view", "description": "View data" },
{ "name": "$XSAPPNAME.create", "description": "Create data"}
],
"role-templates": [ { "name": "tinyworldView",
"description": "Role for viewing data",
"scope-references": [ "$XSAPPNAME.view" ] },
{ "name": "tinyworldCreate",
"description": "Role for creating data",
"scope-references": [ "$XSAPPNAME.create","$XSAPPNAME.view" ] }
]
}
Create an xs-security.json file in the root folder of your project, copy past the above sample and save.
We must also update the tiny_uaa resource, defined in the mta.yaml file, to use the the xs-security.json file.
To do that, add the lines marked in yellow below to the tiny_uaa definition in the mta.yaml file.
- name: tiny_uaa
type: com.sap.xs.uaa
parameters:
path: ./xs-security.json
NOTE: since the Web IDE does not provision the UAA service automatically yet, the importance of maintaining this additional entry in the mta.yaml file is for the sake of completeness and to enable packaging and deployment of the application using the XS deploy command at a later stage.
2. Provision the UAA service with xs-security.json
Next we need to update our tiny_uaa service with the new authorization configuration defined in the xs-security.json file. To do that you first need to download the xs-security.json file from your project in Web IDE to a folder accessible from your command line tool. Then, we will delete the service (which we provisioned in part 10 of this tutorial (Add authentication) for testing authentication) and recreate it with the new security definitions.
Run the following xs commands:
xs delete-service tiny_uaa
xs create-service xsuaa devuser tiny_uaa -c ./xs-security.json
Note: In the future, this situation will be automatically detected by the tools, and you will not need to do this manually.
Note: deleting the service will unbind it from all applications. As a result our TinyWorld application now became unusable, which we will soon fix.
Note: when creating the UAA service we used the service plan devuser. This service plan is specially designed to be used at development time. It enables multiple developers to create UAA service instances with the same application name in their xs-security.json file.
XS Advanced requires application names to be unique. To resolve this, the UAA service broker adds a suffix to the application name to make every application unique per user e.g. tinyworld!u1 (however a user cannot use the same application name more than once).
This allows multiple developer to work on the same application in isolated environments without worrying about naming conflicts.
3. Add authorization checks to the application
To enable authorization in App Router based applications (such as tinyui), we need to specify the scope a user must be assigned to in order to access resources of specific route. The assignment of scopes to routes is done in the xs-app.json file, located under the tinyui/ folder.
In order to impose authorization check on any request to our application, we need to add additional general route (which is the default behavior hence we didn’t need it up till now), and assign the right scope to it.
Add the following to xs-app.json, (note – the order of the entries in the route list is important, make sure you enter them in the order described below)
- To the /euro.xsodata/ route add "scope": " $XSAPPNAME.view"
(this will enforce the authorization check even if the OData service is accessed directly without the UI) - To the xsjs route add "scope": "$XSAPPNAME.create"
- Add a new general route with the scope assignment
{
"source": "^/(.*)$",
"localDir" : "resources",
"scope" : "$XSAPPNAME.view"
}
Following the above changes your xs-app.json file should look like this (marked in yellow are the new lines)
{
"welcomeFile": "index.html",
"authenticationMethod": "route",
"routes": [{
"source": "^/euro.xsodata/.*$",
"destination": "tinyjs_be",
"authenticationType": "xsuaa",
"scope": "$XSAPPNAME.view"
}, {
"source": ".*\\.xsjs",
"destination": "tinyjs_be",
"scope": "$XSAPPNAME.create"
}, {
"source": "^/(.*)$",
"localDir" : "resources",
"scope" : "$XSAPPNAME.view"
}]
}
From now on, users must be granted with the scope tinyworld.view to view the content of the TinyWorld application.
For the changes to take effect, stop and rerun the tinyjs and tinyui modules. Once you rerun the modules, the application will become inaccessible since your user is not assigned to the required role collection yet. Role assignment will be done in the next step.
4. Create roles
Next you need to create actual roles from the role-template using the Application Role Builder, which is part of the XS Advanced Administration tools.
To use XS Advanced Administration tools you must be assigned with the appropriate authorizations. For now (SPS11) we will use the HANA Web-based Development Workbench, as follows:
Login to the HANA Web-based Development Workbench using user with appropriate privileges. The tool can be found in the following URL: http://<host>:<80><HANA instance>/sap/hana/ide/security (see the note below for more information about required authorizations).
Double click the needed user and navigate to the Application Role Collection tab, add the role collection XS_AUTHORIZATION_ADMIN and save.
Next you need to create actual roles from the role-template using the Application Role Builder, which is part of the XS Advanced Administration tools. The actual URL is installation dependent; to find out the URL, you can run the following command:
xs app xsa-admin
Use the URL to open the XS Advanced Administration tools in your browser:
Click on Application Role Builder. On the left pane click the tinyworld application (the application name corresponds to the XS appname attribute in the xs-security.json file).
You can see that default role instances were already created from the two role-templates with the same names. We use these convenient defaults in this tutorial.
Role instances themselves cannot be assigned to user, only role collections. Role collections are aggregations of roles needed to perform a specific task (by humans). In order to separate the View authorizations from the Create authorizations we need to create two different collections.
To create the role collections, navigate to the Role Collection maintenance screen by clicking the navigation button on the top-left corner of the screen.
In the left pane there is a list of existing role collections. Press the small plus button at the bottom of the screen to add a new collection.
- Enter name TinyViewRC
- Press the + (Add Application Role) to add roles to the collection. A popup is displayed
- Select application name – tinyworld
- Select Template Name – tinyworldView
- Select Application Role – tinyworldView
Press OK and then save the collection.
Repeat these steps to create an additional role collection TinyCreateRC. Select the corresponding template and role for Create.
Assign role collections to application user
The last authorization step is to assign the role collections to application users so end users will be able to use tinyworld. To do that we will use the Security application of HANA Web-based Development Workbench.
Expand the "Users" node and double click the user you would like to assign the roles to. Click on the "Application Role Collections" tab, add the TinyViewRC collection and Save.
Congratulations, the authorization check is now in place. To test your recent changes you must login again to your application (which will create a new security token containing the new scopes assigned to your user). Since there is no logout option in our simple application you have to restart your browser, or open a new incognito session.
NOTE: The following authorizations are needed in order to assign role collections.
- First, in order to grant roles and/or use the security application of HANA Web-based Development Workbench, you must have the SAP HANA role sap.hana.xs.ide.roles::SecurityAdmin. It can be granted using HANA Studio or using SQL.
- To be able to assign role collection to users, you must be granted with user admin and role admin privileges. These privileges can be assigned using HANA Web-based Development Workbench itself, using the "System Privileges" tab:
Or by running the following SQL commands
grant user admin to <user name>
grant role admin to <user name>
Summary of part 11
This part of the TinyWorld tutorial described how you can add authorization to your application. Currently, this is the last part of our TinyWorld tutorial. I hoped you enjoyed this series. Please keep checking back for more information about developing for SAP HANA and XS Advanced with the SAP Web IDE.
- SAP Managed Tags:
4 Comments
