Secure Your Application on SAP Cloud Platform Cloud Foundry

You will let Cloud Foundry retrieve the App Router automatically on deployment. To achieve this, you will first set up the necessary structure.

1. Go to your favourite <destLocation> and create the approuter directory:

   cd <destLocation>
   mkdir approuter
   cd approuter
   

2. Place the following package.json in your approuter directory:

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

3. Within <destLocation>/approuter create a new file called xs-app.json with the following content:

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

4. Last but not least create a new manifest.yml file within <destLocation> for the app router microservice with the following content:

   
   ---
   applications:
   - name: approuter
     routes:
       - route: approuter-<subdomain>.cfapps.<region_id>.hana.ondemand.com
     path: approuter
     memory: 128M
     buildpacks:
       - nodejs_buildpack
     env:
       TENANT_HOST_PATTERN: 'approuter-(.*).cfapps.<region_id>.hana.ondemand.com'
       destinations: '[{"name":"app-destination", "url" :"<APPLICATION_URL>", "forwardAuthToken": true}]'
     services:
       - my-xsuaa
   

   Adapt the file as follows:

   • Replace <subdomain> with your subdomain. You will find your subdomain in the CF cockpit by heading to the overview page of your sub-account:

     

   • Swap out both instances of <region_id> with your specific region (e.g. eu10). You can find it for instance included in the API endpoint (also listed in the image above) just before hana.ondemand.com. More details on the region specific URLs can be found here.

   • In destinations replace <APPLICATION_URL> with the actual URL of your previously deployed app. Again you can find it in the CF cockpit or by listing all existing routes via cf routes. Note: The URI specified for <APPLICATION_URL> must be absolute, e.g. https://<app-name>.cfapps.<region>.hana.ondemand.com.

Understanding the AppRouter’s manifest.yml

On Cloud Foundry every sub-account is assigned exactly one subdomain which is associated to exactly one tenant. In a multi-tenant scenario the app router needs to know which tenant to forward to the XSUAA service. This is achieved by including the subdomain in the host, from which the app router will extract it. That is where the TENANT_HOST_PATTERN comes into play. It is a variable that declares the pattern how tenants in the URL are identified and handled. For this tutorial we expect the host to conform to approuter-<subdomain>. If you desire different URL patterns, you need to change the route and TENANT_HOST_PATTERN accordingly.

Note that the TENANT_HOST_PATTERN variable is only required in real multi-tenant application, i.e, applications where a physical deployment serves multiple clients from the same deployment. This tutorial series assumes that you want to build multi-tenant applications, as it is aimed towards cloud-native development. However, this variable is not necessary if you have a single-tenant application. To realize this, the xs-security.json security descriptor may declare "tenant-mode": "dedicated" (see step 5 below).

Moving on to the destinations entry. It is a variable that declares the internal routes from the App Router to the underlying backend microservices. As you have only one microservice yet, you may define only one destination called app-destination here. This app-destination is referenced by the previously created xs-app.json file.

Last but not least the services section declares to bind your own XSUAA service instance to the App Router. This binding will ensure a corresponding VCAP_SERVICES entry that holds the client ID, client secret and public key that is required to validate any incoming OAuth token/JWT from the XSUAA service:

Bind the XSUAA Service

Now you need to create a service binding to the XSUAA service. As a prerequisite you require an xs-security.json (security descriptor) file that contains a declaration about authorization scopes you intend to use in your application. For example, simply declare a DISPLAY scope that will be used later on to authorize your users. In addition, a so-called role template called Viewer that references our DISPLAY scope is declared.

Put this file to <destLocation>/xs-security.json. For a more detailed explanation on scopes and role templates, see the appendix of this tutorial. More details on the syntax of the xs-security.json can be found here.

Note: The xsappname has to be unique within the entire XSUAA instance. We suggest you follow the same pattern of <app-name>-<subdomain>.

Note: As explained above, the "tenant-mode": "shared" assumes a multi-tenant application and will require the TENANT_HOST_PATTERN variable to be declared. You may also use "tenant-mode": "dedicated" if you develop a single-tenant application.

<destLocation>/xs-security.json:

{
  "xsappname": "firstapp-<subdomain>",
  "tenant-mode": "shared",
  "scopes": [
    {
      "name": "$XSAPPNAME.Display",
      "description": "display"
    }
  ],
  "role-templates": [
    {
      "name": "Viewer",
      "description": "Required to view things in our solution",
      "scope-references"     : [
        "$XSAPPNAME.Display"
      ]
    }
  ]
}

Create the file and change the app name just like before.

Then create a service instance called my-xsuaa of the XSUAA service by issuing the following command and using the xs-security.json file:

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

If you have created this instance of the XSUAA service before without the xs-security.json parameter, you can unbind and delete the existing instance with these commands before creating it with the above command:

cf unbind-service firstapp my-xsuaa
cf delete-service my-xsuaa​

After you have created the XSUAA service instance, deploy the app router using the following (with the appropriate API endpoint of your Cloud Foundry region):

cd <destLocation>
cf push

Afterwards you should be able to locate the app router from within your browser using the host name of your deployment. In my case this is https://approuter-p1942765239trial.cfapps.eu10.hana.ondemand.com/hello which should face you with the following login page where you can use your user e-mail and password:

After logging in you should see the HelloWorld servlet which is now served by the App Router as a proxy to your Java application:

After authentication works with the App Router, your java backend service is still fully visible in the web and not protected. Therefore, you need to protect your java microservices as well so that they accept requests with valid JWTs for the current user only. In addition, you will setup the microservice in a way that it deals with authorization, i.e., understands the OAuth scopes from the JWT that we have configured previously using the xs-security.json file.

<login-config>
    <auth-method>XSUAA</auth-method>
</login-config>

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Baseline Security</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>*</role-name>
    </auth-constraint>
</security-constraint>

<security-role>
    <role-name>Display</role-name>
</security-role>
<!--
<security-role>
    <role-name>Further Role Name</role-name>
</security-role>
-->

@ServletSecurity(@HttpConstraint(rolesAllowed = { "Display" }))
public class BusinessPartnerServlet extends HttpServlet {
  // ...
}

<dependency>
    <groupId>com.sap.cloud.security.xsuaa</groupId>
    <artifactId>xsuaa-spring-boot-starter</artifactId>
</dependency>

@Configuration
@EnableWebSecurity(debug = true) // TODO "debug" may include sensitive information. Do not use in a production system!
@EnableGlobalMethodSecurity(prePostEnabled = true, securedEnabled = true, jsr250Enabled = true)
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

    @Autowired
    XsuaaServiceConfiguration xsuaaServiceConfiguration;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS) // session is created by approuter
                .and()
                .authorizeRequests()
                .antMatchers("/*").authenticated()
                .antMatchers("/*").hasAuthority("Display")
                .anyRequest().denyAll()
                .and()
                .oauth2ResourceServer()
                .jwt()
                .jwtAuthenticationConverter(getJwtAuthenticationConverter());
    }

    /**
     * Customizes how GrantedAuthority are derived from a Jwt
     */
    Converter<Jwt, AbstractAuthenticationToken> getJwtAuthenticationConverter() {
        return new TokenAuthenticationConverter(xsuaaServiceConfiguration).setLocalScopeAsAuthorities(true);
    }
}

At this point you should now rebuild your application and push it to Cloud Foundry.

cd /path/to/firstapp/application
mvn clean install
cd /path/to/firstapp
cf push

If you now call the /businesspartners endpoint of your application you will see a 401 Unauthorized status code, as you were not authorized by the App Router. Calling the /businesspartners endpoint via your App Router on the other hand will give you a 403 Forbidden status code meaning that you do not have the necessary authorization to see this page. This is to be expected, as you secured the endpoint with the annotation above without assigning the requested role Display to your user. You will fix this in the next step.

Now you are ready to build and deploy the application to try all your changes with:

cd /path/to/firstapp/application
mvn clean install
cd /path/to/firstapp
cf push

After deployment, accessing your backend service directly should not be possible anymore and result in the following message:

However, you should still be able to access your application using the App Router as entry point:

If you have previously exposed the backing service directly to the end user, you have used the RestCsrfPreventionFilter on the backend to protect against cross-site request forgery. As this is now in the responsibility of the App Router, you should remove it. For this remove the following lines from your web.xml:

<filter>
  <filter-name>RestCsrfPreventionFilter</filter-name>
  <filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>RestCsrfPreventionFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Sometimes it might be necessary to investigate the JWT on the backend microservice during development to check for potential errors. Here is an example servlet that prints the token out.

@WebServlet("/debug")
public class JwtDebugServlet extends HttpServlet {

    @Override
    protected void doGet(final HttpServletRequest request, final HttpServletResponse response )
            throws ServletException, IOException
    {
        response.setContentType("text/plain");
        Enumeration headerNames = request.getHeaderNames();
        while (headerNames.hasMoreElements()) {
            String key = (String) headerNames.nextElement();
            String value = request.getHeader(key);

            response.getOutputStream().println(key+" : "+value);
        }
    }
}

Afterwards you may use https://jwt.io/ to decode the token. Note: You should never use this with any productive JWT as these tokens are shared on a public website. Fallback to local solutions.