capire · BraunMatthias · Sep 15, 2025 · Sep 18, 2025 · Sep 19, 2025 · Sep 25, 2025
diff --git a/about/features.md b/about/features.md
@@ -114,8 +114,7 @@ Following is an index of the features currently covered by CAP, with status and
 | [Arrayed Elements](../cds/cdl#arrayed-types)                                               | <X/>  |  <X/>   | <X/> |
 | [Streaming & Media Types](../guides/providing-services#serving-media-data)                 | <X/>  |  <X/>   | <X/> |
 | [Conflict Detection through _ETags_](../guides/providing-services#etag)                    | <X/>  |  <X/>   | <X/> |
-| [Authentication via JWT](../guides/security/authorization#prerequisite-authentication)     | <Na/> |  <X/>   | <X/> |
-| [Basic Authentication](../guides/security/authorization#prerequisite-authentication)       | <Na/> |  <X/>   | <X/> |
+| [Authentication](../guides/security/authentication)                                        | <X/> |  <X/>   | <X/> |
 
 
 <br>

diff --git a/get-started/troubleshooting.md b/get-started/troubleshooting.md
@@ -252,7 +252,7 @@ A new option `privilegedUser()` can be leveraged when [defining](../java/event-h
 
 |  | Explanation |
 | --- | ---- |
-| _Root Cause_ | You've [explicitly configured a mock](../java/security#explicitly-defined-mock-users) user with a name that is already used by a [preconfigured mock user](../java/security#preconfigured-mock-users).
+| _Root Cause_ | You've [explicitly configured a mock](../java/security#custom-mock-users) user with a name that is already used by a [preconfigured mock user](../java/security#preconfigured-mock-users).
 | _Solution_ | Rename the mock user and build your project again.
 
 ### Why do I get an "Error on server start"?

diff --git a/guides/deployment/microservices.md b/guides/deployment/microservices.md
@@ -370,7 +370,7 @@ Note that we use the *--ws-pack* option for some modules. It's important for nod
 
 ### Authentication
 
-Add [security configuration](../security/authorization#xsuaa-configuration) using the command:
+Add [security configuration](../security/authentication#authentication) using the command:
 
 ```shell
 cds add xsuaa --for production

diff --git a/guides/deployment/to-cf.md b/guides/deployment/to-cf.md
@@ -159,7 +159,7 @@ cds add xsuaa
 ```
 
 ::: tip This will also generate an `xs-security.json` file
-The roles/scopes are derived from authorization-related annotations in your CDS models. Ensure to rerun `cds compile --to xsuaa`, as documented in the [_Authorization_ guide](/guides/security/authorization#xsuaa-configuration) whenever there are changes to these annotations.
+The roles/scopes are derived from authorization-related annotations in your CDS models. Ensure to rerun `cds compile --to xsuaa`, as documented in the [security guide](/guides/security/cap-users#xsuaa-roles) whenever there are changes to these annotations.
 :::
 
 [Learn more about SAP Authorization and Trust Management/XSUAA.](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all){.learn-more}

diff --git a/guides/providing-services.md b/guides/providing-services.md
@@ -994,7 +994,7 @@ The remaining cases that need custom handlers, reduce to real custom logic, spec
 
 - Domain-specific programmatic [Validations](#input-validation)
 - Augmenting result sets, for example to add computed fields for frontends
-- Programmatic [Authorization Enforcements](/guides/security/authorization#enforcement)
+- Programmatic [Authorization Enforcements](/guides/security/cap-users#developing-with-users)
 - Triggering follow-up actions, for example calling other services or emitting outbound events in response to inbound events
 - And more... In general, all the things not (yet) covered by generic handlers
 

diff --git a/guides/security/aspects.md b/guides/security/aspects.md
@@ -118,7 +118,7 @@ CAP doesn't require any specific authentication strategy, but it provides out of
 On configured authentication, *all CAP endpoints are authenticated by default*.
 
 ::: warning
-❗ **CAP applications need to ensure that an appropriate [authentication method](/guides/security/authorization#prerequisite-authentication) is configured**.
+❗ **CAP applications need to ensure that an appropriate [authentication](./authentication) is configured**.
 It's highly recommended to establish integration tests to safeguard a valid configuration.
 :::
 
@@ -196,7 +196,7 @@ To verify CAP authorizations in your model, it's recommended to use [CDS lint ru
 
 The rules prepared by application developers are applied to business users according to grants given by the subscribers user administrator, that is, they're applied tenant-specific.
 
-CAP authorizations can be defined dependently from [user claims](/guides/security/authorization#user-claims) such as [XSUAA scopes or attributes](https://help.sap.com/docs/btp/sap-business-technology-platform/application-security-descriptor-configuration-syntax)
+CAP authorizations can be defined dependently from [user claims](/guides/security/cap-users#claims) such as [XSUAA scopes or attributes](https://help.sap.com/docs/btp/sap-business-technology-platform/application-security-descriptor-configuration-syntax)
 that are deployed by application developers and granted by the user administrator of the subscriber.
 Hence, CAP provides a seamless integration of central identity service without technical lock-in.