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 ...
This command line tool is able to get information from your cloud foundry account.
Find download and installation information here:
https://docs.cloudfoundry.org/cf-cli/install-go-cli.html
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.
https://chocolatey.org/install
https://chocolatey.org/packages/make
When make is installed, you are able to install the MTA Build tool:
More information here:
https://sap.github.io/cloud-mta-build-tool/
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.
https://github.com/jowavp/SAP-CAPM-Nodejs-Authorisation-example
Clone the project to your PC and try to deploy it to your cloud foundry account.
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.
then you can deploy the project! just run
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'
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:
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 source files of the service are located in the srv folder. When you open the service.cds you can see the following:
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
After the installation of the nod modules, we start the service with the following command:
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
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.
In Cloud Foundry this approuter module requires 2 services:
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
Install the node modules
Run the approuter
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.
We have to define this destination for our local environment.
create a default-env.json file in the approuter folder.
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 …
This will again fail because you need a uaa service to authenticate yourself.
We can reuse the authentication service of our CF account. Let’s first search for the credentials we need for this service.
Get the environment variables for the approuter app
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.
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)
Let’s try to start the approuter again …
The approuter is running on port 5000
let’s go to http://localhost:5000
TADAA …
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.
kr,
Joachim
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.
Prerequisites
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:
https://docs.cloudfoundry.org/cf-cli/install-go-cli.html
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.
https://chocolatey.org/install
https://chocolatey.org/packages/make
When make is installed, you are able to install the MTA Build tool:
npm install -g mbtMore information here:
https://sap.github.io/cloud-mta-build-tool/
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.
https://github.com/jowavp/SAP-CAPM-Nodejs-Authorisation-example
Clone the project to your PC and try to deploy it to your cloud foundry account.
git clone https://github.com/jowavp/SAP-CAPM-Nodejs-Authorisation-example
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: https://api.cf.eu10.hana.ondemand.com
Email> joachim.vanpraet@****.com
Password>
Authenticating...
OK
Select an org (or press enter to skip):
1. S0003564161trial_trial
Org> 1
Targeted org S0003564161trial_trial
Targeted space dev
API endpoint: https://api.cf.eu10.hana.ondemand.com (API version: 2.141.0)
User: joachim.vanpraet@****.com
Org: S0003564161trial_trial
Space: devthen you can deploy the project! just run
npm run deploythis 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...
OK
name requested state instances memory disk urls
CAPMAuthorisation-approuter started 1/1 256M 256M s0003564161trial-trial-dev-capmauthorisation-approuter.cfapps.eu10.hana.ondemand.com
CAPMAuthorisation-srv started 1/1 512M 256M s0003564161trial-trial-dev-capmauthorisation-srv.cfapps.eu10.hana.ondemand.comyou'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:
@impl:'service.js'
@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 installAfter the installation of the nod modules, we start the service with the following command:
npm run start:localThis will start the service locally on https://localhost:4004
If we follow this link, we will get a 403 response ‘Forbidden:
{"error":{"message":"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.
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
parameters:
disk-quota: 256M
memory: 256M
requires:
- name: CAPMAuthorisation-uaa
- name: srv_api
group: destinations
properties:
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 approuterInstall the node modules
npm installRun the approuter
npm run startThis 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.
C:\Users\vanprjo\git\capm-nodejs-authorisations\approuter\node_modules\@sap\approuter\lib\utils\JsonValidator.js:30
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 startThis will again fail because you need a uaa service to authenticate yourself.
C:\git\capm-nodejs-authorisations\approuter\node_modules\@sap\approuter\lib\configuration.js:64
throw new Error('No UAA service found');
Error: No UAA service foundWe can reuse the authentication service of our CF account. Let’s first search for the credentials we need for this service.
run cf appsGet the environment variables for the approuter app
cf env CAPMAuthorisation-approuterWe 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": "https://api.authentication.eu10.hana.ondemand.com",
"clientid": "<your_clientid>",
"clientsecret": "<your_clientsecret>",
"identityzone": "<your_identityzone>",
"identityzoneid": "<your_identityzoneid>",
"sburl": "https://internal-xsuaa.authentication.eu10.hana.ondemand.com",
"tenantid": "<your_tenantid>",
"tenantmode": "dedicated",
"uaadomain": "authentication.eu10.hana.ondemand.com",
"url": "https://<your_account>.authentication.eu10.hana.ondemand.com",
"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": "https://api.authentication.eu10.hana.ondemand.com",
"clientid": "<your_clientid>",
"clientsecret": "<your_clientsecret>",
"identityzone": "<your_identityzone>",
"identityzoneid": "<your_identityzoneid>",
"sburl": "https://internal-xsuaa.authentication.eu10.hana.ondemand.com",
"tenantid": "<your_tenantid>",
"tenantmode": "dedicated",
"uaadomain": "authentication.eu10.hana.ondemand.com",
"url": "https://<your_account>.authentication.eu10.hana.ondemand.com",
"verificationkey": "-----BEGIN PUBLIC KEY-----<public key>-----END PUBLIC KEY-----",
"xsappname": "<your_appname>"
}
}Let’s try to start the approuter again …
npm run startThe approuter is running on port 5000
Note:
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
TADAA …
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.
kr,
Joachim
- SAP Managed Tags:
13 Comments
