Skip to Content
Technical Articles
Author's profile photo Joachim Van Praet

Test your CAP nodejs applications with authentication locally

Recently we started our first CAP nodejs project.
Initially we used the SAP Web IDE, but we ran into the problem that we were not able to test our service with authentication quickly. We always had to deploy the service first, and that was taking a lot of time.

So we decided to move our developments locally and start using visual studio code for CAP developments. To test our service we want to use our data, destinations and authorizations from our Cloud foundry services.

In this blog post I will describe how you can use the XSUAA service on cloud foundry to be able to use authentication in your local environment.


To be able to test the things I’ll describe here you have to install some tools …

cloud foundry cli

This command line tool is able to get information from your cloud foundry account.
Find download and installation information here:

SAP Cloud MTA Build Tool

This command-line tool builds a multitarget application archive file from the artifacts of an MTA project.

Because this tool is using makefile, Windows user should first install Chocolatey and GNU Make.

When make is installed, you are able to install the MTA Build tool:

npm install -g mbt

More information here:

Example project

Through this blog post you can use my example project on github.
You can just deploy this example on your trial account and test it.

Clone the project to your PC and try to deploy it to your cloud foundry account.

git clone
cd SAP-CAPM-Nodejs-Authorisation-example\

in your command you have to log on to your cloud foundry account. Just enter “cf login” in your shell and provide the correct information.

cf login
API endpoint:

Email> joachim.vanpraet@****.com


Select an org (or press enter to skip):
1. S0003564161trial_trial

Org> 1
Targeted org S0003564161trial_trial

Targeted space dev

API endpoint: (API version: 2.141.0)
User:           joachim.vanpraet@****.com
Org:            S0003564161trial_trial
Space:          dev

then you can deploy the project! just run

npm run deploy

this command will build the MTA archive and start deployment on cloud foundry. Time to take a coffee, this can take some time 🙂

If the project is deployed, you can test it by opening the url of the approuter module in our project.
To get this url, just run ‘cf apps’

> cf apps
Getting apps in org S0003564161trial_trial / space dev as joachim.vanpraet@****.com...

name                          requested state   instances   memory   disk   urls
CAPMAuthorisation-approuter   started           1/1         256M     256M
CAPMAuthorisation-srv         started           1/1         512M     256M

you’ll see a table of all applications running on your cloud foundry environment. The last column is the url, if you open this url in a brower, the approuter will route you to the service.

This should be the response:

  "@odata.context": "$metadata#User(username)",
  "@odata.metadataEtag": "W/\"V7/t5WepB4qxHRqSBCe3fnSl+gQ4dVwCnhtBLUGyukQ=\"",
  "value": [
      "username": "joachim.vanpraet@****.com"

Running locally

Let’s get this thing running on our local environment. To know which user is logged on we need the authentication token (in cloud foundry this is the JWT Token) injected in the service. Injecting this token is done by the approuter. The approuter will get the token from the uaa service and add it to the the Authorization header in the request to the service.

The secret for achieving this with minimal effort is in using default-services.json and default-env.json files. These files are included in the .gitignore file because they contain secrets you don’t want to share with the world.

The Service

The source files of the service are located in the srv folder. When you open the service.cds you can see the following:


@cds.query.limit: 100
service CapmAuthUserService @(requires:'authenticated-user'){
  entity User {
    key username   : String;

Important piece of code here is the @(requires:’authenticated-user’) this will only allow authenticated users to access theservice.

open the shell in the root directory of the project and install all npm package

npm install

After the installation of the nod modules, we start the service with the following command:

npm run start:local

This will start the service locally on https://localhost:4004

If we follow this link, we will get a 403 response ‘Forbidden:


This is due to the fact that we’ve annotated the CDS service with @(requires:’authenticated-user’)

Keep this service running, don’t close your shell.

Open a new shell window for the following steps where you will inject a JWT token into the service.
As mentioned earlier, this is done by the approuter.


The approuter is configured in the ‘approuter’ folder in the project. xs-app.json

	"welcomeFile": "/capm-auth-user",
	"authenticationMethod": "route",
	"logout": {
		"logoutEndpoint": "/do/logout"
	"routes": [{
		"source": "^/(.*)$",
		"target": "$1",
		"authenticationType": "xsuaa",
		"scope": "$XSAPPNAME.user",
		"destination": "srv_api",
		"csrfProtection": false

We’ve set authenticationMethod to “route” so we decide in each route which authentication type we want to use. There is only one route that will proxy all requests to the srv_api destination and uses xsuaa for the authentication.

Let’s first check the mta.yaml file for this module in the root folder of the project.

  - name: CAPMAuthorisation-approuter
    type: approuter.nodejs
    path: approuter
      disk-quota: 256M
      memory: 256M
      - name: CAPMAuthorisation-uaa
      - name: srv_api
        group: destinations
          forwardAuthToken: true
          name: srv_api
          strictSSL: false
          url: '~{url}'

In Cloud Foundry this approuter module requires 2 services:

  • The CAPMAuthorisation-uaa service (which is the uaa service)
  • The srv_api destination (which is provided by our CAPMAuthorisation-srv module)

In the srv_api destination, we set forwardAuthToken to true. This will forward the JWT token from the approuter to the destination.

If we want to run this approuter module locally, we must install the node modules for this module. Go into the approuter directry

cd approuter

Install the node modules

npm install

Run the approuter

npm run start

This will fail, because the approuter is not able to find the destination srv_api. When you deploy this app to cloud foundry, the approuter will find the srv_api destination because it is defined in the mta.yaml file.

throw new VError('%s%s: %s',

VError: xs-app.json/routes/0: Format validation failed (Route references unknown destination "srv_api")

We have to define this destination for our local environment.
create a default-env.json file in the approuter folder.

	"destinations": [
			"name": "srv_api",
			"url": "http://localhost:4004",
			"forwardAuthToken": true,
			"strictSSL": false

This will create the destination like we did in the mta.yaml file, but this will point to http://localhost:4004. This is the address where our service is running.

Let’s try to start the approuter again …

npm run start

This will again fail because you need a uaa service to authenticate yourself.

throw new Error('No UAA service found');
Error: No UAA service found

We can reuse the authentication service of our CF account. Let’s first search for the credentials we need for this service.

run cf apps

Get the environment variables for the approuter app

cf env CAPMAuthorisation-approuter

We will only focus on the parameters in System-Provided. There we see a service xsuaa. Copy the values in credentials.

Create a default-services.json file in the approuter folder where we will set the credentials to the UAA service.

This is the content of default-services.json.

    "uaa": {
        "apiurl": "",
        "clientid": "<your_clientid>",
        "clientsecret": "<your_clientsecret>",
        "identityzone": "<your_identityzone>",
        "identityzoneid": "<your_identityzoneid>",
        "sburl": "",
        "tenantid": "<your_tenantid>",
        "tenantmode": "dedicated",
        "uaadomain": "",
        "url": "https://<your_account>",
        "verificationkey": "-----BEGIN PUBLIC KEY-----<public key>-----END PUBLIC KEY-----",
        "xsappname": "<your_appname>"

We also need to copy this file to the root directory of our project because in the service, we need to validate the JWT token. But I found out that in the @sap/cds library they are looking for xsuaa service, so we have to rename uaa to xsuaa … (only rename the service in the default-services.json file in the root directory of the project)

    "xsuaa": {
        "apiurl": "",
        "clientid": "<your_clientid>",
        "clientsecret": "<your_clientsecret>",
        "identityzone": "<your_identityzone>",
        "identityzoneid": "<your_identityzoneid>",
        "sburl": "",
        "tenantid": "<your_tenantid>",
        "tenantmode": "dedicated",
        "uaadomain": "",
        "url": "https://<your_account>",
        "verificationkey": "-----BEGIN PUBLIC KEY-----<public key>-----END PUBLIC KEY-----",
        "xsappname": "<your_appname>"

Let’s try to start the approuter again …

npm run start

The approuter is running on port 5000


It is important to install node modules “passpor”t and “@sap/xssec” in the root folder of the project. Otherwise the injected token will be ignored in the CDS service.

The result

let’s go to http://localhost:5000


Now you have the logon screen of your account.
Enter your credentials and when you navigate to the entity User you should be able to see the current userid.

As you can see running nodejs based cloud foundry application on your own environment is very easy. The new SAP Application studio (which is available as beta feature at the moment) should also support this approach for developing and testing CAP nodejs application.



Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Pierre Dominique
      Pierre Dominique

      Thanks for sharing this with all the details Joachim!

      Author's profile photo SIMMACO FERRIERO

      Hi Joachim,

      thanks for sharing this blog.

      I followed your instructions and I found a couple of issues.

      First of all in order to make my Approuter working I had to use "UAA" instead of "XSUAA" in the default-services.json file.

      The second issue is that after I've made the Approuter starting, assigned the roles

      CA_Admin and CA_User to my user and logged into the Approuter I'm still receiving the error message "Unauthorized" when I go to the URL http://localhost:5000/capm-auth-user/$metadata. In the log, before the JWT printout, I see this:

      #2.0#2019 11 04 11:37:56:141#+01:00#INFO#/Auth/OAuth2#####k2kaji20####0RrAUzT8jnylcEUZA6SxLUuHQpQls_lc######k2kaji20#PLAIN##sending page with client-side redirect to!t12388&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Flogin%2Fcallback#

      #2.0#2019 11 04 11:37:56:141#+01:00#INFO#/Auth/OAuth2#####k2kaji20####0RrAUzT8jnylcEUZA6SxLUuHQpQls_lc######k2kaji20#PLAIN##x-forwarded-path header: undefined#

      { jti: 'c6830ccb7a9f4d2f82bebc591bba8280',


      Have you any idea about what the issue could be?




      Author's profile photo Joachim Van Praet
      Joachim Van Praet
      Blog Post Author

      Hi Simmaco,

      Have you created 2 default-services.json files in this project?

      We are running 2 applications locally here. One cds service and one approuter. Both of the applications need a reference to the uaa service. This reference needs to be configured for each application in the default-services.json file. So, you need to create 2 default-services.json files.

      The first one in the directory of the approuter, as you mentioned, you have to give it the key uaa by default. If you want to use another key, you can define this in an environment variable UAA_SERVICE_NAME (you can define this in default-env.json).

      The second default-services.json file is in the root folder of your application (same directory as where your mta.yaml file is located). And there you need to use the key xsuaa for it.

      You don't need to assign any roles to your user in this example. We only verify if the user is an authenticated user with @(requires:'authenticated-user').

      also check if you have installed node_modules @sap/xssec and passport, but normally you should have them because I've added them to the dependencies in package.json.

      And the last thing I can think of is that we need to forward the JWT token from the approuter to the service. And this is configured in the default-env.json file in the approuter directory ("forwardAuthToken": true).

      I hope one of these solutions fixes your problem. If not, please let me know!






      Author's profile photo SIMMACO FERRIERO

      Thanks Joachim, I was able to make it working now.


      Author's profile photo Manuel Seeger
      Manuel Seeger

      I Simmaco,


      Can you please expand on how you solved this? I am seeing the same output you posted, and I am also getting a 403 on the local service. Any hints on how to make this work?


      Best regards,



      Author's profile photo Cipriano Sanchez
      Cipriano Sanchez

      Hi Simmaco,

      Do you have the default-env.json in the root of the project? I was having this same issue the default-env.json was wrongly in /srv. Then I moved it one level up, in other words the root dir and as it is stated in the blog post works fine.



      Author's profile photo Manuel Seeger
      Manuel Seeger

      I have tried this and getting the local app router to redirect to the CF XSUAA login was straightforward.

      However, it looks like the local service doesn't accept the injected JWT token. No matter what I try, the locally running service responds with 403 and the CDS watch log shows

      GET /key
        data: 'Unsuccessful login attempt',
        user: '::1',
        ip: '::1',
        uuid: '3378654DEE52DD75CE4AE29E65C6DC46',
        time: '2020-03-04T11:56:52.919Z'

      Deployed on SCP the same project works fine, but for some reason it does not accept the authenticated user locally. Any ideas what to look for? Is there a way to debug the service to see what it receives in the JWT token?

      I also have a question on you xs-app.json. Here it looks like you configured the scope. Is this necessary? This would mean I would have to hard code any scope I want the approuter to forward to the service in xs-app.json? I am asking because I don't have this configuration and authorization works fine (on SCP/CF).


      Author's profile photo Manuel Seeger
      Manuel Seeger

      Managed to fix this myself


      Author's profile photo Vinicius Augusto Barrionuevo
      Vinicius Augusto Barrionuevo

      just a tip:

      if you're facing the error 'deploy is not a registered command' after running 'npm run deploy' or 'cf deploy', is because you haven't installed multiapps plugin on your local environment yet. To do so, just run the command below:

      cf install-plugin multiapps
      Author's profile photo Vinicius Augusto Barrionuevo
      Vinicius Augusto Barrionuevo

      btw, excellent post, @joachim.vanpraet

      Author's profile photo Rupinder Kaur
      Rupinder Kaur

      Very well explained..

      Author's profile photo Julia Herrmann
      Julia Herrmann

      Dear Joachim,

      thanks for your tutorial. I've got stuck during the deployment with the following error:

      11 silly lifecycle CAPMAuthorisation@1.0.0~deploy: Returned: code: 1 signal: null
      12 info lifecycle CAPMAuthorisation@1.0.0~deploy: Failed to exec deploy script
      13 verbose stack Error: CAPMAuthorisation@1.0.0 deploy: `mbt build --mtar=auth.mtar && cf deploy mta_archives/auth.mtar`
      13 verbose stack Exit status 1
      13 verbose stack at EventEmitter.<anonymous> (C:\Program Files\nodejs\node_modules\npm\node_modules\npm-lifecycle\index.js:332:16)
      13 verbose stack at EventEmitter.emit (events.js:400:28)
      13 verbose stack at ChildProcess.<anonymous> (C:\Program Files\nodejs\node_modules\npm\node_modules\npm-lifecycle\lib\spawn.js:55:14)
      13 verbose stack at ChildProcess.emit (events.js:400:28)
      13 verbose stack at maybeClose (internal/child_process.js:1055:16)
      13 verbose stack at Process.ChildProcess._handle.onexit (internal/child_process.js:288:5)
      14 verbose pkgid CAPMAuthorisation@1.0.0
      15 verbose cwd C:\Users\j\Desktop\Tutorial\SAP-CAPM-Nodejs-Authorisation-example
      16 verbose Windows_NT 10.0.19043
      17 verbose argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "run" "deploy"
      18 verbose node v14.17.5
      19 verbose npm v6.14.14
      20 error code ELIFECYCLE
      21 error errno 1
      22 error CAPMAuthorisation@1.0.0 deploy: `mbt build --mtar=auth.mtar && cf deploy mta_archives/auth.mtar`
      22 error Exit status 1
      23 error Failed at the CAPMAuthorisation@1.0.0 deploy script.


      Could you help out please?


      Thanks, Julia

      Author's profile photo Trịnh Huỳnh
      Trịnh Huỳnh

      I have tried to test user attribute, I have followed your instruction but I got the problems. The attribute value is empty.

      Here are my configuration.


      Role and Role collection configuration


      Role manager-4000 created with "Client" attribute and the value is 4000

      I want to use this value for later use in select data depending on user authorization.

      Below is my configuration for xs-security.json file in CAP.



      And my local testing console doesn't contain attribute data, it is empty.


      hybrid testing console


      What I am missing in this project?

      What can be the root cause?