From edb0d78b89a31285a8d45f2ad0fc279eeeaec47d Mon Sep 17 00:00:00 2001 From: Daniel Kuntze Date: Thu, 17 Oct 2024 14:30:59 +0200 Subject: [PATCH] Rework sap-java-buildpack-api-usage sample instructions --- .../sap-java-buildpack-api-usage/README.md | 119 +++++++++++------- .../sapbuildpack/xsuaa/HelloTokenServlet.java | 4 +- .../src/main/webapp/WEB-INF/web.xml | 11 +- .../xs-security.json | 44 +++---- 4 files changed, 101 insertions(+), 77 deletions(-) diff --git a/samples/sap-java-buildpack-api-usage/README.md b/samples/sap-java-buildpack-api-usage/README.md index 4ddbcd4445..fb66e9ccc2 100644 --- 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 -sample XSUAA ``` -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) +
+Assign role collection via cockpit +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)). +
-## 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-<>.<>`: +
+Assign role collection via command line +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 --to-user +``` +
+ +### 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-<>.<> +``` +> 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/samples/sap-java-buildpack-api-usage/src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java b/samples/sap-java-buildpack-api-usage/src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java index 688711085b..0d68c01fe4 100644 --- a/samples/sap-java-buildpack-api-usage/src/main/java/sample/sapbuildpack/xsuaa/HelloTokenServlet.java +++ b/samples/sap-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 index c720029593..c581bcbfb0 100644 --- 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 @@ + 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"> XSUAA - - Display - \ No newline at end of file diff --git a/samples/sap-java-buildpack-api-usage/xs-security.json b/samples/sap-java-buildpack-api-usage/xs-security.json index 36ccc3cd17..aa80f38204 100644 --- 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" + ] + } ] }