Page tree
Skip to end of metadata
Go to start of metadata

This article describes how to set up communication between PRIME and Personal Messaging. 

Nexus Personal Messaging is a messaging platform used within Nexus Smart ID to integrate clients into server side processes, via indirect communication. All clients and servers must be able to reach Personal Messaging, but they do not need to be able to reach one another. 

For more information on the architecture and interaction between PRIME and Personal, see Hermod architecture

Expand/Collapse All

Prerequisites

 Prerequisites

The following prerequisites apply: 

  • PRIME is installed, see Install PRIME.
  • Personal Messaging (Hermod) is installed locally or running as a service, see Install Hermod.
  • Server certificates to PRIME and Hermod must be available, to set up an https connection. 

Step-by-step instruction

Set up integration in Personal Messaging

 Add PRIME as client in Personal Messaging

Do settings in Personal Messaging to connect to PRIME over https: 

  1. To set up PRIME as a client, add PRIME as an API user and select a callback URL, according to Add API user and callback URL in Hermod. Do the following settings:

    1. In callbackUrl, enter the Hermod callback endpoint of PRIME Explorer, with the https scheme and corresponding https port

    2. If PRIME shall share users with another system, for example Nexus Hybrid Access Gateway, make sure that they have the same group in the Personal Messaging setup.

      Example: Set up PRIME as client in Personal Messaging
      allowedClients:     
           - clientId: prime-server1
             key: 59c2a0a1999d42dbbe7f16ef1072736a031c5f4739c04025a641ae1751849857
             group: acme
             callbackUrl: https://${hostname}:${port}/prime_explorer/ws/hermod
             callbackBasicAuth: admin:admin
  2. In publicUrl: enter the Personal Messaging service endpoint, with the https scheme and corresponding https port:

    Example: publicUrl
    https://hermod-server-url:28443/hermod/rest/ms

Set up integration in PRIME

 Log in to PRIME Designer as admin
  1. Log into PRIME Designer as an admin user.
 Add Messaging Server in PRIME Designer

To set up the connection to Personal Messaging in PRIME:

  1. In PRIME Designer, go to Home > Messaging Server.

  2. To add a new messaging server:

    1. Click +New. Enter a Name and a Description.

    2. Click Save+Edit. 
      The Messaging Server panel is shown.

    3. In URL, enter the URL of the messaging server ending with command. The example assumes it is deployed as the web app Hermod

      1. Set the scheme to HTTPS and the port to the port number used by Hermod for callbacks. See Add API user and callback URL in Hermod

        Example: URL to Hermod web app
        https://<my-hermod-server>:<port>/hermod/rest/command
    4. In Authentication token, enter base64(clientId:key) with the values for clientId and key that were used in the new client. 

      Example: Authentication token
      cHJpbWUxOjA3OWI2YTY0ZDc1YjRlOTU4NWJkMGMyNGYzNmE3ZGViYTBhZDAzNDk4ZWNmNGQ2OWI1NzY2ZjI0ZmEwMmUwNDU=
    5. In Lifespan, enter the desired lifespan in seconds of a command to Personal Messaging.
      After this time, the command is removed from history and the provisioning will fail. 
    6. In Timeout, enter the desired timeout in seconds of a command to Personal Messaging. The timeout must be shorter than the lifespan.
      After this time, the command is removed from the message box, but kept for polling until the lifespan is reached.
  3. To edit an existing identity template, double-click on its name.

Set up HTTPS connection between PRIME and Personal Messaging

 HTTPS connection set up

The Nexus Personal Mobile and Desktop clients refuse HTTP connections. Therefore, Personal Messaging must be set up to listen on an HTTPS port. It is recommended to also run PRIME over HTTPS, even if callbacks from Personal Messaging to PRIME are also allowed over HTTP. The following instruction assumes that both Personal Messaging and PRIME run in Tomcat.

To set up HTTPS connections for PRIME and Personal Messaging: 

  1. Set up HTTPS ports in the file server.xml in the respective Tomcat installation. 
  2. Make sure that the following URLs have the HTTPS scheme and ports for HTTPS, as described above:
    1. In Personal Messaging:
      1. callbackUrl: PRIME callback base URL for Personal Messaging.
      2. publicUrl: Personal Messaging MS endpoint
    2. In PRIME: 
      1. URL: Personal Messaging command URL for PRIME.
  3. Configure cacerts with the new CA certificate:
    1. Copy the file jre\lib\security\cacerts of the JVM and store it somewhere, for example in C:\the\modified\cacerts
    2. Import the new CA certificate in the new cacerts file. 
    3. Set the cacerts as JVM arguments of each Tomcat, for example, by setting the CATALINA_OPTS environment variable:

      Example: JVM arguments in CATALINA_OPTS
      -Djavax.net.ssl.trustStore="C:\the\modified\cacerts" -Djavax.net.ssl.trustStorePassword="changeit"

This article is valid from PRIME 3.10.

Related information