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

Property	Values
authenticationMethod String	Valid values: route(default), none route - authentication type is defined in the routes configuration none - disables authentication for all routes
routes array of objects	Define all route objects
routes - source RegEx	Regular expression that matches incoming request URL
routes - target String	Defines how incoming request is rewritten
routes - destination String	Name of the destination to which incoming request is forwarded
routes - authenticationType String	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

1234567891011

{
  "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.

JWT on SAP BTP

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

1234
{
  "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

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

@Controller()
export class AppController {
  constructor() {}

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