Add readme

Author: amanteaux

plume-web-jersey/README.md

@@ -137,3 +137,103 @@ public void waitAsync(@Suspended final AsyncResponse asyncResponse) {
 }
 ```
 
+Requests authorization
+----------------------
+Multiple authorization provider are implemented.
+For all provider, the HTTP header `Authorization` is used to fetch the authorization value.
+
+### Basic authorization
+This feature is provided by the `BasicAuthenticator` class.
+Sample usage:
+```java
+@Path("/example")
+@Tag(name = "example", description = "Manage exemple web-services")
+@Consumes(MediaType.APPLICATION_JSON)
+@Produces(MediaType.APPLICATION_JSON)
+// Since we are performing authorization in the resource, we can mark this API as public
+@PublicApi
+@Singleton
+public class ExampleWs {
+    private final BasicAuthenticator<String> basicAuthenticator;
+
+	@Inject
+	public ExampleWs() {
+        this.basicAuthenticator = BasicAuthenticator.fromSingleCredentials(
+            "my-username",
+            "my-password",
+            // Message displayed to the user trying to access the API with a browser
+            "My protected API"
+        );
+	}
+
+	@GET
+	@Path("/test")
+	@Operation(description = "Example web-service")
+	public Test test(@Context ContainerRequestContext requestContext) {
+        basicAuthenticator.requireAuthentication(requestContext);
+
+		return new Test("Hello world");
+	}
+}
+```
+
+One sample valid request: `curl -u 'my-username:my-password' 'http://localhost:8080/api/example/test'`
+
+### API Key authorization
+This feature is provided by the `BearerAuthenticator` class.
+Sample usage:
+```java
+@Path("/example")
+@Tag(name = "example", description = "Manage exemple web-services")
+@Consumes(MediaType.APPLICATION_JSON)
+@Produces(MediaType.APPLICATION_JSON)
+// Since we are performing authorization in the resource, we can mark this API as public
+@PublicApi
+@Singleton
+public class ExampleWs {
+    private final BearerAuthenticator bearerAuthenticator;
+
+    @Inject
+    public ExampleWs() {
+        this.bearerAuthenticator = new BearerAuthenticator("my-bearer-token");
+    }
+
+    @GET
+    @Path("/test")
+    @Operation(description = "Example web-service")
+    public Test test(@Context ContainerRequestContext requestContext) {
+        bearerAuthenticator.verifyAuthentication(requestContext);
+
+        return new Test("Hello world");
+    }
+}
+```
+
+One sample valid request: `curl -H 'Authorization: Bearer my-bearer-token' 'http://localhost:8080/api/example/test'`
+
+### Resource authorization based on annotation
+This feature is provided `AuthorizationSecurityFeature` and works with any authentication system.
+For example using bearer auth:
+- In the `JerseyConfigProvider` file, declare the feature with the annotation used for resource identification: `config.register(new BearerAuthenticator("my-bearer-token").toAuthorizationFeature(BearerRestricted.class));`
+- In the `JerseyConfigProvider` file, register if needed the annotation used in the `RequireExplicitAccessControlFeature`: `config.register(RequireExplicitAccessControlFeature.accessControlAnnotations(PublicApi.class, BearerRestricted.class));`
+- Use the annotation in a resource definition:
+```java
+@Path("/example")
+@Tag(name = "example", description = "Manage exemple web-services")
+@Consumes(MediaType.APPLICATION_JSON)
+@Produces(MediaType.APPLICATION_JSON)
+// The new annotation that will ensure the authorization process before granting access
+@BearerRestricted
+@Singleton
+public class ExampleWs {
+    @GET
+    @Path("/test")
+    @Operation(description = "Example web-service")
+    public Test test() {
+        return new Test("Hello world");
+    }
+}
+```
+
+### Permissions based authorization
+TODO to details

plume-web-jersey/src/main/java/com/coreoz/plume/jersey/security/basic/BasicAuthenticator.java

@@ -1,14 +1,13 @@
 package com.coreoz.plume.jersey.security.basic;
 
-import com.coreoz.plume.jersey.security.AuthorizationVerifier;
-import lombok.extern.slf4j.Slf4j;
-
+import com.coreoz.plume.jersey.security.AuthorizationSecurityFeature;
 import jakarta.ws.rs.ClientErrorException;
 import jakarta.ws.rs.ForbiddenException;
 import jakarta.ws.rs.container.ContainerRequestContext;
 import jakarta.ws.rs.core.HttpHeaders;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.Response.Status;
+import lombok.extern.slf4j.Slf4j;
 
 import java.lang.annotation.Annotation;
 import java.nio.charset.StandardCharsets;
@@ -62,13 +61,17 @@ public static BasicAuthenticator<String> fromSingleCredentials(String singleUser
 	// API
 
     /**
-     * Provide an {@link AuthorizationVerifier} from the basic authenticator to provide annotation based request authorization using {@link com.coreoz.plume.jersey.security.AuthorizationSecurityFeature}
-     * @param annotation The annotation that will be used to identify resources that must be authorized. For example {@link BasicRestricted} can be used if it is not already used in the project for another authorization system
-     * @return The basic authenticator corresponding {@link AuthorizationVerifier}
-     * @param <A> The annotation type
+     * Provide a {@link AuthorizationSecurityFeature} from the bearer basic that can be used in Jersey
+     * to provide authentication on annotated resources.
+     * @param basicAnnotation The annotation that will be used to identify resources that must be authorized. For example {@link BasicRestricted} can be used if it is not already used in the project for another authorization system
+     * @return The corresponding {@link AuthorizationSecurityFeature}
+     * @param <A> The annotation type used to identify required basic authenticated resources
      */
-    public <A extends Annotation> AuthorizationVerifier<A> toAuthorizationVerifier(A annotation) {
-        return (authorizationAnnotation, requestContext) -> requireAuthentication(requestContext);
+    public <A extends Annotation> AuthorizationSecurityFeature<A> toAuthorizationFeature(Class<A> basicAnnotation) {
+        return new AuthorizationSecurityFeature<>(
+            basicAnnotation,
+            (authorizationAnnotation, requestContext) -> requireAuthentication(requestContext)
+        );
     }
 
 	/**

plume-web-jersey/src/main/java/com/coreoz/plume/jersey/security/bearer/BearerAuthenticator.java

@@ -1,7 +1,6 @@
 package com.coreoz.plume.jersey.security.bearer;
 
-import com.coreoz.plume.jersey.security.AuthorizationVerifier;
-import com.coreoz.plume.jersey.security.basic.BasicRestricted;
+import com.coreoz.plume.jersey.security.AuthorizationSecurityFeature;
 import com.google.common.net.HttpHeaders;
 import jakarta.ws.rs.ForbiddenException;
 import jakarta.ws.rs.container.ContainerRequestContext;
@@ -25,20 +24,25 @@ public BearerAuthenticator(String bearerToken) {
     }
 
     /**
-     * Provide an {@link AuthorizationVerifier} from the bearer authenticator to provide annotation based request authorization using {@link com.coreoz.plume.jersey.security.AuthorizationSecurityFeature}
-     * @param annotation The annotation that will be used to identify resources that must be authorized. For example {@link BasicRestricted} can be used if it is not already used in the project for another authorization system
-     * @return The basic authenticator corresponding {@link AuthorizationVerifier}
-     * @param <A> The annotation type
+     * Provide a {@link AuthorizationSecurityFeature} from the bearer authenticator that can be used in Jersey
+     * to provide authentication on annotated resources.
+     * @param bearerAnnotation The annotation that will be used to identify resources that must be authorized. For example {@link BearerRestricted} can be used if it is not already used in the project for another authorization system
+     * @return The corresponding {@link AuthorizationSecurityFeature}
+     * @param <A> The annotation type used to identify required bearer authenticated resources
      */
-    public <A extends Annotation> AuthorizationVerifier<A> toAuthorizationVerifier(A annotation) {
-        return (authorizationAnnotation, requestContext) -> verifyAuthentication(requestContext);
+    public <A extends Annotation> AuthorizationSecurityFeature<A> toAuthorizationFeature(Class<A> bearerAnnotation) {
+        return new AuthorizationSecurityFeature<>(
+            bearerAnnotation,
+            (authorizationAnnotation, requestContext) -> verifyAuthentication(requestContext)
+        );
     }
 
     public void verifyAuthentication(@NotNull ContainerRequestContext requestContext) {
         String bearer = parseBearerHeader(requestContext.getHeaderString(HttpHeaders.AUTHORIZATION));
 
         if (bearer == null || !MessageDigest.isEqual(authenticationSecretHeader.getBytes(), bearer.getBytes())) {
-            throw new ForbiddenException("Invalid bearer header: " + bearer);
+            logger.warn("Invalid bearer header: {}", bearer);
+            throw new ForbiddenException();
         }
     }
 

plume-web-jersey/src/main/java/com/coreoz/plume/jersey/security/permission/PermissionFeature.java

@@ -8,7 +8,6 @@
 import jakarta.ws.rs.container.ResourceInfo;
 import jakarta.ws.rs.core.FeatureContext;
 import lombok.extern.slf4j.Slf4j;
-import org.glassfish.jersey.server.internal.LocalizationMessages;
 
 import java.lang.annotation.Annotation;
 import java.util.Collection;
@@ -37,7 +36,7 @@ private static <A extends Annotation> AuthorizationVerifier<A> makeAuthorization
     ) {
         return (authorizationAnnotation, requestContext) -> {
             if(!authorize(requestPermissionProvider, requestContext, permissionAnnotationExtractor.apply(authorizationAnnotation))) {
-                throw new ForbiddenException(LocalizationMessages.USER_NOT_AUTHORIZED());
+                throw new ForbiddenException();
             }
         };
     }