This blog post series is about developing applications in a multi-cloud environment.
For the blog post about the SAP Business Technology Platform multi-cloud environment, see For the step-by-step series, visit
Questions? Post as comment. Useful? Give us a like and share on social media. Thanks! |
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
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.
https://youtu.be/CMJOqAeY3W4
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.
https://youtu.be/5Bn_ZineHIY?list=PLkzo92owKnVwAlv4joh1M5fhvaq8k0oaY
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.
https://youtu.be/WFbT0XeX_K0
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
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:
A user of a browser-based application (user agent) sends a request to the OAuth 2.0 client.
Since the application has no access token, the client redirects the request to the browser.
The application requests an authorization code at the authorization server.
The authorization server checks the validity of the request and grants an authorization code to the client.
The client receives the authorization code and requests an access token from the authorization server.
The authorization server issues an access token and grants it to the client.
The client presents the access token to request the resource on the resource server.
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
For a more detailed coverage, see the step-by-step tutorials
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.
- 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.jsonThe 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.
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
For a more detailed coverage, see the step-by-step tutorial
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.jsonWe 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.htmlCopy the source code from the repository
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
Business Logic | server.js
Create a new file:
myapp/server.jsWe 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
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: xsuaaAs 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-uaaFor 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: trueAdditional Information
Support
A good place to start is
Tutorials
For more tutorials, see
Blogs
- Guide for User Authentication and Authorization in SAP Cloud Platform by myriadbhoom
- Using Postman for API Testing with XSUAA by mariusobert
- 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
Over the years, for the SAP HANA Academy, SAP’s Partner Innovation Lab, and à titre personnel, I have written a little over 300 posts here for the SAP Community. Some articles only reached a few readers. Others attracted quite a few more. For your reading pleasure and convenience, here is a curated list of posts which somehow managed to pass the 10k-view mile stone and, as sign of current interest, still tickle the counters each month. |
- SAP Managed Tags:
