Guides
SIEM Integration Guide

SIEM Integration Guide

Forward Keycloak security events and logs to external Security Information and Event Management (SIEM) platforms for centralized security monitoring, compliance, and threat detection.

Overview

Skycloak’s SIEM Integration feature enables you to export authentication events and server logs to popular SIEM platforms including Splunk, QRadar, Azure Sentinel, Datadog, and Sumo Logic. This allows security teams to:

  • Monitor authentication patterns and detect anomalies
  • Investigate security incidents across multiple systems
  • Meet compliance requirements (SOC 2, HIPAA, PCI-DSS)
  • Create automated alerting for suspicious activities
  • Retain event logs for extended periods

Supported Destination Types

  • Syslog - Forward to syslog servers (UDP/TCP/TLS) for platforms like Splunk and QRadar
  • AWS S3 - Store events in S3 buckets for long-term retention and analysis
  • HTTP Webhooks - Send to HTTP endpoints for platforms like Datadog and Sumo Logic

Plan Requirements

Plan: Enterprise Add-on: SIEM Integration ($129/month)

SIEM Integration is available as an add-on to Enterprise plans. Upgrade your plan to enable this feature.

Prerequisites

Before configuring SIEM integration:

  1. Enterprise Plan with SIEM Integration add-on
  2. Workspace Owner or Admin permissions
  3. Target SIEM Platform configured and accessible
  4. Network Connectivity from Skycloak to your SIEM destination

Getting Started

Accessing SIEM Integration

  1. Navigate to your Skycloak dashboard
  2. Click SIEM Integration in the left sidebar
  3. Click Add Destination to create your first destination

Creating Your First Destination

The setup wizard guides you through 5 steps:

  1. Basic Information - Name and type
  2. Destination Configuration - Connection details
  3. Event Filtering - Choose which events to forward
  4. Batching Configuration - Optimize performance
  5. Review & Submit - Verify and create

Syslog Configuration

Syslog is ideal for traditional SIEM platforms like Splunk and QRadar.

Step 1: Choose Syslog Type

In the destination wizard, select Syslog as your destination type.

Step 2: Configure Connection

Syslog Host: The hostname or IP address of your syslog server

  • Example: splunk.company.com or 10.0.1.50
  • Must be accessible from Skycloak

Port: Standard syslog ports

  • 514 - UDP/TCP (default)
  • 6514 - TLS (recommended for security)
  • Custom ports are supported

Protocol: Choose based on your requirements

Protocol Speed Reliability Security Best For
UDP Fastest No guarantee Unencrypted High-volume, non-critical
TCP Fast Ordered delivery Unencrypted Most use cases
TLS Fast Ordered delivery Encrypted Production, compliance

Format: Select based on your SIEM platform

  • JSON - Most flexible, works with all platforms
  • CEF (Common Event Format) - Optimized for ArcSight and Splunk
  • LEEF (Log Event Extended Format) - Optimized for QRadar
  • RFC5424 - Standard syslog format

Step 3: Configure Filtering

Choose which events to forward:

Event Types: Select from 50+ Keycloak event types

  • LOGIN - Successful user logins
  • LOGIN_ERROR - Failed login attempts
  • LOGOUT - User logouts
  • UPDATE_PASSWORD - Password changes
  • UPDATE_EMAIL - Email address changes
  • And many more…

Tip: Start with login-related events, then expand based on your needs.

Include Server Logs: Toggle on to include Keycloak server logs

  • Adds detailed application logs to your SIEM
  • Increases data volume significantly
  • Recommended for troubleshooting and deep investigations

Include Security Logs: Toggle on to include WAF and security events

  • Web Application Firewall (WAF) attack detections and blocks
  • Geo-blocking events from restricted countries/regions
  • Rate limiting violations
  • Detailed attack metadata including OWASP CRS rules, severity levels, and source IPs
  • Recommended for security monitoring and threat detection

Realm Filtering (Optional): Forward events from specific realms only Cluster Filtering (Optional): Forward events from specific clusters only

Step 4: Configure Batching

Batching reduces network overhead and improves performance.

Batch Size: Number of events to group together (1-1000)

  • High volume (1000+ events/min): 500-1000 events
  • Medium volume (100-1000 events/min): 100-500 events
  • Low volume (<100 events/min): 10-100 events

Batch Interval: Maximum time to wait before sending (10-600 seconds)

  • Real-time monitoring: 10-30 seconds
  • General monitoring: 60-120 seconds
  • Compliance archival: 300-600 seconds

Step 5: Test and Enable

  1. Review your configuration
  2. Click Complete Setup
  3. Test the connection by triggering a login event
  4. Check your SIEM platform for received events
  5. Toggle Enable to start continuous forwarding

Syslog Best Practices

  1. Use TLS for production environments to encrypt data in transit
  2. Start with specific events rather than forwarding all events
  3. Monitor batch size and adjust based on event volume
  4. Configure firewall rules to allow outbound syslog traffic
  5. Set up health monitoring in your SIEM to alert on missing data

AWS S3 Configuration

Store events in S3 for long-term retention, compliance, and batch analysis.

Step 1: Create S3 Bucket

  1. Sign in to AWS Console
  2. Create a new S3 bucket (e.g., company-keycloak-siem-logs)
  3. Enable encryption (recommended: AES-256 or KMS)
  4. Configure lifecycle policies for cost optimization
  5. Note the bucket name and region

Step 2: Choose Authentication Method

Skycloak supports two authentication methods for S3 access. Choose based on your deployment environment and security requirements:

Method Security Use Case Credentials Required
Access Key Basic Non-AWS environments, development Access Key ID + Secret
IAM Role High EC2 instances, ECS tasks None (uses instance/task role)

Recommendation: Use IAM Role for production environments when running on AWS. Access Keys should only be used when IAM roles are not available (e.g., non-AWS deployments).

Step 3: Configure Authentication

Choose the authentication method that matches your deployment:

Access Key Authentication

Best for: Non-AWS environments, development, testing

Setup Steps:

  1. Go to IAM Console
  2. Create a new IAM user (e.g., skycloak-siem-writer)
  3. Attach inline policy with s3:PutObject permission:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::company-keycloak-siem-logs/*"
    }
  ]
}
  1. Create access key and save credentials securely
  2. In Skycloak wizard, select Access Key as authentication type
  3. Enter Access Key ID and Secret Access Key

Security Note: Access keys provide long-lived credentials. Rotate regularly and store securely.

IAM Role Authentication (EC2/ECS)

Best for: Skycloak running on EC2 instances or ECS tasks

Setup Steps:

  1. Create IAM role with the following trust policy:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
  1. Attach inline policy with s3:PutObject permission (same as above)
  2. For EC2: Attach role to your EC2 instance profile
  3. For ECS: Specify role in your ECS task definition
  4. In Skycloak wizard, select IAM Role as authentication type
  5. No additional credentials needed - automatically uses instance/task role

Benefits: No credential management, automatic rotation, follows AWS best practices.

Step 4: Configure in Skycloak

Bucket Name: Your S3 bucket name

  • Example: company-keycloak-siem-logs
  • Must exist and be accessible

Region: AWS region where your bucket is located

  • Example: us-east-1, eu-west-1
  • Must match your bucket’s region

Prefix (Optional): Organize logs with a prefix

  • Example: keycloak/events/
  • Creates folder structure: keycloak/events/2024-01-15/...

Authentication Type: Select from dropdown (Access Key, IAM Role)

  • Shows conditional fields based on selection
  • See authentication setup instructions above

Conditional Fields:

  • Access Key: Enter Access Key ID and Secret Access Key
  • IAM Role: No additional fields (uses instance/task role)

Step 5: Configure Filtering and Batching

Same as Syslog configuration (see above).

S3 File Format

Events are stored as JSON files with this structure:

s3://bucket-name/prefix/YYYY-MM-DD/HHMM-UUID.json

Example: s3://my-logs/keycloak/events/2024-01-15/1430-a1b2c3d4.json

Each file contains a batch of events in JSON format:

{
  "source": "skycloak",
  "type": "keycloak_events",
  "timestamp": "2024-01-15T14:30:00Z",
  "event_count": 1,
  "events": [
    {
      "type": "LOGIN",
      "timestamp": "2024-01-15T14:30:00Z",
      "realm": { "id": "realm-uuid", "name": "production" },
      "user": { "id": "user-123", "username": "[email protected]", "ip_address": "203.0.113.42" },
      "geo": { "country": "United States", "city": "San Francisco" },
      "metadata": { "event_type": "keycloak_events", "workspace_id": "ws-uuid", "cluster_id": "cluster-uuid", "source": "skycloak" }
    }
  ]
}

S3 Best Practices

  1. Enable bucket encryption for data at rest (AES-256 or KMS)
  2. Configure lifecycle policies to move old logs to Glacier or automatically delete after retention period
  3. Use IAM roles instead of access keys whenever possible:
    • IAM Role for EC2/ECS deployments (most secure)
    • Access Keys only when IAM roles are unavailable (e.g., non-AWS deployments)
  4. Set up S3 event notifications to trigger processing on new files (e.g., Lambda functions)
  5. Monitor S3 bucket metrics for cost optimization and performance tracking
  6. Enable S3 server access logging to audit bucket access for compliance

HTTP Webhook Configuration

Send events to HTTP endpoints for modern SIEM platforms and custom integrations.

Step 1: Prepare HTTP Endpoint

Your HTTP endpoint should:

  • Accept POST requests with JSON payload
  • Return 2xx status code for success
  • Handle high request volume (depends on your batch size)
  • Implement retry logic for temporary failures

Step 2: Configure in Skycloak

Webhook URL: Your HTTPS endpoint

  • Example: https://api.datadog.com/api/v2/logs
  • Must use HTTPS for security (HTTP allowed only for testing)

Authentication Type: Choose based on your endpoint

  • None - No authentication (not recommended for production)
  • Bearer Token - Token sent as Authorization: Bearer <token>
  • Basic Auth - Username/password encoded as Authorization: Basic <base64>

Auth Token: Required for Bearer and Basic auth

  • For Bearer: Your API token/key
  • For Basic: Format as username:password
  • Stored encrypted in Skycloak

Custom Headers (Optional): Add custom HTTP headers as JSON

{
  "X-API-Version": "2.0",
  "X-Environment": "production"
}

Step 3: Configure Filtering and Batching

Same as Syslog configuration (see above).

HTTP Payload Format

Events are sent as JSON POST request:

{
  "source": "skycloak",
  "type": "keycloak_events",
  "timestamp": "2024-01-15T14:30:00Z",
  "event_count": 1,
  "events": [
    {
      "type": "LOGIN",
      "timestamp": "2024-01-15T14:30:00Z",
      "realm": { "id": "realm-uuid", "name": "production" },
      "user": { "id": "user-123", "username": "[email protected]", "ip_address": "203.0.113.42" },
      "geo": { "country": "United States", "city": "San Francisco" },
      "metadata": { "event_type": "keycloak_events", "workspace_id": "ws-uuid", "cluster_id": "cluster-uuid", "source": "skycloak" }
    }
  ]
}

HTTP Best Practices

  1. Always use HTTPS to encrypt data in transit
  2. Implement rate limiting on your endpoint to handle bursts
  3. Return proper status codes (2xx success, 4xx client error, 5xx server error)
  4. Log failed requests for troubleshooting
  5. Monitor endpoint health and set up alerts for downtime

Managing Destinations

Viewing Destinations

All configured destinations are displayed on the SIEM Integration page with:

  • Name and Type - Destination identifier and protocol
  • Health Status - Healthy, Degraded, or Failed
  • Metrics - Events sent, logs sent, data volume
  • Configuration - Connection details summary
  • Enable/Disable Toggle - Pause forwarding without deleting

Editing Destinations

  1. Click Edit on any destination card
  2. Modify configuration settings
  3. Note: Destination type cannot be changed after creation
  4. Credentials: Leave blank to keep existing credentials

Enabling/Disabling Destinations

Toggle the switch to pause or resume event forwarding:

  • Disabled - No events are forwarded, but configuration is preserved
  • Enabled - Events are batched and forwarded continuously

Use this to temporarily pause forwarding during maintenance.

Deleting Destinations

  1. Click Delete on the destination card
  2. Confirm deletion in the modal dialog
  3. Warning: This action cannot be undone

Tip: Consider disabling instead of deleting if you might need it again.

Monitoring and Health Status

Health Status Indicators

Healthy (Green):

  • No failures in last 10 send attempts
  • Events flowing normally
  • No action required

Degraded (Yellow):

  • 1-5 failures in last 10 attempts
  • Partial connectivity issues
  • Review error message and configuration

Failed (Red):

  • 6+ consecutive send failures
  • No events being forwarded
  • Immediate action required

Metrics

Each destination displays key metrics:

  • Events Sent - Total Keycloak events forwarded
  • Logs Sent - Total server logs forwarded (if enabled)
  • Data Sent - Total bytes transferred

Metrics are updated in real-time as events are forwarded.

Troubleshooting Failed Destinations

When a destination shows “Failed” status:

  1. Check error message displayed on the destination card
  2. Verify connectivity - Ensure network path is open
  3. Test credentials - Verify auth tokens/credentials are valid
  4. Check destination - Ensure target system is operational
  5. Review configuration - Confirm host, port, URL are correct
  6. Check firewall rules - Ensure outbound traffic is allowed

Common issues:

  • Connection timeout: Firewall blocking or host unreachable
  • Authentication failed: Invalid credentials or expired tokens
  • Permission denied: Insufficient IAM permissions (S3) or API scopes
  • Invalid format: SIEM platform expecting different format

Event Types Reference

Authentication Events

  • LOGIN - Successful user login
  • LOGIN_ERROR - Failed login attempt
  • LOGOUT - User logout
  • LOGOUT_ERROR - Failed logout
  • CODE_TO_TOKEN - Authorization code exchanged for token
  • CODE_TO_TOKEN_ERROR - Token exchange failed

Account Management Events

  • REGISTER - New user registration
  • REGISTER_ERROR - Registration failed
  • UPDATE_EMAIL - Email address changed
  • UPDATE_PASSWORD - Password changed
  • UPDATE_PROFILE - User profile updated
  • DELETE_ACCOUNT - User account deleted

Token Events

  • REFRESH_TOKEN - Access token refreshed
  • REFRESH_TOKEN_ERROR - Token refresh failed
  • REVOKE_GRANT - Consent/grant revoked
  • CLIENT_LOGIN - Service account authenticated

Administrative Events

  • UPDATE_CONSENT - User consent updated
  • FEDERATED_IDENTITY_LINK - Social login linked
  • REMOVE_FEDERATED_IDENTITY - Social login unlinked
  • IMPERSONATE - Admin impersonated user

For complete list of 50+ event types, see Keycloak Event Types.

Security Log Types

When “Include Security Logs” is enabled, Skycloak forwards security events detected by the Web Application Firewall (WAF) and other security controls. These logs provide detailed attack metadata for security monitoring and threat detection.

Web Application Firewall (WAF) Events

WAF logs include attacks detected and blocked by the OWASP ModSecurity Core Rule Set (CRS):

Attack Types:

  • SQL Injection - Attempts to inject SQL commands (e.g., ' OR 1=1--)
  • Cross-Site Scripting (XSS) - Script injection attempts (e.g., <script>alert(1)</script>)
  • Remote Code Execution - Code execution attempts (e.g., system(), eval())
  • Path Traversal - Directory traversal attempts (e.g., ../../../etc/passwd)
  • Remote File Inclusion - Attempts to include remote files (e.g., http://evil.com/shell.php)
  • Command Injection - System command injection (e.g., ; whoami)
  • Protocol Violations - Invalid HTTP requests or malformed headers

Event Fields:

  • type: “waf” - Identifies WAF security events
  • action: “block” or “detect” - Whether attack was blocked or only detected
  • rule_id: OWASP CRS rule ID (e.g., “942100” for SQL injection)
  • severity: “CRITICAL”, “ERROR”, “WARNING”, or “NOTICE”
  • attack_type: Human-readable attack category (e.g., “SQL Injection”)
  • source_ip: Attacker’s IP address
  • uri: Targeted URL path
  • method: HTTP method (GET, POST, etc.)
  • matched_data: Exact payload that triggered the rule
  • tags: OWASP tags (attack types, CAPEC IDs, compliance references)
  • anomaly_score: Cumulative score for threshold-based blocking
  • crs_version: OWASP CRS version (e.g., “OWASP_CRS/4.14.0”)
  • unique_id: Correlation ID for grouping related log entries

Example WAF Log:

{
  "timestamp": "2024-01-15T14:30:00Z",
  "type": "waf",
  "action": "block",
  "rule_id": "942100",
  "severity": "CRITICAL",
  "attack_type": "SQL Injection",
  "source_ip": "203.0.113.42",
  "uri": "/api/users?id=1' OR '1'='1",
  "method": "GET",
  "matched_data": "' OR '1'='1",
  "tags": ["attack-sqli", "OWASP_CRS", "capec/1000/152/248/66"],
  "anomaly_score": 15,
  "crs_version": "OWASP_CRS/4.14.0",
  "unique_id": "abc123"
}

Geo-blocking Events

Geographic access control events when requests from blocked countries are denied:

Event Fields:

  • type: “geo” - Geographic blocking event
  • action: “block” - Request was blocked
  • source_ip: Blocked IP address
  • country_code: ISO country code (e.g., “CN”, “RU”)
  • uri: Requested URL path

Rate Limiting Events

Requests blocked due to exceeding rate limits:

Event Fields:

  • type: “rate_limit” - Rate limiting event
  • action: “rate_limit” - Request was rate limited
  • source_ip: Client IP address
  • uri: Requested URL path
  • method: HTTP method

Security Log Use Cases

Threat Detection:

  • Identify attack patterns and trends
  • Detect reconnaissance and vulnerability scanning
  • Monitor for zero-day exploit attempts

Incident Response:

  • Investigate security incidents with detailed attack metadata
  • Correlate WAF blocks with authentication failures
  • Track attacker IP addresses across multiple systems

Compliance:

  • Demonstrate security controls for SOC 2, ISO 27001
  • Provide audit trail of security events
  • Meet logging requirements for PCI-DSS, HIPAA

Security Analytics:

  • Analyze attack frequency by type, severity, and source
  • Identify most targeted endpoints and vulnerabilities
  • Create dashboards for security operations center (SOC)

Initial Setup Behavior

Industry-Standard Start Time (NOW)

When you create a new SIEM destination, Skycloak automatically starts forwarding events from NOW (current time) — only new events from this point forward. This matches the behavior of popular log forwarders like Filebeat, Fluentd, Splunk, and Datadog.

Why Start from NOW?

This is the standard approach used by all major SIEM forwarders:

  • ✅ Filebeat: Default tail_files: true (reads from end, not beginning)
  • ✅ Fluentd: Default read_from_head: false (reads new data only)
  • ✅ Splunk Universal Forwarder: Starts from deployment time
  • ✅ Datadog Agent: Default start_position: end (tail mode)
  • ✅ Vector: Reads from current position
  • ✅ AWS CloudWatch: Starts streaming from current time

Benefits:

  • ✅ Immediate Value: See new security events within seconds of setup
  • ✅ No Resource Waste: Avoid processing months of old events you likely don’t need
  • ✅ No Alert Fatigue: Historical events won’t trigger false alerts
  • ✅ Cost Efficient: Save on SIEM ingestion costs for outdated data
  • ✅ Expected Behavior: Matches what security teams expect from SIEM forwarders

How It Works:

  1. First Run: When your new destination has no checkpoint saved, it automatically starts from NOW
  2. Subsequent Runs: The system saves a checkpoint after each batch and resumes from where it left off
  3. Only New Events: You receive security events as they happen in real-time
  4. No Duplicates: Client-side deduplication ensures events are never sent twice

Timeline:

[Cluster Created]────[3 months of events]────────────────────[Now]
                                                               ↑
                                                     SIEM starts here
                                                  (only forwards new events)

If You Need Historical Data:

Most customers don’t need historical events in their SIEM (real-time monitoring is the primary use case), but if you do need historical data:

  1. Contact Support: Request a one-time backfill for specific date ranges
  2. Export from Dashboard: Download historical events from the Skycloak event log
  3. Future Feature: UI option to specify custom start date when creating destinations

Monitoring:

You can verify your destination is forwarding new events by checking your SIEM platform. The first event timestamp should be approximately when you created the destination (within a few seconds).

Advanced Features

User-Agent Enrichment

Skycloak automatically enriches authentication and security events with browser and device information by correlating Keycloak events with HTTP access logs from the ingress gateway.

How It Works:

  1. When a user authenticates, Keycloak records the event with IP address and timestamp
  2. Skycloak correlates this with the HTTP access logs using IP address and timestamp matching (±2 second tolerance)
  3. The user-agent string from the HTTP request is added to the event before forwarding to SIEM

Enriched Field:

  • user_agent: Full user-agent string from the HTTP request (e.g., Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36)

Example Enriched Event:

{
  "timestamp": "2024-01-15T14:30:00Z",
  "event_type": "LOGIN",
  "user_id": "user-123",
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
}

Use Cases:

  • Device Tracking: Identify which devices users authenticate from
  • Browser Compatibility: Track browser usage across your user base
  • Bot Detection: Identify automated login attempts from bots and scripts
  • Security Monitoring: Detect unusual user-agents indicating potential attacks
  • Compliance: Meet audit requirements for session tracking with full device context

Availability:

  • Enabled automatically for all SIEM destinations and webhooks
  • Works with all destination types (Syslog, S3, HTTP)
  • Best-effort enrichment - events are forwarded even if user-agent lookup fails

Technical Details:

  • Matches events using IP address + timestamp correlation with ±2 second tolerance
  • Queries istio-proxy access logs from the ingress gateway
  • Filters for /realms API requests only (excludes static resources)
  • Supports both default domains (*.skycloak.io) and custom domains
  • Enrichment happens in real-time before forwarding to SIEM

Security Considerations

Data Encryption

  • In Transit: Use TLS (syslog), HTTPS (webhooks), or AWS encryption (S3)
  • At Rest: Credentials are encrypted in Skycloak database
  • Best Practice: Always enable encryption for production environments

Credential Management

  • Rotation: Update credentials regularly (recommend 90 days)
  • Least Privilege: Grant minimum required permissions
  • Storage: Credentials never returned in API responses
  • Deletion: Credentials permanently deleted when destination is removed

Access Control

  • Workspace Isolation: Destinations are isolated per workspace
  • Role Requirements: Owner or Admin role required to manage destinations
  • Audit Logging: All SIEM configuration changes are logged

Compliance

SIEM Integration helps meet compliance requirements:

  • SOC 2: Centralized security event monitoring
  • HIPAA: Audit trail of authentication and access
  • PCI-DSS: Logging and monitoring requirements
  • GDPR: Event retention and incident response

Performance Optimization

Batch Size Recommendations

Based on your event volume:

Events/Minute Batch Size Batch Interval Expected Latency
1-10 10-50 10-30s <1 minute
10-100 50-200 30-60s 1-2 minutes
100-1000 200-500 60-120s 2-3 minutes
1000+ 500-1000 120-300s 3-5 minutes

Network Considerations

  • Bandwidth: Each event is approximately 1-5KB
  • Latency: Higher batch intervals reduce network load
  • Reliability: TCP/TLS recommended for critical events
  • Cost: Larger batches reduce API costs for cloud SIEM platforms

Platform-Specific Guides

For detailed platform-specific configuration:

Next Steps

  • Configure alert rules in your SIEM platform
  • Create dashboards for authentication monitoring
  • Set up automated incident response workflows
  • Review and optimize event filtering based on usage
  • Document your SIEM integration for your team

Support

For assistance with SIEM Integration:

Internationalization GuideMulti-Factor Authentication Setup