Sumo Logic Integration

Forward Keycloak authentication events and logs to Sumo Logic for cloud-native log analytics, machine learning-powered insights, and comprehensive security monitoring.

Overview

This guide walks you through configuring Skycloak to send security events to Sumo Logic using HTTP Source collectors. Sumo Logic is ideal for organizations requiring advanced analytics, compliance reporting, and cloud-scale log management.

What You’ll Achieve

• Real-time authentication event streaming to Sumo Logic
• Machine learning-powered threat detection
• Advanced search and analytics capabilities
• Custom dashboards and automated alerts

Prerequisites

Before starting, ensure you have:

1. Skycloak Requirements

   • Enterprise plan, or a Launch or Business plan with the SIEM Export add-on
   • Workspace Owner or Admin permissions

2. Sumo Logic Requirements

   • Active Sumo Logic account (Professional or Enterprise plan recommended)
   • Permission to create Collectors and Sources
   • Access to Log Search and Dashboards

Step 1: Create HTTP Source Collector

Option A: Create New Hosted Collector

1. Log in to Sumo Logic

2. Navigate to Manage Data → Collection

3. Click Add Collector → Hosted Collector

4. Configure:

   • Name: Skycloak Keycloak
   • Description: Authentication events from Skycloak managed Keycloak
   • Category: keycloak/authentication
   • Time Zone: Select your timezone

5. Click Save

Add HTTP Logs Source

1. Click Add Source next to your new collector
2. Select HTTP Logs & Metrics
3. Configure:

Source Information:

• Name: Keycloak Events
• Description: Keycloak authentication and security events
• Source Category: keycloak/events (important for searches)

Advanced Options for Logs:

• Timestamp Format: Auto Detect
• Timestamp Locator: Leave blank (auto-detect)
• Time Zone: Use Collector Default
• Multiline Processing: Detect messages spanning multiple lines → Infer Boundaries

Processing Rules (optional but recommended): Add field extraction rule:

• Name: Extract Keycloak Fields
• Filter: _sourceCategory=keycloak/events
• Expression:

  parse json field=_raw as event_type, username, ip_address, realm, timestamp

4. Click Save

Copy HTTP Source URL

After creating the source, you’ll see a unique URL:

https://collectors.sumologic.com/receiver/v1/http/UNIQUE_ENDPOINT_ID

Copy and save this URL - you’ll need it for Skycloak configuration.

Optional: Create Source Fields

For better organization:

1. Go to Manage Data → Logs → Fields
2. Click Add Field
3. Create these fields:
   • event_type (string)
   • keycloak_realm (string)
   • keycloak_username (string)
   • keycloak_ip (string)

Step 2: Configure Skycloak SIEM Destination

1. Log in to your Skycloak dashboard
2. Navigate to SIEM Integration in the left sidebar
3. Click Add Destination
4. Configure the destination:

Basic Information

• Name: Sumo Logic Production
• Destination Type: HTTP Webhook

Connection Details

• Webhook URL: Your HTTP Source URL from Step 1
• Authentication Type: None (URL contains authentication token)
• Custom Headers (optional): Add this JSON to set source metadata:

  {
    "X-Sumo-Name": "keycloak-events",
    "X-Sumo-Category": "keycloak/events",
    "X-Sumo-Host": "skycloak"
  }

Event Filtering

Select events to forward:

• LOGIN - Successful logins
• LOGIN_ERROR - Failed login attempts
• LOGOUT - User logouts
• UPDATE_PASSWORD - Password changes
• UPDATE_EMAIL - Email changes
• REGISTER - New user registrations
• CODE_TO_TOKEN - Token exchanges
• REFRESH_TOKEN - Token refreshes
• REVOKE_GRANT - Consent revocations
• UPDATE_PROFILE - Profile updates

Include Server Logs: Enable for detailed application logs (increases ingestion volume)

Batching Configuration

• Batch Size: 500 (Sumo Logic accepts up to 1MB per request)
• Batch Interval: 60 seconds (recommended for near-real-time)

5. Click Complete Setup
6. Toggle Enable to start forwarding events

Step 3: Verify Data Flow

Check Data Volume Index

1. Navigate to Manage Data → Collection
2. Find your HTTP Source (Keycloak Events)
3. Check Data Volume - should show incoming data within 2-3 minutes

Search for Events

1. Navigate to Log Search

2. Run this query:

   _sourceCategory=keycloak/events
   | limit 10

3. Events should appear within 2-3 minutes of enabling the destination

Verify Event Structure

Run this query to see field distribution:

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username", "ip_address", "realm", "timestamp"
| count by event_type

Test with Login Event

1. Log in to one of your Keycloak realms
2. Wait 2-3 minutes for batch processing
3. Search:

   _sourceCategory=keycloak/events
   | json field=_raw "event_type" as event_type
   | where event_type = "LOGIN"
   | limit 1

Step 4: Create Field Extraction Rules

Automatic Field Extraction

1. Navigate to Manage Data → Logs → Field Extraction Rules
2. Click Add Rule
3. Configure:

Rule Name: Keycloak Event Fields

Applied At: Ingest Time

Scope:

• Source Category: keycloak/events

Parse Expression:

json field=_raw "event_type", "username", "ip_address", "realm", "timestamp", "user_id", "client_id"
| fields event_type, username, ip_address, realm, timestamp, user_id, client_id

4. Click Save

Now these fields will be automatically extracted for all Keycloak events.

Step 5: Create Monitors

Example: Brute Force Detection Monitor

1. Navigate to Manage Data → Monitoring → Monitors
2. Click Add → New Monitor
3. Configure:

Monitor Type: Logs

Query:

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username", "ip_address" as event_type, username, ip_address
| where event_type = "LOGIN_ERROR"
| count by username, ip_address
| where _count >= 5

Trigger Conditions:

• Alert Type: Critical
• Trigger if: Result count is greater than 0
• Time Range: -5m (last 5 minutes)
• Evaluation Frequency: Every 5 minutes

Notifications:

• Connection Type: Email, Slack, PagerDuty, etc.
• Subject: Brute Force Attack Detected - Keycloak
• Message:

  Multiple failed login attempts detected:
  {{ResultsJson}}
  
  Time: {{TriggerTime}}
  Query: {{QueryURL}}

4. Click Save

Example: Account Modification Alert

Alert on password or email changes:

Query:

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username" as event_type, username
| where event_type in ("UPDATE_PASSWORD", "UPDATE_EMAIL")
| count by event_type, username

Trigger: When result count > 0 in last 5 minutes

Example: New User Registration Alert

Monitor new user registrations:

Query:

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username", "realm" as event_type, username, realm
| where event_type = "REGISTER"
| count by realm

Trigger: When result count > 10 in last 15 minutes (adjust based on baseline)

Step 6: Create Dashboards

Example: Authentication Overview Dashboard

1. Navigate to Dashboards → New Dashboard
2. Name: Keycloak Authentication Monitoring
3. Add panels:

Panel 1: Login Success Rate (Single Value)

_sourceCategory=keycloak/events
| json field=_raw "event_type" as event_type
| where event_type in ("LOGIN", "LOGIN_ERROR")
| count by event_type
| if (event_type="LOGIN", _count, 0) as success
| if (event_type="LOGIN_ERROR", _count, 0) as failure
| sum(success) as total_success, sum(failure) as total_failure
| (total_success / (total_success + total_failure)) * 100 as success_rate
| fields success_rate

Panel 2: Failed Logins Over Time (Area Chart)

_sourceCategory=keycloak/events
| json field=_raw "event_type" as event_type
| where event_type = "LOGIN_ERROR"
| timeslice 5m
| count by _timeslice

Panel 3: Top Failed Login Users (Bar Chart)

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username" as event_type, username
| where event_type = "LOGIN_ERROR"
| count by username
| top 10 username by _count

Panel 4: Login Activity by Realm (Pie Chart)

_sourceCategory=keycloak/events
| json field=_raw "event_type", "realm" as event_type, realm
| where event_type = "LOGIN"
| count by realm

Panel 5: Geographic Distribution (Map)

_sourceCategory=keycloak/events
| json field=_raw "event_type", "ip_address" as event_type, ip_address
| where event_type = "LOGIN"
| lookup latitude, longitude, country_name from geo://location on ip=ip_address
| count by latitude, longitude, country_name

Panel 6: Event Type Distribution (Column Chart)

_sourceCategory=keycloak/events
| json field=_raw "event_type" as event_type
| count by event_type
| sort by _count desc

4. Click Save

Useful Sumo Logic Queries

Recent Failed Logins

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username", "ip_address", "timestamp" as event_type, username, ip_address, timestamp
| where event_type = "LOGIN_ERROR"
| sort by timestamp desc
| limit 100

User Login History

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username", "ip_address", "realm", "timestamp" as event_type, username, ip_address, realm, timestamp
| where event_type = "LOGIN" and username = "john.doe"
| sort by timestamp desc

Suspicious Multiple IP Logins

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username", "ip_address" as event_type, username, ip_address
| where event_type = "LOGIN"
| count_distinct(ip_address) by username
| where _count_distinct > 3
| sort by _count_distinct desc

Account Changes Summary

_sourceCategory=keycloak/events
| json field=_raw "event_type", "username" as event_type, username
| where event_type in ("UPDATE_PASSWORD", "UPDATE_EMAIL", "UPDATE_PROFILE", "DELETE_ACCOUNT")
| count by event_type, username
| sort by _count desc

Login Success Rate by Realm

_sourceCategory=keycloak/events
| json field=_raw "event_type", "realm" as event_type, realm
| where event_type in ("LOGIN", "LOGIN_ERROR")
| count by realm, event_type
| transpose row realm column event_type
| LOGIN / (LOGIN + LOGIN_ERROR) * 100 as success_rate
| fields realm, success_rate
| sort by success_rate asc

Failed Login Trend Analysis

_sourceCategory=keycloak/events
| json field=_raw "event_type" as event_type
| where event_type = "LOGIN_ERROR"
| timeslice 1h
| count by _timeslice
| compare with timeshift 1d

Advanced Features

Scheduled Searches

Create recurring searches that email results:

1. Navigate to Log Search
2. Create your query
3. Click Save As → Scheduled Search
4. Configure:
   • Run Frequency: Daily, Hourly, etc.
   • Time Range: Last 24 hours
   • Email Recipients: Your team
   • Alert Condition: When results exist

Log Compare

Compare login activity week-over-week:

_sourceCategory=keycloak/events
| json field=_raw "event_type" as event_type
| where event_type = "LOGIN"
| timeslice 1d
| count by _timeslice
| compare timeshift 7d

Anomaly Detection

Use Sumo Logic’s ML-powered anomaly detection:

_sourceCategory=keycloak/events
| json field=_raw "event_type" as event_type
| where event_type = "LOGIN_ERROR"
| timeslice 5m
| count by _timeslice
| outlier _count window=10

Troubleshooting

No Data Appearing in Sumo Logic

1. Check Skycloak destination status:

   • Navigate to SIEM Integration page
   • Verify “Healthy” status
   • Check “Events Sent” metric is increasing

2. Verify HTTP Source URL:

   • Ensure URL is correct and includes unique endpoint ID
   • Check for trailing spaces or missing characters
   • Test manually:

   curl -X POST "YOUR_HTTP_SOURCE_URL" \
     -H "Content-Type: application/json" \
     -d '{"test": "data", "timestamp": "2024-01-15T10:00:00Z"}'

3. Check Data Volume:

   • Navigate to Manage Data → Collection
   • Check if source shows incoming data volume
   • Look for error messages in source status

4. Verify Source Category:

   • Ensure searches use correct _sourceCategory
   • Check if source category was set during setup

Fields Not Extracted

• Check Field Extraction Rule: Verify rule is enabled and scope matches
• Test Parse Expression: Use Log Search to test parse logic
• Check JSON Structure: Ensure events are valid JSON

High Data Volume Costs

1. Filter events: Only forward critical event types
2. Reduce batch frequency: Increase batch interval to 120-300 seconds
3. Disable server logs: Turn off “Include Logs” if not needed
4. Set up data forwarding: Archive to S3 for long-term retention
5. Use partitions: Create partitions for different event types

Query Performance Issues

• Use indexed fields: Always filter by _sourceCategory first
• Limit time range: Use smaller time windows for better performance
• Use field extraction: Pre-extract fields instead of parsing at search time
• Add partitions: Create partitions for frequently searched categories

Best Practices

1. Use Source Categories: Organize logs with consistent category naming
2. Create Field Extraction Rules: Extract common fields at ingest time
3. Set Up Partitions: Improve query performance for high-volume logs
4. Configure Data Forwarding: Archive to S3 for compliance and cost savings
5. Use Scheduled Searches: Automate regular security reports
6. Create Lookup Tables: Maintain lists of VIP users, known IPs, etc.
7. Set Up Role-Based Access: Limit access to sensitive authentication logs

Next Steps

• Create additional monitors for your security requirements
• Build comprehensive dashboards for your security team
• Set up scheduled searches for weekly security reports
• Configure data forwarding to S3 for long-term retention
• Explore Sumo Logic Cloud SIEM Enterprise for advanced threat detection
• Create lookup tables for user enrichment and threat intelligence

Support

For assistance:

• Skycloak Support
• Sumo Logic Documentation