Important LinksGeneral
SAP BTP, Kyma Runtime scenario SAP BTP, Cloud Foundry Runtime scenario |
Dear readers,
We are delighted to have you join us for our latest blog post, where we delve into the world of building Software-as-a-Service (SaaS) applications on the SAP Business Technology Platform (BTP), utilizing the powerful SAP BTP, Kyma runtime. This time, we are excited to share with you our newest piece of candid sample content!
You only got 1 min ➔ Read the summary and check out our GitHub repository to get started! The respective Expert Feature tutorial will provide you a step-by-step guide and a lot of additional information!
Summary
In this blog post, we address two crucial requirements for SaaS providers on SAP BTP. Firstly, we explore the significance of end-to-end automation when it comes to subscriber tenant onboarding. Additionally, we delve into the concept of implementing a one-domain approach for your SaaS application. As before, we harness the great capabilities of the SAP BTP, Kyma Runtime to achieve these objectives.
Read on to discover how you as a SaaS provider as well as your consumer can benefit from a self-registration option (e.g., to allow interested customers to test your solution), using SAP Identity Authentication Service (IAS), combined with a a fully-automated subaccount setup (using SAP BTP Setup Automator) including:
SaaS application subscription, API Service instance creation, Service Key instantiation, Role Collection assignments, SAP IAS trust setup, Read-Only SAP BTP platform access for SaaS consumer, Destination maintenance by SaaS consumer, SaaS consumer initiated on- and offboarding, …
Explore the one-domain approach, which addresses the current challenge of having separate subscriber subdomains for each SaaS consumer. Discover how leveraging SAP IAS and a cookie-based approach in our scenario can provide a solution to:
Provide a public Home Page, Authenticate a self-registered user, Identify a subscriber using a cookie, Use a single unique application domain for all SaaS consumers, …
Visit our GitHub repository and the respective step-by-step guide for further details and to set up the sample scenario in your own environment. This is particularly valuable if you have plans to offer a free trial to potentially interested SaaS consumers, which was the initial idea behind this scenario.
You gotta few more minutes and feel excited by the summary? ➔ Great then feel free to read on!
Back to the roots
Let's take a trip down memory lane and give you some background on this blog post. We've been hearing it for ages—everyone wants more automation features and examples for SAP BTP! Whether it's automating subaccount creation, service setup, role assignments, or even automating automation itself, the demand is real...!
Now, here's the thing: while tools like the SAP BTP Setup Automator and handy CLIs have been around for a while and keep getting better, most of the available scenarios focus on standalone stuff. Hardly anyone talks about automating SaaS processes!
Well, guess what? We're here to change that! We've put together some awesome sample content / code and inspiration to fill this gap. Brace yourself as we show you the power of the SAP BTP Setup Automator in automating the whole onboarding process for new SaaS customers. Not a single step left for you as a SaaS provider! Sounds good?!
But wait, there's more - We didn't stop there! We've also put in the effort to make your application even more user-friendly. In our existing samples for Kyma and Cloud Foundry, we use a tenant-specific subdomain to identify subscribers. But hey, we'll blow your mind with a super basic sample that skips this requirement by using a cookie to identify your tenant after login!
Exciting, right? So stick around, folks! We're about to embark on an incredible journey together.
The High-Level Concept
Although we've shared numerous blog posts on building SaaS applications using Cloud Foundry or Kyma Runtime as a partner or customer, we've realized that we're missing out on some crucial puzzle pieces when it comes to automation. Well, today, we're going to cover one of those puzzle pieces! Still wondering about the differences between the SAP BTP Cloud Foundry and Kyma Runtime? No worries, my colleague alperdedeoglu will get you covered in his recent blog post!
To create a top-notch SaaS service, it should allow users to self-register for a trial version of your application, granting them access to a new customer tenant automatically (ideally within minutes or seconds). No manual intervention from the SaaS provider, no manual role assignments or subaccount setup! Imagine a customer in Sydney 🇦🇺 ☀️ signing up for your SaaS application trial in the middle of the European night 🇪🇺 🌑, or offering new tenants to dozens of interested customers. In both cases, a manual onboarding process would be quite a hassle, right?
Let's imagine that your interested new customer can validate their email address or even their mobile number, and you want to grant them access to a new trial tenant of your SaaS application automatically. Sounds complicated? Well, we're here to show you that it's not! You have all the tools you need, even in a SAP BTP Trial (available soon!) or Free Tier context. Give it a try and prepare to be amazed by the almost endless capabilities of the SAP BTP Setup Automator in the SAP BTP, Kyma runtime context!
The SAP BTP Setup Automator is a Container Image maintained by our fantastic SAP colleagues. It provides you with a toolbox to automate SAP BTP Subaccount setups in a simplified way, utilizing various CLIs like the SAP BTP CLI or the Cloud Foundry CLI. Just a few JSON configurations, and you're good to go. Did you catch the mention of Docker? Wouldn't that be a perfect integration use-case for our existing Kyma scenario, SAP's managed Kubernetes offering? Absolutely! And that's precisely what we will do! Let's quickly summarize the approach before diving into the actual flow.
The concept is straightforward. When a user self-registers in SAP IAS (which is an out-of-the-box feature) and validates the registered email address, they can trigger the onboarding of a new subscriber tenant/subaccount through a dedicated onboarding user interface.
This action sets off a CAP application in the backend, which spins up a new SAP BTP Setup Automator instance in the Kyma Cluster as a Kubernetes Job (check out the respective coding). The SAP BTP Setup Automator handles the setup of the new tenant subaccount for the authenticated user. Once the subaccount (including subscription, role assignments, IAS trust, and more) is successfully created, the tenant details are returned to the user. That's it! The user can log in to the new tenant and even his dedicated SAP BTP subaccount, and instantly start using the SaaS application!
We all know a picture is worth a thousand words, so let us witness the end-to-end process in action!
| Customer visits the public SaaS Application | Customer registers for the SaaS Application | Customer provides the required account data | Customer sets an initial password |
 |  |  |  |
| Customer confirms email address (similar) | Customer logs in to the SaaS Application | Customer triggers tenant onboarding | Onboarding process takes a few minutes |
 |  |  |  |
| New Kyma Job is instantiated | Kyma Job runs the SAP BTP Setup Automator | Setup Automator provisions subaccount | Tenant subaccount is created with generic ID |
 |  |  |  |
| Labels help matching subaccount to IAS user | SaaS subscription is automatically created | API Service instance automatically created | SAP IAS trust automatically set up |
 |  |  |  |
| IAS user is assigned the SaaS Admin role | IAS user is assigned the Subaccount Viewer role | Login buttons displayed after onboarding ends | User can also trigger offboarding process |
 |  |  |  |
| User can access the SaaS tenant launchpad | Access to SAP BTP subaccount possible | User has permission to edit destinations only | Read-only permissions for other interfaces |
 |  |  |  |
Taking a high-level view, the process is quite straightforward, don't you think? It's a lean and efficient approach. Plus, the architecture behind this self-registration and onboarding flow is not overly complex. So before you dive into the actual sample implementation, let's provide you with some architecture diagrams to give you a clear understanding of the overall structure.
End-to-End Self-Onboarding
While the self-registration functionality is readily available through the SAP Identity Authentication Service (click here), the actual onboarding process is remarkably simple. It only requires a few lines of code to initiate a new Kyma/Kubernetes Job, which in turn runs a parameterized instance of the SAP BTP Setup Automator.
In this particular scenario, we rely on the authentication capabilities of SAP IAS, along with the SAP Application Router and CAP. The entire onboarding process does not involve the use of the tenant specific XSUAA. The reason for having a separate Application Router for the registration process is fairly simple. As we rely on SAP IAS in this case, a parallel binding of SAP XSUAA and IAS in a multitenant Application Router is possible, but requires the usage of the so called SAP Subscription Management Service, which is not available externally. Therefore, we need a second Application Router to cater the SAP IAS related authentication requirements.
Once a user registers in the central SAP IAS instance and successfully validates their email address, we can extract all the necessary user-details from the trusted JWT token issued by SAP IAS within our CAP application. Both the Application Router and CAP support authentication using SAP IAS, ensuring that only verified and authenticated users can access the onboarding user interface and trigger the CAP-based onboarding service. The CAP backend ensures that only one tenant can be created per authenticated SAP IAS user. By adding the authenticated user as the SaaS Admin and Subaccount Viewer to the newly created subaccount, we prevent other SAP IAS users from authenticating and accessing the tenant. To further enhance security, we disable the automated creation of shadow users in all subscriber subaccounts.
For tenant management and security purposes, a list of provider administrator (having a Subaccount Administrator role collection) users can be configured. These users are added as Subaccount Administrators to the respective tenant subaccounts. Additionally, the authenticated SAP IAS user is assigned the Subaccount Viewer role collection, granting SAP BTP Platform Access to configure destinations or retrieve API credentials. Also this process is completely automated and is crucial for SaaS providers, who are not planning to develop dedicated user-interfaces for complex destination management processes!
To prevent the creation of multiple tenants, the Kyma/Kubernetes Job name and corresponding API Rule are derived from the SAP IAS SCIM User ID. Once the initial tenant is created, an additional check skips the setup of a new Job. The same principle applies to the offboarding process. If no tenant is found for the SAP IAS current user, no offboarding Job is triggered. Currently, the availability of a tenant is checked based on the existence of a corresponding API Rule. Alternatively, this information could be stored in a SAP HANA Cloud database.
Feel free to explore the relevant parts of our sample repository to gain a better understanding of what's happening behind the scenes before we move on to the next topic.
One-Domain Concept
Now that you have familiarized yourself with the self-onboarding logic, let's move on to the second puzzle piece. Providing a unique domain for your SaaS application, usable by all your SaaS consumers.
By implementing a One-Domain concept, we aim to streamline the user experience and simplify the access to your SaaS application. This approach allows your subscribers to access your application through a single domain, providing a consistent and seamless experience. Gone are the days of remembering complex subdomains (especially in combination with self-onboarding features generating a generic subdomain, this can become extremely tedious)!
Take a moment to study the following architecture diagram and try to grasp the flow of the process. Maybe you can already guess where this story is ending up down the road... Cookieeeeesss 🍪 Rest assured, we will delve deeper into the details and provide you with step-by-step instructions shortly.
1) Users visiting the SaaS application will see the Home Screen including a login/registration button. This Home Screen can be reached without any authentication.
Application Router (click here)
{
"welcomeFile": "/sapsusaasuihome/",
"authenticationMethod": "route",
"login": {
"callbackEndpoint": "/login/callback"
},
"routes": [
{
"source": "^(/sapsusaasuihome/.*)$",
"service": "html5-apps-repo-rt",
"authenticationType": "none"
}
]
}
2) Clicking on the login/registration button will send the user to a dedicated function of a new CAP-based Gateway Service. This redirect handled by the Application Router triggers an IAS-based authentication.
Home Page Controller (click here)
onPressLoginRegister: function(){
URLHelper.redirect('/sapsusaasgateway/redirect', false);
}Application Router (click here)
{
"welcomeFile": "/sapsusaasuihome/",
"authenticationMethod": "route",
"login": {
"callbackEndpoint": "/login/callback"
},
"routes": [
{
"source": "^/sapsusaasgateway/(.*)$",
"target": "/catalog/GatewayService/$1",
"destination": "obd-api",
"authenticationType": "ias"
}
]
}
3) After successful authentication, the request proceeds to the Gateway Service which determines the tenant associated with the authenticated user, using information such as the SAP IAS User ID. If no tenant exists, the user will be directed to the Onboarding UI, where a new tenant can be created.
CAP Gateway Service (click here)
service GatewayService @(
path : '/catalog/GatewayService',
protocol: 'rest',
requires: 'authenticated-user',
impl: 'srv/gateway-service'
){
function redirect() returns String;
}this.on("redirect", async (req)=> {
try {
const tenantId = crypto.createHash('shake256', { outputLength: 10 })
.update(`${saasHelmRelease}-${kymaNamespace}
-${clusterShootname}-${scimId}`)
.digest('hex');
const result = await k8sCustObjApi.listNamespacedCustomObject(
'gateway.kyma-project.io', 'v1beta1', kymaNamespace,
'apirules', '', false, '', '','app.sap.com/subdomain=' +
encodeURI(tenantId));
4) The Gateway Service sets a cookie named "x-custom-host" (you might know that from some other place already) with a duration of one day (can be adjusted). This cookie holds the subdomain associated with the tenant of the authenticated SAP IAS user.
CAP Gateway Service (click here)
req._.res.cookie(
'x-custom-host',
tenantId,
{ maxAge: 1*24*60*60*1000, httpOnly: false }
);5) Subsequently, the user is redirected to the mock launchpad of the actual SaaS application, wherein the redirect request includes the "x-custom-host" cookie as an integral component.
CAP Gateway Service (click here)
req._.res.redirect('/sapsusaasuipublicflp/');6) Upon detecting the presence of the "x-custom-host" cookie, Istio Virtual Service identifies and routes the request to the actual multitenant SaaS Application Router. Conversely, requests lacking the "x-custom-host" cookie are redirected to the central Home Page.
Istio Virtual Service (click here)
http:
- match:
- uri:
regex: ^.*(uipublic|uiadmin).*$
headers:
Cookie:
regex: ^.*(x-custom-host=).*$
route:
- destination:
host: susaas-router.default.svc.cluster.local
port:
number: 5000
7) By leveraging the extension features of our multitenant SaaS Application Router, the existence of the "x-custom-host" cookie can be verified and its value is used as "x-custom-host" header. This eliminates the necessity for a subscriber-specific subdomain, streamlining the overall process.
SaaS Application Router (click here)
ar.first.use(function myMiddleware(req, res, next) {
const cookieHeader = req.headers["cookie"] ?? req.headers["Cookie"];
if(!cookieHeader) {
return next()
};
const customHost = cookieHeader.match('(^|;)\\s*' +
'x-custom-host' + '\\s*=\\s*([^;]+)')?.pop();
if(customHost){
req.headers['x-custom-host'] = `${customHost}-
${process.env["EXPOSED_HOST"]}`
};
next();
});
8) By setting the "x-custom-host" header, the multitenant SaaS Application Router determines the Identity Zone for tenant authentication. A redirection to the XSUAA instance specific to the tenant's identity zone is initiated, facilitating the XSUAA user authentication.
9) Leveraging the trust between the tenant subaccounts XSUAA and the central SAP IAS, single sign-on will operate seamlessly. Therefore, users can effortlessly access the SaaS application launchpad of their tenant, which now includes an additional tile for managing tenant onboarding or offboarding (only visible if "x-custom-host" cookie is set (backward compatible).
Launchpad Configuration (click here)
ManageTenant: {
semanticObject: "Tenant",
action: "manage",
title: "Manage Tenant",
signature: {
parameters: {},
additionalParameters: "ignored"
},
resolutionResult: {
applicationType: "URL",
url: window.location.protocol + "//" +
window.location.host + '/sapsusaasuionboarding/'
}
}
To avoid a cookie collision between the two Application Router instances, the Istio Virtual Service ensures a redirect to the appropriate onboarding subdomain when the user clicks on the mock launchpad tile.
Istio Virtual Service (click here)
- match:
- uri:
regex: ^.*(uionboarding).*$
authority:
exact: susaas.sap-demo.com
redirect:
authority: onboarding-susaas.sap-demo.com
Incorporating SAP IAS as a pre-authentication layer (before the SaaS user actually authenticate using the XSUAA "authentication layer" of their tenant) offers numerous benefits in simplifying the SaaS setup from the providers but also the consumer's standpoint.
By identifying users before they actually reach the multitenant SaaS Application Router, the SaaS provider gain greater flexibility in terms of tenant management and the utilization of cookies for propagating tenant details.
However, it is important to acknowledge that this approach also entails certain drawbacks and additional costs. One notable drawback is the requirement for an additional Application Router, as the parallel binding of SAP IAS and SAP XSUAA is currently a challenge when using the Application Router in multitenant mode (setting a TENANT_HOST_PATTERN).
Additionally, this pattern introduces added complexity in handling cookies and session management. Each Application Router issues its own JSESSIONID cookie, necessitating the use of a separate subdomain for the onboarding application. Neglecting to do so will result in scenarios where active sessions clash, leading to authorization errors or manual re-login demands. In our scenario, the applications will automatically reload if the corresponding Application Router returns an "unauthorized" 401 response to cater this issue.
While this might be fine for a Proof-of-Concept (PoC), a productive scenario should implement a more reliable solution. So, it is important to note that this example serves primarily as an inspiration, and we do not recommend using it as-is for a productive application. Also the various different match patterns used in the Virtual Service are probably not ideal and can be optimized!
Not being an expert for cookies (except the chocolate ones 😀), for a production-ready application, a much more comprehensive cookie handling tailored to your specific requirements should be implemented. Alternatively, you might consider different approaches like using an iFrame instead of a redirect or new tab. It might also be worth checking the CORS capabilities/settings that Application Router offers in this context!
Summary
Okay let us summarize what we learned today! This blog post covered two essential components of an enterprise-ready SaaS solution, allowing the self-registration of users for a trial version of a SaaS application, as well as the automated end-to-end setup for subscriber subaccounts. Joined with a very basic One-Domain concept, SaaS subscribers will have a very convenient experience testing and evaluating your SAP BTP SaaS solution, before buying a premium plan!
The given scenario bears some limitations, which will be further evaluated as part of our GitHub repository. Primarily, the setup is focusing on the self-registration of single users, that would like to test and evaluate a SaaS application. In an enterprise context, you will need to consider further concepts of assigning multiple users to the same subscriber subaccount and deriving a user's available tenant(s) after SAP IAS login.
Feel free to test the sample scenario by setting up Sustainable SaaS application in your own SAP BTP environment. Please let us know your thoughts, whether this blog post was helpful and any further topics should be covered in future SaaS-related publications.
Cheers and have fun when setting up the sample scenario!
- SAP Managed Tags:
14 Comments
