@cerema/cadriciel 0.5.0

package/template/{{project}}-presentation/Readme.md

@@ -0,0 +1,98 @@
+# Module de gestion des contrôleurs de l'application
+
+Ce module est responsable du dialogue entre le Client et notre API. Nous utilisons des annotations springdoc pour
+générer un swagger de l'API.
+
+## Implémentation de l'authentification
+
+L'authentification se fait par l'intermédiaire d'Orion. Nous nous basons sur la réception d'un token JWT qui doit être
+présent dans les entêtes HTTP Authorization avec le nom Bearer. Ce qui donne :
+
+<code>
+Authorization: Bearer << jeton JWT encodé en Base64 >>
+</code>
+
+Ce jeton est signé numériquement par Orion, nous disposons de sa clé publique pour le valider. Les informations
+contenues dedans sont donc sûres :
+
+- orionId : l'id unique généré par Orion pour cet utilisateur qui peut être une personne ou une application. Il est
+  récupéré dans le champ "sub", qui correspond au Subject du token.
+- email : champ "email" du token
+
+On ajoute des rôles en consultant la base locale d'Aspro et en se basant sur l'id orion. Ceci est fait dans la classe :
+<code>fr.cerema.dsi.commons.security.auth.jwt.JwtAuthenticationProvider</code>
+
+### Sécurisation d'une API
+
+Pour activer l'authentification sur une partie de l'API, il faut faire deux choses :
+
+1. Ajouter l'url dans la variable protectedEndpointList de la méthode configure de la classe WebSecurityConfiguration.
+   par exemple : <code>"/protected/\*\*", "/interne/\*\*"</code>
+2. Ajouter le contrôle des rôles grâce aux annotations @Secured. Elles peuvent être placées soit sur les méthodes, soit
+   sur la classe, auquel cas, elle s'appliquera à toutes les méthodes. Par exemple : <code>@Secured("ROLE_ADMIN")</code>
+
+Si on se contente de l'étape 1, alors les urls sont protégées, mais uniquement par la présence d'un jeton Orion valide.
+Toute personne s'étant créé un compte sur Orion (n'importe qui peut le faire) aura accès à l'url. La protection est donc
+quasi inexistante. Il faut impérativement combiner avec le point 2, car les rôles sont ajoutés manuellement par un
+administrateur d'ASPRO dans sa base locale.
+
+Il est possible d'ajouter une icône cadenas dans le swagger pour faciliter l'expérimentation de l'API directement à
+partir de la documentation :
+
+```java
+@SecurityRequirement(name = ORION_AUTH)
+```
+
+ATTENTION : C'est purement de la documentation, la véritable authentification est assurée par les annotations @Secured
+comme vu ci-dessus
+
+### Récupération d'informations sur l'authentification
+
+En plus de la sécurisation par rôle comme vu ci-dessus, il est possible de récupérer les infos sur l'utilisateur
+contenues dans le token en ajoutant simplement un paramètre <code>Authentication authentication</code> dans le
+contrôleur concerné.
+
+### Autres possibilités pour une gestion fine des droits
+
+Il existe des annotations plus puissantes comme :
+
+- <code>@PreAuthorize</code> qui permet d'utiliser des expressions utilisant le langage de scripting spEL
+- <code>@PostAuthorize</code> qui permet en plus de vérifier le résultat de la fonction. Mais ATTENTION, elle sera
+  exécutée quoi qu'il arrive
+- <code>@PreFilter</code> qui permet de filtrer une collection
+
+Il faudrait au préalable les activer dans <code>WebSecurityConfiguration</code> avec l'ajout de :
+
+```java
+@EnableGlobalMethodSecurity(
+        prePostEnabled = true,
+)
+```
+
+Pour plus d'infos voir cet [article](https://www.baeldung.com/spring-security-method-security)
+
+## Gestion des erreurs
+
+La gestion des erreurs au sein de l'application est centralisée dans 3 classes :
+
+- AppAuthenticationFailureHandler : est dédié aux problèmes d'authentification (mais pas les autorisations)
+- RestResponseEntityExceptionHandler : contient une liste d'exceptions qui sont traitées de manière particulière
+- CustomErrorController : toutes les autres erreurs (les exceptions non interceptées dans l'ensemble du code de l'
+  application) passent ici.
+
+Le parti qui a été pris est de limiter le plus possible la possibilité d'une erreur pendant l'affichage d'une erreur,
+car en général ça se termine par de nombreux rebonds inutiles, voire des boucles infinies particulièrement difficiles à
+comprendre en production.
+
+Les erreurs sont encapsulées dans la classe JsonApiError. Nous n'utilisons pas ResponseEntity<JsonApiError> pour générer
+la réponse envoyée au client, car elle est source de trop d'erreurs, en particulier liées à la gestion de la négociation
+du format du contenu (json, xml, csv, text, etc...). En revanche, nous l'utilisons bien sûr pour le reste de l'
+application.
+
+L'envoi effectif est fait dans la classe : AbstractErrorHandler
+
+Nous disposons également d'Analyser pour certaines erreurs qui peuvent se produire au démarrage de l'application. Ils
+sont utilisés par Spring Boot pour donner des explications. Elle forme une sorte de documentation complémentaire :
+
+- JwtConfMalformedAnalyzer
+- SecretInterneNotDefinedAnalyzer

package/template/{{project}}-presentation/pom.xml

@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>fr.cerema.dsi</groupId>
+    <artifactId>{{project}}</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+  </parent>
+  <packaging>jar</packaging>
+
+  <artifactId>{{project}}-presentation</artifactId>
+
+  <!-- Dépendances spécifiques à ce module -->
+  <dependencies>
+
+    <!-- Dépendances avec les autres modules -->
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>{{project}}-transverse</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>{{project}}-metier</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>{{project}}-data</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>{{project}}-ihm</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <!-- starter-web : pour lancer un tomcat -->
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+
+    <!-- dépendance spring-security -->
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-security</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>org.springframework.security</groupId>
+      <artifactId>spring-security-oauth2-resource-server</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>org.springframework.security</groupId>
+      <artifactId>spring-security-oauth2-jose</artifactId>
+    </dependency>
+
+    <!-- dépendance librairies JWT -->
+    <!--    <dependency>-->
+    <!--      <groupId>io.jsonwebtoken</groupId>-->
+    <!--      <artifactId>jjwt-impl</artifactId>-->
+    <!--      <version>0.11.5</version>-->
+    <!--    </dependency>-->
+    <dependency>
+      <groupId>io.jsonwebtoken</groupId>
+      <artifactId>jjwt-impl</artifactId>
+      <version>0.11.5</version>
+    </dependency>
+    <dependency> <!-- Temporaire : dépendance manquante dans cette librairie...-->
+      <groupId>io.jsonwebtoken</groupId>
+      <artifactId>jjwt-jackson</artifactId>
+      <version>0.11.5</version>
+    </dependency>
+
+    <!-- Pour générer une doc de l'API -->
+    <dependency>
+      <groupId>org.springdoc</groupId>
+      <artifactId>springdoc-openapi-ui</artifactId>
+      <version>1.6.9</version>
+    </dependency>
+    <dependency>
+      <groupId>org.springdoc</groupId>
+      <artifactId>springdoc-openapi-security</artifactId>
+      <version>1.6.9</version>
+    </dependency>
+
+
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-actuator</artifactId>
+    </dependency>
+
+
+    <dependency>
+      <groupId>org.aspectj</groupId>
+      <artifactId>aspectjweaver</artifactId>
+      <version>1.9.5</version>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <!-- and the engine for surefire and failsafe -->
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.jacoco</groupId>
+      <artifactId>jacoco-maven-plugin</artifactId>
+      <version>0.8.7</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <finalName>{{project}}_${project.version}</finalName>
+    <resources>
+      <resource>
+        <directory>${basedir}/src/main/resources-filtered</directory>
+        <filtering>true</filtering>
+      </resource>
+      <resource>
+        <directory>${basedir}/src/main/resources</directory>
+        <filtering>false</filtering>
+      </resource>
+    </resources>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-war-plugin</artifactId>
+        <version>3.3.1</version>
+        <configuration>
+          <failOnMissingWebXml>false</failOnMissingWebXml>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <version>3.1.2</version>
+        <executions>
+          <execution>
+            <id>merge</id>
+            <phase>prepare-package</phase>
+            <goals>
+              <goal>unpack</goal>
+            </goals>
+            <configuration>
+              <artifactItems>
+                <artifactItem>
+                  <groupId>${project.groupId}</groupId>
+                  <artifactId>{{project}}-ihm</artifactId>
+                  <version>${project.version}</version>
+                  <type>jar</type>
+                  <overWrite>true</overWrite>
+                  <outputDirectory>${project.build.directory}/classes/static</outputDirectory>
+                </artifactItem>
+              </artifactItems>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-failsafe-plugin</artifactId>
+        <version>${maven-failsafe-plugin.version}</version>
+        <configuration>
+          <!-- Due to spring-boot repackage, without adding this property test classes are not found
+               See https://github.com/spring-projects/spring-boot/issues/6254 -->
+          <classesDirectory>${project.build.outputDirectory}</classesDirectory>
+          <!-- Force alphabetical order to have a reproducible build -->
+          <runOrder>alphabetical</runOrder>
+          <includes>
+            <include>**/*IT*</include>
+            <include>**/*IntTest*</include>
+          </includes>
+        </configuration>
+        <executions>
+          <execution>
+            <id>integration-test</id>
+            <goals>
+              <goal>integration-test</goal>
+            </goals>
+          </execution>
+          <execution>
+            <id>verify</id>
+            <goals>
+              <goal>verify</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+        <version>0.8.7</version>
+        <executions>
+          <execution>
+            <id>pre-unit-tests</id>
+            <goals>
+              <goal>prepare-agent</goal>
+            </goals>
+          </execution>
+          <!-- Ensures that the code coverage report for unit tests is created after unit tests have been run -->
+          <execution>
+            <id>post-unit-test</id>
+            <phase>test</phase>
+            <goals>
+              <goal>report</goal>
+            </goals>
+          </execution>
+          <execution>
+            <id>pre-integration-tests</id>
+            <goals>
+              <goal>prepare-agent-integration</goal>
+            </goals>
+          </execution>
+          <!-- Ensures that the code coverage report for integration tests is created after integration tests have been run -->
+          <execution>
+            <id>post-integration-tests</id>
+            <phase>post-integration-test</phase>
+            <goals>
+              <goal>report-integration</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+
+</project>

package/template/{{project}}-presentation/src/main/java/fr/cerema/dsi/commons/beans/errors/ApiSubError.java

@@ -0,0 +1,5 @@
+package fr.cerema.dsi.commons.beans.errors;
+
+public abstract class ApiSubError {
+
+}

package/template/{{project}}-presentation/src/main/java/fr/cerema/dsi/commons/beans/errors/ApiValidationSubError.java

@@ -0,0 +1,13 @@
+package fr.cerema.dsi.commons.beans.errors;
+
+public class ApiValidationSubError extends ApiSubError {
+    private String object;
+    private String field;
+    private Object rejectedValue;
+    private String message;
+
+    ApiValidationSubError(String object, String message) {
+        this.object = object;
+        this.message = message;
+    }
+}

package/template/{{project}}-presentation/src/main/java/fr/cerema/dsi/commons/beans/errors/JsonApiError.java

@@ -0,0 +1,308 @@
+/*
+ * Copyright 2017 - CEREMA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License
+ */
+
+package fr.cerema.dsi.commons.beans.errors;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlElementWrapper;
+import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;
+import org.springframework.http.HttpStatus;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * This class holds the necessary fields of the error
+ * that has to be sent in case of API call failure.
+ * <p>
+ * Error fields are stored in an instance of an inner class {@link JsonApiError.ApiError}.
+ * The Json error is sent back as an array (one element in this case) as asked by the Json Api Specification V1.0
+ * See <a href="http://jsonapi.org/format/#errors">http://jsonapi.org/format/#errors</a>
+ * <p>
+ * Generally, your {@link org.springframework.web.bind.annotation.RestController} will
+ * throw an exception and you will instantiate {@link JsonApiError} in a exception handler
+ * as done for instance in {@link fr.cerema.dsi.commons.controllers.RestResponseEntityExceptionHandler}
+ *
+ * @author alain.charles
+ */
+public class JsonApiError {
+
+    private JsonApiError.ApiError error;
+
+    /**
+     * Returns the API Error as an array of one error in this case
+     * as aked by Json Api Specification V1.0
+     *
+     * @return the list of (one) error.
+     */
+    @JsonProperty
+    @JacksonXmlElementWrapper(localName = "errors")
+    @JacksonXmlProperty(localName = "error")
+    public List<JsonApiError.ApiError> getErrors() {
+        List<ApiError> returnValue = new ArrayList<>();
+        returnValue.add(this.error);
+        return returnValue;
+    }
+
+    private JsonApiError() {
+        this.error = new JsonApiError.ApiError();
+    }
+
+    /**
+     * Creates a new instance of {@link JsonApiError}
+     * using supplied {@link HttpStatus}
+     *
+     * @param status the HTTP status
+     */
+    public JsonApiError(HttpStatus status) {
+        this();
+        this.error.status = status;
+        this.error.message = status.getReasonPhrase();
+    }
+
+    /**
+     * Creates a new instance of {@link JsonApiError}
+     * using supplied {@link HttpStatus} and {@link Throwable}
+     *
+     * @param status the HTTP status
+     * @param ex     the Throwable whose message will be included in {@link JsonApiError#getDebugMessage()}
+     */
+    public JsonApiError(HttpStatus status, Throwable ex) {
+        this(status);
+        if (Objects.nonNull(ex)) this.error.debugMessage = ex.getLocalizedMessage();
+    }
+
+    /**
+     * Creates a new instance of {@link JsonApiError}
+     * using supplied {@link HttpStatus}, {@link String} and {@link Throwable}
+     *
+     * @param status  the HTTP status
+     * @param message the message that will be stored in {@link JsonApiError#getMessage()}
+     * @param ex      the Throwable whose message will be included in {@link JsonApiError#getDebugMessage()}
+     */
+    public JsonApiError(HttpStatus status, String message, Throwable ex) {
+        this(status, ex);
+        this.error.message = message;
+    }
+
+
+    /**
+     * Returns the error time stamp
+     *
+     * @return the timestamp
+     */
+    @JsonIgnore
+    public LocalDateTime getTimestamp() {
+        return error.timestamp;
+    }
+
+    /**
+     * Returns the Http Status Code value
+     *
+     * @return the status code value
+     */
+    @JsonIgnore
+    public int getHttpErrorCode() {
+        return error.status.value();
+    }
+
+    /**
+     * Returns the reason of Http Error
+     *
+     * <p>See <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html">
+     * https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html</a>
+     *
+     * @return the reason of error
+     */
+    @JsonIgnore
+    public String getStatusReasonPhrase() {
+        return error.status.getReasonPhrase();
+    }
+
+    /**
+     * Returns the error main message
+     *
+     * @return the main message
+     */
+    @JsonIgnore
+    public String getMessage() {
+        return error.message;
+    }
+
+    /**
+     * Returns the error debug message
+     *
+     * @return the debug message
+     */
+    @JsonIgnore
+    private String getDebugMessage() {
+        return error.debugMessage;
+    }
+
+    /**
+     * Returns the list of {@link ApiSubError} instances or {@code null}
+     *
+     * @return the list of subErrors
+     */
+    @JsonIgnore
+    public List<ApiSubError> getSubErrors() {
+        return error.subErrors;
+    }
+
+    /**
+     * Retourne the {@link HttpStatus} of the error
+     *
+     * @return the Http status
+     */
+    @JsonIgnore
+    public HttpStatus getStatus() {
+        return error.status;
+    }
+
+
+    @JsonIgnore
+    public List<ApiSubError> getApiSubErrors() {
+        return error.getSubErrors();
+    }
+
+    /**
+     * Minimalist output of the error contained in this instance
+     * Used when the json or xml serialization failed
+     */
+    @Override
+    public String toString() {
+        return error.toString();
+    }
+
+    /**
+     * This class holds the necessary fields of the error
+     * that has to be sent in case of API call failure.
+     *
+     * <p>Generally, you will instantiate {@link JsonApiError} in the
+     * {@link org.springframework.web.bind.annotation.RestController} if the API call raised an exception.
+     *
+     * @author alain.charles
+     */
+    @JsonPropertyOrder({"httpErrorCode", "reason", "timestamp", "message", "debugMessage", "subErrors"})
+    public class ApiError {
+
+        private HttpStatus status;
+
+        private LocalDateTime timestamp;
+
+        private String message;
+
+        private String debugMessage;
+
+        private List<ApiSubError> subErrors;
+
+        private ApiError() {
+            timestamp = LocalDateTime.now();
+        }
+
+
+        /**
+         * Returns the error time stamp
+         *
+         * @return the timestamp
+         */
+        @JsonProperty
+        @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "dd-MM-yyyy HH:mm:ss")
+        public LocalDateTime getTimestamp() {
+            return timestamp;
+        }
+
+        /**
+         * Returns the Http Status Code value
+         *
+         * @return the status code value
+         */
+        @JsonProperty
+        public int getHttpErrorCode() {
+            return status.value();
+        }
+
+        /**
+         * Returns the reason of Http Error
+         *
+         * <p>See <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html">
+         * https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html</a>
+         *
+         * @return the reason of error
+         */
+        @JsonProperty("reason")
+        public String getStatusReasonPhrase() {
+            return status.getReasonPhrase();
+        }
+
+        /**
+         * Returns the error main message
+         *
+         * @return the main message
+         */
+        @JsonProperty
+        public String getMessage() {
+            return message;
+        }
+
+        /**
+         * Returns the error debug message
+         *
+         * @return the debug message
+         */
+        @JsonProperty
+        public String getDebugMessage() {
+            return debugMessage;
+        }
+
+        /**
+         * Returns the list of {@link ApiSubError} instances or {@code null}
+         *
+         * @return the list of subErrors
+         */
+        @JsonProperty
+        List<ApiSubError> getSubErrors() {
+            return subErrors;
+        }
+
+        @Override
+        public String toString() {
+            final String UNKNOWN = "inconnu";
+
+            StringBuilder sb = new StringBuilder();
+
+            sb.append("httpErrorCode : ");
+            sb.append(error.status != null ? error.status.value() : UNKNOWN);
+            sb.append("\nreason : ");
+            sb.append(error.status != null ? error.status.getReasonPhrase() : UNKNOWN);
+            sb.append("\ntimestamp : ");
+            sb.append(error.timestamp != null ? error.timestamp : UNKNOWN);
+            sb.append("\nmessage : ");
+            sb.append(error.message != null ? error.message : UNKNOWN);
+            sb.append("\ndebugMessage : ");
+            sb.append(error.debugMessage != null ? error.debugMessage : UNKNOWN);
+            sb.append("\nsubErrors : ");
+            sb.append(error.subErrors != null ? error.subErrors : UNKNOWN);
+
+            return sb.toString();
+        }
+    }
+}