Blog on App Router implementation as a sequence to this blog – Live now!

SAP Cloud Platform provides security functions such as Business User authentication, authorization management, etc. We will start with basics on some of the terminologies in security.

• Identification – User identification is all about claiming who the user is. This could be through user id, user name, email address, etc.

• Authentication – Providing the necessary credentials to prove the user. This could be through password, certificates, single sign-on, etc.

• Authorization – Once the user is authenticated, the system must verify if the user can access/perform certain operations. This can be role based, group based, etc.

Every application must be able to identify, authenticate and authorization a user to perform necessary actions. Consider the case of monolith systems that implements all the functionalities itself, it has the store of users, credentials and authorizations. In case of interconnected monoliths, it would become cumbersome to store the user credentials in all the systems individually. This is where Single Sign-On (SSO) helps. SSO provides the necessary solution for keeping the user store in one system thereby sharing the same across the required resources within a system landscape with one central login.

The following diagram represents the architecture with the components that offer the business user authentication and authorization services.

The User Account and Authorization (UAA) component is the central infrastructure component of the runtime platform for user authentication and authorization management. Some of the terminologies that are important to understand the security concept:

SAML Authentication: The Security Assertion Markup Language (SAML 2.0) is an open standard based on XML for exchanging authentication and authorization data of a principal (user) between an identity provider (IdP) and a service provider (SP). The data exchange is done through messages termed “Bearer Assertions”.

A “Bearer” is any party in possession of the assertion (see also here for further details). The integrity of the assertion is protected through XML encryption and XML signature. SAML addresses the requirement of web browser single sign-on across the internet.

OAuth Authorization: OAuth is a protocol for delegating authorizations. It defines resource owner (application that owns the data to be shared), resource server (capable of accepting and responding to resource request using access tokens), client (application that requests access) and authorization server (User Account and Authentication Service – UAA that issues tokens).

Web Tokens: JSON Web Tokens (JWT) contains header and information (like issuer, expiration time, etc.) and is signed with a private key of the UAA service. JWT transmits information as JSON object. When trying to access the application, the user must get the JWT token from the security API after which the application opens a session for the access.

Security services

As illustrated in the diagram, the application router is the entry point for the application running on the Cloud Foundry environment. The application router triggers the authentication process in UAA. The application instance is presumed to be the OAuth client and the security APIs act as the resource servers. At the time of user authentication process, the container security APIs receive an Authorization: Bearer HTTP header that contains an OAuth access token in the JWT format from the application router.

The OAuth token that is received expires after a period, post which the application instance must use the refresh token that the UAA provides to get a new access token. These tokens must be validated by the container security APIs using the security libraries provided by the UAA.

For the authentication to work, the following components need to be deployed in the Cloud Foundry environment.

Application router

The application router can be deployed along with the application instance and it is bound to the XS UAA service. It is used to serve any static contents and can be used for any application URL masking/redirection. The application router depends on the xs-app.json file for any configuration.

The approuter can be deployed by adding the following in the package.json file in a different folder in the main project:

{
    "name": "approuter",
    "dependencies": {
       "@sap/approuter": "2.6.1"
    },
    "scripts": {
        "start": "node node_modules/@sap/approuter/approuter.js"
    }
}

A sample xs-app.json file is as mentioned below:

{
   "welcomeFile": "index.html",
    "routes": [
      {
        "source": "^/application",
        "target": "/",
        "destination": "application"
      }]
}

The welcomefile attribute is to display the users with a standard screen post authentication. The redirection to the application URL is taken care by the attributes mentioned in routes. The destination is derived from the manifest.yml file that is used to deploy the application on Cloud Foundry environment of SAP Cloud Platform.

The XSUAA service instance can be created using the CLI command with the help of a xs-security.json security descriptor. The file describes the role templates, scopes, etc.

cf create-service <service_name> <service_plan> <service_instance_name> -c xs-security.json

Following is a sample manifest file:

---
applications:
- name: <<Application name>>
  memory: 256M
  buildpack: <<Buildpack>>
  env:
     USER_ROUTE: 'https://<<application name>>.cfapps.us20.hana.ondemand.com/'
#Provide service instance name required by the application
  services:
  - MyMongo 
#approuter application used for authentication and is the single point of entry
- name: approuter
  host: approuter
#path as per the project structure
  path: src/main/approuter
  buildpack: nodejs_buildpack
  memory: 128M
#Application redirect details
  env:
    destinations: >
      [
        {
          "name": "application",
          "url": "https://sentimentanalysisi048564.cfapps.us20.hana.ondemand.com",
          "forwardAuthToken": true
        }
      ]
#XS UAA service instance
    services:
    - MyUAA

Application Container

The application container acts as the resource server that provides the necessary security context for the authentication. The application container would contain certain SAP security modules to verify the scope and authorize the user access. As mentioned in the blog, you can use the following modules from the SAP NPM registry.

Sap-xssec: Contains the library for using the JWTStrategy that is used to pass the JWTokens to be validated on every API calls. It also contains the xsenv library that is used to add the XS UAA service to the JWT strategy.

Sample code as shown below:

var JWTStrategy = require(‘sap-xssec').JWTStrategy;
passport.use(new JWTStrategy(xsenv.getServices({uaa:{tag:'xsuaa'}}).uaa));
app.use(passport.initialize());
app.use(passport.authenticate('JWT', { session: false }),
/index);

We recommend that you disable the session as in the example above. Each request comes with a JWT token so it is authenticated explicitly and identifies the user. If you still need the session, you can enable it but then you should also implement user serialization/deserialization and some sort of session persistence.

With the above steps, the user authentication and authorization are taken care of using the XS UAA in Cloud Foundry environment.