Revised security guide #2223

BraunMatthias · 2025-11-21T09:26:08Z

No description provided.

finkmanAtSap

I did not do an in-depth review but I found some things while skimming through

guides/security/cap-users.md

finkmanAtSap · 2025-11-21T09:59:03Z

guides/security/cap-users.md

+entity Books : withGenre { ... }
+```
+
+The detailed syntax of `@ams` annotation provides an `attribute` property which might be helpful to decouple the external from the internal name:


I think we never implemented this detailled syntax. It looks like it is just a more verbose version that offers the same semantic?

guides/security/cap-users.md

finkmanAtSap · 2025-11-21T10:19:32Z

guides/security/cap-users.md

+
+You can now perform following tasks in the Administrative Console for the IAS tenant (see prerequisits [here](../guides/security/authentication#ias-admin)):
+- Assign (base or custom) policies to IAS users
+- Create custom policies


I think, by now, admin policy may be the official name. If that name is used in the help.sap.com documentation, we should keep it coherent. I'm not sure though.

guides/security/cap-users.md

menu.md

guides/security/cap-users.md

patricebender · 2025-12-05T07:41:28Z

guides/security/authentication.md

+            - ~{app-api/app-protocol}://~{app-api/app-uri}/*/logout.html            
+```
+:::
+


this seems like an abrupt end, how can I now access the UI in hybrid mode to test authentication?

patricebender · 2025-12-05T08:40:39Z

guides/security/authorization.md

 #### Events to Auto-Exposed Entities { #events-and-auto-expose}

-In general, entities can be exposed in services in different ways: they can be **explicitly exposed** by the modeler (for example, by a projection), or they can be **auto-exposed** by the CDS compiler due to some reason.
+In general, entities can be exposed in services in different ways: they can be **explicitly exposed** by the modeler (for example, by a projection), or they can be **auto-exposed** by the CDS compiler for some reason.


Suggested change

In general, entities can be exposed in services in different ways: they can be **explicitly exposed** by the modeler (for example, by a projection), or they can be **auto-exposed** by the CDS compiler for some reason.

In general, entities can be exposed in services in different ways: they can be **explicitly exposed** by the modeler (for example, by a projection), or they can be [**auto-exposed**](cdl#auto-exposed-entities) by the CDS compiler for some reason.

patricebender · 2025-12-05T09:27:33Z

guides/security/authorization.md

+:::
+
+::: warning _Warning_ <!--  -->
+A service level entity can't inherit a restriction with a `where` condition that doesn't match the projected entity. The restriction has to be overridden in this case.


Are you reffering to the situation where an element of the where condition is NOT part of the projection on top - in which case the compilation would fail ?

patricebender · 2025-12-05T10:18:51Z

guides/security/authentication.md

for node, we need to check again if this works without cds add hana - for java it appears to be working without hana as sqlite is then used in the cloud

patricebender · 2025-12-10T16:35:51Z

guides/security/authentication.md

+Hence, start with `broker` if you want to provides technial APIs potentially.
+:::
+
+[Learn more about XSUAA application security descriptor configuration syntax](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-developer-guide-for-cloud-foundry-multitarget-applications-sap-web-ide-full-stack/application-security-descriptor-configuration-syntax){.learn-more}


link leads to a blank page (no 404 - nothing but a white page) (tried with safari and chrome)

patricebender · 2025-12-10T16:45:42Z

guides/security/authentication.md

+See [Application Security Descriptor Configuration Syntax](https://help.sap.com/docs/HANA_CLOUD_DATABASE/b9902c314aef4afb8f7a29bf8c5b37b3/6d3ed64092f748cbac691abc5fe52985.html) in the SAP HANA Platform documentation for the syntax of the _xs-security.json_ and advanced configuration options.
+
+<!-- REVISIT: Not ideal cds compile --to xsuaa can generate invalid xs-security.json files -->
+::: warning Avoid invalid characters in your models


is there a pointer which characters to avoid?

patricebender · 2025-12-10T17:27:38Z

guides/security/authentication.md

+❗ **Never share service keys or tokens** ❗
+:::
+
+As second step, assign the generated role collection with name `admin (bookshop cdsruntime-cap-zone-bookshop-xsuaa)` to your **test user** by following instructions from [Assign Roles in SAP BTP Cockpit](./cap-users##xsuaa-assign).


I had trouble with adding the roles to the role collection because I did not know which application identifier to pick… I figured it out by looking at the clientid from the service key…

PDT42 · 2025-12-11T08:44:15Z

guides/security/cap-users.md

+**In most casese, there is no need to write custom code dependent on the CAP user - leverage CDS modelling whenever possible**.
+:::
+
+### Reflection { #reflection .java }


For Node.js, this section will be somewhat redundant to:

https://pages.github.tools.sap/cap/docs/node.js/cds-tx#event-contexts

https://pages.github.tools.sap/cap/docs/node.js/events#cds-context

ok, but I think we need to centralize the security-relevant documentation. In the runtime-specific versions additional or more detailed content could be shown.

patricebender · 2025-12-11T11:08:38Z

guides/security/authentication.md

+Now we want to fetch a token to prepare a fully authenticated test request. 
+As first step we add a new client for the XSUAA application by creating an appropriate service key:
+
+```sh
+cf create-service-key bookshop-auth bookshop-auth-key
+```
+
+
+```sh
+cf service-key bookshop-auth bookshop-auth-key
+```


Is it really necessary to create a service key? I was able to do it with:

❯ cf env bookshop-srv | grep '"xsuaa":' -A 20 "xsuaa": [ { "binding_guid": "d10bccfe-b325-4ede-aecc-6644af1ba01b", "binding_name": null, "credentials": { "apiurl": "https://api.authentication.eu12.hana.ondemand.com", "clientid": "sb-bookshop-cap-sandbox-patrice!t50015", "clientsecret": "…", "credential-type": "binding-secret", "identityzone": "cap-sandbox", "identityzoneid": "a6d85e7a-c4cb-49e0-afec-2449a59dde87", "sburl": "https://internal-xsuaa.authentication.eu12.hana.ondemand.com", "serviceInstanceId": "fb12c45d-aecf-4acb-ad51-4cfc38e277e2", "subaccountid": "127c6f37-462d-4157-a41b-a2427e2f4b6a", "tenantid": "a6d85e7a-c4cb-49e0-afec-2449a59dde87", "tenantmode": "dedicated", "uaadomain": "authentication.eu12.hana.ondemand.com", "url": "https://cap-sandbox.authentication.eu12.hana.ondemand.com", "verificationkey": "…", "xsappname": "bookshop-cap-sandbox-patrice!t50015", "zoneid": "a6d85e7a-c4cb-49e0-afec-2449a59dde87"

patricebender · 2025-12-11T11:12:18Z

guides/security/authentication.md

+```sh [Token for named user]
+curl -X POST \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d 'grant_type=password' \
+  -d 'client_id=<clientid>' \
+  -d 'client_secret=<clientsecret>' \
+  -d 'username=<username>' \
+  -d 'password=<userpassword>' \
+  <url>/oauth/token


First, I created the service keys described as above and used it to fetch a token for the "Technical User". WIth this token, I was able to access catalog/Books but got a 403 for admin/Books (which was a nice learning effect). Then I added my user to the auto-generated role collection (admin (…)). After that, I used the clientid and client_secret from cf env bookshop-srv in combination with my user + password to fetch a token for the "Named User" → with this token I was able to also access admin/Books.

patricebender · 2025-12-11T11:24:55Z

guides/security/authentication.md

+TODO: the below command currently does not setup sqlite for production.
+
+In addition, activate SQLite to serve as in-memory DB (**not** recommended for production!):
+```sh
+cds add sqlite --for production
+```


@swaldmann fyi

I just did it with HANA, not sure if all trial users have this possibility. Probably easier to have the in-memory db also in the deployed application for the sake of this guide

PDT42 · 2025-12-11T12:20:03Z

guides/security/cap-users.md

+| User Property | UserInfo Getter | XSUAA JWT Property               | IAS JWT Property        | `@restrict`-annotation
+|---------------|---------------------|----------------------------------|-------------------------|--------------------|
+| _Logon name_     | `getName()`    | `user_name`                      | `sub`                   | `$user`  |
+| _Tenant_   | `getTenant()`  | `zid`                            | `zone_uuid`             | `$user.tenant` |


PDT42 · 2025-12-11T12:56:41Z

guides/security/cap-users.md

+        onBehalfOf: systemUserProvider
+```
+
+The parameter `onBehalfOf` in the binding configuration section allows to define following *user propagation* strategies:


Suggested change

The parameter `onBehalfOf` in the binding configuration section allows to define following *user propagation* strategies:

The parameter `onBehalfOf` in the binding configuration section allows to define the following *user propagation* strategies:

swaldmann · 2025-12-11T20:58:02Z

guides/security/assets/ias-ui-setup.drawio

@@ -0,0 +1,142 @@
+<mxfile host="65bd71144e">


Don't separate the ias-ui-setup.drawio and ias-ui-setup.svg into just ias-ui-setup.drawio.svg, which can be directly edited and rendered in the browser. We want to avoid the double maintenance and export steps.

Same for the other graphics where this applies.

swaldmann · 2025-12-11T20:59:44Z

guides/security/assets/ams.excalidraw

@@ -0,0 +1,5982 @@
+{


Pls replace that file by a .drawio.svg. 6000 lines added vs. the ~200-400 we see in the Draw.io ones.

Makes this diff so huge that GitHub forces you to review by file.

swaldmann · 2025-12-11T21:04:40Z

guides/deployment/microservices.md

 ### Authentication

-Add [security configuration](../security/authorization#xsuaa-configuration) using the command:
+Add [security configuration](../security/authentication#authentication) using the command:


Bit of an awkward URL with the stuttering. As "#authentication" is just the h1 heading in the linked guide, why use it at all?

Suggested change

Add [security configuration](../security/authentication#authentication) using the command:

Add [security configuration](../security/authentication) using the command:

However, I wouldn't hide this link in the prose text but rather add a {.learn-more} one, e.g. after the cds add command:

[Learn more about Authentication in CAP](../security/authentication){.learn-more}

This makes it clearer to the user what you're trying to cross-reference.

Adding node specific snippets and sections to the revised security guide, originally added in #2223. --------- Co-authored-by: Manuel Fink <[email protected]>

…curity-guide

PDT42 · 2025-12-12T14:21:42Z

guides/security/cap-users.md

+
+CAP is not tied to any specific authentication method, nor to concrete user information such as that provided by IAS or XSUAA. 
+Instead, an abstract [user representation](cap-users#claims) is attached to the request which can be used to influence request processing.
+For example, both authorization enforcement and domain logic can depend on the current user properties.


Suggested change

For example, both authorization enforcement and domain logic can depend on the current user properties.

For example, both authorization enforcement and domain logic can depend on properties of the the current user.

PDT42 · 2025-12-12T15:15:36Z

guides/security/authentication.md

+
+- For _local development_ and _unit testing_, [Mock User Authentication](#mock-user-auth) is an appropriate built-in authentication feature.
+
+- For _cloud deployments_, in particular deployments for production, CAP provides integration of several identity services:  


Suggested change

- For _cloud deployments_, in particular deployments for production, CAP provides integration of several identity services:

- For _cloud deployments_, in particular deployments for production, CAP provides integration of several identity services out of the box:

BraunMatthias requested a review from renejeglinsky as a code owner November 21, 2025 09:26

BraunMatthias added the do not merge label Nov 21, 2025

finkmanAtSap requested changes Nov 21, 2025

View reviewed changes

renejeglinsky reviewed Nov 21, 2025

View reviewed changes

menu.md Outdated Show resolved Hide resolved

BraunMatthias force-pushed the revised-security-guide branch 2 times, most recently from bfad258 to cb794d1 Compare November 25, 2025 11:18

BraunMatthias requested a review from smahati as a code owner November 25, 2025 19:15

chgeo marked this pull request as draft November 26, 2025 09:07

finkmanAtSap reviewed Nov 26, 2025

View reviewed changes

guides/security/cap-users.md Outdated Show resolved Hide resolved

[email protected] added 21 commits November 27, 2025 13:35

new structure

0c4ce18

restructured, auth guide in progress

28b426b

ias cli testing

4d9d55d

safepoint

6cc3dc2

UI IAS flow

81e81f3

ias auth beta

722354a

custom auth

abaa8d4

restructed chapters

2907a71

next step

411e9d8

finalized AMS role assignment

8362811

finalized AMS

1613da9

cap user propagation

a53d04a

user propagation

c86ed58

finalized cap users

61c5142

restructured images

5d04142

next step

ff238d4

continued

9aea779

external authentication

f6e8f75

remote service part2

bfa12d9

cleaned assets

13d9669

fxed typo menu

d1e2302

PDT42 mentioned this pull request Dec 10, 2025

Adding node specific Snippets & Sections (CAP User) #2264

Merged

patricebender reviewed Dec 10, 2025

View reviewed changes

wip: xsuaa node

f24c530

PDT42 reviewed Dec 11, 2025

View reviewed changes

some adjustements to mock auth in node

9fba623

patricebender reviewed Dec 11, 2025

View reviewed changes

patricebender added 4 commits December 11, 2025 12:20

add learnings after cli testing with xsuaa for node

2b7b744

rm unused file

dc6d970

format

b847c82

add TODO

7166e1a

patricebender reviewed Dec 11, 2025

View reviewed changes

more infos in UI testing guide

f9e42a2

PDT42 reviewed Dec 11, 2025

View reviewed changes

swaldmann reviewed Dec 11, 2025

View reviewed changes

PDT42 and others added 8 commits December 12, 2025 09:26

Adding node specific Snippets & Sections (CAP User) (#2264)

b4cada0

Adding node specific snippets and sections to the revised security guide, originally added in #2223. --------- Co-authored-by: Manuel Fink <[email protected]>

DB support

8e08443

Sync changes from 'revised-security-guide-ams-nodejs' into revised-se…

fc41f60

…curity-guide

fix: missing closing tag

eaca12d

fix: smaller messes

13518fc

fix: add section on validating node config

48e2099

feat: add node specific graphics

98ee89c

feat: integrate node specific graphic and update examples

2f192e3

PDT42 reviewed Dec 12, 2025

View reviewed changes

PDT42 added 2 commits December 12, 2025 15:44

fix: graphic format

ce81253

fix: small messes

30cd275

PDT42 reviewed Dec 12, 2025

View reviewed changes

	In general, entities can be exposed in services in different ways: they can be explicitly exposed by the modeler (for example, by a projection), or they can be auto-exposed by the CDS compiler for some reason.
	In general, entities can be exposed in services in different ways: they can be explicitly exposed by the modeler (for example, by a projection), or they can be [auto-exposed](cdl#auto-exposed-entities) by the CDS compiler for some reason.

	\| _Tenant_ \| `getTenant()` \| `zid` \| `zone_uuid` \| `$user.tenant` \|
	\| _Tenant_ \| `getTenant()` \| `zid` \| `app_tid` \| `$user.tenant` \|

	The parameter `onBehalfOf` in the binding configuration section allows to define following user propagation strategies:
	The parameter `onBehalfOf` in the binding configuration section allows to define the following user propagation strategies:

	Add [security configuration](../security/authentication#authentication) using the command:
	Add [security configuration](../security/authentication) using the command:

	For example, both authorization enforcement and domain logic can depend on the current user properties.
	For example, both authorization enforcement and domain logic can depend on properties of the the current user.


		- For _local development_ and _unit testing_, [Mock User Authentication](#mock-user-auth) is an appropriate built-in authentication feature.

		- For _cloud deployments_, in particular deployments for production, CAP provides integration of several identity services:

Revised security guide #2223

Are you sure you want to change the base?

Revised security guide #2223

Uh oh!

Conversation

BraunMatthias commented Nov 21, 2025

Uh oh!

finkmanAtSap left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swaldmann Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

swaldmann Dec 11, 2025 •

edited

Loading