subscribersConf.yml

Par défaut, un fichier subscribersConf.yml vide est présent dans le sous-répertoire extdConfig de l'archive de l'application. Ce fichier au format YAML contient la description des souscripteurs Adélia à exécuter.

Il est nécessaire de le compléter si l'on veut démarrer statiquement des souscripteurs (c'est-à-dire sans passer par les API de création REST).

Configuration du runtime AMBSS

Elle est regroupée dans le fichier Spring boot application.yml (et son pendant application-dev.yml) présents dans le sous-répertoire config de l'archive de l'application. Ces deux fichiers contiennent des propriétés standards de comportement d'application Web Spring Boot ainsi que des propriétés spécifiques à l'AMBSS.

application-dev.yml

Ce fichier est chargé lorsque l'AMBSS est lancé avec le profil de développement (via le fichier de commande ambss-dev.bat / ambss-dev.sh). Ce profil est à utiliser lorsque l'utilisateur est en phase de développement de ses souscripteurs Adélia.

Avec ce profil, certains comportements sont forcés :

• Désactivation de l'authentification par jeton JWT pour l'utilisation des API REST,
• Niveau de log du runtime Adélia AMBSS fixé à DEBUG,
• Autorisation d'arrêter ou de redémarrer l'AMBSS par API REST.

Propriétés Spring boot

Sans décrire exhaustivement l'ensemble des propriétés mises à disposition (voir documentation Spring boot sur le sujet), on retiendra :

• server.port : numéro de port HTTP de l'application
• logging.level.ROOT : niveau de log général de l'application
• logging.config : par défaut, application log dans la sortie standard. Il est possible de définir un fichier de log.

Propriétés AMBSS

Par défaut, le fichier de configuration des souscripteurs subscribersConf.yml à utiliser doit être passé en ligne de commande au lancement de l'ABMSS.

La propriété 'ambss.subscribers.configuration' permet de fixer le chemin d'un fichier de configuration. Ce chemin peut être soit absolu, soit relatif au répertoire racine de l'AMBSS (le répertoire parent du sous-répertoire config où se trouve le fichier application-dev.yml).

La propriété 'ambss.subscribers.writer' permet d'activer la sauvegarde des créations et modifications des souscripteurs par les web services REST dans le fichier de configuration des souscripteurs Adélia (la valeur par défaut est "false"). Si aucun fichier de configuration des souscripteurs n'est spécifié au lancement de l'AMBSS, un fichier subscribersConf.yml est créé dans le répertoire racine de l'AMBSS (le répertoire parent du sous-répertoire config où se trouve le fichier application-dev.yml).

application.yml

Ce fichier est chargé lorsque l'AMBSS est lancé sans profil (via le fichier de commande ambss.bat / ambss.sh). Le profil par défaut correspond au profil de production.

Propriétés Spring boot

Sans décrire exhaustivement l'ensemble des propriétés mises à disposition (voir documentation Spring boot sur le sujet), on retiendra :

• server.port : numéro de port HTTP de l'application
• logging.level.ROOT : niveau de log général de l'application
• logging.config : par défaut, application log dans la sortie standard. Il est possible de définir un fichier de log.

Propriétés AMBSS

Par défaut, le fichier de configuration des souscripteurs subscribersConf.yml à utiliser doit être passé en ligne de commande au lancement de l'ABMSS.

La propriété 'ambss.subscribers.configuration' permet de fixer le chemin d'un fichier de configuration. Ce chemin peut être soit absolu, soit relatif au répertoire racine de l'AMBSS (le répertoire parent du sous-répertoire config où se trouve le fichier application.yml).

La propriété 'ambss.subscribers.writer' permet d'activer la sauvegarde des créations et modifications des souscripteurs par les services web REST dans le fichier de configuration des souscripteurs Adélia (la valeur par défaut est "false"). Si aucun fichier de configuration des souscripteurs n'est spécifié au lancement de l'AMBSS, un fichier subscribersConf.yml est créé dans le répertoire racine de l'AMBSS (le répertoire parent du sous-répertoire config où se trouve le fichier application-dev.yml).

Activation de l'authentification

L'activation de l'authentification par jeton JWT se fait avec la propriété 'ambss.security.enabled'. L'authentification est activée par défaut.

Rôles

L'AMBSS définit deux rôles distincts pour les droits d'utilisation des services web REST :

• Un rôle utilisateur qui a les droits d'utilisation des services de lecture (services utilisant la méthode HTTP GET).
• Un rôle administrateur qui a les droits d'utilisation de la totalité des services (services utilisant les méthodes HTTP GET / POST / DELETE / UPDATE) ainsi que l'accès à la servlet d'administration du pool de sessions Middleware utilisées par les programmes EADELIA,

Il est possible de définir les noms des rôles utilisateur et administrateur grâce aux propriétés 'ambss.security.role-names.user-role' (valeur par défaut : "USER") et 'ambss.security.role-names.admin-role' (valeur par défaut : "ADMIN").

Jeton JWT

Il est possible de définir les caractéristiques du jeton JWT attendu.

• La propriété 'ambss.security.jwt.algorithm' permet de définir l'algorithme d'encryptage du jeton ("RSA256" par défaut).
• La propriété 'ambss.security.jwt.user-role-claim' permet de définir le nom du claim role ("roles" par défaut).
• La propriété 'ambss.security.jwt.keystore-type' permet de définir le type de key store ("JKS" par défaut).
• La propriété 'ambss.security.jwt.keystore-file' permet de définir le fichier contenant les clés d'encryptage du jeton (valeur par défaut : le fichier "RSJwtSecurity.key" fourni par Hardis pour son serveur d'authentification jwtStandalone).
• La propriété 'ambss.security.jwt.keystore-alias' permet de définir le nom d'alias du fichier contenant les clés d'encryptage du jeton (valeur par défaut : le fichier "jwtProviderKey").

Serveur d'authentification autonome

Adélia Studio fournit un serveur d'authentification compatible avec l'AMBSS. Ce service (ou serveur) d'authentification peut-être déployé de façon autonome.

Pour cela, il faut copier le fichier %adeliws%/javarun/jwtProviderStandAlone/jwtProviderStandAlone.war à l'emplacement ad hoc du serveur d'applications (Tomcat par exemple).

Configuration

La configuration du service se fait via un fichier (jwtProv.properties) externalisé sous la forme d'une ressource jndi de type URL via l'alias url/jwtProv avec une fabrique pointant sur la classe com.hardis.common.JndiURLPropsFactory.

Exemple :

Déclaration d'une ressource jndi de nom url/jwtProv de type URL utilisant la fabrique com.hardis.common.JndiURLPropsFactory.

L'emplacement du fichier jwtProv.properties contenant les informations de configuration du service est fixé à l'aide de l'URL : file:///d:/extcfg/jwtProv.properties

Dans le sous répertoire de l'application web jwtProviderStandAlone installée, créer un fichier META-INF\context.xml :

<Context>  
  <Resource auth="Container" factory="com.hardis.common.JndiURLPropsFactory" name="url/jwtProv" type="java.net.URL" url="file:///d:/extcfg/jwtProv.properties"/>  
</Context>

Le fichier jwtProv.properties référencé doit déclarer les valeurs pour les propriétés des objets JwtProviderConfig et JwtJEELoginModule, de la façon suivante :

;jwtProviderConfig
jwtProviderConfig.jwtUserRoleClaim=roles
jwtProviderConfig.jwtValidityTimeClaim=iat
jwtProviderConfig.jwtTtl=3600
jwtProviderConfig.jwtIssuer=jwtIssuer
jwtProviderConfig.jwtPrefixId=jwtId_
jwtProviderConfig.jwtAudienceKind=RscServers
jwtProviderConfig.jwtAudience=http://srvapis1.com/apis ;http://srvapis2.com/apis
jwtProviderConfig.jwtLoginModuleName=jwtJEELoginModule
 
 
;jwtJEELoginModule
jwtJEELoginModule.userParameterName=login
jwtJEELoginModule.passwordParameterName=password
jwtJEELoginModule.securityRoles=ADMIN,USER
jwtJEELoginModule.securityRequestUrl=

Le service requiert également un Keystore pour le chiffrement du jeton. Ce Keystore est de facto externalisé sous la forme d'une ressource jndi de type URL utilisant la fabrique com.hardis.common.JndiURLFactory via l'alias url/adelRSJwtSecurity.

Exemple :

Déclaration d'une ressource jndi de nom url/adelRSJwtSecurity de type URL utilisant la fabrique com.hardis.common.JndiURLFactory.

L'emplacement du Keystore est fixé à l'aide de l'URL : file:///d:/extcfg/RSJwtSecurity.key

<Context>  
  <Resource auth="Container" factory="com.hardis.common.JndiURLPropsFactory" name="url/jwtProv" type="java.net.URL" url="file:///d:/extcfg/jwtProv.properties"/>  
  <Resource auth="Container" factory="com.hardis.common.JndiURLFactory" name="url/adelRSJwtSecurity" type="java.net.URL" url="file:///d:/extcfg/RSJwtSecurity.key "/>
</Context>

Un Keystore par défaut (nommé RSJwtSecurity.key), contenant les clés de l'algorithme de chiffrement asymétrique RSA256 et permettant de chiffrer ou de valider un jeton, est livré par défaut dans le répertoire extdConfig de la distribution standard de l'AMBSS (%ADELIWS%\distrib\AdeliaBrokerSubscribersService).

Le même Keystore doit être utilisé par le service d'authentification (chiffrement du jeton) et par l'AMBSS (validation du jeton).

Le Keystore fourni par défaut peut-être remplacé par un autre Keystore qu'il faut créer à l'aide de la commande suivante :

java -cp jwtProvider-{version}.jar;bcprov-jdk15-1.45.jar com.hardis.jwtprovider.JwtKeyTool -generate pathto\RSJwtSecurity.key

Le service requiert ensuite d'associer les utilisateurs (leurs credentials) aux rôles.

Exemple :

La déclaration des utilisateurs et des rôles sous Tomcat se fait dans le fichier de configuration conf\tomcat-users.xml.

<?xml version='1.0' encoding='cp1252'?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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.
-->
<tomcat-users
    xmlns="http://tomcat.apache.org/xml"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">
    <role rolename="ADMIN"/>
    <role rolename="USER"/>
    <user username="bobTheUser" password="bob" roles="USER"/>
    <user username="johnTheAdmin" password="john" roles="ADMIN"/>
</tomcat-users>

Enfin le service d'authentification autonome requiert par défaut un transport sécurisé (HTTPS). Une configuration doit par conséquent être mise en œuvre au niveau du Container Java EE pour satisfaire ce besoin.

Création d'un jeton

Le service a pour rôle d'authentifier un utilisateur et, en cas de succès de l'authentification, de lui délivrer un jeton JWT.

A l'aide de ce dernier, et pendant toute la période de validité du jeton, l'utilisateur peut s'authentifier auprès du serveur de ressources et accéder aux ressources qui lui sont autorisées.

Le service d'authentification est accessible via la Servlet nommée JWTServlet. Les identifiants de connexion (credentials) sont passés en paramètres de la requête.

Exemple :

https://host:port/wtProviderStandAlone/JWTServlet?login=user&password=pwd

Remarque : Il est également possible d'appeler la servlet en POST et de lui transmettre les identifiants de connexion dans le corps (payload) de la requête à la manière d'un formulaire HTML.

Pour des raisons évidentes de sécurité, l'utilisation du protocole HTTPS est fortement conseillée pour accéder à la Servlet JWTServlet.

La partie authentification propose différents modules : un module d'authentification LDAP, un module d'authentification Java EE et un module d'authentification Adélia.

Il est possible de chaîner plusieurs modules d'authentification.

Le choix du ou des modules se fait via la propriété jwtLoginModuleName de l'objet JwtProviderConfig, décrit dans le fichier de configuration /WEB-INF/beans.xml de l'application hébergeant le service d'authentification.

Si le module d'authentification reconnaît l'utilisateur, la phase de création du jeton JWT entre en jeu.

Celle-ci repose sur :

• Des informations retournées par le module d'authentification (nom de l'utilisateur authentifié, attributs supplémentaires optionnels liés à l'utilisateur).

• Des informations issues de l'objet JwtProviderConfig décrit dans le fichier de configuration /WEB-INF/beans.xml de l'application.

• Une clé de chiffrement nécessaire pour signer numériquement le jeton.
  Cette clé de chiffrement est fournie par un keystore au format JKS nommé RSJwtSecurity.key ; le Keystore est externalisé sous forme d'une ressource jndi de type URL via l'alias url/adelRSJwtSecurity utilisant la fabrique com.hardis.common.jndiURLFactory.

En cas d'échec de l'authentification, le service retourne dans le corps de sa réponse, non plus un jeton JWT, mais une chaîne commençant par [ERROR], suivie d'un message explicatif.

bean-context.xml

Lors du traitement de la charge utile d'un message dans un programme EADELIA (bloc onMessage), l'ordre BRK_RECUP_MSG permet de récupérer cette donnée dans une variable Adélia REF_CLASSE.

Lorsque cette donnée est alphanumérique ou un tableau d'octets, une désérialisation JSON est effectuée en utilisant le convertisseur par défaut de la librairie tierce Jackson.

Description

Il est possible de définir d'autres convertisseurs en modifiant ses propriétés dans le fichier bean-context.xml.

La liste des propriétés (description et valeur par défaut) liées à la désérialisation est disponible ici : https://github.com/FasterXML/jackson-databind/wiki/Deserialization-features

Il faut déclarer un bean de type com.hardis.adelia.webservice.CustomObjectMapper avec les propriétés à fixer (le fichier peut contenir plusieurs déclarations de bean, chacun ayant un id différent).

Remarque : D'une part les noms des propriétés suivent une notation de style "camel case". D'autre part, les propriétés "DeserializationFeature" sont préfixées par Deser.

Exemple :  DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES devient DeserFailOnUnknownProperties.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
        
    <bean id="customJacksonMapper" class="com.hardis.adelia.webservice.CustomObjectMapper" init-method="init">
        <property name="DeserFailOnUnknownProperties" value="false" />
    </bean>    
    
</beans>

Utilisation

Un bean décrit sera utilisé par un souscripteur à l'exécution de l'ordre BRK_RECUP_MSG. Pour cela, il est nécessaire de spécifier le bean à utiliser dans la description du souscripteur via la propriété 'config/adeliaPgm/customObjectMapper' : celle-ci doit avoir comme valeur l'identifiant du bean.

id: processOrderMRK8
startOnCreation: true
config:
  adeliaPgm:
    javaPackage: my.company
    objectFileName: AMQP1
    parameters:
      - 456
      - MR_K_8
    customObjectMapper: customJacksonMapper
  brokerConfig:
    factory:
      id: com.hardis.adelia.ambss.rabbitmq.amqp.RabbitmqAMQPSubscriberFactory
    brokerConnection:
      password: guest
      username: guest
    subscribeTopic:
      consumerPrefetchCount: 1000
      autoAck: false
      queue:
        declarePassive: true
        name: order_event_queue

Configuration du runtime Adélia

Elle est regroupée dans les fichiers présents dans le sous-répertoire extdConfig de l'archive de l'application, à savoir :

• CfgConfiguration.properties,
• wagon.key,
• wagon.xml. Dans le cadre des programmes EADELIA, seule la configuration des virtualFileSystems est prise en compte,
• wicfgvla.ini,
• Pool.properties

Cliquez sur les liens ci-dessus pour la description de leur contenu.