End-to-End Tutorial | Developing Secure Applications on the SAP Business Technology Platform Cloud Foundry Runtime

Hands-On Tutorial

Developing Secure Applications on SAP BTP: End-to-End

In this blog series, we explore in some detail how we can use XSUAA service instances in the SAP Business Technology Platform (BTP), Cloud Foundry (CF) environment for authentication and authorisation.

In this blog post, you will find a brief summary of the exploration with an end-to-end example.

You can download the sample code from repository

• github.com/saphanaacademy/XSUAA

Part I – Business Applications, XSUAA and Scopes

In the first video, we explain the concept of a business application and the MTA concept. We start our exploration with the XSUAA service.

Part II – Application Router and Business Logic App

In part two, we continue our exploration and cover the application router and business logic app components.

Part III – Deploy and Review

In part III we build and deploy the business application to the platform and review the apps, services, and security artifacts in the cockpit administration tool and check the token and scopes of the app.

SAP BTP | Prerequisites

Although we aim to provide an end-to-end tutorial, we assume the BTP domain model and the environment have been configured and the tools installed. We also also assume you are familiar with platform user and business users. Below a short summary.

Accounts and Environments

Out of scope of this end-to-end tutorial are

• BTP global accounts with the different account types and entitlements – the commercial area we could say – with the notion of subaccounts which map to a regional data center hosted by a cloud provider, like AWS in Frankfurt, Germany or Azure in Singapore.
• Kyma and ABAP environments; for this tutorial series we are only concerned with the Cloud Foundry environment to host our applications and services.

Tools

As tools, we will be using the BTP cockpit, a code editor, the Cloud Foundry CLI, command line interface with a plugin developed by SAP to deploy multi-target applications or MTAs.

For more information about account model setup, creating subaccounts, enabling Cloud Foundry and creating orgs and spaces, cf CLI installation and connecting to the platform, see

• SAP BTP Developer Onboarding | Hands-on Video Tutorials
• Basic Platform Concepts | SAP BTP

Users and Identify Providers

There are two type of user accounts: platform users and business users.

• Platform users serve to deploy and administer servces and applications in an environment. That is our role.
• Business users, or end users, to use another common term, are the ones using our apps.

For both user types, SAP ID Service is the default identity provider, but these are separate entities, and can be configured to use a different IdP as corporate user store. Microsoft Active Directory, for example, either in the cloud or on-premises.

Business Application Pattern

Microservices

The figure illustrates the pattern for business application development in the SAP BTP Cloud Foundry environment.

The business logic is provided by one or typically multiple apps, developed and deployed as microservices, which bind to service instances for logging, persistence, security, and other functionality relevant but not distinctive to our application.

XSUAA Service Instances

Security is one such service. In the Cloud Foundry environment this service is  provided by the UAA component, short for User Accounts and Authentication, or more precisely, by the XSUAA component, an SAP adaptation for SAP BTP.

This component was initially developed for the SAP HANA XS Advanced model, XSA in short, which provided a local Cloud Foundry environment for application development with runtimes for the SAP HANA in-memory platform, hence the XS in XSUAA.

As a platform service, we need to instantiate XSUAA, that is, to create a dedicated service instance. This allows us to configure the service with the authorisations, scopes and role templates, specific to our app.

We also will be adding  an application router, in itself another microsservice, to act as the browser access endpoint and to route the different service requests to the appropriate microservice.

Browser access endpoint means that this is the URL that the business user connects to and remains connected to, even though the content may be served by other microservices apps.

OAuth

In technical terms, UAA is the OAuth authorization server, the App Router the OAuth client, and our app containing the business logic, the OAuth resource server.

The authentication and authorization flow is illustrated in the next figure with the following steps:

1. A user of a browser-based application (user agent) sends a request to the OAuth 2.0 client.

2. Since the application has no access token, the client redirects the request to the browser.

3. The application requests an authorization code at the authorization server.

4. The authorization server checks the validity of the request and grants an authorization code to the client.

5. The client receives the authorization code and requests an access token from the authorization server.

6. The authorization server issues an access token and grants it to the client.

7. The client presents the access token to request the resource on the resource server.

8. In the final step, the resource server validates the access token and allows the client to access the resource.

Hotel Room and Key Card

To use a common analogy, the resource service could be a hotel room, the App Router the concierge, and UAA the receptionist. The receptionist first authenticates the business user, for example using a passport issued by an identify provider, based on a trust relationship. Then the authorisation is established. This could be prepaid fee or credit card. With this information, a key card is generated which the business user can use to consume the service, that is access the room, maybe access the parking lot, open the safe, or the minibar. To consume these services, the business user does not have to show passport and credit card, just the key card, the JWT, suffices, and like a key card, a JWT typically expires after some time and does not contain any personal information, just the authorisations.

XSUAA Service Instance

XSUAA is available as a service on SAP BTP and provides both authentication and authorization to business applications.

• For authentication no additional configuration is required.
• For authorization, we need to configure the authorization security descriptor.

For more information, see the service reference on the SAP Discovery Center

• Authorization and Trust Management

For a more detailed coverage, see the step-by-step tutorials

• Authentication using XSUAA
• Authorization using XSUAA

Authentication and Default Identity Provider (IdP)

The XSUAA service instances provides authentication out-of-the-box for our business application using the default identity provider SAP ID services. This requires no additional configuration.

You can use Trust Configuration under Security for the subaccount to configure an alternative IdP.

As documented

• Trust and Federation with Identity Providers | SAP Cloud Platform

Authorization and the Application Security Descriptor | xs-security.json

The application security descriptor xs-security.json file defines authorizations. For this we use OAuth scopes. At runtime, the UAA validates the scope, which are part of a role, and roles are bundled in a role collection.

For our sample app, after deployment we will use the SAP Cloud Platform cockpit to manually assign the role collection to the business user. In practice, XSUAA role collections are mapped to IdP user groups.

For the documentation, see

• The Application Security Descriptor | SAP BTP
• User Account and Authentication (UAA) Server > Scopes | Cloud Foundry

Hands On

Create a new file:

xs-security.json

The header defines app name and whether the configuration is shared or dedicated.

  "xsappname": "myapp",
  "tenant-mode": "dedicated",

Scopes

In the section scopes, the scopes are defined.

  "scopes": [
    {
      "name": "uaa.user",
      "description": "Token Exchange"
    },
    {
      "name": "$XSAPPNAME.User",
      "description": "User Scope"
    },
    {
      "name": "$XSAPPNAME.Admin",
      "description": "Admin Scope"
    }
  ],

The uaa.user scope simply validates the user as an authorized user. This is a default scope.

• 2876853 – User does not have scope “uaa.user” / JWT token does not include scope “uaa.user”

Variable $XSAPPNAME is mapped when the application is bound to the XSUAA instance.

Role Template

The scopes are referenced in role templates. In our example, the MyApp Administrator role template contains both the User and the Admin scope.

 "role-templates": [
    {
      "name": "TOKEN_EXCHANGE",
      "scope-references": [
        "uaa.user"
      ]
    },
    {
      "name": "MyAppUser",
      "description": "MyApp User",
      "scope-references": [
        "$XSAPPNAME.User"
      ]
    },
    {
      "name": "MyAppAdministrator",
      "description": "MyApp Administrator",
      "scope-references": [
        "$XSAPPNAME.User",
        "$XSAPPNAME.Admin"
      ]
    }
  ],

XSUAA instantiates the roles based on the role template.

Role Collection

The role templates are referenced in role collections, excluding the built-in uaa.user scope.

  "role-collections": [
    {
      "name": "MyApp User",
      "description": "MyApp User",
      "role-template-references": [
        "$XSAPPNAME.MyAppUser"
      ]
    },
    {
      "name": "MyApp Administrator",
      "description": "MyApp Administrator",
      "role-template-references": [
        "$XSAPPNAME.MyAppAdministrator"
      ]
    }
  ]

Application Router

The application router provides the browser access end-point, which is the URL the business user (or more precisely the User Agent) connects to and remains connected to regardless what microservice app function is executed.

Application router is an SAP-provided package. For our business application we need to configure the routes and provide a home page.

For information about the package, visit

• www.npmjs.com/package/@sap/approuter

For a more detailed coverage, see the step-by-step tutorial

• Application Router

Application Descriptor File | package.json

Create a new file:

approuter/package.json

Enter the approuter package as dependency with start command.

{
  "name": "approuter",  
  "dependencies": {
     "@sap/approuter": "latest"
  },
  "scripts": {
     "start": "node node_modules/@sap/approuter/approuter.js"
  } 
} 

Application Router Configuration File | xs-app.json

The application router configuration file defines the routes (amongst others, see the documentation).

Hands On

Create a new file:

xs-app.json

We can map a scope to a specific route. The destination is an environment variable defined when the app router is bound to an XSUAA instance.

// sample, do not copy
    "routes": [
        {
            "source": "/sample/(.*)",
            "destination": "sampledestination",
            "authenticationType": "xsuaa",
            "scope": "$XSAPPNAME.SampleScope"
        },

For our sample application, we only require authenticated users for the /srv route, which will define in the business logic app. The target or destination is defined in the deployment descriptor (below).

For the root route (/) no authentication is required and this maps to a local directory of the app router.

  "routes": [
      {
          "source": "^/srv/(.*)$",
          "authenticationType": "xsuaa",
          "scope": "uaa.user",
          "destination": "srv"
      },
      {
          "source": "/(.*)",
          "authenticationType": "none",
          "localDir": "resources"
      }
  ]

Application Router Home Page | index.html

Create a new file:

approuter/resources/index.html

Copy the source code from the repository

• index.html

The app router home page is publicly accessible (“authenticationType”: “none”) and contains two images from app router resources (static content).

The page also references three URLs using the /srv/ route using xsuaa authentication

• /srv/authinfo
• /srv/user
• /srv/admin

The first hyperlink returns the authentication information which includes the JTW (token). You can use the JSON Viewer Chrome extension to format the page.

You can use jwt.io to decode the token.

Business Logic App(s)

XSUAA and App Router provide the security infrastructure. How the authorization is mapped to the business logic is defined in the service apps, the OAuth2 resource providers.

For application written in Node.js, SAP provides several packages to simplify the security configuration.

• Authentication for Node.js Applications | SAP BTP
• @sap/xssec: XS Advanced Container Security API for node.js

For a more detailed coverage, see the step-by-step tutorials

• Authorization using XSUAA

Business Logic | server.js

Create a new file:

myapp/server.js

We implement the “ready-made authentication strategy” using xsenv, xssec, and passport, as documented.

// As documented
// https://www.npmjs.com/package/@sap/xssec
// https://www.npmjs.com/package/@sap/xsenv
var JWTStrategy = require('@sap/xssec').JWTStrategy;
var xsenv = require('@sap/xsenv');
var express = require('express');
var passport = require('passport');
var app = express();
passport.use(new JWTStrategy(xsenv.getServices({xsuaa:{tag:'xsuaa'}}).xsuaa)); 
app.use(passport.initialize());
app.use(passport.authenticate('JWT', { session: false }));

The /srv/authinfo route referenced in the application router home page returns all authentication information including the JWT token and public key as shown above.

app.get('/srv/authinfo', function (req, res) {
    res.status(200).json(req.authInfo);
});

The other routes check for the presence of a scope; the order is reversed for the Admin scope to illustrate that multiple approaches are possible.

app.get('/srv/user', function (req, res) {
    var isAuthorized = req.authInfo.checkScope('$XSAPPNAME.User');
    if (isAuthorized) {
        res.status(200).json(req.authInfo.scopes);
    } else {
      res.status(403).send('Forbidden');
    }
  });
  
  app.get('/srv/admin', function (req, res) {
    const isAuthorized = req.authInfo.checkScope('$XSAPPNAME.Admin');
    if (!isAuthorized) {
      res.status(403).json('Forbidden');
      return;
    }
    res.status(200).json(req.authInfo.scopes);
  });

Application Descriptor File | package.json

Create a new file:

myapp/package.json

Enter the approuter package as dependency and provide the start command (as a minimum).

{
  "dependencies": {
    "@sap/xsenv": "^3.0.0",
    "@sap/xssec": "^2",
    "express": "^4.17.1",
    "passport": "^0.4.1"
  },
  "scripts": {
    "start": "node server.js"
  }
}

Multi-Target Application Deployment

Deploy the business application using the MTA specification and related tools.

For a more detailed coverage, see the step-by-step tutorial

• Multi-target applications (MTA)

MTA Development File | mta.yaml

Create a new file:

mta.yaml

In the resource section, define the XSUAA service instance configuration with reference to the xs-security.json file. As an alternative, we can also directly enter scopes, role templates, and role collections.

resources:
  - name: myapp-uaa
    type: org.cloudfoundry.managed-service
    parameters:
      path: ./xs-security.json
      service-plan: application
      service: xsuaa

As module, define the business application with the myapp-uaa service instance as dependency. Also specify the URL for the app: ${default-url} is mapped to <subaccount>-<space>-<appname> as host and cfapps.<region>hana.ondemand.com as domain.

8e3c745atrial-dev-myapp-srv.cfapps.eu10.hana.ondemand.com

Memory and disk-quota parameters are optional.

modules:
  - name: myapp-srv
    type: nodejs
    path: myapp
    parameters:
      memory: 128M
      disk-quota: 512M
    provides:
      - name: srv_api
        properties:
          url: ${default-url}
    requires:
      - name: myapp-uaa

For the application router, define the XSUAA service instance and business app API as dependency. We also define the route /srv/ referenced in the business app logic (server.js) and the application router configuration (xs-app.json).

  - name: myapp-approuter
    type: nodejs
    path: approuter
    parameters:
      memory: 128M
      disk-quota: 256M
    requires:
      - name: myapp-uaa
      - name: srv_api
        group: destinations
        properties:
          name: srv
          url: ~{url}
          forwardAuthToken: true

Additional Information

Support

A good place to start is

• Troubleshooting for Authorization and Trust Management in the Cloud Foundry Environment

Tutorials

For more tutorials, see

• Tutorials for Authorization and Trust Management

Blogs

• Guide for User Authentication and Authorization in SAP Cloud Platform by Bhoomika Agarwal
• Using Postman for API Testing with XSUAA by Marius Obert
• SAP Application Router by Zvi Zeltser

Share and Connect

Questions? Please post as comment.

Useful? Give us a like and share on social media.

Thanks!

If you would like to receive updates, connect with me on

• LinkedIn > linkedin.com/in/dvankempen
• Twitter > @dvankempen

For the author page of SAP PRESS, visit

• Denys van Kempen