Versions Compared

Old Version 2

changes.mady.by.user Ann Base

Saved on

compared with

New Version 3

changes.mady.by.user Karolin Hemmingsson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: updated to clarify and align

This article describes how to set up virtual smart card management in Nexus Smart ID Identity Manager (PRIME), by integrating PRIME to Nexus Smart ID Desktop App (Personal Desktop App and Hermod) and Nexus Personal Messaging. 



Prerequisites

Expand
titlePrerequisites

The following prerequisites apply:

Step-by-step instruction

PRIME and Hermod must trust each other's respective certificate.

Make sure that Hermod and PRIME trust each other's certificates, in either of the following ways:
  • The Java Virtual Machines (JVMs) that are used by PRIME and Hermod have valid SSL certificates.
  • In case of self-signed certificates, that PRIME and Hermod have each other's certificates in their cacerts file.

    • The cacerts content is passed as JVM arguments to the respective Tomcat, for example via CATALINA_OPTS:

    Expand
    titleConfigure server certificates
    Code Block
    titleAlternative: JVM arguments to Tomcat
    -Djavax.net.ssl.trustStore="C:\the\modified\cacerts" 
-Djavax.net.ssl.trustStorePassword="changeit"
    Expand
    titleConfigure Hermod callback to PRIME

    To configure the Hermod callback to PRIME:

    In the Hermod installation, open cod-hermod.yml and configure the callback to PRIME. For more information, see Install Hermod. Do the following settings:
  • In datasource: enter the details for your database. The database must be empty and initialized using scripts from the Hermod distribution. Use the script with the highest version number.
  • In X-Api-Key: enter a valid key.
    For more information, see Add API user and callback URL in Hermod

    • In callbackUrl: enter the Hermod callback endpoint of PRIME Explorer, for example:

    Code Block
    titleExample: callbackUrl
    https://prime-server-url:18443/prime_explorer/ws/hermod

    In publicUrl: enter the Hermod REST service endpoint, for example:

    Code Block
    titleExample: publicUrl
    https://hermod-server-url:28443/hermod/rest/ms
    Code Block
    titleExample: webapps\hermod\WEB-INF\classes\cod-hermod.yml
    ...
application:
  hermod:
    rest:
      log: false
      # Hide exception information to clients
      hideExceptions: true
    # Command callback retries
    callback:
      attempts: 1
      retryDelay: 30
    # Hermod clients/users. Connecting clients must set X-Api-Key            
    allowedClients:
      # Note!
      # The X-Api-Key should be created using base64(clientId:key)
      #
      # Hermod has a helper endpoint to generate configuration. 
      # Simply use (make sure you have the correct host/port)
      # curl 'http://localhost:18080/hermod/rest/util/generateclient/default'
      # to get a snippet which can be pasted to the configuration file
      # X-Api-Key: aGVybW9kLXRlc3RhcHA6NTljMmEwYTE5OTlkNDJkYmJlN2YxNmVmMTA3MjczNmEwMzFjNWY0NzM5...
      - clientId: hermod-app
        key: 59c2a0a1999d42dbbe7f16ef1072736a031c5f4739c04025a641ae1751849857
        group: acme
        # The callback URL base for this specific client
        callbackUrl: https://prime-server-url:18443/prime_explorer/ws/hermod
        callbackBasicAuth: primeuser:primeuserpw   
...
    Expand
    titleConfigure Hermod connection in PRIME

    To configure the connection to Hermod, do the following settings in PRIME:

    1. Open the system properties file for PRIME Explorer: \prime_explorer\WEB-INFclasses\system.properties
    2. Do the following settings:
      1. In authenticationToken, enter the X-API-Key from the Hermod configuration.
      2. Optionally, set provisionCallback.deviceNameField to override the default field into which the device name is stored by the provisioning callback.
        Personal Desktop App returns the configured computer name as deviceName instead of just a generic name. This is only for information, and not a unique identifier.
    Code Block
    titleExample: PRIME Explorer system.properties
    hermod.url=https://hermod-server-url:28443/hermod
hermod.authenticationToken=aGVybW9kLXRlc3RhcHA6NTljMmEwYTE5OTlkNDJkYmJlN2YxNmVmMTA3MjczNmEwMzFjNWY0NzM5YzA0MDI1YTY0MWFlMTc1MTg0OTg1Nw==
 
#set processmap field into which to save the device name after profile provisioning through Hermod,
#defaults to "deviceName" if not explicitly set
# provisionCallback.deviceNameField=deviceName
    Integrate PRIME with Personal Messaging
    1. Set up communication between PRIME and Personal Messaging over HTTPS. See Integrate Identity Manager with Smart ID Messaging.  

    Troubleshooting

    Note

    Popups must be allowed for the running PRIME server to be able to call the Personal Desktop App plugout URL. Most browsers block them by default and show a very subtle hint that a popup was blocked.

    If the Personal Desktop App plugout URL is not called, check your browser's URL bar for any indication about blocked popups and add an exception.


    Expand
    titleTroubleshooting

    To troubleshoot Personal Desktop App, consult the logfile. Here are some common errors and suggestions how to fix them:

    Virtual smart card creation failed - Insufficient resources

    Error: Virtual Smart Card creation failed! --> System.Exception: The target device has insufficient resources to complete the operation. (Exception from HRESULT: 0x80070142)

    Solution: Remove some virtual smart cards and try again.

    Virtual smart card creation failed - Operation requires elevation

    Error: Virtual Smart Card creation failed! --> System.Exception: The requested operation requires elevation. (Exception from HRESULT: 0x800702E4)

    Solution: Make sure you follow the prerequisites listed above. Login as administrator and try again.

    Domain mismatch

    Error: Domain mismatch error message

    Solution: Make sure you use HTTPS for PRIME and Hermod

    Personal Desktop App crashes

    Error: Personal Desktop App crashes

    Solution: Update Windows



    This article is valid from PRIME 3.9. 

    Related information