On this page
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:
Class | Description |
---|---|
Configuration | Variable values that will be configured in the Curity Identity Server |
Alarm Handler | The alarm handler custom implementation, which uses the AWS SDK |
Descriptor | The descriptor is used by the plugin system to find and load the alarm handler class |
Managed AWS Client | An object that is created and configured only once, to notify the AWS Events Bridge efficiently |
Credentials Provider | An object responsible for providing AWS credentials in order for the remote call to succeed |
JSON Formatter | A utility class to format data for the destination cloud system |
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.