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 <> demonstrates an endpoint that uses both Jakarta REST and Common Security annotations to describe and secure its endpoints. @@ -477,6 +476,8 @@ The following <> 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;