Skip to main content

Datadog

The datadog payload format sends Keycloak events to the Datadog Logs HTTP intake. The log entries look like the ones Datadog's own Keycloak integration collects:

  • ddsource:keycloak
  • the org.keycloak.events logger name
  • a message that is exactly the line Keycloak's event logger writes

So Datadog's Keycloak log pipeline parses them, and the Cloud SIEM Keycloak content pack's detection rules apply, the same as for logs collected from Keycloak's log files.

Complete the steps in Before you start first. Send Events to a SIEM explains how formats and the headers auth type work in general.

Set up Datadog​

  1. Create an API key under Organization Settings > API Keys. An application key is not needed.

  2. Find your logs intake host from your Datadog site:

    SiteIntake URL
    US1 (datadoghq.com)https://http-intake.logs.datadoghq.com/api/v2/logs
    US3 (us3.datadoghq.com)https://http-intake.logs.us3.datadoghq.com/api/v2/logs
    US5 (us5.datadoghq.com)https://http-intake.logs.us5.datadoghq.com/api/v2/logs
    EU1 (datadoghq.eu)https://http-intake.logs.datadoghq.eu/api/v2/logs
    AP1 (ap1.datadoghq.com)https://http-intake.logs.ap1.datadoghq.com/api/v2/logs
    AP2 (ap2.datadoghq.com)https://http-intake.logs.ap2.datadoghq.com/api/v2/logs
    UK1 (uk1.datadoghq.com)https://http-intake.logs.uk1.datadoghq.com/api/v2/logs
    US1-FED (ddog-gov.com)https://http-intake.logs.ddog-gov.com/api/v2/logs
    US2-FED (us2.ddog-gov.com)https://http-intake.logs.us2.ddog-gov.com/api/v2/logs

    Datadog lists the current hosts under Send logs.

  3. Optionally, for Cloud SIEM detections, enable the Keycloak content pack under Security > Cloud SIEM > Content Packs. Datadog applies its Keycloak log pipeline to source:keycloak logs automatically.

You don't need the Datadog Agent or Keycloak's syslog output, which Datadog's Keycloak integration page describes. This format posts log entries straight to the intake API, in a form the same pipeline parses.

Create the webhook​

Create the webhook with a POST to your realm's webhooks endpoint, sending an access token:

POST https://<your-cluster-host>/auth/realms/<realm>/webhooks
{
"enabled": true,
"url": "https://http-intake.logs.datadoghq.com/api/v2/logs",
"eventTypes": ["access.*", "admin.*"],
"payloadFormat": "datadog",
"authType": "headers",
"config": {
"header.DD-API-KEY": "<api-key>",
"service": "keycloak",
"tags": "env:prod,team:iam"
}
}

The API key is sent as the DD-API-KEY header, and the API returns it masked.

Events show up in the Log Explorer under source:keycloak.

Options​

config keyDefaultDescription
servicekeycloakThe service attribute
sourcekeycloakThe ddsource attribute. Keep keycloak for Datadog's Keycloak pipeline and the content pack to apply.
hostnameThis Keycloak node's hostnameThe hostname attribute
tagsComma-separated ddtags, e.g. env:prod,team:iam

The log entries​

Each request posts a JSON array of log entries:

AttributeContents
ddsource, service, hostname, ddtagsFrom the options above
messageKeycloak's event log line (see below)
timestampWhen the event happened, in epoch milliseconds
statusinfo, or warn when the event has an error
loggerName, logger.nameorg.keycloak.events, which the Keycloak pipeline uses to recognise event logs
evt.nameThe type as Keycloak names it: LOGIN, LOGIN_ERROR, ... for user events; CREATE, UPDATE, ... for admin events
evt.outcomesuccess or failure
evt.categoryauthentication for login, logout, token, impersonation and identity provider login events; admin for admin events
usr.id, usr.nameThe user the event is about. For admin events, the admin who made the change.
usr.emailUser events: the email detail, when present
network.client.ipThe client IP address
error.messageThe error, e.g. invalid_user_credentials
keycloak.*The whole event: id, uid, type (e.g. access.LOGIN), category, realmId, realmName, clientId, sessionId, error, details. Admin events also carry operationType, resourceType, resourcePath and authRealm.

The evt.*, usr.*, network.* and error.* attributes follow Datadog's standard attributes, so detections work even where the message isn't parsed.

The message​

message is the line Keycloak's org.keycloak.events logger writes for the event, quoted and sanitized the same way. For a user event:

type="LOGIN", realmId="ce09554b-...", realmName="master", clientId="admin-cli", userId="fe94cd42-...", sessionId="77crxycrk_Y-_m4usiaErjZh", ipAddress="192.168.65.1", auth_method="openid-connect", grant_type="password", username="admin"

For an admin event:

operationType="CREATE", realmId="ce09554b-...", realmName="master", clientId="fd4272a8-...", userId="fe94cd42-...", ipAddress="192.168.65.1", resourceType="USER", resourcePath="users/3771790e-...", resourceUserId="3771790e-...", resourceUsername="datadog-user"

Phase Two adds the changed user's userId and username to admin events on users. In the message they are renamed resourceUserId and resourceUsername, so they don't overwrite the admin's userId when the pipeline extracts attributes. Any other detail whose name collides with a field of the line gets a detail_ prefix.

A complete entry for a login:

[
{
"ddsource": "keycloak",
"service": "keycloak",
"hostname": "fa6957957f32",
"ddtags": "env:test,team:iam",
"message": "type=\"LOGIN\", realmId=\"ce09554b-70dd-4726-8244-a20cd8f2d869\", realmName=\"master\", clientId=\"admin-cli\", userId=\"fe94cd42-324d-4e69-adff-480bae053351\", sessionId=\"77crxycrk_Y-_m4usiaErjZh\", ipAddress=\"192.168.65.1\", auth_method=\"openid-connect\", grant_type=\"password\", username=\"admin\"",
"timestamp": 1794836612105,
"status": "info",
"loggerName": "org.keycloak.events",
"logger": { "name": "org.keycloak.events" },
"evt": {
"name": "LOGIN",
"outcome": "success",
"category": "authentication"
},
"usr": { "id": "fe94cd42-324d-4e69-adff-480bae053351", "name": "admin" },
"network": { "client": { "ip": "192.168.65.1" } },
"keycloak": {
"id": "9abdf8a9-baac-4945-b7a8-004309d313d3",
"uid": "3f4cfa7c-8a50-4ceb-98b0-378bd97dbf2f",
"type": "access.LOGIN",
"category": "user",
"realmId": "ce09554b-70dd-4726-8244-a20cd8f2d869",
"realmName": "master",
"clientId": "admin-cli",
"sessionId": "77crxycrk_Y-_m4usiaErjZh",
"details": {
"auth_method": "openid-connect",
"grant_type": "password",
"username": "admin"
}
}
}
]

Example searches​

WhatLog Explorer query
All Keycloak eventssource:keycloak
Failed loginssource:keycloak @evt.name:LOGIN_ERROR
Failed logins for a usersource:keycloak @evt.outcome:failure @usr.name:jdoe
Admin changes to userssource:keycloak @evt.category:admin @keycloak.resourceType:USER
One realmsource:keycloak @keycloak.realmName:my-realm

Retries​

ResponseWhat happens
202Sent
400, 401, 403, 413Not retried: an invalid payload, a bad or revoked API key, or a request that is too large
408, 429, 5xx, network errorsRetried with backoff

Limits​

  • Each request carries one event. The intake accepts up to 1,000 entries and 5 MB per request, and each entry is far smaller than that.
  • Datadog truncates log entries over 1 MB.

Troubleshooting​

The webhook's delivery history shows the response status of each send, when delivery history is available on your cluster.

SymptomCheck
403The webhook URL is for your Datadog site, and header.DD-API-KEY holds an API key, not an application key.
Logs arrive but aren't parsedsource is keycloak, and the Keycloak pipeline is enabled under Logs > Pipelines.
No Cloud SIEM signalsThe Keycloak content pack is enabled, and logs are indexed in an index Cloud SIEM analyzes.