Express sample (#4)

* add ams-expressjs-shopping project
* set-up separate github workflows for respective sample folders

Author: finkmanAtSap

.github/workflows/build_and_test_cap.yml

@@ -1,13 +1,19 @@
 # This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
 
-name: CAP sample - Build and Test
+name: CAP sample
 
 on:
   push:
     branches: [ "main" ]
+    paths:
+      - "ams-cap-nodejs-bookshop/**"
+      - ".github/workflows/build_and_test_cap.yml"
   pull_request:
     branches: [ "**" ]
+    paths:
+      - "ams-cap-nodejs-bookshop/**"
+      - ".github/workflows/build_and_test_cap.yml"
 
 jobs:
   npm:
@@ -16,7 +22,7 @@ jobs:
       JAVA_HOME: /usr/lib/jvm/java-17-openjdk
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x]
+        node-version: [20.x, 22.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:

.github/workflows/build_and_test_expressjs.yml

@@ -0,0 +1,44 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Express sample
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - "ams-expressjs-shopping/**"
+      - ".github/workflows/build_and_test_expressjs.yml"
+  pull_request:
+    branches: [ "**" ]
+    paths:
+      - "ams-expressjs-shopping/**"
+      - ".github/workflows/build_and_test_expressjs.yml"
+
+jobs:
+  npm:
+    runs-on: [ ubuntu-latest ]
+    env:
+      JAVA_HOME: /usr/lib/jvm/java-17-openjdk
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+        cache-dependency-path: ams-expressjs-shopping
+    - name: Set up JDK 17 # for DCL -> DCN compilation to work before tests
+      uses: actions/setup-java@v4
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+    - run: npm ci
+      working-directory: ams-expressjs-shopping
+    - run: npm test
+      working-directory: ams-expressjs-shopping

ams-expressjs-shopping/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+
+test/dcn

ams-expressjs-shopping/README.md

@@ -0,0 +1,69 @@
+# SAP Identity Service Authentication and Authorization Sample
+
+This project is a sample application that demonstrates how to use SAP Identity Service for authentication and authorization via the client libraries [`@sap/xssec`](https://www.npmjs.com/package/@sap/xssec) and [`@sap/ams`](https://www.npmjs.com/package/@sap/ams).
+
+---
+
+## Demonstrated Features
+
+1. **Authentication via IAS (Identity Authentication Service)**:
+   - Uses the `@sap/xssec` library to authenticate users via SAP Identity Service.
+
+1. **Authorization via AMS (Authorization Management Service)**:
+   - Uses the `@sap/ams` library to check user privileges for specific actions and resources and provide instance-based authorization.
+   - Demonstrates how to configure and use the `IdentityServiceAuthProvider` for authorization based on IAS tokens.
+
+1. **Middleware Integration**:
+   - Demonstrates how to integrate the client libraries into an Express application for seamless access to the security context and authorization checks in any place where the `req` object is available.
+
+1. **Technical communication** via SAP Identity Service APIs
+   - Demonstrates how the `IdentityServiceAuthProvider` can authorize principal propagation requests from other systems that consume SAP Identity Service APIs of this application. The resulting authorizations are the intersection of the user's policies and the policies defined for the consumed API.
+
+1. **Mocking security contexts for Testing**:
+   - Shows how different security contexts can be mocked for testing without authenticating via a real IAS instance.
+   - Demonstrates how to compile DCL policies locally to DCN and use users with mocked policy assignments for testing without a real AMS instance.
+
+1. **Privilege-Based UI Rendering**:
+   - Includes an example of how to retrieve potential user privileges to determine which UI elements to display.
+
+---
+
+## Project Structure
+
+- **`server.js`**:
+  - The main application server setup.
+
+- **`auth/authenticate.js` and `auth/authorize.js`**:
+  - Contains the main logic for setting up authentication and authorization.
+
+- **`auth/dcl`**:
+  - Defines the authorization policies.
+
+- **`db`**:
+  - A mock database with dummy data.
+
+- **`service`**:
+  - Service layer of the application with request handlers for the REST API.
+
+- **`ui`**:
+  - A simple UI to demonstrate features of this project when logged in with users that have different policies assigned.
+
+- **`test`**:
+  - Tests against the REST API that demonstrate the expected result of the authorization checks.
+
+---
+
+## Testing
+
+### Run Unit Tests
+```bash
+npm i
+npm test
+```
+
+### Start server for local testing
+```bash
+NODE_ENV=test npm start
+```
+
+The application UI will be accessible under https://localhost:3000.

ams-expressjs-shopping/auth/apis.js

@@ -0,0 +1,25 @@
+const TECHNICAL_USER_APIS = [
+    "GetProducts"
+]
+
+const PRINCIPAL_PROPAGATION_APIS = [
+    "GetProducts",
+    "ExternalOrder"
+]
+
+function mapTechnicalUserApi(api) {
+    if (TECHNICAL_USER_APIS.includes(api)) {
+        return `internal.${api}`;
+    }
+}
+
+function mapPrincipalPropagationApi(api) {
+    if (PRINCIPAL_PROPAGATION_APIS.includes(api)) {
+        return `internal.${api}`;
+    }
+}
+
+module.exports = {
+    mapTechnicalUserApi,
+    mapPrincipalPropagationApi
+}

ams-expressjs-shopping/auth/authenticate.js

@@ -0,0 +1,63 @@
+const { SECURITY_CONTEXT } = require('@sap/xssec'); // USER_AGENT is just a placeholder during development until the SECURITY_CONTEXT Symbol is available
+const { createSecurityContext, IdentityService, IdentityServiceToken, IdentityServiceSecurityContext, errors: { ValidationError } } = require('@sap/xssec');
+
+// --- Sets up AUTHENTICATION as pre-condition for AUTHORIZATION ---
+
+const authenticate = process.env.NODE_ENV === 'test' ? buildMockAuthMiddleware() : buildAuthMiddleware();
+
+/*
+Middleware for SAP Identity Service based authentication 
+following the example in the @sap/xssec documentation:
+https://www.npmjs.com/package/@sap/xssec#example
+*/
+function buildAuthMiddleware() {
+    const identityService = require('./identityService');
+
+    return async function authenticate(req, res, next) {
+        try {
+            const secContext = await createSecurityContext(identityService, { req });
+            req[SECURITY_CONTEXT] = secContext;
+            return next();
+        } catch (e) {
+            if (e instanceof ValidationError) {
+                console.error("Unauthenticated request: ", e);
+                return res.sendStatus(401);
+            }
+
+            throw e; // handled in express error handler
+        }
+    }
+}
+
+/*
+Middleware for mocked authentication 
+following the recommendation in the @sap/xssec documentation for testing without real JWTs:
+https://www.npmjs.com/package/@sap/xssec#testing
+*/
+function buildMockAuthMiddleware() {
+    return async function mockAuthentication(req, res, next) {
+        const basicAuthUser = req.headers['authorization']?.split(' ')[1];
+        if (!basicAuthUser) {
+            return res.sendStatus(401);
+        }
+
+        const user = Buffer.from(basicAuthUser, 'base64').toString().split(':')[0];
+        const [username, api] = user.split('|');
+        const mockPayload = {
+            app_tid: "default",
+            scim_id: username,
+            sub: username,
+            azp: "client_id",
+            ias_apis: api ? [api] : []
+        };
+
+        const mockToken = new IdentityServiceToken(null, { header: {}, payload: mockPayload });
+        const mockService = new IdentityService({});
+        const mockedSecurityContext = new IdentityServiceSecurityContext(mockService, mockToken, {});
+
+        req[SECURITY_CONTEXT] = mockedSecurityContext;
+        next();
+    }
+}
+
+module.exports = authenticate;

ams-expressjs-shopping/auth/authorize.js

@@ -0,0 +1,46 @@
+const { AuthorizationManagementService, IdentityServiceAuthProvider, TECHNICAL_USER_FLOW, PRINCIPAL_PROPAGATION_FLOW } = require("@sap/ams");
+const { mapTechnicalUserApi, mapPrincipalPropagationApi } = require("./apis");
+
+let ams;
+if (process.env.NODE_ENV === 'test') {
+    ams = AuthorizationManagementService.fromLocalDcn("./test/dcn", {
+        assignments: "./test/mockPolicyAssignments.json"
+    });
+} else {
+    // production
+    const identityService = require('./identityService');
+    ams = AuthorizationManagementService.fromIdentityService(identityService);
+}
+
+const authProvider = new IdentityServiceAuthProvider(ams)
+    .withApiMapper(mapTechnicalUserApi, TECHNICAL_USER_FLOW)
+    .withApiMapper(mapPrincipalPropagationApi, PRINCIPAL_PROPAGATION_FLOW);
+const amsMw = authProvider.getMiddleware();
+const authorize = amsMw.authorize();
+
+if (process.env.DEBUG?.split(",").includes("ams")) {
+    ams.on("authorizationCheck", event => {
+        if (event.type === "checkPrivilege") {
+            if (event.decision.isGranted()) {
+                console.log(`Privilege '${event.action} ${event.resource}' for ${event.context.token.scimId} was granted based on input`, event.input);
+            } else if(event.decision.isDenied()) {
+                console.log(`Privilege '${event.action} ${event.resource}' for ${event.context.token.scimId} was denied based on input`, event.input);
+            } else {
+                console.log(`Privilege '${event.action} ${event.resource}' for ${event.context.token.scimId} was conditionally granted based on input`, event.input);
+            }
+        }
+    });
+
+    ams.on("error", event => {
+        if (event.type === "bundleRefreshError") {
+            console.warn("AMS bundle refresh error:", event.error);
+        }
+    });
+}
+
+module.exports = {
+    authorize,
+    ams,
+    amsMw,
+    authProvider
+}

ams-expressjs-shopping/auth/dcl/internal/internalPolicies.dcl

@@ -0,0 +1,8 @@
+INTERNAL POLICY GetProducts {
+    USE shopping.ReadProducts;
+}
+
+INTERNAL POLICY ExternalOrder {
+    USE shopping.CreateOrders RESTRICT order.total < 100, product.category IS NOT RESTRICTED;
+    USE shopping.DeleteOrders;
+}

ams-expressjs-shopping/auth/dcl/local/adminPolicies.dcl

@@ -0,0 +1,3 @@
+POLICY OrderAccessory {
+    USE shopping.CreateOrders RESTRICT product.category = 'accessory', order.total IS NOT RESTRICTED;
+}

ams-expressjs-shopping/auth/dcl/schema.dcl

@@ -0,0 +1,12 @@
+SCHEMA {
+    "$user": {
+        scim_id: String
+    },
+    order: {
+        total: Number,
+        createdBy: String
+    },
+    product: {
+        category: String
+    }
+}