Secure a Multitenant Application with the Authorization and Trust Management Service (XSUAA)

Each multitenant application has to deploy its own application router, and the application router handles requests of all tenants to the application. The application router is able to determine the tenant identifier out of the URL and then forwards the authentication request to the tenant User Account and Authentication (UAA) service and the related identity zone.

To use a multitenant application router, you must have a shared UAA service: SAP Authorization and Trust Management Service (also known as XSUAA)

In Kubernetes, you can create and bind to a service instance using the Service Catalog. Create a new deployment file k8s-deployment-services.yaml to define objects for XSUAA instance and binding:

################### XSUAA ###################
---
apiVersion: services.cloud.sap.com/v1
kind: ServiceInstance
metadata:
  name: xsuaa-service
spec:
  serviceOfferingName: xsuaa
  servicePlanName: application
  parameters:
    xsappname: multitenant-kyma-demo
    tenant-mode: shared  # define the application provider tenant as a shared tenant
    description: Security profile of called application
    scopes:
    - name: $XSAPPNAME.Callback
      description: With this scope set, the callbacks for subscribe, unsubscribe and getDependencies can be called.
      grant-as-authority-to-apps:
      - $XSAPPNAME(application,sap-provisioning,tenant-onboarding)  # provide access to the SAP SaaS Provisioning service SAP Authorization and Trust Management service (technical name: saas-registry) for calling callbacks and getting the dependencies API by granting scopes:  
    oauth2-configuration:
      redirect-uris:
      - https://*.<clusterdomain>/**  # Replace <clusterdomain> with your actual Kyma cluster domain

---
apiVersion: services.cloud.sap.com/v1
kind: ServiceBinding
metadata:
  name: xsuaa-service-binding
spec:
  serviceInstanceName: xsuaa-service
  secretName: xsuaa-service-binding

Upon creation of the binding, the Service Catalog will create a Kubernetes Secret (by default with the same name as the binding) containing credentials, configurations and certificates.

SAP’s approuter uses @sap/xsenv package internally to parse and load service keys and secrets bound to the application, this makes the process to load secrets easy.

Kubernetes offers several ways of handling application configurations for bound services and certificates. @sap/xsenv expects that such configurations are handled as Kubernetes Secrets and mounted as files to the pod at a specific path. This path can be provided by the application developer, but the default is /etc/secrets/sapcp. From there, @sap/xsenv assumes that the directory structure is the following /etc/secrets/sapcp/<service-name>/<instance-name>. Here <service-name> and <instance-name> are both directories and the latter contains the credentials/configurations for the service instance as files, where the file name is the name of the configuration/credential and the content is respectively the value.

For example, the following folder structure:

/etc/
    /secrets/
            /sapcp/
                 /hana/
                 |    /hanaInst1/
                 |    |          /user1
                 |    |          /pass1
                 |    /hanaInst2/
                 |               /user2
                 |               /pass2
                 /xsuaa/
                       /xsuaaInst/
                                  /user
                                  /pass

For more details, please visit @sap/xsenv package page.

Now, mount the Secret just generated to the pods of both approuter and node application as a volume in the k8s-deployment-backend.yaml and k8s-deployment-approuter.yaml:

        volumeMounts:
        - name: xsuaa-volume
          mountPath: "/etc/secrets/sapcp/xsuaa/xsuaa-service"
          readOnly: true
        - mountPath: /tmp
          name: tmp
      securityContext:
        runAsNonRoot: true
      volumes:
      - emptyDir: {}
        name: tmp
      - name: xsuaa-volume
        secret:
          secretName: xsuaa-service-binding

Secrets can be found in the pod directory /etc/secrets/sapcp/<service-name>/<instance-name>:

1. Add libraries for enabling authentication in the kyma-multitenant-node/app.js file:

var app = express();

//**************************** Libraries for enabling authentication *****************************
var passport = require('passport');
var xsenv = require('@sap/xsenv');
//************************************************************************************************

2. Enable authorization in the kyma-multitenant-node/app.js file:

The properties name and label both are supported by CF and K8S. You are recommended to use name or label to get xsuaa credentials by. You can find the query value definition on xsenv package page.

If you want to use the label, which maps to Service name, get the XSUAA credentials with:
xsenv.getServices({xsuaa: { label: 'xsuaa' }})

If you want to use the name, which maps to Service instance name, get the XSUAA credentials with:
xsenv.getServices({xsuaa: { name: 'xsuaa-service' }})

app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'jade');

//*********************************** Enabling authorization  ***********************************
console.log('Fetching xsuaa service...');
const services = xsenv.getServices({xsuaa: { label: 'xsuaa' }});
const credentials = services.xsuaa;
const { XssecPassportStrategy, XsuaaService } = require("@sap/xssec");
const authService = new XsuaaService(credentials) // or: IdentityService, XsaService, UaaService ...
console.log( `Found XSUAA service credentials for client: ${services.xsuaa.clientid}` )
passport.use(new XssecPassportStrategy(authService));

console.log('Initializing passport...');
app.use(passport.initialize());

console.log('Authenticating with JWT strategy...');
app.use('/callback', passport.authenticate('JWT', { session: false }));
app.use('/users', passport.authenticate('JWT', { session: false }));
app.use('/user', passport.authenticate('JWT', { session: false }));
//************************************************************************************************

3. Add new route /user in kyma-multitenant-node/routes/index.js

Separate the / route as non-authenticated. Add a new route /user to verify user authentication in the subscribed multitenancy application from the consumer’s side.

router.get("/", function(req, res, next) {
    try {
        var responseMsg = "Welcome to the Kyma Multitenant Application!";
        res.send(responseMsg);
    } catch (e) {
        console.log("AuthInfo object undefined.");
        var responseMsg = "Hello World!";
        res.send(responseMsg);
    }
});

router.get("/user", function(req, res, next) {
    try {
        var line1 = "Hello " + req.authInfo.getLogonName();
        var line2 = "your tenant sub-domain is " + req.authInfo.getSubdomain();
        var line3 = "your tenant zone id is " + req.authInfo.getZoneId();
        var responseMsg = line1 + "; " + line2 + "; " + line3;
        res.send(responseMsg);
    } catch (e) {
        console.log("AuthInfo object undefined.");
        var responseMsg = "Cannot get user information. Please check your authentication.";
        res.send(responseMsg);
    }
});

4. Add dependencies @sap/xsenv, @sap/xssec and passport in the kyma-multitenant-node/package.json file, for example:

    "dependencies": {
        "@sap/xsenv": "^5",
        "@sap/xssec": "^4",
        "passport": "^0.7.0",
        ...
    }
}

Update the /kyma-multitenant-approuter/xs-app.json file:

{
    "authenticationMethod": "route",
    "routes": [{
        "source": "/",
        "target": "/",
        "destination": "dest_kyma_multitenant_node",
        "authenticationType": "xsuaa"
    }]
}

The application router must determine the tenant-specific subdomain for the UAA that in turn determines the identity zone, used for authentication. This determination is done by using a regular expression defined in the environment variable TENANT_HOST_PATTERN.

TENANT_HOST_PATTERN is a string containing a regular expression with a capturing group. The request host is matched against this regular expression. The value of the first capturing group is used as the tenant subdomain. For more details, please visit: Multitenancy.

1. Add a new ConfigMap to provide your Kyma cluster domain in the k8s-deployment-approuter.yaml file:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-domain
data:
  cluster-domain: <clusterdomain>  # Replace <clusterdomain> with your actual Kyma cluster domain

2. Refer to the ConfigMap and add environment variable TENANT_HOST_PATTERN in the k8s-deployment-approuter.yaml file:

      containers:
      - env:
        - name: CLUSTER_DOMAIN
          valueFrom:
            configMapKeyRef:
              key: cluster-domain
              name: cluster-domain
        - name: TENANT_HOST_PATTERN
          value: "^(.*)-approuter.$(CLUSTER_DOMAIN)"