AMS Java 4.0.6 (#25)

* 4.0.6 CHANGELOG
* improve migration guide

Author: finkmanAtSap

docs/Libraries/java/changelog.md

@@ -1,6 +1,13 @@
 # Release Notes for AMS Client Library Java 
 
-## 4.0.0 - 4.0.5*
+## Version 4
+
+### 4.0.6
+
+- Fix: Read Number constants from DCN as `Double` instead of `Long/Int` to avoid runtime errors when comparing with `Double` attribute input
+- Fix `AmsCapAutoConfiguration`: Use @Order(-100) for `AmsUserInfoProvider` bean to make sure it runs late in the `UserInfoProvider` chain. For example, this fixes incompatibilities with DwcUserInfoProvider which must run before the `AmsUserInfoProvider` to extract user information from the token.
+
+### 4.0.0 - 4.0.5*
 
 Version 4 drastically changes the core API to streamline it with the Node.js library which received positive feedback since it introduced the same changes.
 
@@ -17,7 +24,7 @@ during application start. As a result, the authorization checks themselves remai
 ::: tip ZTIS Auto-Configuration
 There is out-of-the-box support for ZTIS service bindings via the Spring Boot starters.
 :::
-- Domain-Specific `Authorizations` by [wrapping](https://github.com/SAP-samples/ams-samples-java/blob/new_lib_v4/ams-javalin-shopping/src/main/java/com/sap/cloud/security/ams/samples/auth/AuthHandler.java#L68) `Authorizations` objects with [domain-specific methods](https://github.com/SAP-samples/ams-samples-java/blob/new_lib_v4/ams-javalin-shopping/src/main/java/com/sap/cloud/security/ams/samples/auth/ShoppingAuthorizations.java#L27-L46) for [better readability](https://github.com/SAP-samples/ams-samples-java/blob/new_lib_v4/ams-javalin-shopping/src/main/java/com/sap/cloud/security/ams/samples/service/OrdersService.java#L151-L153) and reusability of authorization checks across your application.
+- Domain-Specific `Authorizations` by [wrapping](https://github.com/SAP-samples/ams-samples-java/blob/main/ams-javalin-shopping/src/main/java/com/sap/cloud/security/ams/samples/auth/AuthHandler.java#L68) `Authorizations` objects with [domain-specific methods](https://github.com/SAP-samples/ams-samples-java/blob/main/ams-javalin-shopping/src/main/java/com/sap/cloud/security/ams/samples/auth/ShoppingAuthorizations.java#L27-L46) for [better readability](https://github.com/SAP-samples/ams-samples-java/blob/main/ams-javalin-shopping/src/main/java/com/sap/cloud/security/ams/samples/service/OrdersService.java#L151-L153) and reusability of authorization checks across your application.
 ::: tip CdsAuthorizations
 The CAP Spring Boot starter already wraps the standard `Authorizations` in a `CdsAuthorizations` adapter that provides CAP-specific methods for role checks.
 :::
@@ -51,17 +58,19 @@ Our performance tests have indicated that the performance impact of authorizatio
 
 For example, for both library versions, the request latency for a localhost CAP OData endpoint with instance-based authorization filters was `<= 5ms` of which most of the time was likely spent on database and network handling instead of the AMS library.
 
-## 3.8.0
+## Version 3
+
+### 3.8.0
 
 - This release removes the dependencies from `com.sap.cloud.security.ams.dcl` artifacts. All required classes,
 interfaces, etc., are now part of the `jakarta-ams` module using the same packages. So, everything should continue
 to work without any changes. Please remove any direct dependencies on `com.sap.cloud.security.ams.dcl` artifacts.
 
-## 3.7.0
+### 3.7.0
 
 - Maintenance release with updated dependencies and fixes for the Maven Central release process.
 
-## 3.6.0
+### 3.6.0
 
 - The property `cds.security.mock.enabled` is now used to enable the mock users in the
   `cap-ams-support` module.

docs/Libraries/java/v3/migration-v3-to-v4.md

@@ -115,16 +115,18 @@ boolean allowed = !authorizations
 
 ### Spring Route Security
 
-- Replace `SecurityExpressionHandler` with `AmsRouteSecurity` (CAP: `AmsCdsRouteSecurity`) bean in `SecurityFilterChain`.
+- Replace `SecurityExpressionHandler` with `AmsRouteSecurity`/`AmsCdsRouteSecurity` (CAP) bean in `SecurityFilterChain`.
 - Update route authorization checks based on following mapping:
 
-| v3 Route Check Syntax                                        | v4 Route Check Syntax                          |
-|--------------------------------------------------------------|------------------------------------------------|
-| `hasBaseAuthority("action", "resource")`                     | `precheckPrivilege("action", "resource")`      |
-| `forAction("action")`                                        | `checkPrivilege("action", "*")`                |
-| `forResource("resource")`                                    | `checkPrivilege("*", "resource")`              |
-| `forResourceAction("resource", "action")`                    | `checkPrivilege("action", "resource")`         |
-| `forResourceAction("resource", "action", attributes...)`     | use method security instead                    |
+| v3 Route Check Syntax                                        | AmsRouteSecurity                           | AmsCdsRouteSecurity       |
+|--------------------------------------------------------------|--------------------------------------------|---------------------------------|
+| `hasBaseAuthority("read", "products")`                       | `precheckPrivilege("read", "products")`    | —                               |
+| `hasBaseAuthority("Admin", "$SCOPES")`                       | `precheckPrivilege("Admin", "$SCOPES")`    | `precheckRole("Admin")`         |
+| `forAction("read")`                                          | `checkPrivilege("read", "*")`              | —                               |
+| `forResource("products")`                                    | `checkPrivilege("*", "products")`          | —                               |
+| `forResourceAction("products", "read")`                      | `checkPrivilege("read", "products")`       | —                               |
+| `forResourceAction("$SCOPES", "Admin")`                      | `checkPrivilege("Admin", "$SCOPES")`       | `checkRole("Admin")`            |
+| `forResourceAction("products", "read", attributes...)`       | use method security                 | use method security      |   
 
 **Example**:
 
@@ -139,19 +141,39 @@ public SecurityFilterChain filterChain(
             new WebExpressionAuthorizationManager("hasBaseAuthority('read', 'orders')");
     readOrders.setExpressionHandler(amsHttpExpressionHandler);
 
+    WebExpressionAuthorizationManager adminRole =
+            new WebExpressionAuthorizationManager("forResourceAction('$SCOPES', 'Admin')");
+    adminRole.setExpressionHandler(amsHttpExpressionHandler);
+
     http.authorizeHttpRequests(authz -> authz
-            .requestMatchers(GET, "/orders/**").access(readOrders));
+            .requestMatchers(GET, "/orders/**").access(readOrders)
+            .requestMatchers("/admin/**").access(adminRole));
     return http.build();
 }
 ```
 
-```java [v4]
+```java [v4 AmsRouteSecurity]
 @Bean
 public SecurityFilterChain filterChain(HttpSecurity http, AmsRouteSecurity via) {
 
     http.authorizeHttpRequests(authz -> authz
             .requestMatchers(GET, "/orders/**")
-                .access(via.precheckPrivilege("read", "orders")));
+                .access(via.precheckPrivilege("read", "orders"))
+            .requestMatchers("/admin/**")
+                .access(via.checkPrivilege("Admin", "$SCOPES")));
+    return http.build();
+}
+```
+
+```java [v4 AmsCdsRouteSecurity (CAP)]
+@Bean
+public SecurityFilterChain filterChain(HttpSecurity http, AmsCdsRouteSecurity via) {
+
+    http.authorizeHttpRequests(authz -> authz
+            .requestMatchers(GET, "/orders/**")
+                .access(via.precheckPrivilege("read", "orders"))
+            .requestMatchers("/admin/**")
+                .access(via.checkRole("Admin")));
     return http.build();
 }
 ```
@@ -201,10 +223,10 @@ Replace the DCL output directory with the new default output directory for AMS D
 
 ### CAP Java Configuration
 
-- Remove test sources property from `application.yaml`:
+- Remove test sources property from `application.yaml`. It is no longer used:
 
 ```yaml
-cds:
+cds: # [!code --:5]
   security:
     authorization:
       ams:
@@ -217,5 +239,5 @@ In v4, the existence of `spring-boot-starter-ams-cap-test` on the classpath dete
 
 ### Spring Security Tests
 
-The `MockOidcTokenRequestPostProcessor.userWithPolicies` from `jakarta-ams-test` has been removed because the real AMS production code can now be tested.
+The `MockOidcTokenRequestPostProcessor.userWithPolicies` from `jakarta-ams-test` has been removed because now, the full AMS production code can be tested including the real `AuthorizationProvider`.
 It requires the definition of a [policy assignments](/Authorization/Testing#assigning-policies-to-mocked-users) map from which AMS determines the used policies based on the `app_tid` and `scim_id` claims of the token, and for advanced token flows: other claims as needed.