Integrate Alarms with Cloud Monitoring Systems

Overview

In this tutorial we will show how to report details of Curity Alarms to cloud monitoring systems. Our solution will use AWS and consist of the following steps:

• A custom plugin receives alarm information from Curity
• The AWS SDK is used to send JSON data to the AWS Events Bridge
• Monitoring actions are defined in AWS to process the incoming events

Alarm Handler Plugin

The Java code for the plugin can be downloaded from the Github Repository. The alarm handler interface will be called whenever the state of an alarm changes within the Curity Identity Server:

package se.curity.identityserver.sdk.alarm;

public interface AlarmHandler {
    void handle(Alarm var1);
}

The plugin code consists of a number of Java source files, and the role of each is summarised below:

Development Setup

First ensure that the following resources are installed on the development machine:

• Java 11 or later
• Maven 3
• AWS CLI

The Java project will use the AWS SDK, and AWS libraries are referenced in its pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>eventbridge</artifactId>
</dependency>
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>sts</artifactId>
</dependency>

Create an Events Bus in AWS

In the AWS Console, navigate to AWS Events Bridge and create a Custom Events Bus, which we will call curity.events:

The next step is add an Events Rule, along with a Target, to handle incoming messages. You can do pretty much anything here, such as publishing to an SNS topic or invoking a lambda function.

We will use a simple option of saving data to Cloudwatch logs. Note that the rule must specify an Event Pattern in order to match incoming messages against a 'source' property.

Deploy the Plugin

To build the plugin's JAR files, run 'mvn package', to update the 'target' folder with the below library and all of its dependencies:

target/identityserver.plugins.alarmhandler.awseventsbridge-1.0.0.jar

Then create a plugin folder for alarm handlers in the Curity Identity Server and copy all of the the target/*.jar files there:

$IDSVR_ROOT/usr/share/plugins/<folder>

Activate the Plugin

Restart the Curity Identity Server to load the plugin, after which there will be an additional option under Alarm Handlers in the Admin UI:

The alarm needs to be configured with properties from the plugin's configuration object, so ensure that these match the values that were configured in AWS:

Test the Plugin

If a developer has the AWS CLI configured locally then the plugin will by default pick up AWS credentials from the ~./aws/credentials file. Run 'mvn clean test' to trigger an integration test that fires an alarm, and the console output will indicate success or failure:

[main] INFO io.curity.identityserver.plugin.alarmhandler.EventsBridgeAlarmHandler - Alarm sent successfully to AWS Events Bridge: 03194eb3-5435-1096-4c09-f9579513d1cd

In AWS this will result in a JSON object being saved to Cloudwatch logs, and this data is provided by the plugin's JsonFormatter class:

The plugin sends data in a readable manner, with the same fields as those rendered in the Curity Identity Server's Admin UI:

Create a Cloudwatch Query

The JSON data saved to Cloudwatch is contained in each entry's @message object, and JSON fields within this object can be queried with a dot syntax, as explained in the Insights Query Documentation.

We will use a simple list query to get received alarm events for a recent time period, then save results as a Log Table Widget:

Add to a Monitoring Dashboard

Once the query is built, the Add to Dashboard option can be used to render recent results in a Cloudwatch Monitoring Dashboard. The data shown will be controlled in the standard way, via the widget's currently configured time range:

The data rendered shows the current state of alarms and the vast majority of the time the widget would be empty. In the event of intermittent problems, the widget's time period can be extended to understand the history, or you can change its filter to focus on a particular type of alarm.

Conclusion

Alarm handlers allow you to receive immediate notification when a dependency of the Curity Identity Server experiences problems. It is then straightforward to send the data to cloud monitoring systems and integrate with their features.

We provided basic visualization via a monitoring dashboard, though the incoming event and its alarm data could be handled in many additional ways. A common option would be to add a second Event Bus rule for alarm messages, whose role is to send people alerts.