Add User Authentication to Your Application (SAP HANA Cloud)

In the previous tutorial, we generated an Application Router into a our project. When we did, the wizard created an xs-security.json file in the root of the project. This file is used during the creation or update of the XSUAA service instance and controls the roles, scopes, attributes and role templates that will be part of the security for your application. What was generated was a basic version of the xs-security.json that will only require authentication but not specific roles.

We won’t add application scopes in this tutorial, but those can be added using the CDS syntax in your services. If you do add scopes to the services you can generate a sample xs-security.json using the following command and merge that into the basics xs-security.json file generated by the Application Router wizard.

cds compile srv/ --to xsuaa

Since we want to test the security setup from the Business Application Studio, we are going to have add some additional configuration to the xs-security.json. You need to add another property to the xs-security.json to configure which redirect URIs are allowed.

"oauth2-configuration": {
    "redirect-uris": [
        "https://*.applicationstudio.cloud.sap/**"
    ]
}

This wild card will allow testing from the Application Studio by telling the XSUAA it should allow authentication requests from this URL. See section Application Security Descriptor Configuration Syntax for more details on configuration options.

Open a terminal and create the XSUAA services instance with the xs-security.json configuration using the following command:

cf create-service xsuaa application MyHANAApp-xsuaa-service -c xs-security.json

In the previous tutorial, we used a default-env.json file in the root of the project, to configure the connection to the SAP HANA Cloud database. We will now extend that same file to do the same for the XSUAA instance we just created in the previous step.

Open the default-env.json and add an xsuaa section with a placeholder for the credentials which we will fill soon:

"xsuaa": [{
        "name": "MyHANAApp-xsuaa-service",
        "label": "xsuaa",
        "tags": ["xsuaa"],
        "credentials": {
            [...]
        }
    }],

From the terminal, we need to create a service key. This will give us access to the credentials for your XSUAA instance.

cf create-service-key MyHANAApp-xsuaa-service default
cf service-key MyHANAApp-xsuaa-service default

Copy the output of the service-key command and paste it into the credentials section of the default-env.json file.

Next we need to enhance the CAP application configuration in the package.json file in the root of the project. Add an uaa section to the cds.requires section of the file.

While in the package.json, also change the scripts section. Change the start script to the following:

"scripts": {
  "start": "NODE_ENV=production cds run"
}

We make this change because otherwise CAP will try to mock the authentication. But we want to test with the real production security of the XSUAA and this change will tell CAP to run in Production mode and use the XSUAA instance.

Open the srv/interaction_srv.cds file. You need to add @requires: 'authenticated-user' to the service definition. Authentication and scopes can also be applied at the individual entity level.

Finally we are going to need some additional Node.js modules for CAP to process the authentication. We can both add them to the package.json dependencies and install them all in one step from the terminal.

npm install -save passport @sap/xssec @sap/xsenv @sap/audit-logging

The approuter component implements the necessary handshake with XSUAA to let the user log in interactively. The resulting JWT token is sent to the application where it’s used to enforce authorization.

The application router configuration was generated in the previous tutorial via wizard. We now want to extend that application router setup. Start with the package.json file in the /app folder. We want to update the version of the @sap/approuter to at least version 9.1.

From the terminal change to the /app folder and run npm install to update to this newer version.

Next open the xs-app.json file in the /app folder. Here want to make several adjustments. Change the authenicationMethod to route. This will turn on authentication. You can deactivate it later by switching back to none. Also add/update the routes. We are adding authentication to CAP service route. We are also adding the Application Router User API route (which is nice for testing the UAA connection). Finally add the route to the local directory to serve the UI5/Fiori web content.

{
"authenticationMethod": "route",
"routes": [{
        "source": "/catalog/(.*)",
        "destination": "srv-api",
        "csrfProtection": true,
        "authenticationType": "xsuaa"
    },
    {
        "source": "^/user-api(.*)",
        "target": "$1",
        "service": "sap-approuter-userapi"
    }, {
        "source": "/(.*)",
        "localDir": ".",
        "authenticationType": "xsuaa"
    }
    ]
}

The application router is going to need a default-env.json file as well so during testing it can connect to the UAA instance. Copy the default-env.json file from the root of the project into the /app folder. Edit this file and add a destinations section:

"destinations": [{
  "name": "srv-api",
  "url": "http://localhost:4004",
  "forwardAuthToken": true
}],

This is setting up the internal routing from the Application Router to the CAP since we will run each separately. If you are working where the localhost:4004 came from, you can see that in the CAP log when you test the service.