Skip to Content
Author's profile photo Hariprasauth R

User Identity Management on SAP Cloud Platform

Blog on App Router implementation as a sequence to this blogLive 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:

- name: <<Application name>>
  memory: 256M
  buildpack: <<Buildpack>>
     USER_ROUTE: 'https://<<application name>>'
#Provide service instance name required by the application
  - 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
    destinations: >
          "name": "application",
          "url": "",
          "forwardAuthToken": true
#XS UAA service instance
    - 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.authenticate('JWT', { session: false }),

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.

Assigned Tags

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

      Thanks for the info. Do you have a working github project example?

      Author's profile photo Hariprasauth R
      Hariprasauth R
      Blog Post Author

      You can refer to the structure in the Git. This is currently being used for a different project.

      Author's profile photo Saurabh Jain
      Saurabh Jain

      Can we use another route service along with XSUAA in cloud foundry? Can you share relevant resources if this is possible?

      Author's profile photo Hariprasauth R
      Hariprasauth R
      Blog Post Author

      Yes. You can. You need to create a map-route and just simply use it with a destination in the metadata yml file. Look out for a blog post on this soon.

      Author's profile photo Guilherme Dellagustin
      Guilherme Dellagustin

      Is there a more detailed documentation on the XSUAA service and what each plan should be used for?

      Author's profile photo Hariprasauth R
      Hariprasauth R
      Blog Post Author

      You can find the list of plans along with the respective description in the service marketplace on SAP Cloud Platform.

      Author's profile photo Goga Didebashvili
      Goga Didebashvili

      This approach only lets SAP cloud registered users use the application though right ? How does the xsuaa attach to id service other than SAP ID service and how can we implement registration/social sign in this sample ?

      Author's profile photo Hariprasauth R
      Hariprasauth R
      Blog Post Author

      You could use SAP Identity Authentication Service (IAS) tenant to do so. You will have to provide the handshake of SAP IAS with XSUAA and bingo - You could implement any security logic you want.

      Author's profile photo Former Member
      Former Member

      Hi Community, we have also encountered an issue while using XSUAA in conjunction with SAP HANA on the SCP CF Azure environment. If anyone will also run into HTTP 500 error for node.js on SCP w/ Azure, please have a look on this SAP Note: 2470084