Implementing Application Router in TypeScript NestJS application

After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Implementing Application Router in TypeScript NestJS application

Implementing Application Router in TypeScript NestJS application

The application router is the single point-of-entry for an application running in Cloud Foundry environment on SAP BTP. Its responsibilities consist of dispatching requests to backend microservices, delegating the process of authenticating users and serving static content. The application router can be implemented as a simple Node.js program using the @sap/approuter npm module.

Application Router Setup

You can use the application router that is managed by SAP or you can set up and run your own application router. For the most part, you can simply use the application router that is managed by SAP. When setting up your own application router, you have 2 options.

  • Node.js program using the @sap/approuter npm module
  • Container image on Docker Hub

Steps Involved

These are the basic steps to set up your own application router using a Node.js program.

  • Create a simple Node.js program using npm init command
  • Install the @sap/approuter npm module
  • Edit the start script to run the approuter.js file
  • Create the xs-app.json configuration file

Application Router Configuration

The application router configuration file is named xs-app.json. This file needs to be created at the root level of your Node.js program.

Some of the important properties of the configuration file are listed below

Configuration file properties



Valid values: route(default), none

route - authentication type is defined in the routes configuration

none - disables authentication for all routes


array of objects

Define all route objects
routes - source


Regular expression that matches incoming request URL
routes - target


Defines how incoming request is rewritten
routes - destination


Name of the destination to which incoming request is forwarded
routes - authenticationType


Valid values: xsuaa (default), basic, none

xsuaa - specified UAA server handles authentication

Sample Application Router Configuration file

The following sample application router configuration file is used in our exercises.

Code snippet

  "welcomeFile": "/",
  "authenticationMethod": "route",
  "routes": [{
    "source": "^/service/(.*)$",
    "target": "$1",
    "destination": "backend",
    "authenticationType": "xsuaa"

The configuration file has a single route defined. The target property in the route has a value of $1. $1 is mapped to the (.*) part of the regular expression in the source property. When a request with path /service/business-partner is received, the request will be rewritten as /business-partner. This rewritten source path (/business-partner) is appended to the destination URL (In this case, the destination URL is our TypeScript application URL). And this endpoint requires authentication since we have specified the authenticationType property as xsuaa.

So in essence, when an end user accesses the application router URL with the path /service/business-partner, the end user is authenticated first and then redirected to the backend service with the rewritten path /business-partner.


The retrieval of a JSON Web Token (JWT) is done by the approuter together with the XSUAA. The flow is as follows.

  • Unauthenticated user requests a protected resource
  • Approuter delegates the authentication to the Identity Provider
  • XSUAA issues a JWT
  • Approuter adds the JWT to the request headers and redirects the request to the initially requested protected resource
Code snippet
  "headers": {"authorization": "Bearer yourJwtTokenBase64Encoded"}

Use JWT in application

The SAP Cloud SDK provides a convenience function to extract the JWT from the request object.

Code snippet
import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';
import { retrieveJwt } from '@sap-cloud-sdk/connectivity';

export class AppController {
  constructor() {}

  getSomeSampleEndpoint(@Req() request: Request): Promise {
    const myJwt = retrieveJwt(request);
    //Do something with the JWT e.g. fetch some data using a destination

Log in to track your progress & complete quizzes