This article describes how to add a new API user in Hermod to get a unique API key for authentication to the API.

Step-by-step instruction

Edit configuration file for Hermod docker image

To configure Hermod, do the following:

1. Open Hermod Config file. 

   1. Navigate to the top-level directory where docker-compose.yml is located. The configuration file should then be found in a config/ directory.

      Example: File structure

      mydir/ 
      |-- cacerts 
      |-- certificates 
      |-- config 
      | 
      |-- application.yml -> cod-hermod.yml 
      | `-- cod-hermod.yml 
      `-- docker-compose.yml

   2. Open the configuration file for editing.

      Example: Command to edit configuration file

      vi config/cod-hermod.yml

Edit configuration file for Hermod WAR file

1. Navigate to and open for editing application.yml.
   Default file path: /wbapps/hermod/WEB-INF/classes/application.yml 

2. Open a browser and go to the following URL, using a unique <myclientid>:

   Example: Generate client URL

   http://localhost:20400/<contextPath>/<uriBase>/util/generateclient/<myclientid>
   
   The default value for /<contextPath>/<uriBase> is /hermod/rest

   
   Find port number

   All requests below are triggered from the host itself, thus localhost is used.

   The port number (20400 in the example above) might have been assigned a different value. To find out the current port number, do the following:
   For docker:
   Type the command

   docker ps | grep hermod_hermod

   For tomcat:
   Check server.xml

3. Copy the content from the resulting web page and paste it into the allowed-clients section of the configuration file. 

Example: Generate client

# X-Api-Key: a2Fyb2xpbjpmZDA0ZGUyZjFlNTU0NGIyOTE1ZDFhNjUwOThjNDkwNjM3YTA3MTVmNWM5ODQzNDU5ZjA1ZGZjMjk4MzQyOTM2 
- client-id: <myclientid> 
    key: fd04de2f1e5544b2915d1a65098c490637a0715f5c9843459f05dfc298342936
    # 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

4. Edit callback-url to receive the callbacks from the Hermod API.
   Also edit username and password if the callback URL requires basic authentication.

5. Optional - If visual data is to be fetched from an external content provider:

   1. Configure content-provider-url to point to the Content provider API.

   2. Also edit user and pwd if the content provider requires basic authentication.

          # Optional: username and password to be supplied for basic authentication to the content provider
          content-provider-basic-auth: user:pwd
          # Optional: The URL to the content provider API
          # When Identity Manager is used as content provider, the URL will look like this: https://<IDM-OPERATOR>/ws/hermod/contentprovider/getcontent
          content-provider-url: https://myprovider/getcontent

6. Save and exit the configuration file.

Refresh configuration and test API key

1. Refresh the configuration:

   Example: Refresh configuration

   curl -X POST http://localhost:20400/<contextPath>/refresh

2. Test the new key by sending a request using curl (set THE-NEW-KEY below):
   
   Example: Test API key

   curl -w%{http_code} -X POST \
     http://localhost:20400/<contextPath>/<uriBase>/command/ping \
     -H 'cache-control: no-cache' \
     -H 'content-type: application/json' \
     -H 'x-api-key: THE-NEW-KEY' \
     -d '{
     "commandHeader" : {
       "to": ["api-test"]
     }
   }'

3. Check the response.

   1. If you get a 403 response, you have the wrong API key.

   2. If you get a 404 response, then you have the correct API key. A 404 response means that the user api-test isn't found, which is expected at this point.