@sap/approuter

• Overview
• Deploying a business application with microservices
• Working directory
• Configurations
  • Destinations
    • Environment-destinations
    • Destination-service
  • UAA configuration
  • Additional headers configuration
  • Additional Cookie Attributes
  • Plugins configuration
  • Session timeout configuration
  • X-Frame-Options configuration
  • Cross-Origin Resource Sharing configuration
  • Direct Routing URI Patterns configuration
  • NodeJS Minimal Logging Level configuration
  • Dynamic Identity Provider configuration
• Routes
  • Example routes
• Replacements
• xs-app.json configuration file
  • welcomeFile property
  • authenticationMethod property
  • routes property
  • login property
  • logout property
  • destinations property
  • services property
  • responseHeaders property
  • compression property
  • pluginMetadataEndpoint property
  • whitelistService property
  • websockets property
  • errorPage property
  • cors property
  • Complete example of an xs-app.json configuration file
• Headers
  • Forwarding Headers
  • Hop-by-hop Headers
  • Custom Headers
  • Authorization Header
• CSRF Protection
• Support of SAP Statistics
• Connectivity
• SaaS Application Registration in SAP BTP
  • How To Expose Approuter for SaaS Subscription
• Authentication with Identity Service (IAS)
• Mutual TLS Authentication (mTLS) and Certificates Handling
• Integration with HTML5 Application Repository
• Integration with Business Services
• Web Sockets
• Session Handling
  • Session Contents
• External Session Management
• Service to Application Router
• Central Logout
• User API Service
• Allowlist Service
  • Enable the service
  • Configuring allowed hostnames / domains
  • Return value
• Scaling
• Sizing Guide for Application Router
• Configure server-side HTTPS
• Audit-Log Service
• Troubleshooting
• Getting Support
• Extending Application Router
• Best practices
  • Security best practices
    • Content-Security-Policy

Overview

When a business application consists of several different apps (microservices), the application router is used to provide a single entry point to that business application. It has the responsibility to:

• Dispatch requests to backend microservices (reverse proxy)
• Authenticate users
• Serve static content

Let's think of the different apps (microservices) as destinations to which the incoming request will be forwarded. The rules that determine which request should be forwarded to which destination are called routes. For every destination there can be more than one route. You may read more on the concept of routes later in this document. If the backend microservices require authentication, the application router can be configured to authenticate the users and propagate the user information. Again by using routes, the application router can serve static content.

The application router is designed to work in XS Advanced - Cloud Foundry and XS OnPremise Runtime.

A calling component accesses a target service by means of the application router only if there is no JWT token available, for example, if a user invokes the application from a Web browser. If a JWT token is already available, for example, because the user has already been authenticated, or the calling component uses a JWT token for its own OAuth client, the calling component calls the target service directly; it does not need to use the application router.

Note that the application router does not hide the backend microservices in any way. They are still directly accessible bypassing the application router. So the backend microservices must protect all their endpoints by validating the JWT token and implementing proper scope checks. Network isolation is not provided currently by the platform.

Deploying a business application with microservices

For example we can have a business application that has the following structure:

+-- manifest.yml
+-- manifest-op.yml
|  +-- microservice-1
|  | +-- ...
|  | +-- ...
|  +-- microservice-2
|  | +-- ...
|  | +-- ...
|  +-- web
|  | +-- ...
|  | +-- ...

The manifest.yml file is used to deploy the business application on Cloud Foundry and the manifest-op.yml - on the XS OnPremise Runtime. These files should describe all the microservices for that business application.

Folders are used to isolate the different microservices. Let's assume that the application router is the microservice in the web folder (every business application has its own application router). Here is how we can include the application router:

• Manually create the node_modules folder in the web folder.
• Copy and paste the folder that contains the self-contained application router into node_modules. In this example the name of that folder is @sap/approuter, see the start script in the package.json below.
• Check the version of the application router you just copied.
• Create a package.json file in web with content similar to the following and replace the version's value with the version of your application router:

{
    "name": "hello-world-approuter",
    "dependencies": {
       "@sap/approuter": "2.6.1"
    },
    "scripts": {
        "start": "node node_modules/@sap/approuter/approuter.js"
    }
}

In order to use the application router you don't have to write any JavaScript code. Only some configurations have to be provided in the web folder. Here is a complete example:

+-- web
| +-- package.json
| +-- xs-app.json
| +-- resources
| | +-- hello-world.html
| | +-- my-page.html
| +-- node_modules
| |   +-- ...
| +-- default-env.json
| +-- default-services.json

The web folder contains the package.json, node_modules, some configuration files used by the application router, and static resources to be served. You can read more about the configurations later in this document.

By default, the application router runs on port 5000 (if started locally) or it takes the port from the PORT environment variable.

Working directory

The working directory contains configuration files that the application router needs and static resources that can be served at runtime. In the previous example, the web folder is the working directory. By default the current directory is the working directory. It is possible to configure it during start up of the application router with the following command line argument:

node approuter.js -w 

Application router will abort if the working directory does not contain xs-app.json file.

Configurations

The application router makes use of the following configurations:

• Main configuration - this is the xs-app.json file. This file is mandatory and contains the main configurations of the application router.

• UAA configuration - the application router reads this configuration either from the VCAP_SERVICES environment variable (when deployed on Cloud Foundry or XS Advanced OnPremise Runtime) or from the default-services.json file (when running locally). Refer to the documentation of the @sap/xsenv package for more details.

• Configurations from the environment - these configurations are either read from the application router's environment (when deployed on Cloud Foundry or XS Advanced OnPremise Runtime) or from the default-env.json file (when running locally). Refer to the documentation of the @sap/xsenv package for more details. The environment variables that the application router takes into account are:

Destinations

The destinations configuration can be provided by the destinations environment variable or by destination service. There has to be a destination for every single app (microservice) that is a part of the business application.

Environment destinations

The destinations configuration is an array of objects. Here are the properties that a destination can have:

Note: The timeout specified will also apply to the destination's logout path or service's logout path (if you have set one).
Note: proxyHost and proxyPort are optional, but if one of them is defined, then the other one becomes mandatory.

Sample content of the destinations environment variable:

[
  {
    "name" : "ui5",
    "url" : "https://ui5.sap.com",
    "proxyHost" : "proxy",
    "proxyPort" : "8080",
    "forwardAuthToken" : false,
    "timeout" : 1200
  }
]

It is also possible to include the destinations in the manifest.yml and manifest-op.yml files:

- name: node-hello-world
  memory: 100M
  path: web
  env:
    destinations: >
                  [
                    {"name":"ui5", "url":"https://ui5.sap.com"}
                  ]

Destination service

Destination configuration can also be read from destination service .
Here are the Approuter limitations to destination properties configuration from destination service :

Optional additional properties:

Note:

• In case destination with the same name is defined both in environment destination and destination service, the destination configuration will load from the environment.
• Destinations on destination service instance level are supported.
• Only destination client certificates of type p12 are supported.
• Only destination trust certificates of the type privacy-enhanced mail (PEM) are supported.

UAA configuration

The User Account and Authentication (UAA) server is responsible for user authentication. In Cloud Foundry and XS OnPremise Runtime a service is created for this configuration and by using the standard service binding mechanism the content of this configuration is available in the VCAP_SERVICES environment variable.
Note: The service should have xsuaa in its tags or the environment variable UAA_SERVICE_NAME should be specified (stating the exact name of the UAA service).
During local development the UAA configuration is provided in the default-services.json file. When the UAA is used for authentication the user is redirected to the UAA's login page to enter their credentials.

Sample content for a default-services.json file:

{
    "uaa": {
        "url" : "https://my.uaa.server/",
        "clientid" : "client-id",
        "clientsecret" : "client-secret",
        "xsappname" : "my-business-application"
    }
}

The application router supports the $XSAPPNAME placeholder (upper case letters). You may use it in your route configurations in the scope property. The value of $XSAPPNAME is taken from the UAA configuration (the xsappname property).

Additional headers configuration

If configured, the application router can send additional http headers in its responses to the client. Additional headers can be set in the httpHeaders environment variable.

Sample configuration for additional headers:

[
  {
    "X-Frame-Options": "ALLOW-FROM https://localhost"
  },
  {
    "Test-Additional-Header": "1"
  }
]

In this case, the application router sends two additional headers in the responses to the client.
Custom response headers, configured in the application router configuration file (xs-app.json) are added to the list of additional http headers. If the response header name already exists in the additional http headers list, the value of the response header name overrides the value of the http header.

Caution: For security reasons, the following headers must not be configured: authorization', 'cookie', and 'set-cookie'.

Additional Cookie Attributes

If configured, the application router sends additional cookie attributes in its responses to the client. The cookie attributes can be set in the COOKIES environment variable.

Example of configuration for cookies in the manifest.yml :

  env:
   COOKIES: >
     {
       "SameSite":"None",
       "Partitioned":
            {
               "supportedPartitionAgents":"^Mozilla.*(Chrome|Chromium|)/((109)|(1[1-9][0-9])|([2-9][0-9][0-9]))",
               "unsupportedPartitionAgents":"PostmanRuntime/7.29.2"
            }
     }

In this example, the application router sets the SameSite attribute of the cookie to "None" and the specifies a Partitioned attribute that is sent in the responses to the client. Note: Currently, only the values "None" and "Lax" are supported for the SameSite attribute. The value "Strict" is not supported. The Partitioned attribute contains two required regular expressions:

• supportedPartitionAgents for supported agents

• unsupportedPartitionAgents for unsupported agents

You can use a wildcard '(.*)' in supportedAgents to allow all agents to use the Partitioned attribute. Note: unsupportedPartionAgents overwrites the configurations in supportedAgents. If an agent is allowed in supportedPartitionAgents but disallowed in unsupportedPartitionAgents, the Partitioned attribute will not be returned.

Plugins configuration

A plugin serves almost the same purpose as routes. The difference is that plugins can be configured through the environment and that way you can add new routes to the application router without changing the design-time artefact xs-app.json. The plugin configuration properties are the same as those of a route except that you can't configure localDir, replace and cacheControl.