# Collect Keycloak logs

Supported in:

This document explains how to configure Keycloak to push logs to Google Security Operations using webhooks.

Keycloak is an open-source identity and access management (IAM) solution that provides single sign-on (SSO), user federation, identity brokering, and social login capabilities. It supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols and tracks user events (login, logout, registration, password changes) and admin events (user, client, realm, and role management operations) for security auditing.

## Before you begin

Make sure that you have the following prerequisites:

- A Google SecOps instance
- A running Keycloak instance (version 20 or later recommended)
- Administrator access to the Keycloak Admin Console
- Access to the Keycloak server filesystem or container to deploy extensions
- Access to Google Cloud Console (for API key creation)

## Create webhook feed in Google SecOps

### Create the feed

1. Go to **Settings \> Data Management \> Feeds** . If you are on a SIEM-only platform, go to **Settings \> Feeds**.
2. Click **Add New Feed**.
3. On the next page, click **Configure a single feed**.
4. In the **Feed name** field, enter a name for the feed (for example, `Keycloak Events`).
5. Select **Webhook** as the **Source type**.
6. Select **Keycloak** as the **Log type**.
7. Click **Next**.
8. Specify values for the following input parameters:
   - **Split delimiter** (optional): Enter `\n` to split multi-line events (each webhook POST contains a single event, so this can be left empty).
   - **Asset namespace** : The [asset namespace](https://docs.cloud.google.com/chronicle/docs/investigation/asset-namespaces.md.txt)
   - **Ingestion labels**: The label to be applied to the events from this feed
9. Click **Next**.
10. Review your new feed configuration in the **Finalize** screen, and then click **Submit**.

### Generate and save secret key

After creating the feed, you must generate a secret key for authentication:

1. On the feed details page, click **Generate Secret Key**.
2. A dialog displays the secret key.
3. **Copy and save** the secret key securely.

**Important**: The secret key is displayed only once and cannot be retrieved later. If you lose it, you must generate a new secret key.

### Get the feed endpoint URL

1. Go to the **Details** tab of the feed.
2. In the **Endpoint Information** section, copy the **Feed endpoint URL**.
3. The URL format is:

       https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import

   Where `{region}` is the region of your Google SecOps instance (for example, `us`, `europe`, or `asia-southeast1`), and `{parent}` is the resource path in the format `projects/<PROJECT_ID>/locations/<LOCATION>/instances/<INSTANCE_ID>/logTypes/<LOG_TYPE>`.
4. Save this URL for the next steps.

5. Click **Done**.

## Create Google Cloud API key

Chronicle requires an API key for authentication. Create a restricted API key in the Google Cloud Console.

### Create the API key

1. Go to the [Google Cloud Console Credentials page](https://console.cloud.google.com/apis/credentials).
2. Select your project (the project associated with your Chronicle instance).
3. Click **Create credentials \> API key**.
4. An API key is created and displayed in a dialog.
5. Click **Edit API key** to restrict the key.

### Restrict the API key

1. In the **API key** settings page:
   - **Name** : Enter a descriptive name (for example, `Chronicle Webhook API Key`)
2. Under **API restrictions** :
   1. Select **Restrict key**.
   2. In the **Select APIs** dropdown, search for and select **Google SecOps API** (or **Chronicle API**).
3. Click **Save**.
4. **Copy** the API key value from the **API key** field at the top of the page.
5. Save the API key securely.

> [!NOTE]
> **Note:** Restricting the API key ensures it can only be used with the Chronicle API, reducing security risk if the key is compromised.

## Enable event storage in Keycloak

Before configuring the webhook extension, enable event storage in Keycloak so that events are generated and available for forwarding.

### Enable user events

1. Sign in to the **Keycloak Admin Console**.
2. Select the **realm** you want to monitor from the realm dropdown in the upper-left corner.
3. Go to **Realm Settings \> Events**.
4. Select the **User events settings** sub-tab.
5. Enable the **Save events** toggle.
6. Set the **Expiration** period (minimum recommended: **7 days**).
7. Click **Save**.

### Enable admin events

1. On the same **Events** tab, select the **Admin events settings** sub-tab.
2. Enable the **Save events** toggle.
3. Enable the **Include representation** toggle to capture full details of changed objects.
4. Set the **Expiration** period (minimum recommended: **7 days**).
5. Click **Save**.

## Install the webhook event listener extension

Keycloak does not include a native webhook event listener. Install the `keycloak-events` extension from Phase Two (p2-inc) to enable webhook delivery.

### Download and deploy the extension

1. Download the latest release JAR from the [keycloak-events releases page on Maven Central](https://github.com/p2-inc/keycloak-events) or build from source:

   ```bash
   git clone https://github.com/p2-inc/keycloak-events.git
   cd keycloak-events
   mvn clean install
   ```
2. Copy the resulting fat JAR file into the Keycloak `providers` directory:

   ```bash
   cp target/keycloak-events-*.jar /opt/keycloak/providers/
   ```
3. Rebuild and restart Keycloak:

   ```bash
   /opt/keycloak/bin/kc.sh build
   /opt/keycloak/bin/kc.sh start
   ```

   > [!NOTE]
   > **Note:** For containerized deployments, add the JAR to the `/opt/keycloak/providers/` directory in your container image and rebuild.

### Enable the webhook event listener

1. Sign in to the **Keycloak Admin Console**.
2. Select the target **realm** from the realm dropdown.
3. Go to **Realm Settings \> Events**.
4. In the **Event listeners** dropdown, select **ext-event-webhook**.
5. Click **Save**.

## Configure Keycloak webhook

### Construct the webhook URL

- Combine the Chronicle endpoint URL and API key:

      <ENDPOINT_URL>?key=<API_KEY>

- **Example:**

      https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...

### Create webhook subscription via Keycloak REST API

The `keycloak-events` extension provides REST endpoints for managing webhook subscriptions. Use the Keycloak Admin REST API to create a webhook.

#### Step 1: Obtain an access token

- Request an access token from Keycloak using an admin account:

  ```bash
  TOKEN=$(curl -sS -X POST "https://<KEYCLOAK_HOST>/realms/master/protocol/openid-connect/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=password" \
    --data-urlencode "client_id=admin-cli" \
    --data-urlencode "username=<ADMIN_USERNAME>" \
    --data-urlencode "password=<ADMIN_PASSWORD>" \
    | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')
  ```

Replace the following:

- `<KEYCLOAK_HOST>`: Your Keycloak server hostname and port (for example, `keycloak.example.com:8443`)
- `<ADMIN_USERNAME>`: Your Keycloak admin username
- `<ADMIN_PASSWORD>`: Your Keycloak admin password

#### Step 2: Create the webhook

- Send a POST request to create the webhook subscription for the target realm:

  ```bash
  curl -sS -X POST "https://<KEYCLOAK_HOST>/realms/<REALM_NAME>/webhooks" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": "true",
      "url": "<ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY>",
      "secret": "<WEBHOOK_HMAC_SECRET>",
      "eventTypes": ["*"]
    }'
  ```

Replace the following:

- `<KEYCLOAK_HOST>`: Your Keycloak server hostname
- `<REALM_NAME>`: The name of the realm to monitor (for example, `master` or `my-realm`)
- `<ENDPOINT_URL>`: The Chronicle feed endpoint URL copied earlier
- `<API_KEY>`: The Google Cloud API key created earlier
- `<SECRET_KEY>`: The Chronicle webhook secret key generated earlier
- `<WEBHOOK_HMAC_SECRET>`: An arbitrary secret string for HMAC signing of webhook payloads (for example, `mySecretKey123`)

#### Step 3: Verify the webhook

- Confirm the webhook was created by listing all webhooks for the realm:

  ```bash
  curl -sS -X GET "https://<KEYCLOAK_HOST>/realms/<REALM_NAME>/webhooks" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/json"
  ```

The response returns a list of webhook objects. Verify that your webhook appears with `"enabled": "true"` and the correct URL.

### Webhook event types

The `eventTypes` field accepts an array of expressions to filter which events are sent:

- `*` --- Send all events (recommended for SIEM integration)
- `access.*` --- Send all access events
- `admin.*` --- Send all admin events
- `admin.USER-*` --- Send all admin events related to users
- `admin-USER-CREATE` --- Send only user creation admin events

### Webhook retry behavior

The extension uses automatic exponential backoff for retries when a non-2xx response is received:

| Parameter | Default Value | Description |
|---|---|---|
| **backoffInitialInterval** | 500 ms | Initial retry interval |
| **backoffMaxElapsedTime** | 900000 ms (15 min) | Maximum total retry time |
| **backoffMaxInterval** | 180000 ms (3 min) | Maximum interval between retries |
| **backoffMultiplier** | 5 | Multiplier for each retry interval |
| **backoffRandomizationFactor** | 0.5 | Randomization factor for jitter |

## Authentication methods reference

Chronicle webhook feeds support multiple authentication methods. Choose the method that your vendor supports.

### Method 1: Custom headers (Recommended)

If your vendor supports custom HTTP headers, use this method for better security.

- **Request format:**

  ```console
  POST <ENDPOINT_URL> HTTP/1.1
  Content-Type: application/json
  x-goog-chronicle-auth: <API_KEY>
  x-chronicle-auth: <SECRET_KEY>

  {
          "event": "data",
          "timestamp": "2025-01-15T10:30:00Z"
  }
  ```

**Advantages:**

- API key and secret not visible in URL
- More secure (headers not logged in web server access logs)
- Preferred method when vendor supports it

### Method 2: Query parameters

If your vendor does not support custom headers, append credentials to the URL.

- **URL format:**

      <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY>

- **Example:**

      https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...&secret=abcd1234...

- **Request format:**

  ```console
  POST <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY> HTTP/1.1
  Content-Type: application/json

  {
          "event": "data",
          "timestamp": "2025-01-15T10:30:00Z"
  }
  ```

**Disadvantages:**

- Credentials visible in URL
- May be logged in web server access logs
- Less secure than headers

### Method 3: Hybrid (URL + Header)

Some configurations use API key in URL and secret key in header.

- **Request format:**

  ```console
  POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
  Content-Type: application/json
  x-chronicle-auth: <SECRET_KEY>

  {
          "event": "data",
          "timestamp": "2025-01-15T10:30:00Z"
  }
  ```

### Authentication header names

Chronicle accepts the following header names for authentication:

**For API key:**

- `x-goog-chronicle-auth` (recommended)
- `X-Goog-Chronicle-Auth` (case-insensitive)

**For secret key:**

- `x-chronicle-auth` (recommended)
- `X-Chronicle-Auth` (case-insensitive)

> [!NOTE]
> **Note:** The Keycloak `keycloak-events` webhook extension sends events as HTTP POST with JSON content type. Because the extension does not support custom HTTP headers on outbound requests, use the query parameter method (Method 2) by appending `?key=<API_KEY>&secret=<SECRET_KEY>` to the webhook URL.

## Webhook limits and best practices

### Request limits

| Limit | Value |
|---|---|
| **Max request size** | 4 MB |
| **Max QPS (queries per second)** | 15,000 |
| **Request timeout** | 30 seconds |
| **Retry behavior** | Automatic with exponential backoff |

## Supported sample logs

The following examples show Keycloak JSON logs that the default parser maps to
Unified Data Model (UDM) event types:

- User login event (`USER_LOGIN`)

  ```json
  {
    "timestamp": "2024-10-12T15:10:04.123456789Z",
    "log_type": "KEYCLOAK",
    "uuid": "dummy_user_01",
    "read_timestamp": "2024-10-12T15:10:04Z",
    "source_timestamp": "2024-10-12T15:10:04.123456781Z",
    "object": "synth_object_01",
    "read_method": "synth_read_method_01",
    "stream_name": "synth_stream_name_01",
    "schema_key": "synth_schema_key_01",
    "sort_keys": "synth_sort_keys_01",
    "source_metadata": {
      "schema": "synth_schema_01",
      "table": "synth_table_01",
      "is_deleted": true,
      "change_type": "synth_change_type_01",
      "tx_id": "synth_tx_id_01",
      "lsn": "synth_lsn_01",
      "primary_keys": "synth_primary_keys_01"
    },
    "payload": {
      "id": "synth_id_01",
      "client_id": "synth_client_id_01",
      "error": "synth_error_01",
      "ip_address": "1.1.1.1",
      "realm_id": "synth_realm_id_01",
      "session_id": "synth_session_id_01",
      "event_time": "2024-10-12T15:10:04Z",
      "type": "LOGIN",
      "user_id": "dummy_user_01",
      "details_json": "{\"uuid\":\"dummy_user_01\",\"read_timestamp\":\"2024-10-12T15:10:04Z\",\"source_timestamp\":\"2024-10-12T15:10:04.123456781Z\",\"object\":\"synth_object_01\",\"read_method\":\"synth_read_method_01\",\"stream_name\":\"synth_stream_name_01\",\"schema_key\":\"synth_schema_key_01\",\"sort_keys\":\"synth_sort_keys_01\",\"username\":\"dummy_user_01\",\"redirect_uri\":\"synth_redirect_uri_01\",\"st\":\"synth_st_01\",\"refresh_token_id\":\"synth_refresh_token_id_01\",\"token_id\":\"synth_token_id_01\",\"environnement\":\"synth_environnement_01\",\"status_code\":\"200\",\"parameters\":{}}"
    },
    "username": "dummy_user_01",
    "redirect_uri": "synth_redirect_uri_01",
    "ctx": {
      "actionId": "synth_actionId_01",
      "clientId": "synth_clientId_01",
      "executionId": "synth_executionId_01",
      "host": "host-01.dummy.net",
      "ip": "1.1.1.1",
      "messageId": "dummy_user_01@dummy.net",
      "process": "synth_process_01",
      "realmId": "synth_realmId_01",
      "referer": "synth_referer_01",
      "requestId": "synth_requestId_01",
      "sessionId": "synth_sessionId_01",
      "source": "synth_source_01",
      "trackerId": "synth_trackerId_01",
      "uri": "synth_uri_01",
      "userAgent": "dummy_user_01",
      "userId": "dummy_user_01",
      "username": "dummy_user_01"
    },
    "env": {
      "application": "synth_application_01",
      "instance": "synth_instance_01",
      "st": "synth_st_01"
    },
    "st": "synth_st_01",
    "refresh_token_id": "synth_refresh_token_id_01",
    "token_id": "synth_token_id_01",
    "environnement": "synth_environnement_01",
    "status_code": "200",
    "events": [
      {
        "typeEv": "LOGIN",
        "message": "HTTP 200 Found"
      }
    ]
  }
  ```
- User logout event (`USER_LOGOUT`)

  ```json
  {
    "timestamp": "2024-10-12T16:17:17.123456789Z",
    "log_type": "KEYCLOAK",
    "uuid": "dummy_admin_02",
    "read_timestamp": "2024-10-12T16:17:17Z",
    "source_timestamp": "2024-10-12T16:17:17.123456782Z",
    "object": "synth_object_02",
    "read_method": "synth_read_method_02",
    "stream_name": "synth_stream_name_02",
    "schema_key": "synth_schema_key_02",
    "sort_keys": "synth_sort_keys_02",
    "source_metadata": {
      "schema": "synth_schema_02",
      "table": "synth_table_02",
      "is_deleted": false,
      "change_type": "synth_change_type_02",
      "tx_id": "synth_tx_id_02",
      "lsn": "synth_lsn_02",
      "primary_keys": "synth_primary_keys_02"
    },
    "payload": {
      "id": "synth_id_02",
      "client_id": "synth_client_id_02",
      "error": "synth_error_02",
      "ip_address": "1.1.1.2",
      "realm_id": "synth_realm_id_02",
      "session_id": "synth_session_id_02",
      "event_time": "2024-10-12T16:17:17Z",
      "user_id": "dummy_admin_02",
      "details_json": "{\"parameters\":{}}"
    },
    "username": "dummy_admin_02",
    "redirect_uri": "synth_redirect_uri_02",
    "ctx": {
      "actionId": "synth_actionId_02",
      "clientId": "synth_clientId_02",
      "executionId": "synth_executionId_02",
      "host": "gw-edge-02.dummy.net",
      "ip": "1.1.1.2",
      "messageId": "dummy_admin_02@dummy.net",
      "process": "synth_process_02",
      "realmId": "synth_realmId_02",
      "referer": "synth_referer_02",
      "requestId": "synth_requestId_02",
      "sessionId": "synth_sessionId_02",
      "source": "synth_source_02",
      "trackerId": "synth_trackerId_02",
      "uri": "synth_uri_02",
      "userAgent": "dummy_admin_02",
      "userId": "dummy_admin_02",
      "username": "dummy_admin_02"
    },
    "env": {
      "application": "synth_application_02",
      "instance": "synth_instance_02",
      "st": "synth_st_02"
    },
    "st": "synth_st_02",
    "refresh_token_id": "synth_refresh_token_id_02",
    "token_id": "synth_token_id_02",
    "environnement": "synth_environnement_02",
    "status_code": "200",
    "events": [
      {
        "typeEv": "LOGOUT",
        "message": "HTTP 302 Found"
      }
    ]
  }
  ```
- User resource-access event (`USER_RESOURCE_ACCESS`)

  ```json
  {
    "timestamp": "2024-10-12T17:24:30.123456789Z",
    "log_type": "KEYCLOAK",
    "uuid": "dummy_svc_03",
    "read_timestamp": "2024-10-12T17:24:30Z",
    "source_timestamp": "2024-10-12T17:24:30.123456783Z",
    "object": "synth_object_03",
    "read_method": "synth_read_method_03",
    "stream_name": "synth_stream_name_03",
    "schema_key": "synth_schema_key_03",
    "sort_keys": "synth_sort_keys_03",
    "source_metadata": {
      "schema": "synth_schema_03",
      "table": "synth_table_03",
      "is_deleted": true,
      "change_type": "synth_change_type_03",
      "tx_id": "synth_tx_id_03",
      "lsn": "synth_lsn_03",
      "primary_keys": "synth_primary_keys_03"
    },
    "payload": {
      "id": "synth_id_03",
      "client_id": "synth_client_id_03",
      "error": "synth_error_03",
      "ip_address": "1.1.1.3",
      "realm_id": "synth_realm_id_03",
      "session_id": "synth_session_id_03",
      "event_time": "2024-10-12T17:24:30Z",
      "user_id": "dummy_svc_03",
      "details_json": "{\"parameters\":{}}"
    },
    "username": "dummy_svc_03",
    "redirect_uri": "synth_redirect_uri_03",
    "ctx": {
      "actionId": "synth_actionId_03",
      "clientId": "synth_clientId_03",
      "executionId": "synth_executionId_03",
      "host": "auth-srv-03.dummy.net",
      "ip": "1.1.1.3",
      "messageId": "dummy_svc_03@dummy.net",
      "process": "synth_process_03",
      "realmId": "synth_realmId_03",
      "referer": "synth_referer_03",
      "requestId": "synth_requestId_03",
      "sessionId": "synth_sessionId_03",
      "source": "synth_source_03",
      "trackerId": "synth_trackerId_03",
      "uri": "synth_uri_03",
      "userAgent": "dummy_svc_03",
      "userId": "dummy_svc_03",
      "username": "dummy_svc_03"
    },
    "env": {
      "application": "synth_application_03",
      "instance": "synth_instance_03",
      "st": "synth_st_03"
    },
    "st": "synth_st_03",
    "refresh_token_id": "synth_refresh_token_id_03",
    "token_id": "synth_token_id_03",
    "environnement": "synth_environnement_03",
    "status_code": "200",
    "events": [
      {
        "typeEv": "USER_INFO_REQUEST",
        "message": "HTTP 401 Found"
      }
    ]
  }
  ```
- Network connection event (`NETWORK_CONNECTION`)

  ```json
  {
    "timestamp": "2024-10-12T18:31:43.123456789Z",
    "log_type": "KEYCLOAK",
    "uuid": "dummy_auditor_04",
    "read_timestamp": "2024-10-12T18:31:43Z",
    "source_timestamp": "2024-10-12T18:31:43.123456784Z",
    "object": "synth_object_04",
    "read_method": "synth_read_method_04",
    "stream_name": "synth_stream_name_04",
    "schema_key": "synth_schema_key_04",
    "sort_keys": "synth_sort_keys_04",
    "source_metadata": {
      "schema": "synth_schema_04",
      "table": "synth_table_04",
      "is_deleted": false,
      "change_type": "synth_change_type_04",
      "tx_id": "synth_tx_id_04",
      "lsn": "synth_lsn_04",
      "primary_keys": "synth_primary_keys_04"
    },
    "payload": {
      "id": "synth_id_04",
      "client_id": "synth_client_id_04",
      "error": "synth_error_04",
      "ip_address": "1.1.1.4",
      "realm_id": "synth_realm_id_04",
      "session_id": "synth_session_id_04",
      "event_time": "2024-10-12T18:31:43Z",
      "user_id": "dummy_auditor_04",
      "details_json": "{\"parameters\":{}}"
    },
    "username": "dummy_auditor_04",
    "redirect_uri": "synth_redirect_uri_04",
    "ctx": {
      "actionId": "synth_actionId_04",
      "clientId": "synth_clientId_04",
      "executionId": "synth_executionId_04",
      "host": "db-node-04.dummy.net",
      "ip": "1.1.1.4",
      "messageId": "dummy_auditor_04@dummy.net",
      "process": "synth_process_04",
      "realmId": "synth_realmId_04",
      "referer": "synth_referer_04",
      "requestId": "synth_requestId_04",
      "sessionId": "synth_sessionId_04",
      "source": "synth_source_04",
      "trackerId": "synth_trackerId_04",
      "uri": "synth_uri_04",
      "userAgent": "dummy_auditor_04",
      "userId": "dummy_auditor_04",
      "username": "dummy_auditor_04"
    },
    "env": {
      "application": "synth_application_04",
      "instance": "synth_instance_04",
      "st": "synth_st_04"
    },
    "st": "synth_st_04",
    "refresh_token_id": "synth_refresh_token_id_04",
    "token_id": "synth_token_id_04",
    "environnement": "synth_environnement_04",
    "status_code": "200",
    "events": [
      {
        "message": "HTTP 403 Found",
        "typeEv": ""
      }
    ]
  }
  ```
- Status update event (`STATUS_UPDATE`)

  ```json
  {
    "timestamp": "2024-10-12T19:38:56.123456789Z",
    "log_type": "KEYCLOAK",
    "uuid": "dummy_analyst_05",
    "read_timestamp": "2024-10-12T19:38:56Z",
    "source_timestamp": "2024-10-12T19:38:56.123456785Z",
    "object": "synth_object_05",
    "read_method": "synth_read_method_05",
    "stream_name": "synth_stream_name_05",
    "schema_key": "synth_schema_key_05",
    "sort_keys": "synth_sort_keys_05",
    "source_metadata": {
      "schema": "synth_schema_05",
      "table": "synth_table_05",
      "is_deleted": true,
      "change_type": "synth_change_type_05",
      "tx_id": "synth_tx_id_05",
      "lsn": "synth_lsn_05",
      "primary_keys": "synth_primary_keys_05"
    },
    "payload": {
      "id": "synth_id_05",
      "client_id": "synth_client_id_05",
      "error": "synth_error_05",
      "ip_address": "1.1.1.5",
      "realm_id": "synth_realm_id_05",
      "session_id": "synth_session_id_05",
      "event_time": "2024-10-12T19:38:56Z",
      "user_id": "dummy_analyst_05",
      "details_json": "{\"parameters\":{}}"
    },
    "username": "dummy_analyst_05",
    "redirect_uri": "synth_redirect_uri_05",
    "ctx": {
      "actionId": "synth_actionId_05",
      "clientId": "synth_clientId_05",
      "executionId": "synth_executionId_05",
      "ip": "1.1.1.5",
      "messageId": "dummy_analyst_05@dummy.net",
      "process": "synth_process_05",
      "realmId": "synth_realmId_05",
      "referer": "synth_referer_05",
      "requestId": "synth_requestId_05",
      "sessionId": "synth_sessionId_05",
      "source": "synth_source_05",
      "trackerId": "synth_trackerId_05",
      "uri": "synth_uri_05",
      "userAgent": "dummy_analyst_05",
      "userId": "dummy_analyst_05",
      "username": "dummy_analyst_05"
    },
    "env": {
      "application": "synth_application_05",
      "instance": "synth_instance_05",
      "st": "synth_st_05"
    },
    "st": "synth_st_05",
    "refresh_token_id": "synth_refresh_token_id_05",
    "token_id": "synth_token_id_05",
    "environnement": "synth_environnement_05",
    "status_code": "200",
    "events": [
      {
        "message": "HTTP 404 Found",
        "typeEv": ""
      }
    ]
  }
  ```
- Uncategorized user event (`USER_UNCATEGORIZED`)

  ```json
  {
    "timestamp": "2024-10-12T20:45:09.123456789Z",
    "log_type": "KEYCLOAK",
    "uuid": "dummy_user_01",
    "read_timestamp": "2024-10-12T20:45:09Z",
    "source_timestamp": "2024-10-12T20:45:09.123456786Z",
    "object": "synth_object_06",
    "read_method": "synth_read_method_06",
    "stream_name": "synth_stream_name_06",
    "schema_key": "synth_schema_key_06",
    "sort_keys": "synth_sort_keys_06",
    "source_metadata": {
      "schema": "synth_schema_06",
      "table": "synth_table_06",
      "is_deleted": false,
      "change_type": "synth_change_type_06",
      "tx_id": "synth_tx_id_06",
      "lsn": "synth_lsn_06",
      "primary_keys": "synth_primary_keys_06"
    },
    "payload": {
      "id": "synth_id_06",
      "client_id": "synth_client_id_06",
      "error": "synth_error_06",
      "realm_id": "synth_realm_id_06",
      "session_id": "synth_session_id_06",
      "event_time": "2024-10-12T20:45:09Z",
      "user_id": "dummy_user_01",
      "details_json": "{\"parameters\":{}}"
    },
    "username": "dummy_user_01",
    "redirect_uri": "synth_redirect_uri_06",
    "ctx": {
      "actionId": "synth_actionId_06",
      "clientId": "synth_clientId_06",
      "executionId": "synth_executionId_06",
      "host": "host-01.dummy.net",
      "messageId": "dummy_user_01@dummy.net",
      "process": "synth_process_06",
      "realmId": "synth_realmId_06",
      "referer": "synth_referer_06",
      "requestId": "synth_requestId_06",
      "sessionId": "synth_sessionId_06",
      "source": "synth_source_06",
      "trackerId": "synth_trackerId_06",
      "uri": "synth_uri_06",
      "userAgent": "dummy_user_01",
      "userId": "dummy_user_01",
      "username": "dummy_user_01"
    },
    "env": {
      "application": "synth_application_06",
      "instance": "synth_instance_06",
      "st": "synth_st_06"
    },
    "st": "synth_st_06",
    "refresh_token_id": "synth_refresh_token_id_06",
    "token_id": "synth_token_id_06",
    "environnement": "synth_environnement_06",
    "status_code": "200",
    "events": [
      {
        "message": "HTTP 200 Found",
        "typeEv": ""
      }
    ]
  }
  ```
- Generic event (`GENERIC_EVENT`)

  ```json
  {
    "timestamp": "2024-10-12T21:52:22.123456789Z",
    "log_type": "KEYCLOAK",
    "read_timestamp": "2024-10-12T21:52:22Z",
    "source_timestamp": "2024-10-12T21:52:22.123456787Z",
    "object": "synth_object_07",
    "read_method": "synth_read_method_07",
    "stream_name": "synth_stream_name_07",
    "schema_key": "synth_schema_key_07",
    "sort_keys": "synth_sort_keys_07",
    "source_metadata": {
      "schema": "synth_schema_07",
      "table": "synth_table_07",
      "is_deleted": true,
      "change_type": "synth_change_type_07",
      "tx_id": "synth_tx_id_07",
      "lsn": "synth_lsn_07",
      "primary_keys": "synth_primary_keys_07"
    },
    "payload": {
      "id": "synth_id_07",
      "client_id": "synth_client_id_07",
      "error": "synth_error_07",
      "realm_id": "synth_realm_id_07",
      "session_id": "synth_session_id_07",
      "event_time": "2024-10-12T21:52:22Z",
      "user_id": "dummy_admin_02",
      "details_json": "{\"parameters\":{}}"
    },
    "username": "dummy_admin_02",
    "redirect_uri": "synth_redirect_uri_07",
    "ctx": {
      "actionId": "synth_actionId_07",
      "clientId": "synth_clientId_07",
      "executionId": "synth_executionId_07",
      "host": "gw-edge-02.dummy.net",
      "messageId": "dummy_admin_02@dummy.net",
      "process": "synth_process_07",
      "realmId": "synth_realmId_07",
      "referer": "synth_referer_07",
      "requestId": "synth_requestId_07",
      "sessionId": "synth_sessionId_07",
      "source": "synth_source_07",
      "trackerId": "synth_trackerId_07",
      "uri": "synth_uri_07",
      "userAgent": "dummy_admin_02",
      "userId": "dummy_admin_02"
    },
    "env": {
      "application": "synth_application_07",
      "instance": "synth_instance_07",
      "st": "synth_st_07"
    },
    "st": "synth_st_07",
    "refresh_token_id": "synth_refresh_token_id_07",
    "token_id": "synth_token_id_07",
    "environnement": "synth_environnement_07",
    "status_code": "200",
    "events": [
      {
        "message": "HTTP 302 Found",
        "typeEv": ""
      }
    ]
  }
  ```

## UDM mapping table

| Log Field | UDM Mapping | Logic |
|---|---|---|
| payload.client_id | additional.fields | Merged with fields created from payload.client_id, payload.realm_id |
| payload.realm_id | additional.fields |   |
| source_timestamp | metadata.event_timestamp | Parsed using date filter with patterns ISO8601 and yyyy-MM-dd'T'HH:mm:ss.SSSZ |
| payload.ip_address | metadata.event_type | Set to "STATUS_UPDATE" if payload.ip_address is not empty, else "USER_UNCATEGORIZED" if uuid is not empty, else "GENERIC_EVENT" |
| uuid | metadata.event_type |   |
| payload.type | metadata.product_event_type | Value copied directly |
| payload.session_id | network.session_id | Value copied directly |
| payload.ip_address | principal.ip | Value copied directly |
| source_metadata.schema | principal.resource.attribute.labels | Merged with labels created from source_metadata.schema, source_metadata.table, source_metadata.is_deleted (converted to string), source_metadata.change_type, source_metadata.tx_id, source_metadata.lsn |
| source_metadata.table | principal.resource.attribute.labels |   |
| source_metadata.is_deleted | principal.resource.attribute.labels |   |
| source_metadata.change_type | principal.resource.attribute.labels |   |
| source_metadata.tx_id | principal.resource.attribute.labels |   |
| source_metadata.lsn | principal.resource.attribute.labels |   |
| uuid | principal.user.userid | Value copied directly |
| object | security_result.detection_fields | Merged with labels created from object, read_method, payload.id |
| read_method | security_result.detection_fields |   |
| payload.id | security_result.detection_fields |   |
| redirect_uri | target.url | Value copied directly |
| username | target.user.userid | Value copied directly |
| metadata.product_name | metadata.product_name | Set to "KEYCLOAK" |
| metadata.vendor_name | metadata.vendor_name | Set to "KEYCLOAK" |
| `username" from "details_json` | `target.user.userid` | Mapped from changelog |
| `redirect_uri" from "details_json` | `target.url` | Mapped from changelog |
| `realm_id" and "client_id` | `additional.fields` | Mapped from changelog |

## Change Log

[View the Change Log for this parser](https://docs.cloud.google.com/chronicle/docs/ingestion/parser-list/keycloak-changelog.md.txt)

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)