subscribersConf.yml

By default, an empty subscribersConf.yml file is present in the extdConfig sub-directory of the application archive. This file in YAML format contains the description of the Adelia subscribers to execute.

This needs to be completed if we want to start subscribers statically (i.e. not via the REST create APIs).

AMBSS runtime configuration

This is grouped in the Spring boot application.yml file (and its equivalent application-dev.yml) present in the config sub-directory of the application archive. These two files contain Web Spring Boot application behavior standard properties as well as properties specific to the AMBSS.

application-dev.yml

This file is loaded when the AMBSS is started with the development profile (via the ambss-dev.bat/ambss-dev.sh command file). This profile must be used when the user is in the Adelia subscriber development phase.

With this profile, some behaviors are forced:

• JWT token authentication is disabled for the use of REST APIs,
• AMBSS Adelia runtime log level is set to DEBUG,
• Authorization to stop or restart the AMBSS with REST API.

Spring boot properties

Without describing all the available properties exhaustively (see Spring boot documentation on the subject), the following are worth noting:

• server.port: application's HTTP port number
• logging.level.ROOT: application's general log level
• logging.config: by default, log application in the standard output. A log file can be defined.

AMBSS properties

By default, the subscribersConf.yml subscriber configuration file to use must be passed in the command line when the ABMSS is started.

The 'ambss.subscribers.configuration' property is used to set a configuration file path. This path can either by absolute, or relative to the AMBSS root directory (the parent directory of the config sub-directory where the application-dev.yml file is).

The 'ambss.subscribers.writer' property is used to enable the saving of subscriber creations and changes by REST web services in the Adelia subscriber configuration file (the default value is "false"). If no subscriber configuration file is specified when the AMBSS is started, a subscribersConf.yml file is created in the AMBSS root directory (the parent directory of the config sub-directory where the application-dev.yml file is).

application.yml

This file is loaded when the AMBSS is started without a profile (via the ambss.bat/ambss.sh command file). The default profile corresponds to the production profile.

Spring boot properties

Without describing all the available properties exhaustively (see Spring boot documentation on the subject), the following are worth noting:

• server.port: application's HTTP port number
• logging.level.ROOT: application's general log level
• logging.config: by default, log application in the standard output. A log file can be defined.

AMBSS properties

By default, the subscribersConf.yml subscriber configuration file to use must be passed in the command line when the ABMSS is started.

The 'ambss.subscribers.configuration' property is used to set a configuration file path. This path can either by absolute, or relative to the AMBSS root directory (the parent directory of the config sub-directory where the application.yml file is).

The 'ambss.subscribers.writer' property is used to enable the saving of subscriber creations and changes by REST web services in the Adelia subscriber configuration file (the default value is "false"). If no subscriber configuration file is specified when the AMBSS is started, a subscribersConf.yml file is created in the AMBSS root directory (the parent directory of the config sub-directory where the application-dev.yml file is).

Enabling authentication

JWT token authentication is enabled with the 'ambss.security.enabled' property. Authentication is enabled by default.

Roles

The AMBSS defines two separate roles for REST web service permissions for use:

• A user role with permissions for use for read services (services using the HTTP GET method).
• An administrator role with permissions for use for all the services (services using HTTP GET/POST/DELETE/UPDATE methods) as well as access to the Middleware session pool administration servlet used by EADELIA programs.

The user and administrator role names can be defined using the 'ambss.security.role-names.user-role' (default value: "USER") and 'ambss.security.role-names.admin-role' (default value: "ADMIN") properties.

JWT token

The characteristics of the expected JWT token can be defined.

• The 'ambss.security.jwt.algorithm' property is used to define the token encryption algorithm ("RSA256" by default).
• The 'ambss.security.jwt.user-role-claim' property is used to define the role claim name ("roles" by default).
• The 'ambss.security.jwt.keystore-type' property is used to define the keystore type ("JKS" by default).
• The 'ambss.security.jwt.keystore-file' property is used to define the file containing the token encryption keys (default value: the "RSJwtSecurity.key" file provided by Hardis for its jwtStandalone authentication server).
• The 'ambss.security.jwt.keystore-alias' property is used to define the alias name of the file containing the token encryption keys (default value: the "jwtProviderKey" file).

Autonomous authentication server

Adelia Studio provides an AMBSS-compatible authentication server. The authentication service (or server) may be deployed autonomously.

To do this, copy the %adeliws%/javarun/jwtProviderStandAlone/jwtProviderStandAlone.war file to the ad hoc location on the application server (Tomcat for example).

Configuration

The service is configured via a file (jwtProv.properties) externalized in the form of a URL-type jndi resource via the url/jwtProv alias with a factory pointing to the com.hardis.common.JndiURLPropsFactory class.

Example:

Declaration of a URL-type jndi resource called url/jwtProv using the com.hardis.common.JndiURLPropsFactory factory.

The location of the jwtProv.properties file containing the service configuration information is set using the URL: file:///d:/extcfg/jwtProv.properties

In the installed web application sub-directory jwtProviderStandAlone, create a META-INF\context.xml file:

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

The referenced jwtProv.properties file must declare the values for the JwtProviderConfig and JwtJEELoginModule object properties as follows:

;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=

The service also requires a Keystore for token encryption. This Keystore is, in fact, externalized in the form of a URL-type jndi resource using the com.hardis.common.JndiURLFactory factory via the url/adelRSJwtSecurity alias.

Example:

Declaration of a URL-type jndi resource called url/adelRSJwtSecurity using the com.hardis.common.JndiURLPropsFactory factory.

The location of the Keystore is set using the 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>

A default Keystore (called RSJwtSecurity.key), containing the keys of the RSA256 asymmetric encryption algorithm and used to encrypt or validate a token, is delivered to the extdConfig directory of the AMBSS (%ADELIWS%\distrib\AdeliaBrokerSubscribersService) standard distribution by default.

The same Keystore must be used by the authentication service (token encryption) and the AMBSS (token validation).

The Keystore provided by default may be replaced by another Keystore which needs to be created using the following command:

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

The service then requires the users (their credentials) to be associated with the roles.

Example:

Users and roles are declared in Tomcat in the conf\tomcat-users.xml configuration file.

<?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>

Finally, the standalone authentication service requires secure transport (HTTPS) by default. Configuration must therefore be carried out in the Java EE Container to satisfy this requirement.

Creating a token

The service's role is to authenticate a user and, if the authentication is successful, deliver a JWT to them.

Using the JWT, and throughout the token's validity period, the user can authenticate him/herself with the resource server and access the resources he/she is authorized to access.

The authentication service is accessible via the Servlet called JWTServlet. The connection identifiers (credentials) are passed in the request parameters.

Example:

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

Note: The servlet can also be called using POST and be sent the connection identifiers in the body (payload) of the request, similar to an HTML form.

For obvious security reasons, the use of the HTTPS protocol is strongly recommended for accessing the JWTServlet servlet.

The authentication part offers different modules: an LDAP authentication module, a Java EE authentication module and an Adelia authentication module.

Several authentication modules can be chained.

The module(s) is/are chosen via the jwtLoginModuleName property of the JwtProviderConfig object described in the /WEB-INF/beans.xml configuration file of the application hosting the authentication service.

If the authentication module recognizes the user, the JWT creation phase begins.

This is based on:

• information returned by the authentication module (name of authenticated user, additional optional attributes relating to the user).

• Information from the JwtProviderConfig object described in the application's /WEB-INF/beans.xml configuration file.

• An encryption key needed to digitally sign the token.
  This encryption key is provided by a keystore in JKS format called RSJwtSecurity.key. The Keystore is externalized in the form of a URL-type jndi resource via the url/adelRSJwtSecurity alias using the com.hardis.common.jndiURLFactory factory.

If authentication fails, the service no longer returns a JWT but a string beginning with [ERROR] followed by an explanatory message in the body of its response.

bean-context.xml

When handling the payload of a message in an EADELIA program (onMessage block), the BRK_GET_MSG instruction is used to retrieve this data from a REF_CLASS Adelia variable.

When this data is alphanumeric or a byte array, JSON deserialization is carried out using the default converter of the third-party Jackson library.

Description

Other converters can be defined by modifying their properties in the bean-context.xml file.

The list of properties (default description and value) related to deserialization is available here: https://github.com/FasterXML/jackson-databind/wiki/Deserialization-features

A com.hardis.adelia.webservice.CustomObjectMapper-type bean needs to be declared with the properties to set (the file can contain several bean declarations, each with a different ID).

Note: On the one hand property names use "camel case" notation. On the other, "DeserializationFeature" properties are prefixed with Deser.

Example:  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>

Use

A described bean will be used by a subscriber when executing the BRK_GET_MSG instruction. To do this, the bean to use in the subscriber description must be specified via the 'config/adeliaPgm/customObjectMapper' property. This must have the bean identifier as a value.

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

Adelia runtime configuration

This is grouped in the files in the extdConfig sub-directory of the application archive, namely:

• CfgConfiguration.properties
• wagon.key
• wagon.xml. For EADELIA programs, only the virtualFileSystems configuration is taken into account.
• wicfgvla.ini
• Pool.properties

Click on the links above for a description of their content.