Rework sap-java-buildpack-api-usage sample instructions

SAP · Oct 17, 2024 · edb0d78 · edb0d78
1 parent 4f709e9
commit edb0d78
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 77 deletions.
diff --git a/samples/sap-java-buildpack-api-usage/README.md b/samples/sap-java-buildpack-api-usage/README.md
@@ -1,81 +1,111 @@
-# Description
-This sample is a Java Back-End application that demonstrates usage of [SAP Java Buildpack](https://help.sap.com/docs/btp/sap-business-technology-platform/developing-java-in-cloud-foundry-environment).
-SAP Java Buildpack bundles the [Java Security](/java-security/) client library to authenticate JWT tokens issued by the `Xsuaa` service.
-It inspects incoming requests to determine if the user has the appropriate authorization by using the [`XsuaaTokenAuthenticator`](/java-security/src/main/java/com/sap/cloud/security/servlet/XsuaaTokenAuthenticator.java).
+# SAP BTP Java Security Client Library Buildpack sample application
+This Java backend application demonstrates the usage of the [SAP Java Buildpack](https://help.sap.com/docs/btp/sap-business-technology-platform/developing-java-in-cloud-foundry-environment).
+The SAP Java Buildpack bundles the [java-security](/java-security/) module, which is used to validate JWT tokens issued by the `XSUAA` service.
+Authentication and authorization of incoming requests are handled using the [`XsuaaTokenAuthenticator`](/java-security/src/main/java/com/sap/cloud/security/servlet/XsuaaTokenAuthenticator.java).
 
-:warning: Please note that this sample is based on the `java-security` library, which requires the Tomcat 10 runtime.
+:warning: Please note that this sample is based on the `java-security` module, which requires the Tomcat 10 runtime.
 Therefore, it needs to be deployed using the [SAP Java Buildpack 2](https://help.sap.com/docs/btp/sap-business-technology-platform/sap-jakarta-buildpack) (sap_java_buildpack_jakarta).
 
-In a typical UI5 application, the application router server HTML files and REST data would be provided by a back-end application. To focus on the security part, UI5 has been omitted.
+In a typical UI5 application, the application router serves HTML files and REST data would be provided by a back-end application.
+To focus on the security part, UI5 has been omitted.
 
-> :bulb: This application manages your SAP Java buildpack dependencies using [Bill of Materials](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/6c6936e8e4ea40c9a9a69f6783b1e978.html). Check [SJB BoM on Maven Repository](https://mvnrepository.com/artifact/com.sap.cloud.sjb.cf/sap-java-buildpack-bom) to see which versions are provided.
+:bulb: This application manages your SAP Java buildpack dependencies using [Bill of Materials](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/6c6936e8e4ea40c9a9a69f6783b1e978.html). Check [SJB BoM on Maven Repository](https://mvnrepository.com/artifact/com.sap.cloud.sjb.cf/sap-java-buildpack-bom) to see which versions are provided.
 
-The [web.xml](src/main/webapp/WEB-INF/web.xml) of the application must use auth-method with value `XSUAA`. This enables authentication of requests using incoming OAuth authentication tokens.
+The [web.xml](src/main/webapp/WEB-INF/web.xml) of the application must use auth-method with value `XSUAA`.
+This enables authentication of requests using incoming OAuth tokens.
 
 ```xml
 <web-app>
-<display-name>sample</display-name>
   <login-config> 
     <auth-method>XSUAA</auth-method>
   </login-config> 
 </web-app> 
 ```
 
-In your Web Servlet, use then the `@ServletSecurity` annotations as implemented in [HelloTokenServlet](/samples/sap-java-buildpack-api-usage/src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java).
-
-# Deployment on Cloud Foundry
-To deploy the application, the following steps are required:
-- Configure the Application Router
-- Compile the Java application
-- Create a xsuaa service instance
-- Configure the manifest
-- Deploy the application
-git
-- Access the application
+In your Web Servlet, then use the `@ServletSecurity` annotation as showcased in [HelloTokenServlet](src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java).
 
 ## Configure the Application Router
-The [Application Router](./approuter/package.json) 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.
-
-## Compile the Java application
-Run maven to package the application
+The [Application Router](approuter/package.json) 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.
+
+## Build and Deploy
+### 1. Run maven to compile and package the sample application:
 ```shell
 mvn clean package
 ```
 
-## Create the xsuaa service instance
-Use the [xs-security.json](./xs-security.json) to define the authentication settings and create a service instance
+### 2. The following steps deploy the application using Cloud Foundry.
+#### Create the XSUAA service instance
+Use the cf CLI to create an XSUAA service instance based on the authentication settings in [xs-security.json](xs-security.json).
 ```shell
 cf create-service xsuaa application xsuaa-buildpack -c xs-security.json
 ```
 
-## Configure the manifest
-
-The [vars](../vars.yml) contains hosts and paths that need to be adopted.
+#### Configure the manifest
+The [vars](../vars.yml) contain hosts and paths that need to be adopted.
 
 This sample uses the `AccessToken` interface to extract user data from the principal. For this to work the environment
-variable `ENABLE_SECURITY_JAVA_API_V2` is set to `true`. This can be done in the `manifest.yml` file inside the
+variable `ENABLE_SECURITY_JAVA_API_V2` is set to `true`. This can be done in the [`manifest.yml`](manifest.yml) file inside the
 configuration block of the `sap-java-buildpack-api-usage` application. With this flag set to `true` the principal from
 `HttpServlet.getUserPrincipal()` will contain an `AccessToken` instead of a `XSUserInfo`.
 
-## Deploy the application
-Deploy the application using cf push. It will expect 1 GB of free memory quota.
+#### Deploy the application
+Deploy the application using the cf CLI.
 
 ```shell
 cf push --vars-file ../vars.yml
 ```
+:warning: This will expect 1 GB of free memory quota.
+
+### 3. Assign Role Collection to user
+:bulb: You can postpone this step if you first want to test the application without the required authorization.
 
-## Cockpit administration tasks: Assign Role to your User
-Finally, as part of your Identity Provider, e.g. SAP ID Service, assign the deployed Role Collection(s) such as `Buildpack_API_Viewer` to your user as depicted in the screenshot below and as documented [here](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9e1bf57130ef466e8017eab298b40e5e.html).
+To get full access to the sample application, you need a user having the role collection `Sample Viewer (java-security-usage)` assigned.
+This can be done in the SAP BTP Cockpit or using the btp CLI.
 
-![](../images/SAP_CP_Cockpit_AssignRoleCollectionToUser.png)
+<details>
+<summary>Assign role collection via cockpit</summary>
+In the cockpit navigate to your subaccount.
+To assign the role collection of the sample application to a user you have basically two options:
 
-Further up-to-date information you can get on sap.help.com:
-- [Maintain Role Collections](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/d5f1612d8230448bb6c02a7d9c8ac0d1.html)
-- [Maintain Roles for Applications](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/7596a0bdab4649ac8a6f6721dc72db19.html).
+1. Navigate to the user by clicking on `Security` -> `Users`,
+   select the user and click on `Assign Role Collection`
+   (more info at [help.sap.com](https://help.sap.com/docs/btp/sap-business-technology-platform/find-users-and-their-role-collection-assignments)).
+2. Navigate to the role collection by clicking on `Security` -> `Role Collections`,
+   select `Sample Viewer (sap-java-buildpack-api-usage)`,
+   click on `Edit` to add the user and finish by clicking on `Save`
+   (more info at [help.sap.com](https://help.sap.com/docs/btp/sap-business-technology-platform/assign-users-to-role-collections)).
+</details>
 
-## Access the application
-After deployment, the application router will trigger authentication. If you have assigned the role-collection provided in the [xs-security.json](./xs-security.json) to your user, you will see an output like when calling `https://approuter-sap-java-buildpack-api-usage-<<ID>>.<<LANDSCAPE_APPS_DOMAIN>>`:
+<details>
+<summary>Assign role collection via command line</summary>
 
+To assign the role collection to a user via the [btp CLI](https://help.sap.com/docs/btp/sap-business-technology-platform/account-administration-using-sap-btp-command-line-interface-btp-cli),
+you need to [log in to your global account](https://help.sap.com/docs/btp/btp-cli-command-reference/btp-login) and execute the following command:
+
+```shell
+btp assign security/role-collection "Sample Viewer (sap-java-buildpack-api-usage)" --subaccount <subaccount id> --to-user <user email>
+```
+</details>
+
+### 3. Access the application
+The sample application provides a single HTTP endpoint:
+- `/hello-token` - authorized access only
+
+After the deployment, the application router will trigger authentication and [route requests](approuter/xs-app.json) to the above endpoint.
+If you have assigned the role-collection as described above, you can access the application at:
+```
+https://approuter-sap-java-buildpack-api-usage-<<ID>>.<<LANDSCAPE_APPS_DOMAIN>>
+```
+> Note: you can find the route of your approuter application using the cf CLI:
+> ```
+> cf app approuter-sap-java-buildpack-api-usage
+> ```
+
+You should see something like this:
 ```
 Client ID: sap-java-buildpack-api-usage!t5721
 Email: user@mail
@@ -84,14 +114,11 @@ First Name: Bob
 OAuth Grant Type: authorization_code
 OAuth Token: eyJhbGciOiJSUzI1NiIsInR5...
 ```
-If not you should get a `403` status code (Forbidden).
 
-> Note: you can find the route of your approuter application using `cf app approuter-sap-java-buildpack-api-usage`.
+### 4. Cleanup
+If you no longer need the sample application, you can free up resources using the cf CLI.
 
-## Clean-Up
-
-Finally, delete your application and your service instances using the following commands:
-```
+```shell
 cf delete -f sap-java-buildpack-api-usage
 cf delete -f approuter-sap-java-buildpack-api-usage
 cf delete-service -f xsuaa-buildpack

diff --git a/...p-java-buildpack-api-usage/src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java b/...p-java-buildpack-api-usage/src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java
@@ -17,10 +17,10 @@
 import java.io.IOException;
 
 /**
- * Servlet implementation configured to check against scope "$XSAPPNAME.Display"
+ * Servlet implementation configured to check against scope "$XSAPPNAME.Read"
  */
 @WebServlet("/hello-token")
-@ServletSecurity(@HttpConstraint(rolesAllowed = { "Display" }))
+@ServletSecurity(@HttpConstraint(rolesAllowed = { "Read" }))
 public class HelloTokenServlet extends HttpServlet {
 
 	/**

diff --git a/samples/sap-java-buildpack-api-usage/src/main/webapp/WEB-INF/web.xml b/samples/sap-java-buildpack-api-usage/src/main/webapp/WEB-INF/web.xml
@@ -2,15 +2,12 @@
 <!-- SPDX-FileCopyrightText: 2018-2023 SAP SE or an SAP affiliate company and Cloud Security Client Java contributors -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 <web-app
-        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xmlns="https://jakarta.ee/xml/ns/jakartaee"
-        xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
-        version="5.0">
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://jakarta.ee/xml/ns/jakartaee"
+    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
+    version="5.0">
 
     <login-config>
         <auth-method>XSUAA</auth-method>
     </login-config>
-    <security-role>
-        <role-name>Display</role-name>
-    </security-role>
 </web-app>
diff --git a/samples/sap-java-buildpack-api-usage/xs-security.json b/samples/sap-java-buildpack-api-usage/xs-security.json
@@ -1,29 +1,29 @@
 {
 	"xsappname": "sap-java-buildpack-api-usage",
+	"description": "SAP BTP Java Security Client Library Buildpack sample application",
 	"tenant-mode": "dedicated",
-	"scopes":
-	[{
-		"name": "$XSAPPNAME.Display",
-		"description": "With this scope, information can be read."
-	}
+	"scopes": [
+		{
+			"name": "$XSAPPNAME.Read",
+			"description": "Scope for sap-java-buildpack-api-usage sample application"
+		}
 	],
-
-	"role-templates":
-	[{
-		"name": "AccessRole",
-		"description": "Role to call the sap-java-buildpack-api-usage service",
-		"scope-references":
-		[
-			"$XSAPPNAME.Display"
-		]
-	}
+	"role-templates": [
+		{
+			"name": "Viewer",
+			"description": "Role for sap-java-buildpack-api-usage sample application",
+			"scope-references": [
+				"$XSAPPNAME.Read"
+			]
+		}
 	],
-	"role-collections": [{
-		"name": "Buildpack_API_Viewer",
-		"description": "Role Collection to call the sap-java-buildpack-api-usage service",
-		"role-template-references": [
-			"$XSAPPNAME.AccessRole"
-		]
-	}
+	"role-collections": [
+		{
+			"name": "Sample Viewer (sap-java-buildpack-api-usage)",
+			"description": "Role collection for sap-java-buildpack-api-usage sample application",
+			"role-template-references": [
+				"$XSAPPNAME.Viewer"
+			]
+		}
 	]
 }