Securing an Application with OAuth 2.0

Estimated time

🕓 60 minutes

Objective

In this exercise, you will learn how to secure the Product List application by using a flexible authorization framework - OAuth 2.0. The Authorization Code grant of OAuth 2.0 provides an excellent security mechanism to grant only authorized users access to your application and its data. The SAP XS Advanced Application Router, the SAP XSUAA OAuth authorization service and an application written using Spring Boot, Node.js or Java are outstanding tools to configure roles, assign them to users and, finally, implement role checks in your application.

Exercise description

Microservices deployed on SAP Cloud Platform are freely accessible via the internet. To restrict access to authorized users only each microservice like the Product List application has to implement appropriate security mechanisms like OAuth 2.0.

Steps overview

The following steps are required to protect the Product List application with OAuth 2.O on the SAP Cloud Platform:

Step 1: Definition of the Application Security Descriptor
Step 2: Creation and configuration of the XSUAA service
Step 3: Configuration of the Application Router
Step 4: Secure the Product List application using XSUAA client libraries
Step 5: Deployment of the Product List Application and Approuter
Step 6: Cockpit administration task: Assign Role Collection to your User
Step 7: Access the Application
Step 8: Clean up

Step 1: Definition of the Application Security Descriptor

An Application Security Descriptor defines the details of the authentication methods and authorization types to use for accessing the Product List application. The Product List application uses this information to perform scope checks. With scopes a fine-grained user authorization can be build up. The container security library integrated in Spring, Node.js and Java Web applications allows to check scopes for each HTTP method on all HTTP endpoints. Scopes are carried by JSON Web Tokens (JWTs) which in turn are issued by the XSUAA Service.

Find xs-security.json in the /samples folder:

{
	"xsappname": "product-list",
	"tenant-mode": "dedicated",
	"scopes": [
		{
			"name": "$XSAPPNAME.read",
			"description": "With this scope, USER can read products."
		}
	],

	"role-templates": [
		{
			"name": "Viewer",
			"description": "Role to get the list of products",
			"scope-references": [
				"$XSAPPNAME.read"
			]
		}
	],
	"role-collections": [
		{
			"name": "ProductListViewer",
			"description": "Product List User",
			"role-template-references": [
				"$XSAPPNAME.Viewer"
			]
		}
	]
}

Note: Please not that $XSAPPNAME is not a placeholder. It gets replaced by the unique application name. You can find further information about the syntax of the Application Security Descriptor on SAP.help.

Step 2: Creation and configuration of the XSUAA service

To grant users access to the Product List application, an instance of the XSUAA service for this application must be created; the XSUAA service instance acts as an OAuth 2.0 client for the bound application.

You need to tell the CF CLI which Cloud Foundry you will use. To do this you have to set the API endpoint to the Cloud Controller of the Cloud Foundry region where you created your Cloud Foundry trial. Open a command prompt, navigate to the folder teched2019-cloud-cf-product-list-teched2019 in the student directory and use the command cf api CLOUD_FOUNDRY_API_ENDPOINT.
- If you attend TechEd and use the prepared subaccounts, target the EU10 region API endpoint:
```
cf api https://api.cf.eu10.hana.ondemand.com
```

💡 Note: You can find the API endpoints for the different regions where Cloud Foundry Environment is available in the SAP Cloud Platform Documentation

Login with your user account. At the command prompt type:
```
 cf login
```
You will be prompted to fill in the e-mail and password you used when you registered for the SAP Cloud Platform trial account:
```
 Email> enter your e-mail, e.g. sec360-XXX@teched.cloud.sap
 Password> password for your user
```
Show the marketplace: cf marketplace or cf m

Create the XSUAA service instance:

D:
cd D:\Files\Session\SEC364\teched2019-cloud-cf-product-list-teched2019\samples
cf create-service xsuaa application xsuaa -c xs-security.json

Display the service instances within your space using the following command: cf service or cf s.

Step 3: Configuration of the Application Router

The Application Router is used to provide a single entry point to a business application that consists of several different apps (microservices). It dispatches requests to backend microservices and acts as a reverse proxy. The rules that determine which request should be forwarded to which destinations are called routes. The application router can be configured to authenticate the users and propagate the user information. Finally, the application router can serve static content.

You can find all files that are required to install and configure the Application Router in the /samples/approuter folder.
- .npmrc
  With this the node modules are downloaded by the NPM package manager from the https://npm.sap.com SAP external NPM repository (aka registry) into a subdirectory node_modules/@sap/approuter.
- package.json Declares version and package (node_modules) of the Application Router, that is a Node.JS application.
- xs-app.json
  Configures the Application Router by defining the destinations and routes:
```
{
  "routes": [{
    "source": "^/",
    "target": "/products",
    "destination": "products-destination"
  }]
}
```

Note the "products-destination" points to the product-list application. The destination URL is configured in the manifest.yml.

Step 4: Secure the Product List application using XSUAA client libraries

Note that the application router does not hide the backend microservices in any way. They are still directly accessible bypassing the application router. So, the backend microservices must protect all their endpoints by validating the JWT token and implementing proper scope checks.

Three different implementation options are provided. For this exercise, choose one of the implementations.

Option 1: Use the Spring Boot implementation of the Product List Sample
Option 2: Use the Java implementation (not using Spring) of the Product List Sample
Option 3: Use the Node.js implementation of the Product List Sample

Step 5: Deploy Approuter and Application to Cloud Foundry

We use placeholder to simplify the personalisation of the Cloud Foundry application descriptor, the manifest.yml.
Adapt the variables ID, LANDSCAPE_APPS_DOMAIN and the others variables in the file /samples/vars.yml according to the application chosen (SpringBoot, Java, NodeJs) by using an editor of your choice.

In the samples folder push the product-list together with the approuter application to your cloud foundry space:

D:
cd D:\Files\Session\SEC364\teched2019-cloud-cf-product-list-teched2019\samples
cf push --vars-file vars.yml

Check with cf apps the status of your applications that are deployed in your Cloud Foundry space.

Note find further details in this Exercise: Deploy the application to SAP Cloud Platform Cloud Foundry Environment.

Step 6: Cockpit administration task: Assign Role Collection to your User

Now let us see how to enable access to the application for the business users or end-users.

Determine the URL of your approuter application by executing cf apps in the command prompt. The output lists the URL for the approuter which should have the following format: approuter-<ID>.<LANDSCAPE_APPS_DOMAIN>.
Launch the approuter application in the browser by opening the determined URL, e.g. https://approuter-<ID>.cfapps.eu10.hana.ondemand.com/products.
Logon with your user credentials.
If you've selected option 1 (Spring Boot) in step 4, you will get an error with HTTP status code 403 ("forbidden") which states that your user is valid and could be successfully authenticated but has no access to the applications products endpoint because of missing scopes.
If you've selected option 2 (Java) or option 3 (Node.js) in step 4, you will get an empty product list.

You can open the Developers Tools in your browser and find a failing HTTP request (status code 403) in the Network view (you need to refresh the page).

In order to enable access, the end-users should be assigned the required authorizations.
Therefore the Role Collection needs to be assigned to the user.

In the cockpit, e.g. https://account.hana.ondemand.com/cockpit/#/home/allaccounts navigate to your Subaccount. Choose Security --> Trust Configuration.
Click on the link SAP ID Service - the default trust configuration.
Now, in the Role Collection Assignment UI, enter your user id used to logon to the current account and click on button Show Assignments.
It lists the current Role Collection assignment to the user and also allows to add new Role Collections to the user
Click on button Assign Role Collection:

Note: In case you get a pop-up from Identity Provider, confirm it.

In the pop-up dialog, choose the Role Collection ProductListViewer you have defined as part of xs-security.json and click on button Assign Role Collection:
Now, the user should be able to access the application.

Further up-to-date information you can get on sap.help.com: Authorization and Trust Management in the Cloud Foundry Environment.

Step 7: Access the Application

According to the Role Collection(s) you've assigned to your user you should have read access to the product list endpoints.

You need to logon again to your application so that the authorities are assigned to your user's JWT. You can provoke a logon screen when clearing your cache. Call again your application endpoints via the approuter Uri using the Chrome browser. You should now be authorized to get a list of products.

Launch the approuter application in the browser again and login with your credentials. In order to provoke a logon-screen you may need to delete the cache or alternatively start a new private (incognito) browser window. You should be able to see the product list.

💡 The logon URL is https://$identityzone.$uaaDomain. This can be identified from the xsuaa binding credentials (cf env approuter and look for xsuaa.credentials.url)

Test the following endpoints:
- https://product-list-<ID>.<LANDSCAPE_APPS_DOMAIN>/products - GET request that provides the list of products. It is secured and provides 401 ("Unauthorized") in case no JWT access token is provided with Authorization header. Even though it shows Unauthorized (and not "Unauthenticated") it indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
- https://approuter-<ID>.<LANDSCAPE_APPS_DOMAIN>/products/ - Points to the url of the AppRouter URI. With /products path the request is routed to the index.html of the product-list app. It should show you three products with details view.
- https://approuter-<ID>.<LANDSCAPE_APPS_DOMAIN>/products/products - GET request that provides list of products (see https://product-list-<ID>.<LANDSCAPE_APPS_DOMAIN>/products).
If you selected option 1 (Spring Boot) in step 4, the following endpoints are also available to test:
- https://approuter-<ID>.<LANDSCAPE_APPS_DOMAIN>/products/productsByParam?name=Notebook Basic 15 - GET request that provides list of products filtered by name.
- https://product-list-<ID>.<LANDSCAPE_APPS_DOMAIN>/actuator/health - GET request that is not secured and can be directly accessed. It provides the information whether the product-list app is up and running.
You can have a look into the logs with:
```
cf logs product-list --recent
```

Step 8: Clean-Up

Finally delete your application and your service instances using the following commands:

cf delete -f product-list
cf delete -f approuter
cf delete-service -f xsuaa

Further Samples

You can further sample applications here:

https://github.com/SAP/cloud-security-xsuaa-integration/tree/master/samples
https://github.com/SAP/cloud-application-security-sample

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Securing an Application with OAuth 2.0

Estimated time

Objective

Exercise description

Steps overview

Step 1: Definition of the Application Security Descriptor

Step 2: Creation and configuration of the XSUAA service

Step 3: Configuration of the Application Router

Step 4: Secure the Product List application using XSUAA client libraries

Step 5: Deploy Approuter and Application to Cloud Foundry

Step 6: Cockpit administration task: Assign Role Collection to your User

Step 7: Access the Application

Step 8: Clean-Up

Further Samples

Files

README.md

Latest commit

History

README.md

File metadata and controls

Securing an Application with OAuth 2.0

Estimated time

Objective

Exercise description

Steps overview

Step 1: Definition of the Application Security Descriptor

Step 2: Creation and configuration of the XSUAA service

Step 3: Configuration of the Application Router

Step 4: Secure the Product List application using XSUAA client libraries

Step 5: Deploy Approuter and Application to Cloud Foundry

Step 6: Cockpit administration task: Assign Role Collection to your User

Step 7: Access the Application

Step 8: Clean-Up

Further Samples