From 013fd6e95d33ea0a43db7642a7cb48f00ddb1fa9 Mon Sep 17 00:00:00 2001
From: Jakub Jedlicka <jjedlick@redhat.com>
Date: Tue, 20 Aug 2024 17:25:15 +0200
Subject: [PATCH] Update and small fixes for security authorize web endpoints
 reference doc

(cherry picked from commit 57e0a1f708815504e9e98c482406f789a903cc18)
---
 ...ity-authorize-web-endpoints-reference.adoc | 31 ++++++++++++-------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc
index a68093fc5f2f1..fd1bc7ced2d30 100644
--- a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc
+++ b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc
@@ -225,7 +225,7 @@ Previous examples demonstrated matching all sub-paths when a path concludes with
 wildcard.
 
 This wildcard also applies in the middle of a path, representing a single path segment.
-It cannot be mixed with other path segment characters; thus, path separators always enclose the `$$*$$` wildcard, as seen in the `/public/`$$*$$`/about-us` path.
+It cannot be mixed with other path segment characters; thus, path separators always enclose the `$$*$$` wildcard, as seen in the `/public/$$*$$/about-us` path.
 
 When several path patterns correspond to the same request path, the system selects the longest sub-path leading to the `$$*$$` wildcard.
 In this context, every path segment character is more specific than the `$$*$$`
@@ -465,8 +465,7 @@ s| `@PermitAll` | Specifies that all security roles are allowed to invoke the sp
 
 `@PermitAll` lets everybody in, even without authentication.
 s| `@RolesAllowed` | Specifies the list of security roles allowed to access methods in an application.
-
-As an equivalent to `@RolesAllowed("**")`, {project-name} also provides the `io.quarkus.security.Authenticated` annotation that permits any authenticated user to access the resource.
+s| `@Authenticated` | {project-name} provides the `io.quarkus.security.Authenticated` annotation that permits any authenticated user to access the resource. It's equivalent to `@RolesAllowed("**")`.
 |===
 
 The following <<subject-example>> demonstrates an endpoint that uses both Jakarta REST and Common Security annotations to describe and secure its endpoints.
@@ -477,6 +476,8 @@ The following <<subject-example>> demonstrates an endpoint that uses both Jakart
 ----
 import java.security.Principal;
 
+import jakarta.annotation.security.DenyAll;
+import jakarta.annotation.security.PermitAll;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
@@ -495,18 +496,27 @@ public class SubjectExposingResource {
         return name;
     }
 
+    @GET
+    @Path("authenticated")
+    @Authenticated <3>
+    public String getSubjectAuthenticated(@Context SecurityContext sec) {
+        Principal user = sec.getUserPrincipal();
+        String name = user != null ? user.getName() : "anonymous";
+        return name;
+    }
+
     @GET
     @Path("unsecured")
-    @PermitAll <3>
+    @PermitAll <4>
     public String getSubjectUnsecured(@Context SecurityContext sec) {
-        Principal user = sec.getUserPrincipal(); <4>
+        Principal user = sec.getUserPrincipal(); <5>
         String name = user != null ? user.getName() : "anonymous";
         return name;
     }
 
     @GET
     @Path("denied")
-    @DenyAll <5>
+    @DenyAll <6>
     public String getSubjectDenied(@Context SecurityContext sec) {
         Principal user = sec.getUserPrincipal();
         String name = user != null ? user.getName() : "anonymous";
@@ -517,9 +527,10 @@ public class SubjectExposingResource {
 <1> The `/subject/secured` endpoint requires an authenticated user with the granted "Tester" role through the use of the `@RolesAllowed("Tester")` annotation.
 <2> The endpoint obtains the user principal from the Jakarta REST `SecurityContext`.
 This returns `non-null` for a secured endpoint.
-<3> The `/subject/unsecured` endpoint allows for unauthenticated access by specifying the `@PermitAll` annotation.
-<4> The call to obtain the user principal returns `null` if the caller is unauthenticated and `non-null` if the caller is authenticated.
-<5> The `/subject/denied` endpoint declares the `@DenyAll` annotation, disallowing all direct access to it as a REST method, regardless of the user calling it.
+<3> The `/subject/authenticated` endpoint allows any authenticated user by specifying the `@Authenticated` annotation.
+<4> The `/subject/unsecured` endpoint allows for unauthenticated access by specifying the `@PermitAll` annotation.
+<5> The call to obtain the user principal returns `null` if the caller is unauthenticated and `non-null` if the caller is authenticated.
+<6> The `/subject/denied` endpoint declares the `@DenyAll` annotation, disallowing all direct access to it as a REST method, regardless of the user calling it.
 The method is still invokable internally by other methods in this class.
 
 CAUTION: If you plan to use standard security annotations on the IO thread, review the information in xref:security-proactive-authentication.adoc[Proactive Authentication].
@@ -556,8 +567,6 @@ all-roles=Administrator,Software,Tester,User
 ----
 import java.security.Principal;
 
-import jakarta.annotation.security.DenyAll;
-import jakarta.annotation.security.PermitAll;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;