docs(security): CDI request context with HTTP perms and proactive auth

docs/src/main/asciidoc/cdi-reference.adoc

@@ -333,6 +333,7 @@ public class EagerAppBean {
 
 NOTE: Quarkus users are encouraged to always prefer the `@Observes StartupEvent` to `@Initialized(ApplicationScoped.class)` as explained in the xref:lifecycle.adoc[Application Initialization and Termination] guide.
 
+[[request-context-lifecycle]]
 === Request Context Lifecycle
 
 The request context is also active:

docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc

@@ -123,9 +123,9 @@ public class CustomNamedHttpSecPolicy implements HttpSecurityPolicy {
     public Uni<CheckResult> checkPermission(RoutingContext event, Uni<SecurityIdentity> identity,
             AuthorizationRequestContext requestContext) {
         if (customRequestAuthorization(event)) {
-            return Uni.createFrom().item(CheckResult.PERMIT);
+            return CheckResult.permit();
         }
-        return Uni.createFrom().item(CheckResult.DENY);
+        return CheckResult.deny();
     }
 
     @Override
@@ -182,6 +182,17 @@ You can also create global `HttpSecurityPolicy` invoked on every request.
 Just do not implement the `io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy.name` method and leave the policy nameless.
 ====
 
+[[policy-active-cdi-request-context]]
+=== Inject `@RequestScoped` beans into `HttpSecurityPolicy`
+
+`@RequestScoped` beans can only be injected when the xref:cdi-reference.adoc#request-context-lifecycle[CDI request context] is active.
+The context can be activated by users, for example with the `@ActivateRequestContext`, however authorization happens before Quarkus prepares some `@RequestScoped` beans.
+We recommend to let Quarkus activate and prepare CDI request context for you.
+For example, consider a situation where you want to inject a bean from the Jakarta REST context, such as the `jakarta.ws.rs.core.UriInfo` bean.
+In this case, you must apply the `HttpSecurityPolicy` to Jakarta REST endpoints. This can be achieved in one of the following ways:
+* Use the `@AuthorizationPolicy` security annotation.
+* Set the `quarkus.http.auth.permission.custom1.applies-to=jaxrs` configuration property.
+
 === Matching on paths and methods
 
 Permission sets can also specify paths and methods as a comma-separated list.
@@ -494,7 +505,7 @@ s| `@PermitAll` | Specifies that all security roles are allowed to invoke the sp
 s| `@RolesAllowed` | Specifies the list of security roles allowed to access methods in an application.
 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("**")`.
 s| `@PermissionsAllowed` | Specifies the list of permissions that are allowed to invoke the specified methods.
-s| `@AuthorizationPolicy` | Specifies named `io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy` that should authorize access to the specified endpoints.HttpSecurityPolicy.
+s| `@AuthorizationPolicy` | Specifies named `io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy` that should authorize access to the specified Jakarta REST endpoints.
 Named HttpSecurityPolicy can be used for general authorization checks as demonstrated by <<authorization-policy-example>>.
 |===
 

docs/src/main/asciidoc/security-customization.adoc

@@ -242,6 +242,8 @@ You can enforce the order by implementing a default `SecurityIdentityAugmentor#p
 By default, the request context is not activated when augmenting the security identity, this means that if you want to use for example Hibernate
 that mandates a request context, you will have a `jakarta.enterprise.context.ContextNotActiveException`.
 
+IMPORTANT: Please also review the xref:security-proactive-authentication.adoc#cdi-request-context-activation[Activating the CDI request context] section of the "Proactive authentication" guide.
+
 The solution is to activate the request context, the following example shows how to get the roles from an Hibernate with Panache `UserRoleEntity`.
 
 [source,java]

docs/src/main/asciidoc/security-proactive-authentication.adoc

@@ -18,6 +18,7 @@ Gain practical insights and strategies for various application scenarios.
 Proactive authentication is enabled in Quarkus by default.
 It ensures that all incoming requests with credentials are authenticated, even if the target page does not require authentication.
 As a result, requests with invalid credentials are rejected, even if the target page is public.
+Requests without credentials are not rejected, because anonymous requests are allowed.
 
 You can turn off this default behavior if you want to authenticate only when the target page requires it.
 To turn off proactive authentication so that authentication occurs only when the target page requires it, modify the `application.properties` configuration file as follows:
@@ -30,7 +31,7 @@ quarkus.http.auth.proactive=false
 If you turn off proactive authentication, the authentication process runs only when an identity is requested.
 An identity can be requested because of security rules that require the user to authenticate or because programmatic access to the current identity is required.
 
-If proactive authentication is used, accessing `SecurityIdentity` is a blocking operation.
+If proactive authentication is not used, accessing `SecurityIdentity` is a blocking operation.
 This is because authentication might have yet to happen, and accessing `SecurityIdentity` might require calls to external systems, such as databases, that might block the operation.
 For blocking applications, this is not an issue.
 However, if you have disabled authentication in a reactive application, this fails because you cannot do blocking operations on the I/O thread.
@@ -96,6 +97,19 @@ public class HelloService {
 }
 ----
 
+[[cdi-request-context-activation]]
+== Activating the CDI request context
+
+You may need to inject `@RequestScoped` beans during authentication and authorization.
+A good example of this is accessing a database during a `SecurityIdentity` augmentation,
+which is described in the xref:security-customization.adoc#security-identity-customization[Security Identity Customization] section of the "Security Tips and Tricks" guide.
+If authentication or authorization fails with the `jakarta.enterprise.context.ContextNotActiveException`, disabling proactive authentication is most often the best solution.
+Users can also activate xref:cdi-reference.adoc#request-context-lifecycle[CDI request context], for example, by using the `@ActivateRequestContext` annotation.
+However, some CDI beans may not be ready for use.
+
+One exception to this solution is a situation when application endpoints are secured with the xref:security-authorize-web-endpoints-reference.adoc#authorization-using-configuration[Authorization using configuration].
+For more information, see the xref:security-authorize-web-endpoints-reference.adoc#policy-active-cdi-request-context[Inject RequestScoped beans into HttpSecurityPolicy] section of the "Authorization of Web endpoints" guide for more information.
+
 [[customize-auth-exception-responses]]
 == Customize authentication exception responses