From 7bdbfade30c5dc6e8d7251a18c8560f2b3a5b638 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 16 Jun 2026 11:43:18 -0400 Subject: [PATCH] website/docs: add Splunk event forwarding docs (#22938) * website/docs: add Splunk event forwarding docs Add Splunk HEC event forwarding under system event docs and keep the Splunk integration guide focused on SAML. Closes: #22223 Agent-thread: https://sdko.org/internal/thr/ak/019ea8d4-d4e4-7fc3-b3b6-aa8a16bd8d40 A7k-product: product A7k-product-repo: 3 Co-authored-by: Agent * website/docs: move Splunk event forwarding guide Move the Splunk event forwarding guide into integrations and add an Events log forwarding overview that links to it. Agent-thread: https://sdko.org/internal/thr/ak/019eb29e-1b34-7681-b887-e03907dac184 A7k-product: product A7k-product-repo: 3 Co-authored-by: Agent * website/integrations: remove Splunk HEC port Use the generic splunk.company HEC endpoint in the Splunk event forwarding guide instead of hardcoding a deployment-specific port. Agent-thread: https://sdko.org/internal/thr/ak/019eb29e-1b34-7681-b887-e03907dac184 A7k-product: product A7k-product-repo: 3 Co-authored-by: Agent * Update website/docs/sys-mgmt/events/log-forwarding.mdx Signed-off-by: Dewi Roberts --------- Signed-off-by: Dewi Roberts Co-authored-by: Agent Co-authored-by: Dewi Roberts --- website/docs/sidebar.mjs | 1 + website/docs/sys-mgmt/events/index.md | 2 + .../docs/sys-mgmt/events/log-forwarding.mdx | 21 ++++ website/integrations/categories.mjs | 1 + website/integrations/index.mdx | 8 +- .../splunk-enterprise/index.mdx | 119 ++++++++++++++++++ .../monitoring/splunk-enterprise/index.mdx | 21 ++-- 7 files changed, 163 insertions(+), 10 deletions(-) create mode 100644 website/docs/sys-mgmt/events/log-forwarding.mdx create mode 100644 website/integrations/log-forwarding/splunk-enterprise/index.mdx diff --git a/website/docs/sidebar.mjs b/website/docs/sidebar.mjs index d32fe47197..93e65ee80a 100644 --- a/website/docs/sidebar.mjs +++ b/website/docs/sidebar.mjs @@ -731,6 +731,7 @@ const items = [ items: ["sys-mgmt/events/notification_rule_expression_policies"], }, "sys-mgmt/events/transports", + "sys-mgmt/events/log-forwarding", "sys-mgmt/events/logging-events", "sys-mgmt/events/event-actions", ], diff --git a/website/docs/sys-mgmt/events/index.md b/website/docs/sys-mgmt/events/index.md index 80e3600b13..5bf05bb50a 100644 --- a/website/docs/sys-mgmt/events/index.md +++ b/website/docs/sys-mgmt/events/index.md @@ -21,3 +21,5 @@ Refer to our [Logging documentation](./logging-events.mdx) for more information. The event retention setting is configured in the **System > Settings** area of the Admin interface, with the default being set to 365 days. If you want to forward these events to another application, forward the log output of all authentik containers. Every event creation is logged with the log level "info". For this configuration, it is also recommended to set the internal retention time period to a short time frame (for example, `days=1`). + +If you want to forward authentik events to another system, see [Log forwarding](./log-forwarding.mdx). diff --git a/website/docs/sys-mgmt/events/log-forwarding.mdx b/website/docs/sys-mgmt/events/log-forwarding.mdx new file mode 100644 index 0000000000..6ef4b8e892 --- /dev/null +++ b/website/docs/sys-mgmt/events/log-forwarding.mdx @@ -0,0 +1,21 @@ +--- +title: Log forwarding +--- + +authentik records system, user, and admin activity as events. You can keep those events in authentik for investigation and audit workflows, or forward them to another system when you need longer retention, centralized search, alerting, or correlation with infrastructure and application logs. + +## Forward all event logs + +Every authentik event creation is written to the container logs at the `info` log level. To collect all events, forward the log output from all authentik containers to your logging platform. This is the recommended option when you want a complete copy of authentik events outside authentik. + +When another system becomes the long-term event store, consider reducing authentik's internal event retention period in **System** > **Settings**. For example, set the retention period to `days=1` if authentik only needs to keep a short local buffer. + +## Forward selected events + +To send selected events to another system, create an event matcher policy, a notification transport, and a notification rule. This forwards only events that match the notification rule, which is useful for security alerts, high-value audit events, or integrations that should receive a narrower event stream. + +Notification transports can send events locally, by email, or to a webhook. Webhook transports can be adapted to systems that accept HTTP event ingestion. + +## Log forwarding integrations + +For an example of integrating with a log forwarder, see [Forward events to Splunk Enterprise](/integrations/log-forwarding/splunk-enterprise/). That guide uses Splunk HTTP Event Collector (HEC), a generic webhook notification transport, and a notification rule to forward matching authentik events. diff --git a/website/integrations/categories.mjs b/website/integrations/categories.mjs index dde2b64615..0347aaf477 100644 --- a/website/integrations/categories.mjs +++ b/website/integrations/categories.mjs @@ -11,6 +11,7 @@ export default [ ["hypervisors-orchestrators", "Hypervisors / Orchestrators"], ["infrastructure", "Infrastructure"], ["learning", "Learning"], + ["log-forwarding", "Log Forwarding"], ["networking", "Networking"], ["media", "Media"], ["miscellaneous", "Miscellaneous"], diff --git a/website/integrations/index.mdx b/website/integrations/index.mdx index a079565a80..b324e35349 100644 --- a/website/integrations/index.mdx +++ b/website/integrations/index.mdx @@ -7,11 +7,11 @@ sidebar_position: 1 ## What is an integration? An integration is how authentik connects to third-party applications, directories, and other identity providers. -Integrations are grouped into two categories: **Applications** and **Sources**. +Integrations can cover application access, source authentication, directory synchronization, provisioning, and operational workflows such as log forwarding. ### Applications -Applications include vendor tools such as Google Workspace, GitHub, Slack, or AWS. These applications can be integrated with authentik to provide single sign-on capabilities to securely authenticate users. +Applications include vendor tools such as Google Workspace, GitHub, Slack, or AWS. These applications can be integrated with authentik to provide single sign-on, provisioning, policy-based access, or other workflow-specific connections. If you want to integrate an application that isn't listed, authentik can be configured to work with most applications that support authentication protocols such as [SAML](/docs/add-secure-apps/providers/saml), [OAuth and OpenID Connect](/docs/add-secure-apps/providers/oauth2). @@ -22,3 +22,7 @@ To learn more, refer to the [Applications](./applications.mdx) page. Sources let authentik use external user credentials for authentication. Supported source integrations include federated directories like Active Directory and social logins such as Facebook and Twitter. These integrations support all major protocols, including [LDAP](/docs/users-sources/sources/protocols/ldap), [SCIM](/docs/users-sources/sources/protocols/scim), [SAML](/docs/users-sources/sources/protocols/saml), and [OAuth and OpenID Connect](/docs/users-sources/sources/protocols/oauth). To learn more, refer to the [Sources](/docs/users-sources/sources) page. + +### Operational integrations + +Operational integrations connect authentik to systems that support administration, monitoring, compliance, and automation. These guides can include log forwarding, machine-to-machine identity, or product-specific configuration that is not limited to user authentication. diff --git a/website/integrations/log-forwarding/splunk-enterprise/index.mdx b/website/integrations/log-forwarding/splunk-enterprise/index.mdx new file mode 100644 index 0000000000..091e610e4a --- /dev/null +++ b/website/integrations/log-forwarding/splunk-enterprise/index.mdx @@ -0,0 +1,119 @@ +--- +title: Forward events to Splunk Enterprise +sidebar_label: Splunk Enterprise forwarding +support_level: community +--- + +authentik can forward selected events to Splunk Enterprise through a generic webhook notification transport and Splunk HTTP Event Collector (HEC). This forwards events that match a notification rule; it does not replace container, system, or reverse-proxy log collection. + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik installation. +- `splunk.company` is the FQDN of the Splunk Enterprise instance or load balancer that receives HEC traffic. +- `` is a Splunk HTTP Event Collector token used to ingest authentik events. + +:::info +This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. +::: + +## Splunk Enterprise configuration + +### Create a Splunk HEC token + +1. Log in to Splunk Enterprise with an administrator account. +2. Navigate to **Settings** > **Data inputs**. +3. Click **HTTP Event Collector**. +4. Click **New Token** and create a token for authentik events. +5. Enable the token and allow it to write to the target index. + +The HEC URL for JSON events is: + +```text +https://splunk.company/services/collector/event +``` + +If you publish HEC through a load balancer or reverse proxy, use the externally reachable HEC URL instead. + +## authentik configuration + +To forward authentik events to Splunk Enterprise, you need to create webhook mappings, a notification transport, and a notification rule. + +### Create webhook mappings + +Create a webhook body mapping that formats authentik notifications for the Splunk HEC JSON event endpoint. + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Customization** > **Property Mappings** and click **Create**. +3. Select **Webhook Mapping** and create the body mapping: + - **Name**: choose a descriptive name, for example `Splunk HEC body`. + - **Expression**: + + ```python + event = notification.event + + return { + "time": event.created.timestamp(), + "host": "authentik.company", + "sourcetype": "authentik:event", + "event": { + "action": event.action, + "app": event.app, + "body": notification.body, + "severity": notification.severity, + "client_ip": event.client_ip, + "user": event.user, + "context": event.context, + }, + } + ``` + +4. Create another **Webhook Mapping** for the HEC authorization header: + - **Name**: choose a descriptive name, for example `Splunk HEC headers`. + - **Expression**: + + ```python + return { + "Authorization": "Splunk ", + } + ``` + +### Create a webhook notification transport + +1. Navigate to **Events** > **Notification Transports** and click **New Notification Transport**. +2. Configure the transport: + - **Transport Name**: choose a descriptive name, for example `Splunk HEC`. + - **Send once**: enable this option. + - **Mode**: select **Webhook (generic)**. + - **Webhook URL**: set to the Splunk HEC event endpoint, for example `https://splunk.company/services/collector/event`. + - **Webhook Body Mapping**: select the Splunk HEC body mapping. + - **Webhook Header Mapping**: select the Splunk HEC headers mapping. +3. Click **Create Notification Transport**. + +### Create a notification rule + +1. Navigate to **Customization** > **Policies** and create an **Event Matcher Policy** for the events that should be sent to Splunk Enterprise. + - Leave the matcher fields empty to match all authentik events. + - Use the **Query** field to forward only a subset of events, such as failed logins or application authorization events. +2. Navigate to **Events** > **Notification Rules** and click **New Notification Rule**. +3. Configure the rule: + - Select a destination group. The rule must have a destination group or **Send notification to event user** enabled before authentik creates notifications. + - Select the Splunk HEC notification transport. +4. Click **Create Notification Rule**. +5. Expand the new rule, click **Create or bind...**, and bind the Event Matcher Policy that you created for Splunk Enterprise. + +## Configuration verification + +To verify log forwarding, click **Test** on the Splunk HEC notification transport in authentik. Then search Splunk Enterprise for the configured sourcetype: + +```text +sourcetype="authentik:event" +``` + +If Splunk Enterprise does not receive the test event, verify the HEC token, the `Authorization` header mapping, the HEC URL, and network access from authentik to the Splunk HEC endpoint. + +## Resources + +- [Splunk Enterprise Documentation - Format events for HTTP Event Collector](https://help.splunk.com/en/splunk-enterprise/get-data-in/get-started-with-getting-data-in/9.2/get-data-with-http-event-collector/format-events-for-http-event-collector) +- [Splunk Enterprise Documentation - HTTP Event Collector REST API endpoints](https://help.splunk.com/en/splunk-enterprise/get-data-in/get-started-with-getting-data-in/9.0/get-data-with-http-event-collector/http-event-collector-rest-api-endpoints) diff --git a/website/integrations/monitoring/splunk-enterprise/index.mdx b/website/integrations/monitoring/splunk-enterprise/index.mdx index 62b81a4cfc..1fec7f1740 100644 --- a/website/integrations/monitoring/splunk-enterprise/index.mdx +++ b/website/integrations/monitoring/splunk-enterprise/index.mdx @@ -19,20 +19,22 @@ import Tabs from "@theme/Tabs"; The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -- `splunk.company` is the FQDN of the Splunk Enterprise instance. +- `splunk.company` is the browser-facing FQDN of the Splunk Enterprise instance. Include a port in this value only if users include that port when they open Splunk Enterprise. :::info This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. ::: :::warning Lockout -Errors in the Splunk SAML configuration can lock users out of Splunk Enterprise. Keep a local Splunk administrator account available while configuring SAML. You can reach the local login page at `https://splunk.company:8000/en-US/account/login?loginType=Splunk`. +Errors in the Splunk SAML configuration can lock users out of Splunk Enterprise. Keep a local Splunk administrator account available while configuring SAML. You can reach the local login page at `https://splunk.company/en-US/account/login?loginType=Splunk`. ::: ## authentik configuration To support the integration of Splunk Enterprise with authentik, you need to create and import a self-signed certificate, create SAML property mappings, create an application/provider pair, and create application entitlements for the Splunk roles users should receive. +To forward authentik events to Splunk Enterprise, see [Forward events to Splunk Enterprise](/log-forwarding/splunk-enterprise/). + ### Create and import a self-signed certificate Splunk verifies the certificate used to sign SAML responses. Certificates generated under **System** > **Certificates** can fail Splunk's certificate validation because they are issued by the authentik internal CA instead of being directly self-signed. To avoid this, create a self-signed certificate and import it into authentik. @@ -115,9 +117,9 @@ Splunk expects the SAML assertion to include user role, email, and display name - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. - **Choose a Provider type**: select **SAML Provider** as the provider type. - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - - Set the **ACS URL** to `https://splunk.company:8000/saml/acs`. - - Set the **Audience** to `https://splunk.company:8000`. - - Set the **SLS URL** to `https://splunk.company:8000/saml/logout`. + - Set the **ACS URL** to `https://splunk.company/saml/acs`. + - Set the **Audience** to `https://splunk.company`. + - Set the **SLS URL** to `https://splunk.company/saml/logout`. - Under **Advanced protocol settings**: - Set **Signing Certificate** to the self-signed certificate that you imported earlier. - Enable **Sign assertions** and **Sign responses**. @@ -156,11 +158,14 @@ For this integration, each entitlement name must exactly match the Splunk SAML g 4. Click **SAML Configuration**. 5. Configure the SAML settings: - Upload the metadata file from authentik by dragging it into the drop zone, or paste the metadata contents into the **Metadata contents** text area. - - Set **Entity ID** to `https://splunk.company:8000`. This value must match the **Audience** value in authentik. + - Set **Entity ID** to `https://splunk.company`. This value must match the **Audience** value in authentik. - If Splunk does not populate the certificate from metadata, copy the contents of the authentik signing certificate, starting with `-----BEGIN CERTIFICATE-----`, into **IdP certificate chains**. - - Under **Advanced Settings**, set **FQDN - Host Name or IP address of the load balancer** to `https://splunk.company`. + - Under **Advanced Settings**, set **FQDN - Host Name or IP address of the load balancer** to `splunk.company`. + - Under **Advanced Settings**, set **Redirect port - load balancer port** to the browser-facing HTTPS port, usually `443`. 6. Click **Save**. +Use the same browser-facing Splunk Enterprise URL in authentik and Splunk Enterprise. Do not use an internal backend URL or IP address for the SAML **ACS URL**, **Audience**, **Entity ID**, or load balancer settings unless users open Splunk Enterprise through that same URL. + ### Configure group mappings Splunk maps values from the SAML `role` attribute to Splunk roles. The authentik property mapping sends application entitlement names in that attribute. @@ -181,7 +186,7 @@ Splunk can auto-map SAML role values to local Splunk roles with the same name. E ## Configuration verification -To verify the integration of authentik with Splunk Enterprise, navigate to the authentik User interface and click the Splunk Enterprise application to initiate a Single Sign-On login. Upon successful login, you should be redirected to Splunk Enterprise and have the appropriate permissions set by your application entitlements. +To verify SAML login, navigate to the authentik User interface and click the Splunk Enterprise application to initiate a Single Sign-On login. Upon successful login, you should be redirected to Splunk Enterprise and have the appropriate permissions set by your application entitlements. ## Resources