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
+
+The `@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.
+Let's consider situation when you want to inject a bean from the Jakarta REST context like the `jakarta.ws.rs.core.UriInfo` bean.
+That means you need the `HttpSecurityPolicy` applied on Jakarta REST endpoints, which can be configured in one of two ways:
+* Use `@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[Activate CDI request context in a safe manner] 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,17 @@ public class HelloService {
 }
 ----
 
+[[cdi-request-context-activation]]
+== Activate CDI request context in a safe manner
+
+You may need to inject `@RequestScoped` beans during authentication and authorization.
+A good example is accessing a database during a `SecurityIdentity` augmentation, please see 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 activate xref:cdi-reference.adoc#request-context-lifecycle[CDI request context] as well, for example with the `@ActivateRequestContext` annotation, however some CDI beans may not be ready.
+
+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].
+In such a situation, delaying a policy's permission check after Quarkus prepared the CDI request context as documented in the xref:security-authorize-web-endpoints-reference.adoc#policy-active-cdi-request-context[respective section] of the Authorization using configuration guide is necessary.
+
 [[customize-auth-exception-responses]]
 == Customize authentication exception responses