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 see Install Hermod (docker).

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

This article includes updates for Hermod 3.6.1.

Related information

Expandall

Prerequisites

Expand

title	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

Expand

title	Download and deploy the Hermod WAR file from Nexus support portal

Sign in to Nexus Support portal.
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.
Unpack the *.zip file.
Open the extracted folder, for example, 3.x.y.RELEASE.
Navigate to cod-hermod-

war-file-*

<version>.tar and unpack it

to get Move the .war

.
Move thecod-hermod-*.war

file.

file to tomcat/webapps/hermod.war.
To deploy Hermod, start Tomcat.

Note

In case you get

If the error message "Could not resolve placeholder 'application.default-key' in value "${application.default-key}" appears when

starting

you start Hermod,

you can

solve the error by creating an environment in Tomcat for application.default-key

or do the following

or follow the instructions below:

Open the file /

wbapps

webapps/hermod/WEB-INF/classes/bootstrap.yml.
Replace the ${application.default-key) with a string of your choice.

Expand

title	Example

Code Block

language	text
title	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"

Expand

title	Store certificate files in the Hermod WAR structure

Create the cacerts and certificates sub-folders under a folder, for example, /tomcat.
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.
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.
Note
You must

include intermediate CA certificates

include intermediate CA certificates.
Add the CA certificates in the cacerts folder to the Java keystore. See the script example below.

Code Block

title	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

5. If SSL is enabled, configure the SSL certificate in the certificate folder with server.xml. For more information, see Edit server.xml.

The certificate containers are referred to from the configuration file application.yml (cod-hermod.yml). For more information, see Edit Hermod configuration below.

Expand

title	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.

Expand

title	Example

Code Block

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

Expand

title	Edit Hermod configuration

Default file path: /

wbapps

webapps/hermod/WEB-INF/classes/application.yml

Note
For more information, see Add API user and callback URL in Hermod.

Do the following to edit the Hermod configuration

if needed

:

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

Important!

The actual values must match the specific deployment scenarios. The

cod-hermod.yml

code below is only intended as an example.
Expand
title Example

Code Block
title Example

: cod-hermod.yml

logging:
  level:
    org.springframework.context.annotation.AnnotationConfigApplicationContext: ERROR
    org.springframework.boot.SpringApplication: ERROR
    org.springframework.cloud.config.client: ERROR
    com.nexusgroup: TRACE
    com.nexusgroup.plugout.message.server.filters.VersionHttpFilter: ERROR
    com.nexusgroup.cod.hermod.service.MessagePlugoutService: ERROR
    org.hibernate.engine.jdbc.spi.SqlExceptionHelper: OFF
  pattern:
    console: "%d{yyyy-MM-dd}T%d{HH:mm:ss.SSS}Z ${LOG_LEVEL_PATTERN:- %5p} [%t] %-40.40logger{39} [%mdc] : %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}"

# Enable info endpoint
management:
  info:
    env:
      enabled: true
 
server:
  ssl:
    # When you enable security below you must put a real certificate in the certificates directory
    enabled: false
    key-store: /tomcat/certificates/hermod-host-bundle.p12
    key-store-password: "PASSWORD"
    key-store-type: PKCS12


# To disable/enable apidocs/swagger-ui 
springdoc:
  override-with-generic-response: false
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

spring:
  datasource:
    ## sqlserver jdbc driver use ssl encryption by default, to disable change it to encrypt=false. For more info: https://learn.microsoft.com/en-us/sql/connect/jdbc/understanding-ssl-support?view=sql-server-ver16
    # url: jdbc:sqlserver://mydbserver:1433;database=hermod;encrypt=true
    url: jdbc:postgresql://mydbserver:5432/hermod
    # url: jdbc:mariadb://mydbserver:3306/hermod    
    username: postgres
    password: postgres@123
    ### Oracle Database example
    # For SID, use the following url
    #url: jdbc:oracle:thin:@HOST_NAME:1521:SID_NAME
    #username: USER_NAME
    #password: PASSWORD
    # For Servername, use the following url
    # url:jdbc:oracle:thin:USER_NAME/PASSWORD@HOST_NAME:1521/SERVICE_NAME
 
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
        # dialect: org.hibernate.dialect.MySQL5InnoDBDialect
        # dialect: org.hibernate.dialect.SQLServer2012Dialect
        # dialect: org.hibernate.dialect.Oracle12cDialect
    hibernate:
      ddl-auto: validate
 
application:
  hermod:
    rest:
      log: false
      # Hide exception information to clients
      hide-exceptions: true
 
    events:
      # Hide sensitive log data. 
      # This should be enabled in production since you shouldn't reveal too much information
      hide-sensitive: true
 
    # Command callback retries
    callback:
      attempts: 3
      retry-delay: 10
 
    # Hermod clients/users. Connecting clients must set X-Api-Key              
    allowed-clients:
      # Note!
      # The X-Api-Key should be created using base64(client-id:key)
      #
      # Hermod has a helper endpoint to generate configuration. Simply use (make sure you have the correct host/port)
      # curl 'http://localhost:20400/hermod/rest/util/generateclient/default'
      # to get a snippet which can be pasted to the configuration file
      #
      # X-Api-Key: ZGVmYXVsdDowZTEyYjNhMTgxYzQ0N2YxYjdkMTc0NTg1OGQ4NTgzZTE5Nzc0M2RiNTY2MzQ0N2E5Y2Q5OWI1ZDc1NDhiMThj
      - client-id: default
        key: 0e12b3a181c447f1b7d1745858d8583e197743db5663447a9cd99b5d7548b18c
        # Optional username:password to be supplied for basic authentication in callbacks
        # callback-basic-auth: username:password
        # The callback URL base for this specific client
        callback-url: http://localhost:20400/hermod/rest
      # X-Api-Key: aGVybW9kLXRlc3RhcHA6MjY5NzJkOGZhOTQxNGI4MWJmMzVjYzllNGI3YmY2NWU1MWZiYjEzNGFiMjY0MGFlYWJkM2U3N2U3ZjE0NDAwMg==
      - client-id: hermod-testapp
        key: 26972d8fa9414b81bf35cc9e4b7bf65e51fbb134ab2640aeabd3e77e7f144002
        # Optional username:password to be supplied for basic authentication in callbacks
        # callback-basic-auth: username:password
        # The callback URL base for this specific client
        callback-url: https://<my-hermod-server>:20488/hermod-testapp/rest
  
    # Message server library settings
    message-server-library:
     
      # Make sure you also change the certificates above if ssl is used
      public-url: https://<my-hermod-server>:20400/hermod/rest/ms

To change the URI base, for example, set the corresponding variable to empty

,

in the application.yml (cod-hermod.yml) configuration file:
Code Block
language text
title Set uribase to empty
application: hermod: rest: uribase: ""

Expand

title	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.

Code Block

language	text
title	Example: Hermod public URL

https://messagingservice.go.nexusgroup.com/ms

Related information

Hermod

Install Hermod test app

Add API user and callback URL in Hermod

Smart ID Messaging

Space shortcuts

Page tree

Versions Compared

Old Version 2

New Version 3

Key

Related information

Prerequisites

Step-by-step instruction

Related information

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 2

New Version 3

Key

Related information

Prerequisites

Step-by-step instruction

Related information