Document toolboxDocument toolbox

Install Hermod (WAR file)

This article includes updates for Hermod 3.6.1.

This article describes how to install the Smart ID Messaging component Hermod as a WAR file.

For information about how to install Hermod as a docker image, see Install Hermod (docker).

From Hermod version 3.5.0, Swagger is enabled by default in the configuration. See "Edit Hermod configuration" below, for an example on how to enable and disable Swagger.

Prerequisites

  • JDK 17

  • Tomcat version 10 or later

  • A Linux host, Windows, or Mac

  • A public DNS name which devices can reach

  • Matching certificates for the public address

  • An installed instance of an SQL server, for example, PostgreSQL, Microsoft SQL Server, Maria DB, or Oracle

Step-by-step instruction

Download and deploy the Hermod WAR file from Nexus support portal

  1. Sign in to Nexus Support portal.

  2. Go to Nexus Smart ID Clients (Personal and Hermod) > Smart ID Messaging  and select Hermod version 3.6.1 or later to download the *.zip file.

  3. Unpack the *.zip file.

  4. Open the extracted folder, for example, 3.x.y.RELEASE.

  5. Navigate to cod-hermod-<version>.tar and unpack it.

  6. Move the cod-hermod-*.war file to tomcat/webapps/hermod.war.

  7. To deploy Hermod, start Tomcat.

Error message when starting Hermod

If the error message "Could not resolve placeholder 'application.default-key' in value "${application.default-key}" appears when you start Hermod, solve the error by creating an environment in Tomcat for application.default-key or follow the instructions below:

  1. Open the file /webapps/hermod/WEB-INF/classes/bootstrap.yml.

  2. Replace the ${application.default-key) with a string of your choice.

Example

Set uribase to empty
spring: application: name: hermod cloud: # Where is the configuration server located? config: enabled: false name: cod-hermod uri: http://localhost:20000 # Don't start if we can't reach the configuration server fail-fast: true discovery: client: composite-indicator: enabled: false info: id: ${spring.application.name}.${application.uuid} encrypt: key: "JM]pE^@SM89%MGF]h@Np3HF]h@Np3H4S\\xpeJM]pE^@SM89%MGF]h@Np3HLS\\xpeASLKJSSDSD"

Store certificate files in the Hermod WAR structure

  1. Create the cacerts and certificates sub-folders under a folder, for example, /tomcat

  2. Put one or multiple CA certificates in base64 format with the .cer file extension in the folder tomcat/cacerts. The file name cannot contain spaces. 

  3. Put one or multiple certificate containers, including the whole certificate chain with any intermediate CA certificates, in pkcs#12 format (with a .pfx or .p12 extension) in the folder tomcat/certificates. The file name cannot contain spaces. 

You must include intermediate CA certificates.

  1. Add the CA certificates in the cacerts folder to the Java keystore. See the script example below.
    Example: Add certificates to Java keystore

# Check if the user has mapped a certificate path from the host MAPPED_PATH="/cacerts" if [ -d "${MAPPED_PATH}" ]; then cd ${JAVA_HOME}/lib/security SUDO=$(which sudo) # Import each found *.cer in the mapped path to the Java keystore for CERT in `ls ${MAPPED_PATH}/*.cer 2>/dev/null`; do ALIAS=$(basename ${CERT} .cer | tr [A-Z] [a-z]) echo "Adding certificate ${CERT} using alias ${ALIAS}" ${SUDO} keytool -noprompt -storepass changeit -keystore cacerts -delete -alias ${ALIAS} > /dev/null 2>&1 ${SUDO} keytool -noprompt -storepass changeit -keystore cacerts -importcert -trustcacerts -alias ${ALIAS} -file "${CERT}" > /dev/null 2>&1 if [ $? -ne 0 ]; then echo "ERROR: Could not add ${ALIAS} to keystore" fi done cd - > /dev/null 2>&1 fi
  1. If SSL is enabled, configure the SSL certificate in the certificate folder with server.xml. For more information, seeEdit server.xml.

The certificate containers are referred to from the configuration file application.yml. For more information, see “Edit Hermod configuration” below.

Edit server.xml

Edit the server.xml file. You can modify the location for CA certificates, IP address, port number, and more. The default file path is: /tomcat/server.xml

Example: server.xml
<?xml version="1.0" encoding="UTF-8"?> <!-- 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. --> <!-- Note: A "Server" is not itself a "Container", so you may not define subcomponents such as "Valves" at this level. Documentation at /docs/config/server.html --> <Server port="8005" shutdown="SHUTDOWN"> <Listener className="org.apache.catalina.startup.VersionLoggerListener" /> <!-- Security listener. Documentation at /docs/config/listeners.html <Listener className="org.apache.catalina.security.SecurityListener" /> --> <!--APR library loader. Documentation at /docs/apr.html --> <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /> <!-- Prevent memory leaks due to use of particular java/javax APIs--> <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" /> <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" /> <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" /> <!-- Global JNDI resources Documentation at /docs/jndi-resources-howto.html --> <GlobalNamingResources> <!-- Editable user database that can also be used by UserDatabaseRealm to authenticate users --> <Resource name="UserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="User database that can be updated and saved" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="conf/tomcat-users.xml" /> </GlobalNamingResources> <!-- A "Service" is a collection of one or more "Connectors" that share a single "Container" Note: A "Service" is not itself a "Container", so you may not define subcomponents such as "Valves" at this level. Documentation at /docs/config/service.html --> <Service name="Catalina"> <!--The connectors can use a shared executor, you can define one or more named thread pools--> <!-- <Executor name="tomcatThreadPool" namePrefix="catalina-exec-" maxThreads="150" minSpareThreads="4"/> --> <!-- A "Connector" represents an endpoint by which requests are received and responses are returned. Documentation at : Java HTTP Connector: /docs/config/http.html Java AJP Connector: /docs/config/ajp.html APR (HTTP/AJP) Connector: /docs/apr.html Define a non-SSL/TLS HTTP/1.1 Connector on port 8080 --> <Connector port="20400" protocol="HTTP/1.1" connectionTimeout="20000" Server=" " Secure="true" redirectPort="8443" /> SSL_COMMENT_IN <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" defaultSSLHostConfigName="localhost" > <SSLHostConfig hostName="localhost" protocols="all"> <Certificate certificateKeystoreFile="/certificates/SSL_CERT_NAME" certificateKeystorePassword="SSL_CERT_PWD" certificateKeystoreType="PKCS12"> </Certificate> </SSLHostConfig> </Connector> SSL_COMMENT_OUT <!-- A "Connector" using the shared thread pool--> <!-- <Connector executor="tomcatThreadPool" port="20400" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /> --> <!-- Define a SSL/TLS HTTP/1.1 Connector on port 8443 This connector uses the NIO implementation. The default SSLImplementation will depend on the presence of the APR/native library and the useOpenSSL attribute of the AprLifecycleListener. Either JSSE or OpenSSL style configuration may be used regardless of the SSLImplementation selected. JSSE style configuration is used below. --> <!-- <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true"> <SSLHostConfig> <Certificate certificateKeystoreFile="conf/localhost-rsa.jks" type="RSA" /> </SSLHostConfig> </Connector> --> <!-- Define a SSL/TLS HTTP/1.1 Connector on port 8443 with HTTP/2 This connector uses the APR/native implementation which always uses OpenSSL for TLS. Either JSSE or OpenSSL style configuration may be used. OpenSSL style configuration is used below. --> <!-- <Connector port="8443" protocol="org.apache.coyote.http11.Http11AprProtocol" maxThreads="150" SSLEnabled="true" > <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" /> <SSLHostConfig> <Certificate certificateKeyFile="conf/localhost-rsa-key.pem" certificateFile="conf/localhost-rsa-cert.pem" certificateChainFile="conf/localhost-rsa-chain.pem" type="RSA" /> </SSLHostConfig> </Connector> --> <!-- Define an AJP 1.3 Connector on port 8009 --> <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" secretRequired = "false" /> <!-- An Engine represents the entry point (within Catalina) that processes every request. The Engine implementation for Tomcat stand alone analyzes the HTTP headers included with the request, and passes them on to the appropriate Host (virtual host). Documentation at /docs/config/engine.html --> <!-- You should set jvmRoute to support load-balancing via AJP ie : <Engine name="Catalina" defaultHost="localhost" jvmRoute="jvm1"> --> <Engine name="Catalina" defaultHost="localhost"> <!--For clustering, please take a look at documentation at: /docs/cluster-howto.html (simple how to) /docs/config/cluster.html (reference documentation) --> <!-- <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/> --> <!-- Use the LockOutRealm to prevent attempts to guess user passwords via a brute-force attack --> <Realm className="org.apache.catalina.realm.LockOutRealm"> <!-- This Realm uses the UserDatabase configured in the global JNDI resources under the key "UserDatabase". Any edits that are performed against this UserDatabase are immediately available for use by the Realm. --> <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/> </Realm> <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true"> <!-- SingleSignOn valve, share authentication between web applications Documentation at: /docs/config/valve.html --> <!-- <Valve className="org.apache.catalina.authenticator.SingleSignOn" /> --> <!-- Access log processes all example. Documentation at: /docs/config/valve.html Note: The pattern used is equivalent to using pattern="common" --> <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log" suffix=".txt" pattern="%h %l %u %t "%r" %s %b" /> </Host> </Engine> </Service> </Server>

Edit Hermod configuration

Default file path: /webapps/hermod/WEB-INF/classes/application.yml

Do the following to edit the Hermod configuration:

  1. Edit the configuration file application.yml with the correct values for your environment.

  1. To change the URI base, for example, set the corresponding variable to empty in the application.yml configuration file:

Set uribase to empty

 

Verify SSL certificate of Hermod public URL

Make sure that the public URL that has been configured in the Hermod configuration file and that it has a valid and trusted SSL certificate. To verify this, open the Hermod public URL in a browser and make sure the connection is secure, by viewing the padlock in the browser bar. See an example above.

Example: Hermod public URL

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions