Skip to Content
Technical Articles
Author's profile photo Denys van Kempen

Getting Started with Multitenant Business Applications on SAP BTP | Hands-on Video Tutorials

The SAP Cloud Platform video tutorial series from SAP Partner Engineering | SAP HANA Academy has just been updated to include the latest features, interfaces, and insights about creating multitenant business applications.

In this blog post you will find the videos embedded with references and additional information.

For the previous blog post, see

In this blog we are going to get started with the development of multitenant business applications and you will find the videos embedded with references and additional information.

Any good? Post a comment, share on social media, and/or give a like. Thanks!


Hands-On Video Tutorials

Philip MUGGLESTONE just updated his Developing Multitenant Business Applications video tutorial series for the SAP Cloud Platform. In this blog, you will find the videos embedded with some additional information and resources. Following along in the patented zero-to-hero format, you will be ready to start developing business applications on the platform with minimal effort and no time wasted.

You can watch the 10 video tutorials in a little under 100 minutes. What you learn is

  • Multitenant business application concepts and components, including the UAA service, SaaS Registry, and routes.
  • How to use SAP Business Application Studio (BAS) and yeoman to generate the scaffolding for the app and how to build and deploy the MTA (multi-target app) to SAP Cloud Platform using BAS (reprise)
  • How to configure the app to automatically generate the unique tenant routes (and remove the routes when unsubscribing)
  • How to configure dependencies
  • How to use SaaS provisioning service APIs to manage multitenant applications
  • How to configure persistence, for example using SAP HANA Cloud HDI
  • How to configure custom domains for multi-tenant apps

As development environment we use the SAP Business Application Studio and the free 90-day SAP Cloud Platform trial environment, for which you can sign up here:

To follow along you will need some basic understanding of the SAP Cloud Platform concepts and be familiar with global and subaccounts, Cloud Foundry, destinations, subscriptions, identity provider, SAP HANA Cloud, and HDI. In case you are new to the SAP Cloud Platform or could use an update, please first join our onboarding program:

As we know your time is precious, this will be a low-code affair as we will be using Yeoman to provide the scaffolding for our app supplemented with sample code from SAP HANA Academy GitHub repository:

Ready? Let’s build some apps!

Multitenant Business Application Architecture diagram (large-scale)

For the binge-watchers here is the complete playlist:


For the documentation, see

For related blog post here on the SAP Community, see


Getting Started

In the first video, the concepts of multitenant SaaS business applications are introduced and where you find this documented. We demonstrate how such an app would work, with isolated database connectivity using HDI containers in SAP HANA Cloud, and dedicated destinations, for example to a back-end private to the tenant.

As always, no smoke-and-mirrors: we can easily subscribe a new tenant and remove one as well and all this in a short 7-minute demo.

0:00 – Introduction

1:10 – Documentation and architecture

3:15 – Demo sample multitenant SaaS business application

5:10 – Subscribe new consumer

8:20 – Create new destination (for back-end connectivity)

9:00 – Offboard subscriber(s)

9:20 – SAP Business Application Studio

9:55 – Create application scaffolding using the Yeoman app generator


First Application – Part I and II

In the first two videos we are going to build a very basic version of the multitenant application to show how everything fits together. In the first video, we scaffold the project and do a bit of code walkthrough. In the second video, we are going to build, deploy, and test the app. After verifying that everything works as expected, we also delete everything so we can start with a clean slate again.

Access the SAP Business Application Studio from your SAP Cloud Platform (trial) subaccount  Subscriptions and create a new Dev space for this project using the Basic tool extension with MTA Tools as additional extension. Next, install the Yeoman code generator and generate the scaffolding for our app.

0:00 – Introduction

0:30 – Open SAP Business Application Studio, create a new dev space (extension Basic + MTA Tools) and open the default workspace.

0:55 – Open terminal and install the yeoman application generator

1:10 – Generate first application (using defaults and No for the advanced options)

1:50 – Generated code walkthrough: multi-target application with app (router) and srv (backend)

2:30 – Application manifest file mta.yaml with XSUAA service and SaaS Registry service

6:30 – Security configuration xs-security.json file with tenant-mode, scopes, and role templates

7:45 – Index.html and xs-app.json file with routing and authorisation settings.

8:20 – Backend Node.js application server.js file with endpoint to on- and offboard, and access

Code Snippets and Commands

Command to install the generator

npm i -g generator-saphanaacademy-saas

Command to generate the app

yo saphanaacademy-saas

0:00 – Introduction

0:30 – Execute Build MTA command

0:40 – Deploy the generated mtar (MTA archive) and provide the Cloud Foundry API endpoint, login and specify Org and space (e.g. trial / dev). This will create the UAA service, and SaaS Registry entry.

1:20 – Access the SAP Cloud Platform cockpit and verify that the app (router) and the srv (backend) apps are up and running (Applications) with bindings to the registry and uaa (Services).

2:10 – Two routes are defined (Routes)

2:30 – Create new subaccount using the same provider and region (e.g. AWS Europe) as the application with a unique subdomain for that environment

3:00 – Connect to the subaccount and navigate to Subscriptions and subscribe to the app (My SaaS App); this will call the subscribe endpoint from Node.js application (server.js)

4:00 – Under Security > Trust Configuration > IdP (sap.default) assign the role collection (e.g. myappsaas_Administrator or _User) as defined in the xs-security.json.

5:00 – Create a new route for the subscription and map it to the application (myappsaas)

6:20 – Unsubscribe

7:00 – Undeploy application from the command line

8:00 – Navigating the UI shows that there are no more apps and services or subscriptions for the consumer subaccounts, nor any role collections.

9:00 – Remove project from the app studio.

Code Snippets and Commands

Command to remove app and services (without confirmation prompt)

cf undeploy myappsaas --delete-services -f

Yeoman input, mta.yaml configuration, and output in the SCP cockpit.



Now that we have seen how (easily) we can create multitenant applications we are now going to make it even easier by automatically generating the route for each new subscription (and each unsubscribe).

0:00 – Introduction

0:30 – From the terminal in SAP Business Application Studio run the yeoman generator again with same responses except for the Would you like to include creation/deletion of tenant routes on subscribe/unsubscribe (using the CF API)?

01:00 – Code walkthrough: Node.js server.js file now include lib.createRoute and deleteRoute functions, defined in library.js

06:00 – Documentation reference Cloud Foundry API

07:00 – After the app is deployed we need to define with cf set-env the environment variables to authenticate the API user used to create the subscription routes

07:40 – Deploy the MTAR

07:50 – Verify apps and services in SCP cockpit

08:20 – Set environment variables for the technical user and restage the application (required after each redeployment)

09:00 – Switch to Consumer subaccount and subscribe: routes are automatically generated

09:45 – Assign role collection

10:10 – Unsuscribe

Code Snippets and Commands

cf set-env myappsaas-srv cf_api_user '<email>'
cf set-env myappsaas-srv cf_api_password '<password>'
cf restage myappsaas-srv



In this video tutorial, we are going to take a look at how you can advantage of multitenant-aware  services within Cloud Foundry, for example a destination service to access a backend system. This destination service needs to be unique for each tenant, yet we do not want to create a dedicated destination service for each subscription. Other examples are the job scheduler or the connectivity service.

00:00 – Introduction

01:00 – From the terminal in SAP Business Application Studio run the yeoman generator again with default settings except for

  • Would you like to include creation/deletion of tenant routes on subscribe/unsubscribe (using the CF API)? y
  • Would you like to include an example of using the destination route service? y

01:30 – Code walkthrough: destination service added to mta.yaml with getDestination called and defined in server.js and library.js. An entry in index.html enables us to show the response of the call.

05:45 – Build and deploy application

06:10 – Using SAP Cloud Platform cockpit create destination in the tenant subaccount

06:30 – Create new tenant subaccount (“consumer 2”) with destination

07:30 – Verify deployment of application and services, including the destination service

07:50 – Subscribe as consumer 1 and 2 and authorise users (end user role)

08:30 – Run the application to get information about destination of subscriber 1 and 2


Registry API

In this video tutorial, we learn how to make use of the SaaS Provisioning service Restful API to manage consumer/tenant subscriptions. An example of using the RESTful API from the multitenant application is shown – followed by how to access the API via Postman.

This topic is documented in the SAP Cloud Platform Guide:

00:00 – Introduction and documentation

01:10 – From the terminal run the yeoman generator with default settings except for

  • Would you like to include an example of the SaaS API (view subscription)? y

03:20 – Code walkthrough:

  • index.html: link to subscription added
  • server.js: lib.getSubscriptions
  • library.js: getSubscriptions and access token

03:30 – Build and deploy

03:45 – SAP Cloud Platform cockpit: subscribe, add role collection, add route, and show API output

05:45 – Get call URL, client secret and client ID from service bindings

06:45 – Get the token

07:30 – Call URL with token as header (authorisation: Bearer <token>)


Persistence – Part 1, 2, and 3

In this video tutorial, we are going to build, deploy and test the multitenant business application example with schema separation using SAP HANA Cloud and HDI containers. We also learn how to get details of HDI containers created via service manager using a ServiceManagement plugin for the Cloud Foundry CLI.

00:00 – Introduction and concepts

00:00 – Introduction

00:50 – SAP HANA Cloud instance created with all IP addresses allowed (advanced settings)

01:15 – From the terminal run the yeoman generator with default settings except for

  • Would you like to include HANA persistence (schema separation) y
  • Would you like to include creation/deletion of tenant routes on subscribe/unsubscribe (using the CF API)? y

01:20 – Code walkthrough:

  • mta.yaml: db module and service manager
  • db module
  • index.hmtl
  • server.js: referencing service manager, lib.createSMInstance
  • package.json: hdbext
  • library.js

00:00 – Introduction

00:30 – Build and deploy

00:50 – Set API user and password as environment variables for CF API and restage app

01:10 – SAP Cloud Platform cockpit: apps and services

02:25 – Install Service Management CF-CLI plugin for SAP Business Application Studio

03:35 – Subscribe first consumer, add role collection, go to application

05:00 – Subscribe second consumer

06:50 – Unsubscribe

07:30 – Recap

Code Snippets and Commands

See the SAP HANA Academy GitHub repository for the plugin

curl -LJ0
cf install-plugin ServiceManagement.linux64

To view the Service Management instances use command

# cf smsi <instance name.
cf smsi myappsaas-sm


Custom Domains

In this video tutorial, we learn how to configure a multitenant business application with a custom domain. This involves generating, building, deploying and testing an example application and explains how to configure “wildcard” host mapping.

Custom domains are only available on production global accounts and not on the trial environment.

As prerequisite, first watch the SAP Cloud Platform Onboarding Video tutorials to learn how to configure your subaccount, create certificates, and other requirements.

00:00 – Introduction and prerequisites

01:00 – Custom domain service as service instance in SAP Cloud Platform cockpit

01:30 – SAP Business Application Studio showing cf domains and cf cdl commands

02:30 – From the terminal run the yeoman generator with default settings except for

  • Would you like to include an example of the SaaS API (view subscription)? y
  • Would you like to include HANA persistence (schema separation) y
  • Will you be using a wildcard custom domain (eg: If so please enter it here <>
  • Would you like to include an example of using the destination route service? y

03:20 – Code walkthrough:

  • xs-security.json: oauth2-configuration added
  • mta.yaml: host and domain added to each application and tenant host pattern
  • server.js: subscribe/unsubscribe

06:55 – Build and deploy

07:15 – Check the routes and add custom route

08:10 – Subscribe and validate configuration

Code Snippets and Commands

cf domains
cf cdl
cf routes
# cf map-route <router application> <custom domain> --hostname "*"
cf map-route myappsaas --hostname "*"


Share and Connect

Questions? Please post as comment.

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


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

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.


Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Gopal Anand
      Gopal Anand

      Hi @denys.kempen,

      Thanks alot for this blog. It covers almost all the topics needed for saas. I have tried and things are working fine in trial account. But in canary when I am trying to access the "/srv/info", it's taking to uaa's domain to login isntead of tenant's authentication domain which is : "". The same behaviour occurs when I am trying to deploy a sample SAAS application using manifest.yaml.

      My subdomain looks like this: "someorgname-saas-dev"

      Is there any specification for having a subdomain/org name in order redirect to the correct authentication URL or if there's anyone that can help in resolving the issue.

      Best regards,


      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Gopal,

      You get this generic login screen when the approuter hasn't been able to determine the subdomain name of your subaccount via the TENANT_HOST_PATTERN environment variable. You need to either adjust the TENANT_HOST_PATTERN or potentially change the hostnames of the app from the default. It very much depends on how similar or different the subdomain name and the org name are.

      If you can share the full route (URL) of your deployed approuter module as well as your TENANT_HOST_PATTERN value and the subdomain name of the subaccount (visible in overview page of cockpit) and the org name of the subaccount I should be able to help further.



      Author's profile photo Gopal Anand
      Gopal Anand

      Hi Philip,

      Here's My url:

      The subdomain & org name is : "referenceapps-ga-saas".

      The tenant host pattern:



      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Gopal,

      So the issue here is the syntax in manifest.yml.

      There's no need to enclose TENANT_HOST_PATTERN in quotes - in fact using quotes causes the matching to fail.

      Use the following syntax for manifest.yml:


      Whereas in a mta.yaml you need to enclose in single quotes:

       TENANT_HOST_PATTERN: '^(.*)'



      Author's profile photo Neil Prince
      Neil Prince

      Hi Gopal

      I ran into the same issue. Create a subdomain and org name without any dashes '-' in it. I have an open support ticket with SAP where I detailed the issue.

      Let me know how you go.\



      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Neil,

      I have examples working that include dashes in the subdomain/org name. So I suspect your issue might be something else.

      When you get the “XS Advanced” authentication screen it means the approuter wasn’t able to extract the tenant (subaccount subdomain) name from the called application URL (route) so was unable to generate the correct authentication URL for the tenant.





      Author's profile photo Gopal Anand
      Gopal Anand

      Hi Neil Prince

      the issue was with tenant host pattern, I was using quotes to enclose the host pattern which was causing the issue.

      My subaccount, org together have 3 dashes in the name, it's still working there. 🙂

      Please look above for Philip's solution.


      Best regards,



      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Hello Denys van Kempen , Philip MUGGLESTONE

      Thank you for the blog post and video tutorials! Very helpful!

      I also followed IV - Local Development and currently trying out a setup for local development of a multitenant app. When trying to start the approuter locally using default-env.json I'm not sure how the TENANT_HOST_PATTERN should look like. Do you have any info on this?

      Thank you,

      Best regards,


      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hello Stefania Santimbrean ,

      Thanks for watching and your interesting question.

      It's rather tricky to do local development / testing of a multi-tenant app because the approuter has to correctly identify the tenant.

      From the @sap/approuter doc:

      In a multi-tenancy landscape, the application router will calculate the tenant id based on the value of a certain request header as follows:

      x-custom-host header or host if EXTERNAL_REVERSE_PROXY is true
      x-forwarded-host header or host if EXTERNAL_REVERSE_PROXY is false or not specified

      So all requests to approuter need to include the host header which contains the tenant which can be decoded via the TENANT_HOST_PATTERN. Effectively the tenant value matches the subdomain value for the tenant subaccount. This is true when calling the Cloud Foundry URL for the app such as:

      However when running locally the URL such as http://localhost:5000 clearly does not contain the tenant value!

      One approach could be to provide the x-forwarded-host header explicitly on all approuter requests when using a tool like Postman.

      From a browser, and assuming you're OK with doing an unsupported "hack", you could make a small change to the @sap/approuter source code in your test/dev project (this kind of thing is not formally supported by SAP so it's really at your own risk but does make it possible to enable local dev). In node_modules/@sap/approuter/lib/utils/url-utils.js look for the function getAppRouterHost and change the last line (return statement) to manually return the app URL of the desired tenant (which should already be subscribed of course). Something like this:

      return '';


      For this to work you also need to configure the xs-security.json to allow redirects back to the local (or "local" Business Application Studio) URL immediately following authentication. Only Cloud Foundry is enabled by default. For example if your'e using trial in us10:

      "oauth2-configuration": {
      "redirect-uris": [


      TENANT_HOST_PATTERN should be in your default-env.json and unchanged.

      And be sure to remove all changes in node_modules before deploying the app to Cloud Foundry in the future.

      Hope that helps?

      Best regards,


      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Hello Philip MUGGLESTONE ,


      Thank you for your quick response and explanation. I tried the hack to modify in the approuter utils and it works!

      Sending headers is not helpful in my scenario as the goal is to have local development together with the UI5 module (in a full stack kind of way).

      This helps a lot!

      Best regards,


      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Philip MUGGLESTONE I thought about the info you shared with me and I found a way which does not require modifying the node_modules.


      I'll post it also here to be available. I followed the docs about Extending the Application Router.

      default-env.json file contains the following:

          "destinations": [...],
          "VCAP_SERVICES": {...},
          "VCAP_APPLICATION": {...},
          "TENANT_HOST_PATTERN": "{{tenant_host_pattern_like_in_deployed_app}}",
          "EXTERNAL_REVERSE_PROXY": true,
          "mockHost": "{{approuter_host_of_a_consumer}}"


      I added a file server.js with the following contents:

      var approuter = require("@sap/approuter");
      var ar = approuter();
      ar.first.use(function myMiddleware(req, res, next) {
          req.headers["x-custom-host"] = process.env.mockHost;  
          console.error('x-custom-host request header overwritten with:' + process.env.mockHost);


      And in package.json I have in scripts:

      "scripts": {
      	"start-mock": "node server.js",
      	"start": "node node_modules/@sap/approuter/approuter.js"

      With npm run start-mock it does the trick you mentioned.


      Highly appreciate again your input! Please let me know if you have any suggestion about this option 🙂


      Kind regards and thanks,


      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Stefania,

      Great stuff - thanks for sharing - a great idea and far more elegant than the hack I proposed.

      Best regards,


      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Later update: No need for extending and any extra implementations, just a different TENANT_HOST_PATTERN and URL.

      In default-env.json:

      TENANT_HOST_PATTERN: "^(.*).localhost"

      And access to http://subdomain.localhost:5000

      Where subdomain is the subdomain of a subscribed tenant (subaccount).


      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Stefania,

      Nice idea - makes things easier when doing truly local dev i.e. from a desktop.

      Unfortunately it doesn't look like this approach is compatible with Business Application Studio where "local" dev is, in reality, achieved via a fixed hostname (configured by BAS) with no possibility to include the tenant subdomain:

      Best regards,


      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Philip MUGGLESTONE

      Good point! In my case I'm using VSCode.

      I guess in BAS, the TENANT_HOST_PATTERN should include the fixed hostname somehow?

      One idea:

      TENANT_HOST_PATTERN: "https://workspaces-ws-wsid-^(.*)"

      But I'm not sure how it can be achieved.

      In BAS maybe @sap/html5-repo-mock can be used for local run.


      Kind regards,



      Author's profile photo Fedor Shestov
      Fedor Shestov

      Hi. Is it possible to debug tenant subscription?

      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Hello Fedor,

      If you subscribe using the REST API from Postman I think you can use the url of the app started locally. I have not tried it myself, but I believe it should be possible.

      I usually just check the logs of the deployed app when I subscribe from the BTP cockpit.



      Author's profile photo Fedor Shestov
      Fedor Shestov

      Hi Stafania. Thanks for your response.

      Author's profile photo Gregor Wolf
      Gregor Wolf

      Hi Denys van Kempen and Philip MUGGLESTONE,

      regarding the setup of tenant specific routes I would suggest to use a destination instead of environment variables for Cloud Foundry API credentials. What do you think?

      Best regards

      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Gregor Wolf,

      Indeed and thanks for suggesting this and watching the videos.

      Personally, I have never been comfortable using environment variables for sensitive information such as credentials. Using a destination instead makes good sense but actually I think there's now an even better way - use the credential store service.

      See this more recent series that covers multi-tenant with CAP - we make use of the credential store service for both CF API credentials and various API keys: See the section "Credential Store".

      This series also shows how to extend app-router to facilitate "local" dev based on ideas Stefania Santimbrean shared in other comments of this blog. See the section "Local Development".

      Best regards,


      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      Philip MUGGLESTONE ,

      Just a short mention, that extending the approuter and EXTERNAL_REVERSE_PROXY is not needed if you set up the

      TENANT_HOST_PATTERN: "^(.*).localhost"

      and access http://subdomain.localhost:5000

      Extending the approuter was a workaround because I have not found any public documentation that states this information and only later received it through an incident opened on the topic.

      Kind regards,


      Author's profile photo Anil k
      Anil k

      Hi Denys van Kempen and Philip MUGGLESTONE,

      Great Blog. One question, how would I configure tenant-specific variables. For example: if my application in the provider account is using a variable like "code = 123" . Just like the dynamic nature of destinations, can we pull "code" variable value based on tenant subaccount? How can I achieve it?


      I tried defining user-provided variables in the provider subaccount, but this approach will have the same value for all requests coming from all tenants.

      Author's profile photo Philip MUGGLESTONE
      Philip MUGGLESTONE

      Hi Anil,

      Thanks for your feedback and question.

      I'm not aware of any specific mechanism for this and regular environment variables relate to the provider app so won't be tenant specific. Creating new environment variables for the provider app at runtime presents challenges and may well require an application restart.

      However there are several ad-hoc approaches you could take depending on your exact needs:

      • "Piggy back" the destination service (or another multi-tenant aware service). You could create a custom additional property (or properties) for a destination which is configured individually for each subscriber tenant and accessible via the destination service from the provider app. This approach is easy to configure as you can use the BTP cockpit to edit the destination settings and therefore tenant-specific variables for each subscriber tenant. This is probably the easiest approach.
      • Database persistence. You could store such values in a parameter table - which of course will be in an individual HDI container for each subscriber. However you'd need a create a mechanism to set the values. Perhaps add an admin option in the app that can be used to set  the values? This option might make more sense if you have a lot of different tenant-specific values to manage.
      • A third option might be to "hard-code" logic in the provider app based on the value of req.user.tenant? This might be adequate for very basic scenarios but of course hard-coding brings its own challenges. I would not recommend this approach.

      Hope that helps.