Explaining Application Security

In this lesson we will look at the Authentication steps involved in Application Security.

The following diagram shows the architecture with the components that are responsible for business user authentication, authorization management, and security.

Approuter – is Node JS library that is available in Public NPM. It represents a single entry point to your application.

Its tasks are:

• The Approuter dispatches requests to our back end microservices, thus acting as a reverse proxy. The back end microservices should not be directly accessible by the client.
• The Approuter can serve static content such as web pages, SAPUI5, or another client-side code.
• The Approuter manages the authentication flows for our entire application.

For authentication (who the user is) and authorization (what the user is allowed to do), the App Router takes all incoming, unauthenticated request and initiates an OAuth2 flow (authorization code grant) with the Extended Services for User Account and Authentication (XSUAA) service of the SAP BTP in the Cloud Foundry environment .

Main Properties on root level

• authenticationMethod

  This property indicates which authentication will be applied for this xs-app.json. Can be none (means that all routes are not protected) and route (authentication type will be chosen according to definition in a particular route). The default value is route .

• logout

  By using this property, you can define two important thing about your business application central logout handling.

  logoutEndpoint – contains some internal path. When accessing this path your application will trigger central logout procedure. Triggering central logout will destroy user session data in Approuter, call XSUAA in order to remove user session on their side and also will call logout paths of destinations that are defined for this specific application (please refer to property destinations).

  logoutpage – can be internal path or absolute external URL. Value of this field describes so called "landing page" page address, that user will be redirected in the browser after central logout.

• destinations

  This property indicates destinations endpoints that need to be called during session/central logout in order to destroy sessions on their side.

• services

  The same as destinations. Services can implement their specific logout logic and approuter will trigger these endpoints during central logout / session timeout scenario.

One of important capabilities of AppRouter is to be a reverse proxy for your application. In order to achieve that you need to model correctly property routes. That property is an array of Objects. Each object represents one particular route.

The App Router is a Node.js component, distributed via the publicly available SAP NPM registry

The SAP Authorization and Trust Management service lets you manage user authorizations and trust to identity providers. Identity providers are the user base for applications. You can use an identity authentication tenant, an SAP on-premise system, or a custom corporate identity provider. User authorizations are managed using technical roles at the application level, which can be aggregated into business-level groups and role collections for large-scale cloud scenarios.

Note

You can set up and run your own application router or you can use the application router that is managed by SAP (for more information see Managed Application Router).

SAP recommends running your standalone app router only in advanced cases, for example when application router extensibility is required

The managed application router enables you to access and run HTML5 applications in a cloud environment without the need to maintain your own runtime infrastructure.

The managed application router is the HTML5 applications runtime capability that is provided by the following products:

• SAP Work Zone

• SAP Launchpad service

• SAP Cloud Portal

To use the managed application router, you must be subscribed to one of these services.

OAuthCloud Foundry Applications use OAuth 2.0, When business users access an application, the application router acts as OAuth client and redirects their request to the OAuth authorization server for authentication. Runtime containers act as resource servers, using the container security API of the relevant container (for example, Java, Nodejs) to validate the token issued by the OAuth authorization server.

JSON Web Token (JWT)A JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self\u0002contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Although JWTs can be encrypted to also provide secrecy between parties, we will focus on signed tokens. Signed tokens can verify the integrity of the claims contained within it, while encrypted tokens hide those claims from other parties. When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

When should you use JSON Web Tokens?

Here are some scenarios where JSON Web Tokens are useful:

This is the most common scenario for using JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single Sign On is a feature that widely

uses JWT nowadays, because of its small overhead and its ability to be easily used across different domains.

JSON Web Tokens are a good way of securely transmitting information between parties. Because JWTs can be signed-for example, using public/private key pairs-you can be sure the senders are who they say they are. Additionally, as the signature is calculated using

the header and the payload, you can also verify that the content hasn't been tampered with.

The Extended Services - User Account and Authentication (XSUAA) service is one of the most important components to deal with when developing your own applications on Cloud Foundry. It takes care to authenticate and authorize your users and assign the right principals to your user’s session so your application can:

Identify the user by Email, UserId, First and Lastname

Check its roles (scopes) to decide if a user is allowed to do something or prohibit its action

The XSUAA is an internal development of SAP. SAP took the base of the open source UAA OAuth2 Provider of Cloud Foundry and extended it with SAP specific features to be used in SAP applications. One important thing is that the XSUAA does NOT store "real" users. This is why the XSUAA needs to trust an external Identity Provider (IdP).

Note

This graphic only applies to SAP Business Technology Platform cloud management tools Feature Set B. Check out User and Member Management in the SAP Help Portal pages to better understand the differences between Feature Set A and Feature Set B in regard to user management.

In Feature Set B, your SAP BTP global account has its own XSUAA tenant. This XSUAA tenant by default has a trust relationship to the SAP ID Service. The SAP ID Service manages a large base of users, that have created a user account with SAP. You can add users, that exist in the SAP ID Service, as members to your global and subaccount. In order for these users to be able to perform administrative tasks, they need to be assigned with corresponding role-collections. There is a set of default platform role-collections, like Global Account Administrator, Global Account Viewer, Subaccount Administrator or Cloud Connector Administrator that you can use for the purpose of assigning SAP BTP account management authorizations.

Contrary to the platform users from the SAP ID Service, your business users can also be provided via your own corporate identity provider. These are the users you want to provide access to your business applications. These might be SaaS applications provided by SAP, like SAP Business Application Studio or SAP Workflow Management, or your own applications that you develop on the SAP BTP. The business applications have their own role-collections, like e.g. Business_Application_Studio_Developer, WorkflowManagementAdmin, or any custom role-collection that you create for your application. It is planned by the end of 2021 to also support corporate identity providers for platform users.

The following image shows the relationships between role-collections, roles and scopes.

Scopes are arbitrary values that express authorizations / access rights in an application or service. Scopes need to be prefixed with an xsappname to make them uniquely identifiable.

Roles are entities that hold several scopes. Scopes can be put in multiple roles, so you are not limited to have scopes sitting in just one role.

Role-collections contain one or more roles. A role can be used in multiple role-collections. But it is totally fine to have for example a role-collection called Admin that only has an admin role.

Role-collections are stored as an assignment in the XSUAA and are THE entity that can be assigned to a certain business user.

Watch this video to learn more about the scope, role-collections, and roles. In this video, you can see that there are different personas. One is the developer working within a project and space. The other persona is an admin taking care of the CF account as a security admin.

What is a xs-security.json? To simplify things, let’s just call the xs-security.json the "declaration of your app’s security".

The following xs-security.json is an excerpt of the office supplies application being built in our example.

{
  "xsappname": "HC_OFF_SUPPLIES",
  "tenant-mode": "dedicated",
  "scopes": [
    {
      "name": "$XSAPPNAME.Vendor",
      "description": "Supplier"
    },
    {
      "name": "$XSAPPNAME.ProcurementManager",
      "description": "Manager"
    }
  ],
  "attributes": [],
  "role-templates": [
    {
      "name": "Vendor",
      "description": "Supplier",
      "scope-references": [
        "$XSAPPNAME.Vendor"
      ],
      "attribute-references": []
    },
    {
      "name": "ProcurementManager",
      "description": "Manager",
      "scope-references": [
        "$XSAPPNAME.ProcurementManager"
      ],
      "attribute-references": []
    }
  ]
}

You have to tell the XSUAA service how to call your application (xsappname) and further define your scopes and role-templates. The scopes are being used within the application to check concrete permissions whenever a user tries to perform a certain action.

In SAP Cloud Application Programming Model we do this by adding respective declarations to CDS models, which are then enforced in service implementations. By adding such declarations, we essentially revoke all default access and then grant individual privileges.

In essence, authentication verifies the user’s identity and the presented claims such as granted roles and tenant membership.

Briefly, authentication reveals who uses the service. In contrast, authorization controls how the user can interact with the application’s resources according to granted privileges. As the access control needs to rely on verified claims, authentication is a prerequisite to authorization.

From perspective of CAP, the authentication method is freely configurable and typically uses central identity and authentication services of the underlying platform.

For the local development scenario, CAP brings a built-in authentication on basis of mock users.

As basis for access control, you can design conceptual roles that are application specific. Such a role should reflect how a user can interact with the application. For instance, the role Vendor could describe users who can read sales articles. In contrast, a ProcurementManager can have full access to sales articles. Users can have several roles, which are assigned by an administrative user in the platform’s authorization management solution.

Note

CDS-based authorization deliberately refrains from using technical concepts such as scopes as in OAuth in favor of user roles, which are closer to the conceptual domain of business applications. This also results in much smaller JWT tokens.

Frequently, it’s required to define access rules that aren’t based on an application-specific user role, but rather on the authentication level of the request.

For instance, a service could be accessible not only for identified, but also for anonymous (for example, unauthenticated) users. Such roles are called pseudo roles as they aren’t assigned by user administration, but are added at runtime automatically.

The following predefined pseudo roles are currently supported by SAP Cloud Application Programming Model:

• authenticated-user refers to (named or unnamed) users who have presented a valid authentication claim such as a logon token.
• system-user denotes an unnamed user used for technical communication.
• any refers to all users including anonymous ones (that means, public access without authentication).

By default, CDS services have no access control. Hence, depending on the configured authentication, CDS services are initially open for anonymous users.

To protect resources according to your business needs, you can define restrictions that make the runtime enforce proper access control. Alternatively, you can add custom authorization logic by means of authorization enforcement API.

Restrictions can be defined on different CDS resources:

• Services
• Entities
• (un)bound actions and functions

You can influence the scope of a restriction by choosing an adequate hierarchy level in the CDS model.

For instance, a restriction on service level applies to all entities in the service.

Additional restrictions on entities or actions can further limit authorized requests. See section combined restrictions for more details. Beside the scope, restrictions can limit access to resources with regards to different dimensions:

• The event of the request, that is, the type of the operation (what?)
• The roles of the user (who?)
• Filter-condition on instances to operate on (which?)

Annotate entities with @readonly or @insertonly to statically restrict allowed operations for all users as demonstrated in the example:

service Catalogservice { 
@readonly entity Products {...}  
@insertonly entity Suppliers {...}
}

Note

Note that both annotations introduce access control on entity level. In contrast, for sake of input validation, you can make use of @readonly also on property level.

@requires: allows specifying one or more user roles (as a single string or an array of strings) that the current user must be assigned.

@restrict: allows fine-grained control through an array of privileges given as grant statements in the form {grant:<operation>, to:<roles>, ...}

service CatalogService @(requires: 'authenticated-user')
{    
    @odata.draft.enabled :true      
    entity Suppliers @(restrict : [
     { grant : [ 'READ' ], to : [ 'Vendor' ] },
     { grant : [ '*' ], to : [ 'ProcurementManager' ] }
     ])as projection on officesupplies.Suppliers;
    entity Products @(restrict : [
     { grant : [ 'READ' ], to : [ 'Vendor' ] },
     { grant : [ '*' ], to : [ 'ProcurementManager' ] } 
     ])as projection on officesupplies.Products;
 
};

whereas the properties are:

• grant one or more events the privilege applies to
• to:one or more user roles the privilege applies to (optional)
• where: a filter condition that further restricts access on instance level (optional)

Following values are supported:

• grant accepts all standard CDS events (such as READ, CREATE, UPDATE, and DELETE) as well as action and function names. WRITE is a virtual event for all standard CDS events with write semantic (CREATE, DELETE, UPDATE, UPSERT) and * is a wildcard for all events.
• The toproperty lists all user roles or pseudo roles the privilege applies to. Note that pseudo-role any does apply for all users and is the default if no value is provided.
• The where-clause can contain a boolean expression in CQL-syntax that filters the instances the event applies to. As it allows user values (name, attributes etc.) and entity data as input, it’s suitable for dynamic authorizations based on the business domain. Supported expressions and typical use cases are presented in instance-based authorization.

A privilege is met, if and only if all properties are fulfilled for the current request. In the following example, only orders can be read by an Vendor who meets Buyer element of the instance:

entity Suppliers @(restrict: [
    { grant: 'READ', to: 'Vendor', where: 'Buyer = $user' }
  ]) {/*...*/}

If a privilege contains several events, only one of them needs to match the request event to comply with the privilege. The same holds, if there are multiple roles defined in the to property:

service Catalogservice @(restrict: [ 
    { grant:['READ', 'WRITE'], to: ['Vendor', 'ProcurementManager'] } 
  ]) {/*...*/}

In this example, all users that have role VendororProcurementManger can read or write on Catalogservice.

You can build restrictions based on multiple privileges:

entity Suppliers @(restrict: [
    { grant: ['READ','WRITE'], to: 'Vendor' },
    { grant: 'READ', where: 'buyer = $user' }
  ]) {/*...*/}

A request passes such a restriction if at least one of the privileges is met. In this example, Admin users can read and write entity Suppliers. But also a user can read all Suppliers, which have a buyer property that matches the request user.

Similarly, the filter conditions of matched privileges are combined with logical OR:

entity Suppliers @(restrict: [
    { grant: 'READ', to: 'Vendor', where: 'country = $user.country' },
    { grant: ['READ','WRITE'], where: 'CreatedBy = $user' },
  ]) {/*...*/}

Here an Vendor user can read all Suppliers with matching country or which has been created by him- or herself.

Annotations such as @requires or @readonly are just convenience shortcuts for @restrict, for example:

• @requires: 'Vendor'is equivalent to@restrict: [{grant:'*', to: 'Vendor'}]
• @readonlyis the same as@restrict: [{ grant:'READ' }]

Supported Combinations with CDS Resources Restrictions can be defined on different types of CDS resources, but there are some limitations with regards to supported privileges:

Note

¹Node.js supports static expressionsthat don’t have any reference to the modelsuch as

where: $user.level = 2.

Basically, the access control for entities in draft mode differs from the general restriction rules that apply to (active) entities. A user, who has created a draft, should also be able to edit (UPDATE) or cancel the draft (DELETE). The following rules apply:

• If a user has the privilege to create an entity (CREATE), he or she also has the privilege to create a new draft entity and update, delete, and activate it.
• If a user has the privilege to update an entity (UPDATE), he or she also has the privilege to put it into draft mode and update, delete, and activate it.
• Draft entities can only be edited by the creator user.

Note

As a result of the derived authorization rules for draft entities, you don’t need to take care of draft events when designing the CDS authorization model.

To enable authentication support in CAP, a node.js module called passport needs to be installed.

Install the passport module. (the --save part makes sure it’s also added as a dependency to your project's package.json)

npm install --save passport

Once the authorization checks have been added to the CAP model, they apply not only when deployed to the cloud but also for local testing. Therefore, you will need a way to log in to the application locally.

SAP Cloud Application Programming Model allows you to add local users for testing as part of the cds configuration. We use the .cdsrc.json file to add the users.

The .cdsrc.json file can be used to store project configurations like in the package.json file.

{
 "[development]": {
 "auth": {
    "passport": {
        "strategy": "mock",
        "users": {
            "vendor@tester.sap.com": {
            "password": "initial",
            "ID": "Vendor",
            "userAttributes": {
            "email": "vendor@tester.sap.com"
        },
        "roles": ["Vendor"]
        },
            "ProcurementManager@tester.sap.com": {
            "password": "initial",
            "ID": "ProcurementManager",
            "userAttributes": {
            "email": "ProcurementManager@tester.sap.com"
        },
        "roles": ["ProcurementManager"]
            }
          }  
         }
        }
    }
 }"]
 }
 }
 }
 }
 }
 }

Note

There’s no logout functionality yet. To clear the basic authentication login data from the browser cache, you can either clear the browser cache or simply close all browser windows.