From 9ac0ff9b953d0cda423817d2b264817b99d437db Mon Sep 17 00:00:00 2001 From: Mariya Yordanova Date: Thu, 16 Oct 2025 18:34:45 +0200 Subject: [PATCH 1/7] Documentation for Hybrid testing with IAS --- node.js/authentication.md | 229 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) diff --git a/node.js/authentication.md b/node.js/authentication.md index 2188408e94..d65c648a5d 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -706,3 +706,232 @@ The login fails pointing to the correct OAuth configuration URL that is expected ``` 3. Retry + +## IAS in Hybrid Setup {#ias-setup} + +### Configure the Application + +1. Configure your application for IAS-authentication by adding the ams plugin and installing it(link to http://localhost:5173/docs/guides/security/authentication#get-ready-with-ias) : + + ```sh + cds add ams + npm install + ``` +2. Add roles and policies with AMS(http://localhost:5173/docs/guides/security/cap-users#prepare-cds-model) + +3. Add App Router for fetching the IAS token (link to http://localhost:5173/docs/guides/security/authentication#testing-ias-on-ui-level) + + ```sh + cds add approuter + ``` + +4. Install `npm` packages for App Router: + + ```sh + npm install --prefix app/router + ``` + +5. Generate the deployment descriptor file `mta.yaml` with: + + ```sh + cds add mta + ``` + ::: details Generated deployment descriptor for IAS instance, AppRouter and binding + ```yaml [mta.yaml] + _schema-version: 3.3.0 + ID: capire.bookshop + version: 2.0.4 + description: "Our primer sample for getting started in a nutshell." + parameters: + enable-parallel-deployments: true + build-parameters: + before-all: + - builder: custom + commands: + - npm ci + - npx cds build --production + modules: + - name: bookshop-srv + type: nodejs + path: gen/srv + parameters: + instances: 1 + buildpack: nodejs_buildpack + routes: + - route: "${default-url}" + - route: "${default-host}.cert.${default-domain}" + build-parameters: + builder: npm-ci + provides: + - name: srv-api # required by consumers of CAP services (e.g. approuter) + properties: + srv-url: ${default-url} + srv-cert-url: '${protocol}://${default-host}.cert.${default-domain}' + requires: + - name: bookshop-auth + parameters: + config: + credential-type: X509_GENERATED + app-identifier: srv + deployed-after: + - bookshop-ams-policies-deployer + properties: + AMS_DCL_ROOT: ams/dcl + + - name: bookshop + type: approuter.nodejs + path: app/router + parameters: + keep-existing-routes: true + disk-quota: 256M + memory: 256M + requires: + - name: srv-api + group: destinations + properties: + name: srv-api # must be used in xs-app.json as well + url: ~{srv-cert-url} + forwardAuthToken: true + forwardAuthCertificates: true + strictSSL: true + - name: bookshop-auth + parameters: + config: + credential-type: X509_GENERATED + app-identifier: approuter + provides: + - name: app-api + properties: + app-protocol: ${protocol} + app-uri: ${default-uri} + + - name: bookshop-ams-policies-deployer + type: javascript.nodejs + path: gen/policies + parameters: + buildpack: nodejs_buildpack + no-route: true + no-start: true + tasks: + - name: deploy-dcl + command: npm start + memory: 512M + requires: + - name: bookshop-auth + parameters: + config: + credential-type: X509_GENERATED + app-identifier: ams-policy-deployer + + resources: + - name: bookshop-auth + type: org.cloudfoundry.managed-service + requires: + - name: app-api + parameters: + service: identity + service-name: bookshop-auth + service-plan: application + config: + display-name: bookshop + oauth2-configuration: + redirect-uris: + - ~{app-api/app-protocol}://~{app-api/app-uri}/login/callback + post-logout-redirect-uris: + - ~{app-api/app-protocol}://~{app-api/app-uri}/*/logout.html + authorization: + enabled: true + ``` + ::: + +5. Configure the local callback URI of AppRouter in `mta.yaml` for `identity` service + + ```sh + - name: bookshop-auth + [...] + parameters: + service: identity + [...] + config: + display-name: bookshop + oauth2-configuration: + redirect-uris: + - http://localhost:5000/login/callback?authType=ias # [!code ++] + post-logout-redirect-uris: + - ~{app-api/app-protocol}://~{app-api/app-uri}/*/logout.html + ``` + +### Deploy the Application + +1. Log in to Cloud Foundry: + ```sh + cf l -a + ``` + If you don't know the API endpoint, have a look at section [Regions and API Endpoints Available for the Cloud Foundry Environment](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/350356d1dc314d3199dca15bd2ab9b0e.html#loiof344a57233d34199b2123b9620d0bb41). + +2. Pack and deploy the application with + + ```sh + cds up + ``` +### Assign users to AMS policies (http://localhost:5173/docs/guides/security/cap-users#ams-deployment) + +### Start hybrid testing + +1. Bind local application to the Identity Service Instance + + ```sh + cds bind -2 bookshop-auth + ``` + ::: details This will generate .cdsrc-private.json + ```json .cdsrc-private.json + { + "requires": { + "[hybrid]": { + "auth": { + "binding": { + "type": "cf", + "apiEndpoint": "https://...", + "org": "cdx-nodejs", + "space": "dev", + "instance": "bookshop-auth", + "key": "bookshop-auth-key" + }, + "kind": "ias-auth", + "vcap": { + "name": "auth" + } + } + } + } + } + ``` + ::: + +2. In your project folder run: + + ::: code-group + ```sh [Mac/Linux] + cds bind --exec -- npm start --prefix app/router + ``` + ```cmd [Windows] + cds bind --exec -- npm start --prefix app/router + ``` + ```powershell [Powershell] + cds bind --exec '--' npm start --prefix app/router + ``` + ::: + + [Learn more about `cds bind --exec`.](../advanced/hybrid-testing#cds-bind-exec){.learn-more} + + This starts an [App Router](https://help.sap.com/docs/HANA_CLOUD_DATABASE/b9902c314aef4afb8f7a29bf8c5b37b3/0117b71251314272bfe904a2600e89c0.html) instance on [http://localhost:5000](http://localhost:5000) with the credentials for the IAS service that you have bound using `cds bind`. + + Since it only serves static files or delegates to the backend service, you can keep the server running. It doesn't need to be restarted after you have changed files. + +4. Make sure that your CAP application is running as well with the `hybrid` profile: + + ```sh + cds watch --profile hybrid + ``` + +5. After the App Router and CAP application are started, log in at [http://localhost:5000](http://localhost:5000) and verify that the routes are protected as expected. \ No newline at end of file From 7cd6054ec40d2a39e05333a07dc4360ad38aebfb Mon Sep 17 00:00:00 2001 From: Mariya Yordanova Date: Tue, 27 Jan 2026 16:28:51 +0100 Subject: [PATCH 2/7] Addapted version --- node.js/authentication.md | 161 +++++++++----------------------------- 1 file changed, 36 insertions(+), 125 deletions(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index 885100bf4b..e43da4abbc 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -671,147 +671,50 @@ The login fails pointing to the correct OAuth configuration URL that is expected 3. Retry + ## IAS in Hybrid Setup {#ias-setup} ### Configure the Application -1. Configure your application for IAS-authentication by adding the ams plugin and installing it(link to http://localhost:5173/docs/guides/security/authentication#get-ready-with-ias) : +1. If there is no deployment descriptor yet, execute in the project root folder ```sh - cds add ams - npm install + cds add mta ``` -2. Add roles and policies with AMS(http://localhost:5173/docs/guides/security/cap-users#prepare-cds-model) -3. Add App Router for fetching the IAS token (link to http://localhost:5173/docs/guides/security/authentication#testing-ias-on-ui-level) +2. Enable IAS authentication for your application by adding and installing the `ams` plugin. For more information see [Adding AMS Support](../guides/security/cap-users#adding-ams-support-1) and [Adding IAS](../guides/security/authentication#adding-ias) ```sh - cds add approuter + cds add ams + cds install ``` + + This command installs `ams` and `ias` plugins, adds the required dependencies to `package.json` and updates `mta.yaml`. -4. Install `npm` packages for App Router: +3. Generate roles and policies with AMS. + To compile the cds annotations to dcl files execute: ```sh - npm install --prefix app/router + cds build --for ams ``` + For more information see [Prepare CDS Model](../guides/security/cap-users#prepare-cds-model) -5. Generate the deployment descriptor file `mta.yaml` with: +4. Add App Router for fetching the IAS token. ```sh - cds add mta - ``` - ::: details Generated deployment descriptor for IAS instance, AppRouter and binding - ```yaml [mta.yaml] - _schema-version: 3.3.0 - ID: capire.bookshop - version: 2.0.4 - description: "Our primer sample for getting started in a nutshell." - parameters: - enable-parallel-deployments: true - build-parameters: - before-all: - - builder: custom - commands: - - npm ci - - npx cds build --production - modules: - - name: bookshop-srv - type: nodejs - path: gen/srv - parameters: - instances: 1 - buildpack: nodejs_buildpack - routes: - - route: "${default-url}" - - route: "${default-host}.cert.${default-domain}" - build-parameters: - builder: npm-ci - provides: - - name: srv-api # required by consumers of CAP services (e.g. approuter) - properties: - srv-url: ${default-url} - srv-cert-url: '${protocol}://${default-host}.cert.${default-domain}' - requires: - - name: bookshop-auth - parameters: - config: - credential-type: X509_GENERATED - app-identifier: srv - deployed-after: - - bookshop-ams-policies-deployer - properties: - AMS_DCL_ROOT: ams/dcl - - - name: bookshop - type: approuter.nodejs - path: app/router - parameters: - keep-existing-routes: true - disk-quota: 256M - memory: 256M - requires: - - name: srv-api - group: destinations - properties: - name: srv-api # must be used in xs-app.json as well - url: ~{srv-cert-url} - forwardAuthToken: true - forwardAuthCertificates: true - strictSSL: true - - name: bookshop-auth - parameters: - config: - credential-type: X509_GENERATED - app-identifier: approuter - provides: - - name: app-api - properties: - app-protocol: ${protocol} - app-uri: ${default-uri} - - - name: bookshop-ams-policies-deployer - type: javascript.nodejs - path: gen/policies - parameters: - buildpack: nodejs_buildpack - no-route: true - no-start: true - tasks: - - name: deploy-dcl - command: npm start - memory: 512M - requires: - - name: bookshop-auth - parameters: - config: - credential-type: X509_GENERATED - app-identifier: ams-policy-deployer - - resources: - - name: bookshop-auth - type: org.cloudfoundry.managed-service - requires: - - name: app-api - parameters: - service: identity - service-name: bookshop-auth - service-plan: application - config: - display-name: bookshop - oauth2-configuration: - redirect-uris: - - ~{app-api/app-protocol}://~{app-api/app-uri}/login/callback - post-logout-redirect-uris: - - ~{app-api/app-protocol}://~{app-api/app-uri}/*/logout.html - authorization: - enabled: true + cds add approuter ``` - ::: -5. Configure the local callback URI of AppRouter in `mta.yaml` for `identity` service +5. Install `npm` packages for App Router: + + ```sh + npm install --prefix app/router + + ``` +6. Configure the local callback URI of AppRouter in `mta.yaml` for `identity` service ```sh - - name: bookshop-auth + - name: bookshop-ias [...] parameters: service: identity @@ -838,14 +741,19 @@ The login fails pointing to the correct OAuth configuration URL that is expected ```sh cds up ``` -### Assign users to AMS policies (http://localhost:5173/docs/guides/security/cap-users#ams-deployment) + +### Assign policies in the Administrative Console + +1. Log in to your IAS Tenant and go to `Applications & Resources` + +2. Assign policies to IAS users or create custom policies, see [Cloud Deployment](../guides/security/cap-users#ams-deployment) ### Start hybrid testing 1. Bind local application to the Identity Service Instance ```sh - cds bind -2 bookshop-auth + cds bind -2 bookshop-ias ``` ::: details This will generate .cdsrc-private.json ```json .cdsrc-private.json @@ -858,8 +766,8 @@ The login fails pointing to the correct OAuth configuration URL that is expected "apiEndpoint": "https://...", "org": "cdx-nodejs", "space": "dev", - "instance": "bookshop-auth", - "key": "bookshop-auth-key" + "instance": "bookshop-ias", + "key": "bookshop-ias-key" }, "kind": "ias-auth", "vcap": { @@ -892,10 +800,13 @@ The login fails pointing to the correct OAuth configuration URL that is expected Since it only serves static files or delegates to the backend service, you can keep the server running. It doesn't need to be restarted after you have changed files. -4. Make sure that your CAP application is running as well with the `hybrid` profile: +3. Make sure that your CAP application is running as well with the `hybrid` profile: ```sh cds watch --profile hybrid ``` -5. After the App Router and CAP application are started, log in at [http://localhost:5000](http://localhost:5000) and verify that the routes are protected as expected. \ No newline at end of file +4. After the App Router and CAP application are started, log in at [http://localhost:5000](http://localhost:5000) and verify that the routes are protected as expected. + + + \ No newline at end of file From 137acea5099c9b843fe7f1d63a10ab9140aa9e8c Mon Sep 17 00:00:00 2001 From: Christian Georgi Date: Tue, 27 Jan 2026 18:58:56 +0100 Subject: [PATCH 3/7] Ignore error in conceptual snippet --- guides/querying/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/guides/querying/index.md b/guides/querying/index.md index 017b5ef8e5..8a891c0732 100644 --- a/guides/querying/index.md +++ b/guides/querying/index.md @@ -116,6 +116,7 @@ entity MyFavoriteBooks as select from Books { } where ID in (SELECT book from MyFavorites) ``` + ```cds entity LatestBooks as projection on Books { ID, title, author.name as author From c89010aa67277f709eac8d31e18d0dd543f6e9d9 Mon Sep 17 00:00:00 2001 From: Christian Georgi Date: Tue, 27 Jan 2026 19:03:19 +0100 Subject: [PATCH 4/7] Fix link --- node.js/authentication.md | 2 +- tools/cds-bind.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index e43da4abbc..862d731aad 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -794,7 +794,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected ``` ::: - [Learn more about `cds bind --exec`.](../advanced/hybrid-testing#cds-bind-exec){.learn-more} + [Learn more about `cds bind --exec`.](../tools/cds-bind#cds-bind-exec){.learn-more} This starts an [App Router](https://help.sap.com/docs/HANA_CLOUD_DATABASE/b9902c314aef4afb8f7a29bf8c5b37b3/0117b71251314272bfe904a2600e89c0.html) instance on [http://localhost:5000](http://localhost:5000) with the credentials for the IAS service that you have bound using `cds bind`. diff --git a/tools/cds-bind.md b/tools/cds-bind.md index b948eb7651..fe1175d3eb 100644 --- a/tools/cds-bind.md +++ b/tools/cds-bind.md @@ -283,6 +283,7 @@ Example output: ``` ### Run Arbitrary Commands with Service Bindings +###### cds-bind-exec With `cds bind` you avoid storing credentials on your hard disk. If you need to start other local applications with cloud service bindings, you can use the `exec` option. From c9f7c7dd892c0fc4df08786a9cb7a40006791abf Mon Sep 17 00:00:00 2001 From: Christian Georgi Date: Tue, 27 Jan 2026 19:06:53 +0100 Subject: [PATCH 5/7] Remove double ID --- tools/cds-bind.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tools/cds-bind.md b/tools/cds-bind.md index fe1175d3eb..b948eb7651 100644 --- a/tools/cds-bind.md +++ b/tools/cds-bind.md @@ -283,7 +283,6 @@ Example output: ``` ### Run Arbitrary Commands with Service Bindings -###### cds-bind-exec With `cds bind` you avoid storing credentials on your hard disk. If you need to start other local applications with cloud service bindings, you can use the `exec` option. From 5add1d13609e562606b43ab43feb834835db6a93 Mon Sep 17 00:00:00 2001 From: Mariya Yordanova Date: Thu, 29 Jan 2026 10:15:24 +0100 Subject: [PATCH 6/7] small fix --- node.js/authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index 862d731aad..cb38ba1e19 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -686,7 +686,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected ```sh cds add ams - cds install + npm install ``` This command installs `ams` and `ias` plugins, adds the required dependencies to `package.json` and updates `mta.yaml`. @@ -794,7 +794,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected ``` ::: - [Learn more about `cds bind --exec`.](../tools/cds-bind#cds-bind-exec){.learn-more} + [Learn more about `cds bind --exec`.](../advanced/hybrid-testing#cds-bind-exec){.learn-more} This starts an [App Router](https://help.sap.com/docs/HANA_CLOUD_DATABASE/b9902c314aef4afb8f7a29bf8c5b37b3/0117b71251314272bfe904a2600e89c0.html) instance on [http://localhost:5000](http://localhost:5000) with the credentials for the IAS service that you have bound using `cds bind`. From acf860891a307e8324de2249c5410161a66a1540 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 29 Jan 2026 11:35:33 +0100 Subject: [PATCH 7/7] Hide point 6 in details block for hybrid testing with IAS (#2351) --- node.js/authentication.md | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index cb38ba1e19..1d0653709e 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -691,6 +691,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected This command installs `ams` and `ias` plugins, adds the required dependencies to `package.json` and updates `mta.yaml`. + 3. Generate roles and policies with AMS. To compile the cds annotations to dcl files execute: @@ -705,28 +706,32 @@ The login fails pointing to the correct OAuth configuration URL that is expected cds add approuter ``` + ::: details This configures the local App Router callback URI for the `identity` service + + In _mta.yaml_, this entry should now be present: + + ```sh + - name: bookshop-ias + [...] + parameters: + service: identity + [...] + config: + display-name: bookshop + oauth2-configuration: + redirect-uris: + - http://localhost:5000/login/callback?authType=ias # [!code ++] + post-logout-redirect-uris: + - ~{app-api/app-protocol}://~{app-api/app-uri}/*/logout.html + ``` + + ::: + 5. Install `npm` packages for App Router: ```sh npm install --prefix app/router - ``` -6. Configure the local callback URI of AppRouter in `mta.yaml` for `identity` service - - ```sh - - name: bookshop-ias - [...] - parameters: - service: identity - [...] - config: - display-name: bookshop - oauth2-configuration: - redirect-uris: - - http://localhost:5000/login/callback?authType=ias # [!code ++] - post-logout-redirect-uris: - - ~{app-api/app-protocol}://~{app-api/app-uri}/*/logout.html - ``` ### Deploy the Application