...

This article describes how to set up communication between Smart ID Identity Manager

...

and Smart ID Messaging. 

...

Smart ID 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 Smart ID Messaging, but they do not need to be able to reach one another. 

For more information on the architecture and interaction between Identity Manager and Smart ID clients, see Hermod architecture. 

...

Prerequisites

...

Prerequisites

The following prerequisites apply: 

• Identity Manager is installed, see Deploy Smart ID (for legacy systems, see Install Identity Manager).

• Smart ID Messaging (Hermod) is installed locally or running as a service

...

• . See Deploy Smart ID.

• Server certificates to Identity Manager and Hermod must be available, to set up an https connection. 

Step-by-step instruction

Set up integration in Smart ID Messaging

...

Add Identity Manager as client in Smart ID Messaging

Do settings in Smart ID Messaging to connect to Identity Manager over https

...

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

...

In callbackUrl, enter the Hermod callback endpoint of Identity Manager with the https scheme and corresponding https port. 

If Identity Manager shall share users with another system, for example Smart ID Digital Access component (Hybrid Access Gateway), make sure that they have the same group in the Smart ID Messaging setup.

allowedClients:     
     - clientId: prime-server1
       key: 59c2a0a1999d42dbbe7f16ef1072736a031c5f4739c04025a641ae1751849857
       group: acme
       callbackUrl: https://${hostname}:${port}/prime_explorer/ws/hermod
       callbackBasicAuth: admin:admin

In publicUrl: enter the Smart ID Messaging service endpoint, with the https scheme and corresponding https port:

...

...

.

See the instructions here: Integrate Smart ID Messaging with other Smart ID components.

Set up integration in Identity Manager

...

Log in to Identity Manager Admin

1. Log in to Identity Manager Admin.

...

Add Messaging Server in Identity Manager Admin

To set up the connection to Smart ID Messaging in Identity Manager:

1. In Identity Manager

...

1. Admin, go

...

1. to Home > Messaging Server.

2. To add a new messaging server:

...

1. 1. Click +New. Enter

...

1. 1. a Name and a Description.

...

1. 1. Click Save+Edit. 
      

...

1. 1. The Messaging Server

...

1. 1.  panel is shown.

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

...

1. 1. 1. See Add API user and callback URL in Hermod

...

1. 1. 1. Example: URL to Hermod web app

         Code Block
         https://<my-hermod-server>:<port>/hermod/rest/command

   2. In Authentication token, enter base64(

...

1. 1. client-id:key) with the values for

...

1. 1. client-id and key that were used in the new client. 

...

1. 1. Example: Authentication token

      Code Block
      cHJpbWUxOjA3OWI2YTY0ZDc1YjRlOTU4NWJkMGMyNGYzNmE3ZGViYTBhZDAzNDk4ZWNmNGQ2OWI1NzY2ZjI0ZmEwMmUwNDU=

   2. In Lifespan, enter the desired lifespan in seconds of a command to Smart ID Messaging.
      After this time, the command is removed from history and the provisioning will fail. 

   3. In Timeout, enter the desired timeout in seconds of a command to Smart ID 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.

   4. In Timeout for SessionStart, enter the desired timeout in seconds until the session with Hermod needs to be started. The value must be shorter than the timeout in step f above. The user needs to confirm a pop up to start Smart ID Desktop App. This timeout defines the wait time when the pop up is ignored or cancelled. The default value if the database is updated is 10 seconds.

2. To edit an existing identity template, double-click on its name.

Create user for Smart ID Messaging

To create a dedicated user for Smart ID Messaging:

1. In Identity Manager Admin, go to Home > User Administration.

2. Click +New. Enter a Username and a Password.

3. Click Save.

Add this user's username and password in the configuration file when adding an API user in the Smart ID Messaging component Hermod, see here: Add API user and callback URL in Hermod.

Set up HTTPS connection between Identity Manager and Smart ID Messaging

...

HTTPS connection set up

The Smart ID clients

...

Mobile and Desktop clients refuse HTTP connections. Therefore, Smart ID Messaging must be set up to listen on an HTTPS port. It is recommended to also run Identity Manager over HTTPS, even if callbacks from Smart ID Messaging to Identity Manager are also allowed over HTTP.

...

 The following instruction assumes that both Smart ID Messaging and Identity Manager run in Tomcat.

To set up HTTPS connections for Identity Manager and Smart ID 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 Smart ID Messaging:

...

1. 1. 1. callback-url: Identity Manager callback base URL for Smart ID Messaging.

...

1. 1. 1. public-url: Smart ID Messaging MS endpoint

   2. In Identity Manager: 

      1. URL: Smart ID Messaging command URL for Identity Manager.

2. 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:

...

1. 1. Example: JVM arguments in CATALINA_OPTS

      Code Block
      -Djavax.net.ssl.trustStore="C:\the\modified\cacerts" -Djavax.net.ssl.trustStorePassword="changeit"

This article is valid from PRIME 3.10.

Related information

...

Check if HTTPS connection is working and service is available

Alive check of callback URL for SmartID Messaging

To check if the callback base URL for Smart ID Messaging is set up correctly and the service is available (for Identity Manager Operator only), use the following URL:

https://[host]:[port]/idm-operator/ws/hermod/callback/alive

Response: http status, empty response body