From 9ac0ff9b953d0cda423817d2b264817b99d437db Mon Sep 17 00:00:00 2001 From: Mariya Yordanova Date: Thu, 16 Oct 2025 18:34:45 +0200 Subject: [PATCH 01/12] 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 02/12] 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 03/12] 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 04/12] 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 05/12] 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 06/12] 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 07/12] 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 From aa2d71301f6abab4b85eb30fcbfaf478b531e911 Mon Sep 17 00:00:00 2001 From: D050513 Date: Tue, 17 Feb 2026 10:46:28 +0100 Subject: [PATCH 08/12] Authentication in Hybrid Setup --- node.js/authentication.md | 22 ++++++++++++---------- tools/cds-bind.md | 5 +++-- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index 1d0653709e..61d105f9f5 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -464,9 +464,11 @@ require('@sap/xssec').Token.decodeCache = false [Learn more about caching CPU intensive operations in `@sap/xssec`](https://www.npmjs.com/package/@sap/xssec#caching-cpu-intensive-operations){.learn-more} -## XSUAA in Hybrid Setup {#xsuaa-setup} +## Authentication in Hybrid Setup {#hybrid-setup} -### Prepare Local Environment +### with XSUAA {#xsuaa-setup} + +#### Prepare Local Environment The following steps assume you've set up the [**Cloud Foundry Command Line Interface**](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/856119883b8c4c97b6a766cc6a09b48c.html). @@ -517,7 +519,7 @@ If you don't know the API endpoint, have a look at section [Regions and API Endp This step is necessary for locally running apps and for apps deployed on Cloud Foundry. ::: -### Configure the Application +#### Configure the Application 1. Create a service key: @@ -560,7 +562,7 @@ cds env list requires.auth --resolve-bindings --profile hybrid This prints the full `auth` configuration including the credentials. -### Set Up the Roles for the Application { #auth-in-cockpit} +#### Set Up the Roles for the Application { #auth-in-cockpit} By creating a service instance of the `xsuaa` service, all the roles from the _xs-security.json_ file are added to your subaccount. Next, you create a role collection that assigns these roles to your users. @@ -579,7 +581,7 @@ By creating a service instance of the `xsuaa` service, all the roles from the _x 7. Add the email addresses for your users to the *Users* list. 8. Choose *Save* -### Running App Router +#### Running App Router The App Router component implements the necessary authentication flow with XSUAA to let the user log in interactively. The resulting JWT token is sent to the application where it's used to enforce authorization and check the user's roles. @@ -672,9 +674,9 @@ The login fails pointing to the correct OAuth configuration URL that is expected 3. Retry -## IAS in Hybrid Setup {#ias-setup} +### with IAS {#ias-setup} -### Configure the Application +#### Configure the Application 1. If there is no deployment descriptor yet, execute in the project root folder @@ -733,7 +735,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected npm install --prefix app/router ``` -### Deploy the Application +#### Deploy the Application 1. Log in to Cloud Foundry: ```sh @@ -747,13 +749,13 @@ The login fails pointing to the correct OAuth configuration URL that is expected cds up ``` -### Assign policies in the Administrative Console +#### 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 +#### Start hybrid testing 1. Bind local application to the Identity Service Instance diff --git a/tools/cds-bind.md b/tools/cds-bind.md index 5b689dd17f..5b7bb87d59 100644 --- a/tools/cds-bind.md +++ b/tools/cds-bind.md @@ -506,9 +506,10 @@ Most of the following use cases are shown for Node.js, but can be easily adapted Learn how to [connect to remote services locally](../guides/services/consuming-services#connect-to-remote-services-locally) using SAP BTP destinations. -### Authentication and Authorization using XSUAA +### Authentication and Authorization + +Learn how to do hybrid testing using the XSUAA or IAS service in the [CAP Node.js authentication documentation](../node.js/authentication#hybrid-setup). -Learn how to do hybrid testing using the XSUAA service in the [CAP Node.js authentication documentation](../node.js/authentication#xsuaa-setup). ### Integration Tests `cds bind` can be handy for testing with real cloud services in your CI/CD pipeline. From 97647d6dd69a6519cf663a5741117295c32ba4fb Mon Sep 17 00:00:00 2001 From: D050513 Date: Tue, 17 Feb 2026 10:54:51 +0100 Subject: [PATCH 09/12] fix link --- node.js/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index 61d105f9f5..5bf9be59da 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -801,7 +801,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#hybrid-testing){.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 8f99c708be2552300994404b126f95e1a8222564 Mon Sep 17 00:00:00 2001 From: mariayord Date: Tue, 10 Mar 2026 14:42:34 +0100 Subject: [PATCH 10/12] Update tools/cds-bind.md Co-authored-by: sjvans <30337871+sjvans@users.noreply.github.com> --- tools/cds-bind.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/cds-bind.md b/tools/cds-bind.md index 5b7bb87d59..3809694a74 100644 --- a/tools/cds-bind.md +++ b/tools/cds-bind.md @@ -508,7 +508,7 @@ Learn how to [connect to remote services locally](../guides/services/consuming-s ### Authentication and Authorization -Learn how to do hybrid testing using the XSUAA or IAS service in the [CAP Node.js authentication documentation](../node.js/authentication#hybrid-setup). +Learn how to do hybrid testing using the XSUAA or IAS + AMS service(s) in the [CAP Node.js authentication documentation](../node.js/authentication#hybrid-setup). ### Integration Tests From 43941d235a69cee372fe796f479c7f70cfc7b288 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Wed, 11 Mar 2026 13:30:43 +0100 Subject: [PATCH 11/12] editing --- node.js/authentication.md | 107 ++++++++++++++++++++------------------ 1 file changed, 56 insertions(+), 51 deletions(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index 5bf9be59da..428940534e 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -284,7 +284,7 @@ npm add @sap/xssec ``` ::: -[Learn more about testing JWT-based authentication in **XSUAA in Hybrid Setup**.](#xsuaa-setup){.learn-more} +[Learn more about testing JWT-based authentication in **XSUAA in Hybrid Setup**.](#with-ias){.learn-more} ### XSUAA-based Authentication { #xsuaa } @@ -308,7 +308,7 @@ npm add @sap/xssec ``` ::: -[See **XSUAA in Hybrid Setup** below for additional information of how to test this](#xsuaa-setup){.learn-more} +[See **XSUAA in Hybrid Setup** below for additional information of how to test this](#with-ias){.learn-more} ### IAS-based Authentication { #ias } @@ -429,7 +429,7 @@ export default function custom_auth(req: Req, res: Response, next: NextFunction) } ``` -[If you want to customize the user ID, please also have a look at this example.](cds-serve#customization-of-cds-context-user){.learn-more} +[Learn more about customizing the user ID in this example.](cds-serve#customization-of-cds-context-user){.learn-more} ## Authentication in Production @@ -466,36 +466,38 @@ require('@sap/xssec').Token.decodeCache = false ## Authentication in Hybrid Setup {#hybrid-setup} -### with XSUAA {#xsuaa-setup} - -#### Prepare Local Environment +### with XSUAA The following steps assume you've set up the [**Cloud Foundry Command Line Interface**](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/856119883b8c4c97b6a766cc6a09b48c.html). 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). + ```sh + cf l -a + ``` + If you don't know the API endpoint, refer to [Regions and API Endpoints Available for the Cloud Foundry Environment](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/350356d1dc314d3199dca15bd2ab9b0e.html#loiof344a57233d34199b2123b9620d0bb41). 2. Go to the project you have created in [Getting started in a Nutshell](../get-started/bookshop). + +#### Configure the Application -3. Configure your app for XSUAA-based authentication if not done yet: +1. Configure your app for XSUAA-based authentication if not done yet: + ```sh cds add xsuaa --for hybrid ``` - This command creates the XSUAA configuration file `xs-security.json` and adds the service and required dependencies to your `package.json` file. + This command creates the XSUAA configuration file `xs-security.json` and adds the service and required dependencies to your `package.json` file. -4. Make sure `xsappname` is configured and `tenant-mode` is set to `dedicated` in `xs-security.json` file: -```json -{ - "xsappname": "bookshop-hybrid", - "tenant-mode": "dedicated", - ... - } -``` +2. Make sure `xsappname` is configured and `tenant-mode` is set to `dedicated` in `xs-security.json` file: + + ```json + { + "xsappname": "bookshop-hybrid", + "tenant-mode": "dedicated", + ... + } + ``` -5. Configure the redirect URI: +3. Configure the redirect URI: Add the following OAuth configuration to the `xs-security.json` file: @@ -507,7 +509,7 @@ If you don't know the API endpoint, have a look at section [Regions and API Endp } ``` -6. Create an XSUAA service instance with this configuration: +4. Create an XSUAA service instance with this configuration: ```sh cf create-service xsuaa application bookshop-uaa -c xs-security.json @@ -519,7 +521,6 @@ If you don't know the API endpoint, have a look at section [Regions and API Endp This step is necessary for locally running apps and for apps deployed on Cloud Foundry. ::: -#### Configure the Application 1. Create a service key: @@ -530,7 +531,7 @@ If you don't know the API endpoint, have a look at section [Regions and API Endp This lets you gain access to the XSUAA credentials from your local application. -2. Bind to the new service key: +1. Bind to the new service key: ```sh cds bind -2 bookshop-uaa @@ -555,11 +556,11 @@ If you don't know the API endpoint, have a look at section [Regions and API Endp >In that case you need to add the environment variable `cds_requires_auth_kind=xsuaa` to the run configuration. -3. Check authentication configuration: -```sh -cds env list requires.auth --resolve-bindings --profile hybrid -``` -This prints the full `auth` configuration including the credentials. +1. Check authentication configuration: + ```sh + cds env list requires.auth --resolve-bindings --profile hybrid + ``` + This prints the full `auth` configuration including the credentials. #### Set Up the Roles for the Application { #auth-in-cockpit} @@ -627,8 +628,8 @@ The resulting JWT token is sent to the application where it's used to enforce au ``` > If you are using BAS Run Configurations, you need to configure `cds watch` with profile `hybrid`: - > 1. Right click on your run configuration - > 2. Choose *Show in File* + > 1. Open the context menu for your run configuration. + > 2. Choose *Show in File*. > 3. Change the command `args`: > ```json > "args": [ @@ -674,17 +675,17 @@ The login fails pointing to the correct OAuth configuration URL that is expected 3. Retry -### with IAS {#ias-setup} +### with IAS #### Configure the Application -1. If there is no deployment descriptor yet, execute in the project root folder +1. Add a deployment descriptor, if there is none in the root of your project: ```sh cds add mta ``` -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) +2. Enable IAS authentication for your application by adding and installing the `ams` plugin: ```sh cds add ams @@ -693,16 +694,20 @@ 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`. + Learn more about [**Adding AMS Support**](../guides/security/cap-users#adding-ams-support) and [**Adding IAS**](../guides/security/authentication#adding-ias).{.learn-more} -3. Generate roles and policies with AMS. - To compile the cds annotations to dcl files execute: + +3. Generate roles and policies with AMS: ```sh cds build --for ams ``` - For more information see [Prepare CDS Model](../guides/security/cap-users#prepare-cds-model) -4. Add App Router for fetching the IAS token. + This compiles the CDS annotations into DCL files. + + [Learn more about Prepare CDS Model](../guides/security/cap-users#prepare-cds-model).{.learn-more} + +4. Add App Router for fetching the IAS token: ```sh cds add approuter @@ -712,7 +717,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected In _mta.yaml_, this entry should now be present: - ```sh + ```yaml - name: bookshop-ias [...] parameters: @@ -741,28 +746,31 @@ The login fails pointing to the correct OAuth configuration URL that is expected ```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). + If you don't know the API endpoint, refer to [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 +2. Pack and deploy the application: ```sh cds up ``` -#### Assign policies in the Administrative Console +#### Assign Policies in the Administrative Console -1. Log in to your IAS Tenant and go to `Applications & Resources` +1. Log in to your Administrative Console for IAS and go to `Applications & Resources`. + + [Learn more about the Administrative Console for IAS.](/@external/guides/security/authentication#ias-admin){.learn-more} -2. Assign policies to IAS users or create custom policies, see [Cloud Deployment](../guides/security/cap-users#ams-deployment) +2. Assign policies to IAS users or create custom policies, see [Cloud Deployment](../guides/security/cap-users#ams-deployment). -#### Start hybrid testing +#### Start Hybrid Testing -1. Bind local application to the Identity Service Instance +1. Bind you local application to the Identity Service Instance: ```sh cds bind -2 bookshop-ias ``` - ::: details This will generate .cdsrc-private.json + + ::: details This generates the _.cdsrc-private.json_ ```json .cdsrc-private.json { "requires": { @@ -813,7 +821,4 @@ The login fails pointing to the correct OAuth configuration URL that is expected cds watch --profile hybrid ``` -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 +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 8ee6c026ce8371eb4318bfdc369be21eeaf12a7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Jeglinsky?= Date: Wed, 11 Mar 2026 13:33:20 +0100 Subject: [PATCH 12/12] Apply suggestion from @renejeglinsky --- node.js/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/node.js/authentication.md b/node.js/authentication.md index 428940534e..0ac7f4146b 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -764,7 +764,7 @@ The login fails pointing to the correct OAuth configuration URL that is expected #### Start Hybrid Testing -1. Bind you local application to the Identity Service Instance: +1. Bind your local application to the Identity Service Instance: ```sh cds bind -2 bookshop-ias