How to add monitoring of service and external dependencies

This PhenixID Solution Document (PSD) is written for PhenixID Server.

This article describes how to add monitoring to PhenixID Server. This is useful for surveillance tools, such as load balancers, to make sure PhenixID Server is running with all external dependencies intact (such as LDAP connectivity).

The reader should have some basic knowledge about PhenixID Server.

Overview

Monitoring will be setup as a function that can be called upon by surveillance tools using HTTP GET. 

Follow the steps below to set it up.

Instruction

We will make changes to the file config/phenix-store.json, so please make sure that you have a recent copy/backup of this file.

Login to PhenixID Configuration Manager.

Click on the Tab “Advanced”.

Click on the pencil beside “Modules”.

Locate the pipes module.

Add the parameters in bold. Change http_configuration_ref value to suite your environment. 

 {
    "name" : "com.phenixidentity~phenix-pipes",
    "scope" : "global",
    "singleton" : "true",
    "config" : {
      "http_enabled" : "true",
      "http_configuration_ref" : "https"
    },
    "enabled" : "true",
    "created" : "2018-05-24T05:41:41.516Z",
    "id" : "ce28bf7c-a641-44ca-82ca-3bf658881f4a"
  }

When done press "Stage changes" and then "Commit changes".

Click on the Tab “Advanced”.

Click on the pencil beside “Pipes”.

Add this pipe. This example will only check LDAP connectivity. Change parameters to suite your environment.
Add valves to suite your environment (sql connectivity, web service connectivity etc. Please view the Valves documentation to find valves that suites your needs). 

{
    "id" : "Ping",
    "description" : "Ping",
    "http_enabled" : "true",
    "http_path_pattern" : "GET:/pipes/phenix/ping",
    "http_response_content_type" : "text/plain",
    "http_response_body_item_property" : "statusb64",
    "valves" : [ 
     {
    "name" : "LDAPSearchValve",
    "config" : {
      "connection_ref" : "c85b6435-762c-48bd-9f74-4045b3c3efbc",
      "base_dn" : "dc=example,dc=local",
      "scope" : "SUB",
      "size_limit" : "0",
      "filter_template" : "uid=my_service_account_that_will_never_change"
    }
  }, {
      "name" : "PropertyAddValve",
      "config" : {
        "name" : "status",
        "value" : "SUCCESS",
        "exec_if_expr": "!flow.isEmpty()"
      }
    },
    {
      "name" : "ItemCreateValve",
      "config" : {
        "dest_id" : "failure",
         "exec_if_expr": "flow.isEmpty()"
      }
    },  {
      "name" : "PropertyAddValve",
      "config" : {
        "name" : "status",
        "value" : "FAILURE",
       "item_include_expr" : "item.getId().contains('failure')"
      }
    },{
      "name" : "PropertyStringBase64EncoderValve",
      "config" : {
        "source" : "status",
        "dest" : "statusb64"
      }
    } ]
  }

This change requires a restart of PhenixID Server.

Test

Open a web browser.

Browse to https://<phenixid_server_domain>:<phenixid_server_port>/pipes/phenix/ping

If the monitoring check is ok, a simple "SUCCESS" string is displayed in the browser.

If the monitoring check is not ok, a white page or a simple "FAILURE" string is displayed in the browser.