diff --git a/website/docs/add-secure-apps/flows-stages/stages/user_login/index.md b/website/docs/add-secure-apps/flows-stages/stages/user_login/index.md
index cefef51426..2a7730a61d 100644
--- a/website/docs/add-secure-apps/flows-stages/stages/user_login/index.md
+++ b/website/docs/add-secure-apps/flows-stages/stages/user_login/index.md
@@ -40,7 +40,7 @@ When creating or editing this stage in the UI of the Admin interface, you can se
When configured, all sessions authenticated by this stage will be bound to the selected network and/or GeoIP criteria.
- Sessions that break this binding will be terminated on use. The created [`logout`](../../../../sys-mgmt/events/index.md#logout) event will contain additional data related to what caused the binding to be broken:
+ Sessions that break this binding will be terminated on use. The created [`logout`](../../../../sys-mgmt/events/event-actions#logout) event will contain additional data related to what caused the binding to be broken:
```json
{
diff --git a/website/docs/sys-mgmt/events/event-actions.md b/website/docs/sys-mgmt/events/event-actions.md
new file mode 100644
index 0000000000..35b57b2652
--- /dev/null
+++ b/website/docs/sys-mgmt/events/event-actions.md
@@ -0,0 +1,308 @@
+---
+Title: Event actions
+---
+
+Whenever any of the following actions occur, an event is created. Actions are used to define [Notification Rules](notifications.md).
+
+### `login`
+
+A user logs in (including the source, if available)
+
+
+Example
+
+```json
+{
+ "pk": "f00f54e7-2b38-421f-bc78-e61f950048d6",
+ "user": {
+ "pk": 1,
+ "email": "root@localhost",
+ "username": "akadmin"
+ },
+ "action": "login",
+ "app": "authentik.events.signals",
+ "context": {
+ "auth_method": "password",
+ "http_request": {
+ "args": {
+ "query": "next=%2F"
+ },
+ "path": "/api/v3/flows/executor/default-authentication-flow/",
+ "method": "GET"
+ },
+ "auth_method_args": {}
+ },
+ "client_ip": "::1",
+ "created": "2023-02-15T15:33:42.771091Z",
+ "expires": "2024-02-15T15:33:42.770425Z",
+ "brand": {
+ "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
+ "app": "authentik_brands",
+ "name": "Default brand",
+ "model_name": "brand"
+ }
+}
+```
+
+
+
+### `login_failed`
+
+A failed login attempt
+
+
+Example
+
+```json
+{
+ "pk": "2779b173-eb2a-4c2b-a1a4-8283eda308d7",
+ "user": {
+ "pk": 2,
+ "email": "",
+ "username": "AnonymousUser"
+ },
+ "action": "login_failed",
+ "app": "authentik.events.signals",
+ "context": {
+ "stage": {
+ "pk": "7e88f4a991c442c1a1335d80f0827d7f",
+ "app": "authentik_stages_password",
+ "name": "default-authentication-password",
+ "model_name": "passwordstage"
+ },
+ "password": "********************",
+ "username": "akadmin",
+ "http_request": {
+ "args": {
+ "query": "next=%2F"
+ },
+ "path": "/api/v3/flows/executor/default-authentication-flow/",
+ "method": "POST"
+ }
+ },
+ "client_ip": "::1",
+ "created": "2023-02-15T15:32:55.319608Z",
+ "expires": "2024-02-15T15:32:55.314581Z",
+ "brand": {
+ "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
+ "app": "authentik_brands",
+ "name": "Default brand",
+ "model_name": "brand"
+ }
+}
+```
+
+
+
+### `logout`
+
+A user logs out.
+
+
+Example
+
+```json
+{
+ "pk": "474ffb6b-77e3-401c-b681-7d618962440f",
+ "user": {
+ "pk": 1,
+ "email": "root@localhost",
+ "username": "akadmin"
+ },
+ "action": "logout",
+ "app": "authentik.events.signals",
+ "context": {
+ "http_request": {
+ "args": {
+ "query": ""
+ },
+ "path": "/api/v3/flows/executor/default-invalidation-flow/",
+ "method": "GET"
+ }
+ },
+ "client_ip": "::1",
+ "created": "2023-02-15T15:39:55.976243Z",
+ "expires": "2024-02-15T15:39:55.975535Z",
+ "brand": {
+ "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
+ "app": "authentik_brands",
+ "name": "Default brand",
+ "model_name": "brand"
+ }
+}
+```
+
+
+
+### `user_write`
+
+A user is written to during a flow execution.
+
+
+Example
+
+```json
+{
+ "pk": "d012e8af-cb94-4fa2-9e92-961e4eebc060",
+ "user": {
+ "pk": 1,
+ "email": "root@localhost",
+ "username": "akadmin"
+ },
+ "action": "user_write",
+ "app": "authentik.events.signals",
+ "context": {
+ "name": "authentik Default Admin",
+ "email": "root@localhost",
+ "created": false,
+ "username": "akadmin",
+ "attributes": {
+ "settings": {
+ "locale": ""
+ }
+ },
+ "http_request": {
+ "args": {
+ "query": ""
+ },
+ "path": "/api/v3/flows/executor/default-user-settings-flow/",
+ "method": "GET"
+ }
+ },
+ "client_ip": "::1",
+ "created": "2023-02-15T15:41:18.411017Z",
+ "expires": "2024-02-15T15:41:18.410276Z",
+ "brand": {
+ "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
+ "app": "authentik_brands",
+ "name": "Default brand",
+ "model_name": "brand"
+ }
+}
+```
+
+
+
+### `suspicious_request`
+
+A suspicious request has been received (for example, a revoked token was used).
+
+### `password_set`
+
+A user sets their password.
+
+### `secret_view`
+
+A user views a token's/certificate's data.
+
+### `secret_rotate`
+
+A token was rotated automatically by authentik.
+
+### `invitation_used`
+
+An invitation is used.
+
+### `authorize_application`
+
+A user authorizes an application.
+
+
+Example
+
+```json
+{
+ "pk": "f52f9eb9-dc2a-4f1e-afea-ad5af90bf680",
+ "user": {
+ "pk": 1,
+ "email": "root@localhost",
+ "username": "akadmin"
+ },
+ "action": "authorize_application",
+ "app": "authentik.providers.oauth2.views.authorize",
+ "context": {
+ "asn": {
+ "asn": 6805,
+ "as_org": "Telefonica Germany",
+ "network": "5.4.0.0/14"
+ },
+ "geo": {
+ "lat": 42.0,
+ "city": "placeholder",
+ "long": 42.0,
+ "country": "placeholder",
+ "continent": "placeholder"
+ },
+ "flow": "53287faa8a644b6cb124cb602a84282f",
+ "scopes": "ak_proxy profile openid email",
+ "http_request": {
+ "args": {
+ "query": "[...]"
+ },
+ "path": "/api/v3/flows/executor/default-provider-authorization-implicit-consent/",
+ "method": "GET"
+ },
+ "authorized_application": {
+ "pk": "bed6a2495fdc4b2e8c3f93cb2ed7e021",
+ "app": "authentik_core",
+ "name": "Alertmanager",
+ "model_name": "application"
+ }
+ },
+ "client_ip": "::1",
+ "created": "2023-02-15T10:02:48.615499Z",
+ "expires": "2023-04-26T10:02:48.612809Z",
+ "brand": {
+ "pk": "10800be643d44842ab9d97cb5f898ce9",
+ "app": "authentik_brands",
+ "name": "Default brand",
+ "model_name": "brand"
+ }
+}
+```
+
+
+
+### `source_linked`
+
+A user links a source to their account
+
+### `impersonation_started` / `impersonation_ended`
+
+A user starts/ends impersonation, including the user that was impersonated
+
+### `policy_execution`
+
+A policy is executed (when a policy has "Execution Logging" enabled).
+
+### `policy_exception` / `property_mapping_exception`
+
+A policy or property mapping causes an exception
+
+### `system_task_exception`
+
+An exception occurred in a system task.
+
+### `system_exception`
+
+A general exception in authentik occurred.
+
+### `configuration_error`
+
+A configuration error occurs, for example during the authorization of an application
+
+### `model_created` / `model_updated` / `model_deleted`
+
+Logged when any model is created/updated/deleted, including the user that sent the request.
+
+:::info
+Starting with authentik 2024.2, when a valid enterprise license is installed, these entries will contain additional audit data, including which fields were changed with this event, their previous values and their new values.
+:::
+
+### `email_sent`
+
+An email has been sent. Included is the email that was sent.
+
+### `update_available`
+
+An update is available
diff --git a/website/docs/sys-mgmt/events/event_matcher.png b/website/docs/sys-mgmt/events/event_matcher.png
deleted file mode 100644
index 61d659dfa0..0000000000
Binary files a/website/docs/sys-mgmt/events/event_matcher.png and /dev/null differ
diff --git a/website/docs/sys-mgmt/events/index.md b/website/docs/sys-mgmt/events/index.md
index 715137e1e3..b872f72f7b 100644
--- a/website/docs/sys-mgmt/events/index.md
+++ b/website/docs/sys-mgmt/events/index.md
@@ -4,319 +4,14 @@ title: Events
Events are authentik's built-in logging system. Every event is logged, whether it is initiated by a user or by authentik.
-Events can be used to define [notification rules](notifications.md), with specified [transport options](transports.md) of local (in the authentik UI), email or webhook.
+Events can be used to define [notification rules](notifications.md), with specified [transport options](transports.md) of either local (in the authentik UI), email, or webhook.
Certain information is stripped from events, to ensure that no passwords or other credentials are saved in the log.
-## Event retention
+## Event retention and forwarding
The event retention 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 pretty low (for example, `days=1`).
+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`).
-## Event actions
-
-Whenever any of the following actions occur, an event is created.
-
-### `login`
-
-A user logs in (including the source, if available)
-
-
-Example
-
-```json
-{
- "pk": "f00f54e7-2b38-421f-bc78-e61f950048d6",
- "user": {
- "pk": 1,
- "email": "root@localhost",
- "username": "akadmin"
- },
- "action": "login",
- "app": "authentik.events.signals",
- "context": {
- "auth_method": "password",
- "http_request": {
- "args": {
- "query": "next=%2F"
- },
- "path": "/api/v3/flows/executor/default-authentication-flow/",
- "method": "GET"
- },
- "auth_method_args": {}
- },
- "client_ip": "::1",
- "created": "2023-02-15T15:33:42.771091Z",
- "expires": "2024-02-15T15:33:42.770425Z",
- "brand": {
- "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
- "app": "authentik_brands",
- "name": "Default brand",
- "model_name": "brand"
- }
-}
-```
-
-
-
-### `login_failed`
-
-A failed login attempt
-
-
-Example
-
-```json
-{
- "pk": "2779b173-eb2a-4c2b-a1a4-8283eda308d7",
- "user": {
- "pk": 2,
- "email": "",
- "username": "AnonymousUser"
- },
- "action": "login_failed",
- "app": "authentik.events.signals",
- "context": {
- "stage": {
- "pk": "7e88f4a991c442c1a1335d80f0827d7f",
- "app": "authentik_stages_password",
- "name": "default-authentication-password",
- "model_name": "passwordstage"
- },
- "password": "********************",
- "username": "akadmin",
- "http_request": {
- "args": {
- "query": "next=%2F"
- },
- "path": "/api/v3/flows/executor/default-authentication-flow/",
- "method": "POST"
- }
- },
- "client_ip": "::1",
- "created": "2023-02-15T15:32:55.319608Z",
- "expires": "2024-02-15T15:32:55.314581Z",
- "brand": {
- "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
- "app": "authentik_brands",
- "name": "Default brand",
- "model_name": "brand"
- }
-}
-```
-
-
-
-### `logout`
-
-A user logs out.
-
-
-Example
-
-```json
-{
- "pk": "474ffb6b-77e3-401c-b681-7d618962440f",
- "user": {
- "pk": 1,
- "email": "root@localhost",
- "username": "akadmin"
- },
- "action": "logout",
- "app": "authentik.events.signals",
- "context": {
- "http_request": {
- "args": {
- "query": ""
- },
- "path": "/api/v3/flows/executor/default-invalidation-flow/",
- "method": "GET"
- }
- },
- "client_ip": "::1",
- "created": "2023-02-15T15:39:55.976243Z",
- "expires": "2024-02-15T15:39:55.975535Z",
- "brand": {
- "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
- "app": "authentik_brands",
- "name": "Default brand",
- "model_name": "brand"
- }
-}
-```
-
-
-
-### `user_write`
-
-A user is written to during a flow execution.
-
-
-Example
-
-```json
-{
- "pk": "d012e8af-cb94-4fa2-9e92-961e4eebc060",
- "user": {
- "pk": 1,
- "email": "root@localhost",
- "username": "akadmin"
- },
- "action": "user_write",
- "app": "authentik.events.signals",
- "context": {
- "name": "authentik Default Admin",
- "email": "root@localhost",
- "created": false,
- "username": "akadmin",
- "attributes": {
- "settings": {
- "locale": ""
- }
- },
- "http_request": {
- "args": {
- "query": ""
- },
- "path": "/api/v3/flows/executor/default-user-settings-flow/",
- "method": "GET"
- }
- },
- "client_ip": "::1",
- "created": "2023-02-15T15:41:18.411017Z",
- "expires": "2024-02-15T15:41:18.410276Z",
- "brand": {
- "pk": "fcba828076b94dedb2d5a6b4c5556fa1",
- "app": "authentik_brands",
- "name": "Default brand",
- "model_name": "brand"
- }
-}
-```
-
-
-
-### `suspicious_request`
-
-A suspicious request has been received (for example, a revoked token was used).
-
-### `password_set`
-
-A user sets their password.
-
-### `secret_view`
-
-A user views a token's/certificate's data.
-
-### `secret_rotate`
-
-A token was rotated automatically by authentik.
-
-### `invitation_used`
-
-An invitation is used.
-
-### `authorize_application`
-
-A user authorizes an application.
-
-
-Example
-
-```json
-{
- "pk": "f52f9eb9-dc2a-4f1e-afea-ad5af90bf680",
- "user": {
- "pk": 1,
- "email": "root@localhost",
- "username": "akadmin"
- },
- "action": "authorize_application",
- "app": "authentik.providers.oauth2.views.authorize",
- "context": {
- "asn": {
- "asn": 6805,
- "as_org": "Telefonica Germany",
- "network": "5.4.0.0/14"
- },
- "geo": {
- "lat": 42.0,
- "city": "placeholder",
- "long": 42.0,
- "country": "placeholder",
- "continent": "placeholder"
- },
- "flow": "53287faa8a644b6cb124cb602a84282f",
- "scopes": "ak_proxy profile openid email",
- "http_request": {
- "args": {
- "query": "[...]"
- },
- "path": "/api/v3/flows/executor/default-provider-authorization-implicit-consent/",
- "method": "GET"
- },
- "authorized_application": {
- "pk": "bed6a2495fdc4b2e8c3f93cb2ed7e021",
- "app": "authentik_core",
- "name": "Alertmanager",
- "model_name": "application"
- }
- },
- "client_ip": "::1",
- "created": "2023-02-15T10:02:48.615499Z",
- "expires": "2023-04-26T10:02:48.612809Z",
- "brand": {
- "pk": "10800be643d44842ab9d97cb5f898ce9",
- "app": "authentik_brands",
- "name": "Default brand",
- "model_name": "brand"
- }
-}
-```
-
-
-
-### `source_linked`
-
-A user links a source to their account
-
-### `impersonation_started` / `impersonation_ended`
-
-A user starts/ends impersonation, including the user that was impersonated
-
-### `policy_execution`
-
-A policy is executed (when a policy has "Execution Logging" enabled).
-
-### `policy_exception` / `property_mapping_exception`
-
-A policy or property mapping causes an exception
-
-### `system_task_exception`
-
-An exception occurred in a system task.
-
-### `system_exception`
-
-A general exception in authentik occurred.
-
-### `configuration_error`
-
-A configuration error occurs, for example during the authorization of an application
-
-### `model_created` / `model_updated` / `model_deleted`
-
-Logged when any model is created/updated/deleted, including the user that sent the request.
-
-:::info
-Starting with authentik 2024.2, when a valid enterprise license is installed, these entries will contain additional audit data, including which fields were changed with this event, their previous values and their new values.
-:::
-
-### `email_sent`
-
-An email has been sent. Included is the email that was sent.
-
-### `update_available`
-
-An update is available
+## Audit logging
diff --git a/website/docs/sys-mgmt/events/logging-events.md b/website/docs/sys-mgmt/events/logging-events.md
new file mode 100644
index 0000000000..6329ac057f
--- /dev/null
+++ b/website/docs/sys-mgmt/events/logging-events.md
@@ -0,0 +1,5 @@
+---
+Title: Logging events
+---
+
+shshhs
diff --git a/website/docs/sys-mgmt/events/notifications.md b/website/docs/sys-mgmt/events/notifications.md
index 035e1709b8..8a2b37d65c 100644
--- a/website/docs/sys-mgmt/events/notifications.md
+++ b/website/docs/sys-mgmt/events/notifications.md
@@ -3,16 +3,32 @@ title: Notifications
---
:::note
-To prevent infinite loops (events created by policies which are attached to a Notification rule), **any events created by a policy which is attached to any Notification Rules do not trigger notifications.**
+To prevent infinite loops of cause and effect (events created by policies which are attached to a notification rule), _any events created by a policy which is attached to any notification rules do not trigger notifications._
:::
-## Filtering Events
+An authentik administrator can create notification rules based on the creation of specified events. Filtering of events is processed by the authentik Policy Engine, using a combination of both 1) a policy and 2) a notification rule.
-An authentik administrator can create notification rules based on the creation of specified events. Filtering is done by using the Policy Engine. You can do simple filtering using the "Event Matcher Policy" type.
+## Workflow overview
-
+To receive notifications about events, follow this workflow:
-An event has to match all configured fields, otherwise the rule will not trigger.
+1. [Create a transport](./transports.md#create-a-transport) (or use an existing default transport)
+2. [Create a policy](#create-a-policy)
+3. [Create a notification rule, and bind the policy to the rule](#create-a-notification-rule)
+
+## Create a policy
+
+First you need to create a policy, either the **Event Matcher** policy or a custom Expression policy.
+
+### **Event Matcher** policy
+
+For simple filtering you can [create and configure](../../customize/policies/working_with_policies.md) a new **Event Matcher** policy to specify exactly which events (known as _Actions_ in the policy) you want to be notified about. For example, you get chose to create a policy for every time a user deletes a model object, or fails to successfully log in.
+
+The authentik policy engine....
+
+Be aware that an event has to match all configured fields in the policy, otherwise the notification rule will not trigger.
+
+### Expression policy for events
To match events with an "Expression Policy", you can write code like so:
@@ -23,14 +39,14 @@ if "event" not in request.context:
return ip_address(request.context["event"].client_ip) in ip_network('192.0.2.0/24')
```
-## Selecting who gets notified
+## Create a notification rule
-After you've created the policies to match the events you want, create a "Notification Rule".
+After you've created the policies to match the events you want, create a **"**Notification Rule\*\*.
You have to select which group the generated notification should be sent to. If left empty, the rule will be disabled.
:::info
-Before authentik 2023.5, when no group is selected, policies bound to the rule are not executed. Starting with authentik 2023.5, policies are executed even when no group is selected.
+Be aware that policies are executed even when no group is selected.
:::
You also have to select which transports should be used to send the notification.
diff --git a/website/docs/sys-mgmt/events/transports.md b/website/docs/sys-mgmt/events/transports.md
index 533c6fdba5..90418037cb 100644
--- a/website/docs/sys-mgmt/events/transports.md
+++ b/website/docs/sys-mgmt/events/transports.md
@@ -2,9 +2,26 @@
title: Transports
---
-Notifications can be sent to users via multiple mediums. By default, the [global email configuration](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended) will be used.
+To receive notifications about events, you will need to [create](#create-a-transport) a transport object, then create a notification rule and a policy. For details on this workflow refer to
-## Generic Webhook
+## Transport types
+
+Notifications can be sent to users via multiple mediums, or _transports_:
+
+- Local
+- Email
+- Webhook (generic)
+- Webhook (Slack/Discord)
+
+### Local transport
+
+This transport will manifest the notification within the authentik user interface (UI).
+
+### Email
+
+select this transport to send event notificstions to an email address. Note that by default, the [global email configuration](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended) is used.
+
+### Webhook (generic)
This will send a POST request to the given URL with the following contents:
@@ -31,6 +48,10 @@ return {
}
```
-## Slack Webhook
+### Webhook (Slack or Discord)
This sends a request using the Slack-specific format. This is also compatible with Discord's webhooks by appending `/slack` to the Discord webhook URL.
+
+## Create a transport
+
+dfvfd
diff --git a/website/sidebars/docs.mjs b/website/sidebars/docs.mjs
index 3f853cf68b..7c9d616536 100644
--- a/website/sidebars/docs.mjs
+++ b/website/sidebars/docs.mjs
@@ -606,7 +606,12 @@ const items = [
type: "doc",
id: "sys-mgmt/events/index",
},
- items: ["sys-mgmt/events/notifications", "sys-mgmt/events/transports"],
+ items: [
+ "sys-mgmt/events/notifications",
+ "sys-mgmt/events/transports",
+ "sys-mgmt/events/logging-events",
+ "sys-mgmt/events/event-actions",
+ ],
},
"sys-mgmt/certificates",
"sys-mgmt/settings",