General information

In both start modes (command scripts and Windows service), you can set your own FreeMarker/FOP engine configuration as well as your own APE runtime configuration:

• Using -Dcom.hardis.adelia.mergedocengine.freemarker.conf and -Dcom.hardis.adelia.transformxslfoengine.fop.conf parameters to specify the Apache FreeMarker configuration file and the Apache FOP configuration file respectively. If one or more of these parameters are missing, the configuration files in the "config" sub-directory (config/freemarker.properties and config/xfop.conf) are used by default.
• Using the configuration files application-prod.yml and application-dev.yml (found in the "config" sub-directory) to externalise the configuration of the Spring Boot Adelia Print Engine application (log level, listening port, security level, etc.) as well as the configuration of the APE runtime.

Execution modes

The APE can be started using two execution modes:

• dev (developer) mode: used when developing/fine tuning templates,
• prod (production) mode: used during the operational execution of the document creation engine.

These two modes are different in the Spring Boot Adelia Print Engine application configuration and the APE runtime (but use the same default FreeMarker/FOP engine configuration).

Dev mode

This mode is enabled when starting the APE via the ape-dev.bat/ape-dev.sh command scripts. It must be used when the user is in the template development phase. This mode uses the config/application-dev.yml configuration file (configuration file in YAML format).

With this profile, some behaviors are set by default:

• HTTP port of the application set to "8080" (server.port property),
• Application log level set to "INFO" (logging.level.ROOT property),
• Application trace logging is displayed in the console (logging.config property),
• No authentication mechanism when calling Web services proposed by the REST API.

See Spring Boot documentation for more details.

Prod mode

This mode is enabled when starting the APE via the ape-prod.bat/ape-prod.sh command scripts. It must be used when the user wants to execute the APE in production. This mode uses the config/application-prod.yml configuration file (configuration file in YAML format).

With this profile, some behaviors are set by default:

• HTTP port of the application set to "8080" (server.port property),
• Application log level set to "WARN" (logging.level.ROOT property),
• Application trace logging is displayed in the console (logging.config property),
• JWT authentication is enabled for the use of REST APIs (ape.security.enabled property).

See Spring Boot documentation for more details.

Enabling SSL/HTTPS

The use of a certificate-based secure connection to access the APE's web services can be made mandatory. To do this, you need to set the server.ssl.enabled property to "true" and enter the underlying properties to describe the authentication certificate characteristics.

Note: The server.ssl.key-store property represents the file path of the keystore containing the certificate. This path may be absolute or relative (to the parent directory of the "config" sub-directory). Below are two examples of syntax:

• file:///C:/certificates/ape_https.p12,
• file:./config/ape_https.jks

Enabling authentication

Authentication is a mechanism for authorizing the call to the Web services proposed by the REST API to the identified users only. In this case, calls to a Web service by an anonymous or unauthenticated user are rejected (HTTP 403 code returned).

JWT authentication is enabled with the ape.security.enabled property. Authentication is enabled by default. This can work equally well in HTTP and HTTPS.

Note: for users who are not interested in APE Web services authentication, simply disable it by setting the ape.security.enabled property to "false" in the application-prod.yml configuration file.

Roles

The APE manages access to mergedoc and mergeandtransform Web services more precisely by also managing the execution authorization for a specific template using roles. A role (character string) is a standardized JWT property which symbolizes one or more permissions for use (according to the defined security policy). In the APE context, a role defines an access permission to a resource: a template. The APE offers a mechanism for associating a template (defined by its path which is comprised of its namespace and name) with a list of roles. This path is deduced from the JSON information provided as an input when calling Web services:

• via the namespace and templateName attributes for the Web service mergedoc,
• via the merge.namespace and merge.templateName attributes for the Web service mergeandtransform.

So, if the user requests access to a template (via an authenticated request - i.e. possessing a valid JWT) for which the path is present in the association, its access will be authorized only if one of the JWT roles provided is in the list of roles associated with the path.

The path/list association is defined via the ape.security.template-role-map property: it takes the form of a map in YAML format and enables keys (a path) to be associated with a list of values (a list of roles).

The path expression takes the form of a generic expression used to describe one or more paths: one or more paths can therefore be associated with a list of roles.

The paths can be expressed using two different syntaxes:

• either via a regular expression. in this case, the syntax is "[regex:<regular expression validating one or more paths>]",
• or via a "glob pattern". In this case, the syntax is "[glob:<glob pattern validating one or more paths>]",

Example: The following template architecture, storing printouts of two companies: my.company1 and my.company2.

In this case, several roles were defined providing access to the templates in the following way:

• the COMPANY2_ALL_DOCS role allows access to all my.company2 documents, i.e. my/company2/brochure.ftlx and my/company2/logistics/delivery.ftlx template paths,
• the COMPANY1_STOCK role allows access to the my.company1 production department document stock, i.e. the my/company1/production/stock.ftlx template path,
• the COMPANY1_FINANCE_MARKETING role allows access to all finance and marketing department documents, i.e. my/company1/finance/report.ftlx and my/company1/marketing/campaign.ftlx template paths,
• the COMPANY1_RESEARCH_CONSULTING_A_B role allows access to the consulting department's customerA and customerB prospect documents, i.e. my/company1/consulting/customerA.ftlx, my/company1/consulting/customerB.ftlx, my/company1/research/prototype.ftlx and my/company1/research/projectX/planning.ftlx template paths,
• the COMPANY1_CONSULTING_ALL_BUT_A_B role allows access to the consulting department's documents for prospects other than customerA and customerB, i.e. my/company1/consulting/customerC.ftlx and my/company1/consulting/customerCbis.ftlx template paths.

The integration of roles in the APE results in the definition of a role and template path expression association via the ape.security.template-role-map property in the application-prod.yml file as follows:

ape:
  template-role-map:
    "[glob:my/company2/**]" : [COMPANY2_ALL_DOCS]
    "[glob:my/company1/production/stock.ftlx]": [COMPANY1_STOCK]
    "[glob:my/company1/{finance,marketing}/*.*]": [COMPANY1_FINANCE_MARKETING]
    "[glob:my/company1/consulting/customer[AB].ftlx]": [COMPANY1_RESEARCH_CONSULTING_A_B]
    "[glob:my/company1/research/**]": [COMPANY1_RESEARCH_CONSULTING_A_B]
    "[glob:my/company1/consulting/customer[!AB]*.ftlx]": [COMPANY1_CONSULTING_ALL_BUT_A_B]

ape:
  template-role-map:
    "[regex:my/company2/((?:[^/]*(?:/|$))*)]" : [COMPANY2_ALL_DOCS]
    "[regex:my/company1/production/stock.ftlx]": [COMPANY1_STOCK]
    "[regex:my/company1/(finance|marketing)/([^/]*)\\.([^/]*)]": [COMPANY1_FINANCE_MARKETING]
    "[regex:my/company1/consulting/customer[AB]\\.ftlx]": [COMPANY1_RESEARCH_CONSULTING_A_B]
    "[regex:my/company1/research/((?:[^/]*(?:/|$))*)]": [COMPANY1_RESEARCH_CONSULTING_A_B]
    "[regex:my/company1/consulting/customer[^AB]([^/]*)\\.ftlx]": [COMPANY1_CONSULTING_ALL_BUT_A_B]

JWT token

The APE offers two JWT validation modes:

• Validation using a public key: you have the public key (in the form of a certificate) which is paired with the private key which encrypted the JWT signature,
• Validation using a JWK (JSON Web Key) contained in a JWKS (JWK Set): the token has two additional claims, "kid" and "iss", which are used to retrieve the public key paired with the private key which encrypted the JWT signature.

Validation using a public key

The characteristics of the expected JWT token can be defined.

• The ape.security.jwt.algorithm property allows the token encryption algorithm to be defined ("RSA256" by default).
• The ape.security.jwt.user-role-claim property allows the role claim name to be defined ("roles" by default).
• The ape.security.jwt.keystore-type property allows the keystore type to be defined ("JKS" by default).
• The 'ape.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 'ape.security.jwt.keystore-alias is used to define the alias name of the file containing the token encryption keys (default value: the "jwtProviderKey" file).

Validation using a JWK

The characteristics of the retrieval mechanism of the JWKs containing the public keys can be defined.

• The ape.security.jwks.trusted-issuers-list property defines the list of one or more trusted issuers in the form of one or more URIs. To search for the JWK associated with the JWT, the token's "iss" claim must be included in the list of trusted issuers.
• The ape.security.jwks.connect-timeout property is used to define the maximum wait time in milliseconds for connections to URI and JWK URI issuers (-1 by default: infinite wait time).
• The ape.security.jwks.read-timeout property is used to define the maximum wait time in milliseconds to read the content of connections to URI and JWK URI issuers (-1 by default: infinite wait time).
• The ape.security.jwk-cache-size property is used to define the JWK cache size (5 by default).
• The ape.security.jwk-expires-in property is used to define the maximum time for caching a JWK. This time is expressed in the form of an alphanumeric string in ISO-8601 time format ("PT10H" by default: 10 hours).
• If token signature validation fails, the ape.security.retry-on-error property is used to retry the validation process by reloading the URI issuer and the JWKs, and by creating new caches ("true" by default).

Autonomous authentication server

Adelia Studio provides an APE-compatible authentication server. This 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 jwtProviderStandAloneweb application sub-directory, 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 config directory of the APE standard distribution by default (%ADELIWS%\distrib\AdeliaPrintEngine).

The same Keystore must be used by the authentication service (token encryption) and the APE (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 (validated by the APE using the public key validation mode).

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.

↑ Top of page

Managing command scripts

The scripts are in the "bin" sub-directory used to start the APE. You need to use ape-XXX.bat scripts in Windows and ape-XXX.sh scripts in Linux.

Note: In Linux, the scripts provided are not directly executable. Therefore, you need to either add the executable attribute via chmod +x ape-XXX.sh to them or run them via the "bash ./ape-XXX.sh" command.

Use the "-h"n option, such as ape-dev.bat -h, to display the help for these command scripts. In addition, you can set your own FreeMarker/FOP engine configuration for these four scripts:

• by using the -Dcom.hardis.adelia.mergedocengine.freemarker.conf="<path_to_directory_conf>" option at script start, where "path_to_directory_conf" is a path to a directory containing the FreeMarker freemarker.properties configuration file (quotation marks for paths with spaces),
• by using the - Dcom.hardis.adelia.transformxslfoengine.fop.conf="<path_to_directory_conf> >" option at script start, where "path_to_directory_conf" is a path to a directory containing the Apache FOP fop.xconf configuration file (quotation marks for paths with spaces),
• by not specifying either of the options described above. In this case, the configuration files in the "config" directory are used.

For example, the listening port of the Spring Boot application itself can be changed in the command line via the "-Dserver.port=<port_number>" option, where "port_number" is the HTTP port number defined for the J2EE application. The default value is 8080 and it is defined in the associated configuration file config/application-XXX.yml.

You need to use theapeService.bat script to launch the application as a Windows service.

↑ Top of page

Windows service management

Automatically enables prod mode.

The apeService.bat script is used to install, uninstall, start and stop the APE application as a Windows service. This script must be run in a DOS command window run as administrator.

To make the service operational, it needs to be installed then started. Run the apeService.bat command without parameters to see the available options:

• install : Application installation command. It is during this stage that we can specify configuration files other than the default ones.
• start : Application start command,
• stop : Application stop command,
• uninstall : Application uninstall command (with automatic stop of the application before uninstalling).

Note that the APE started in service mode is run in prod (for production) execution mode.

In addition, by default, the application uses the configuration files (freemarker.properties and fop.xconf) in the "..\config" sub-directory (in relation to the bin directory containing the apeService.bat script).

To specify another directory containing the configuration files, use the installation options like:

apeService.bat "my ape service" -install -JVMoptions "-Dcom.hardis.adelia.mergedocengine.freemarker.conf=c:\my conf dir" "-Dcom.hardis.adelia.transformxslfoengine.fop.conf=c:\my conf dir"

By default, two logging files (containing the console's output and error logs) called <service name>_out.log and <service name>_err.log are created in the "bin sub-directory (containing the apeService.bat script).

↑ Top of page