Compare commits
6 Commits
dependabot
...
docs-event
| Author | SHA1 | Date | |
|---|---|---|---|
| e5c8229a83 | |||
| 390f4d87da | |||
| 9900312b5d | |||
| 5a69ded74d | |||
| fbc7dbb151 | |||
| 4e2e678de3 |
@ -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
|
||||
{
|
||||
|
||||
308
website/docs/sys-mgmt/events/event-actions.md
Normal file
308
website/docs/sys-mgmt/events/event-actions.md
Normal file
@ -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)
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `login_failed`
|
||||
|
||||
A failed login attempt
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `logout`
|
||||
|
||||
A user logs out.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `user_write`
|
||||
|
||||
A user is written to during a flow execution.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `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.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `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
|
||||
BIN
website/docs/sys-mgmt/events/event-map-chart.png
Normal file
BIN
website/docs/sys-mgmt/events/event-map-chart.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 548 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 46 KiB |
BIN
website/docs/sys-mgmt/events/events-diffs.png
Normal file
BIN
website/docs/sys-mgmt/events/events-diffs.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 242 KiB |
@ -4,319 +4,20 @@ 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.
|
||||
Certain information is stripped from events, to ensure that no passwords or other credentials are saved in the log.
|
||||
|
||||
Certain information is stripped from events, to ensure no passwords or other credentials are saved in the log.
|
||||
## About notifications
|
||||
|
||||
## Event retention
|
||||
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.
|
||||
|
||||
The event retention is configured in the **System > Settings** area of the Admin interface, with the default being set to 365 days.
|
||||
## About logging
|
||||
|
||||
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`).
|
||||
Logging of events in authentik provides several layers of transparency about user and system actions, from a quick view on the Overview dashboard, to a full, searchable list of all events, with a volume graph to highlight any spikes, in the Admin interface under **Events > Logs**.
|
||||
|
||||
## Event actions
|
||||
For more information refer to our [Logging documentation](./logging-events.md).
|
||||
|
||||
Whenever any of the following actions occur, an event is created.
|
||||
## Event retention and forwarding
|
||||
|
||||
### `login`
|
||||
The event retention setting is configured in the **System > Settings** area of the Admin interface, with the default being set to 365 days.
|
||||
|
||||
A user logs in (including the source, if available)
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `login_failed`
|
||||
|
||||
A failed login attempt
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `logout`
|
||||
|
||||
A user logs out.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `user_write`
|
||||
|
||||
A user is written to during a flow execution.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `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.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### `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
|
||||
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`).
|
||||
|
||||
31
website/docs/sys-mgmt/events/logging-events.md
Normal file
31
website/docs/sys-mgmt/events/logging-events.md
Normal file
@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Logging events
|
||||
---
|
||||
|
||||
Logs are an important tool for system diagnoses, event auditing, user management, reports, and so much more. Detailed information about events are captured, including the IP address of the client that triggered the event, the user, the date and timestamp, and the exact action made.
|
||||
|
||||
Event logging in authentik is highly configurable; you can define the [retention period](./index.md#event-retention-and-forwarding) for storing and displaying events, configure which exact events should trigger a [notification](./notifications.md), and view low-level details about when and where the event happened.
|
||||
|
||||
### Troubleshooting with event logs
|
||||
|
||||
For details about troubleshooting using logs, including setting the log level (info, warning, etc.), enabling `trace` mode, viewing past logs, and streaming logs in real-time, refer to [Capturing logs in authentik](../../troubleshooting/logs.mdx).
|
||||
|
||||
## Enhanced audit logging (Enterprise)
|
||||
|
||||
In the enterprise version, each Event details page in the UI, details about each event are abstracted and displayed in an easy-to-access table, and for any event that involves an object being created or modified, the code `diffs` are displayed as well. This allows you to quickly see the previous and new configuration settings.
|
||||
|
||||
For example, say an authentik administraotr updates a user's email address; the old email address and the new one are shown when you drill down in that event's details.
|
||||
|
||||
|
||||
|
||||
Areas of the authentik UI where you can view these audits details are:
|
||||
|
||||
- **Admin interface > Dashboards > Overview**: In the **Recent events** section, click the name of an event to view details.
|
||||
|
||||
- **Admin interface > Events > Logs**: In the list of events, click the arrow toggle beside the name of the even that you want to view details for.
|
||||
|
||||
## Viewing events in maps and charts (Enterprise)
|
||||
|
||||
With the enterprise version, you can view recent events on both a world map view with pinpoints of where events occurred and also as a color-coded chart displaying type of event and volume of each type.
|
||||
|
||||
|
||||
@ -3,16 +3,34 @@ 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 (or use an existing default transport)
|
||||
2. Create a policy
|
||||
3. Create a notification rule, and bind the policy to the rule
|
||||
|
||||
## 1. Create a notification transport
|
||||
|
||||
A transport method (email, UI, webhook) is how the notifications are delivered to a user. Follow these [instructions](./transports.md#create-a-transport) for creating a transport.
|
||||
|
||||
## 2. Create a policy
|
||||
|
||||
You will need to create a policy (either the **Event Matcher** policy or a custom Expression policy) that defines which events will trigger a notification.
|
||||
|
||||
### **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 can chose to create a policy for every time a user deletes a model object, or whenever any user fails to successfully log in.
|
||||
|
||||
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,17 +41,23 @@ 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
|
||||
## 3. Create a notification rule and bind it to the policy
|
||||
|
||||
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.
|
||||
1. Log in as an administrator, open the authentik Admin interface, and navigate to **Event > Notification Rules**.
|
||||
|
||||
2. Click **Create** to add a new notification rule, or click the **Edit** icon next to an existing rule to modify it.
|
||||
|
||||
3. Define the policy configurations, and click **Create** or \*\*Update to save the settings.
|
||||
|
||||
- Note that you have to select which group the generated notification should be sent to. If left empty, the rule will be disabled.
|
||||
- You also have to select which [transports](./transports.md) should be used to send the notification. A transport with the name "default-email-transport" is created by default. This transport will use the [global email configuration](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended).
|
||||
|
||||
4. In the list of Notification rules, click the arrow in the row of the Notification rule to expand the details of the rule.
|
||||
|
||||
5. Click **Bind existing Policy/Group/User**, and in the **Create Binding** modal, select the policy that you created for this notification rule and then click **Create** to finalize the binding.
|
||||
|
||||
:::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.
|
||||
A transport with the name "default-email-transport" is created by default. This transport will use the [global email configuration](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended).
|
||||
|
||||
Starting with authentik 2022.6, a new default transport will be created. This is because notifications are no longer created by default, they are now a transport method instead. This allows for better customization of the notification before it is created.
|
||||
|
||||
@ -2,9 +2,28 @@
|
||||
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 refer to [Workflow overview](./notifications.md#workflow-overview).
|
||||
|
||||
## Generic Webhook
|
||||
## Transport modes
|
||||
|
||||
Notifications can be sent to users via multiple mediums, or _transports_:
|
||||
|
||||
- Local (in the authentik user interface)
|
||||
- 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 notifications 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.
|
||||
|
||||
To edit an email address, follow the same instructions as above, those for configuring the email during installation.
|
||||
|
||||
### Webhook (generic)
|
||||
|
||||
This will send a POST request to the given URL with the following contents:
|
||||
|
||||
@ -31,6 +50,14 @@ 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
|
||||
|
||||
1. Log in as an administrator to the authentik Admin interface, and navigate to **Event > Notification Transports**.
|
||||
|
||||
2. Click **Create** to add a new transport, or click the **Edit** icon next to an existing transport to modify it.
|
||||
|
||||
3. Define the **Name** and **Mode** for the transport, enter required configuration settings, and then click **Create**.
|
||||
|
||||
@ -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",
|
||||
|
||||
Reference in New Issue
Block a user