mirror of
https://github.com/goauthentik/authentik.git
synced 2026-06-17 19:09:11 +03:00
website/docs: capturing outpost logs (#20045)
* Start doc * WIP * WIP * Move files into directory * Add redirect for forward auth * Fix forward auth doc * Update logging-events.mdx Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Fix manually deployed outpost env variable * Update website/docs/troubleshooting/logs/outpost_logs.mdx Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Apply suggestions * Update website/docs/troubleshooting/logs/logs.mdx Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Update website/docs/troubleshooting/logs/logs.mdx Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Update website/docs/troubleshooting/logs/outpost_logs.mdx Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Update website/docs/troubleshooting/logs/outpost_logs.mdx Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Apply suggestions * Update logs.mdx Signed-off-by: Dominic R <dominic@sdko.org> * Update outpost_logs.mdx Signed-off-by: Dominic R <dominic@sdko.org> * Update outpost_logs.mdx Signed-off-by: Dominic R <dominic@sdko.org> --------- Signed-off-by: Dewi Roberts <dewi@goauthentik.io> Signed-off-by: Dominic R <dominic@sdko.org> Co-authored-by: Dominic R <dominic@sdko.org>
This commit is contained in:
Dewi Roberts
GitHub
@@ -158,7 +158,7 @@ If you're authorizing with a JWT, then `request.context["oauth_jwt"]` is availab
|
||||
|
||||
If you receive any error response from authentik it will only be a generic error, error description, and the `request_id`.
|
||||
|
||||
However, more detailed error information can be obtained from the [authentik server container logs](../../../troubleshooting/logs.mdx) by searching for the `request_id` that you're experiencing issues with.
|
||||
However, more detailed error information can be obtained from the [authentik server container logs](../../../troubleshooting/logs/logs.mdx) by searching for the `request_id` that you're experiencing issues with.
|
||||
|
||||
### OAuth introspection endpoint
|
||||
|
||||
|
||||
@@ -984,17 +984,10 @@ const items = [
|
||||
{
|
||||
//#endregion
|
||||
|
||||
//#region Forward auth
|
||||
//#region Logs
|
||||
type: "category",
|
||||
label: "Forward auth",
|
||||
items: ["troubleshooting/forward_auth/general"],
|
||||
link: {
|
||||
type: "generated-index",
|
||||
title: "Forward auth troubleshooting",
|
||||
slug: "troubleshooting/forward_auth",
|
||||
description:
|
||||
"Steps to help debug forward auth setups with various reverse proxies.",
|
||||
},
|
||||
label: "Logs",
|
||||
items: ["troubleshooting/logs/logs", "troubleshooting/logs/outpost_logs"],
|
||||
},
|
||||
{
|
||||
//#endregion
|
||||
@@ -1009,13 +1002,13 @@ const items = [
|
||||
},
|
||||
"troubleshooting/access",
|
||||
"troubleshooting/login",
|
||||
"troubleshooting/logs",
|
||||
"troubleshooting/image_upload",
|
||||
"troubleshooting/missing_permission",
|
||||
"troubleshooting/missing_admin_group",
|
||||
"troubleshooting/csrf",
|
||||
"troubleshooting/emails",
|
||||
"troubleshooting/ldap_source",
|
||||
"troubleshooting/forward_auth",
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Vendored
+5
@@ -80,6 +80,11 @@
|
||||
/security/GHSA-* /security/cves/GHSA-:splat 301!
|
||||
#endregion
|
||||
|
||||
#region Troubleshooting
|
||||
/troubleshooting/logs /troubleshooting/logs/logs 301!
|
||||
/troubleshooting/forward_auth/general /troubleshooting/forward_auth 301!
|
||||
#endregion
|
||||
|
||||
#region Integrations
|
||||
/integrations https://integrations.goauthentik.io 301!
|
||||
/integrations/* https://integrations.goauthentik.io/:splat 301!
|
||||
|
||||
@@ -10,7 +10,7 @@ Event logging in authentik is highly configurable. You can set the [retention pe
|
||||
|
||||
## Troubleshooting with event logs
|
||||
|
||||
For guidance on troubleshooting with logs, including setting log levels (info, warning, etc.), enabling `trace` mode, viewing historical logs, and streaming logs in real-time, see [Capturing logs in authentik](../../troubleshooting/logs.mdx).
|
||||
For guidance on troubleshooting with logs, including setting log levels (info, warning, etc.), enabling `trace` mode, viewing historical logs, and streaming logs in real-time, see [Capturing authentik logs](../../troubleshooting/logs/logs.mdx).
|
||||
|
||||
## Enhanced audit logging :ak-enterprise
|
||||
|
||||
@@ -24,9 +24,9 @@ In the enterprise version, two enhancements make reading the logs even easier:
|
||||
|
||||
You can view audit details in the following areas of the authentik Admin interface:
|
||||
|
||||
- **Admin interface > Dashboards > Overview**: In the **Recent events** section click an event name to view its details.
|
||||
- **Admin interface** > **Dashboards** > **Overview**: In the **Recent events** section click an event name to view its details.
|
||||
|
||||
- **Admin interface > Events > Logs**: In the event list, click the arrow toggle next to the event you want to view.
|
||||
- **Admin interface** > **Events** > **Logs**: In the event list, click the arrow toggle next to the event you want to view.
|
||||
|
||||
## Viewing events in maps and charts :ak-enterprise
|
||||
|
||||
@@ -38,7 +38,7 @@ With the enterprise version, you can view recent events on both a world map view
|
||||
|
||||
You can export your authentik instance's events to a CSV file. To generate a data export, follow these steps:
|
||||
|
||||
1. Log in to authentik as an administrator and navigate to **Events > Logs**.
|
||||
1. Log in to authentik as an administrator and navigate to **Events** > **Logs**.
|
||||
2. Set a [search query](#tell-me-more) as well as the ordering, as needed. The data export will honor these settings.
|
||||
3. Click **Export** above the event list.
|
||||
4. Confirm the export parameters in the confirmation dialog.
|
||||
@@ -49,7 +49,7 @@ To review, download, or delete past data exports, navigate to **Events** > **Dat
|
||||
|
||||
## Advanced queries for event logs:ak-enterprise {#tell-me-more}
|
||||
|
||||
You can construct advanced queries to find specific event logs. In the Admin interface, navigate to **Events > Logs**, and then use the auto-complete in the **Search** field or enter your own queries to return results with greater specificity.
|
||||
You can construct advanced queries to find specific event logs. In the Admin interface, navigate to **Events** > **Logs**, and then use the auto-complete in the **Search** field or enter your own queries to return results with greater specificity.
|
||||
|
||||
- **Field**: `action`, `event_uuid`, `app`, `client_ip`, `user`, `brand`, `context`, `created`
|
||||
- **Operators**: `=`, `!=`, `~`, `!~`, `startswith`, `not startswith`, `endswith`, `not endswith`, `in`, `not in`
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Troubleshooting Forward auth
|
||||
description: Steps to help debug forward auth setups with various reverse proxies
|
||||
---
|
||||
|
||||
## Set the log level to `trace`
|
||||
|
||||
Setting the log level to trace configures the outpost to trace-log all the headers given in forward auth requests.
|
||||
|
||||
This is helpful to confirm that certain required Headers are correctly forwarded from the reverse proxy.
|
||||
|
||||
### When using the embedded outpost
|
||||
|
||||
When using the [embedded outpost](../add-secure-apps/outposts/embedded/embedded.mdx), the logs output identically to all other authenik logs. Refer to the [Capturing authentik logs](./logs/logs.mdx) documentation for instructions on how to enable `trace` logging.
|
||||
|
||||
### When using a standalone outpost
|
||||
|
||||
When using a standalone outpost, the logs output to that specific container. Refer to the [Capturing outpost logs](./logs/outpost_logs.mdx) documentation for instructions on how to enable `trace` logging.
|
||||
|
||||
## Ensure `/outpost.goauthentik.io` is accessible
|
||||
|
||||
Everything under `/outpost.goauthentik.io` should be publicly accessible, as URLs under this path are used for authentication.
|
||||
|
||||
To check this, run `curl -v https://app.company/outpost.goauthentik.io/ping`. A correct setup should return a `HTTP/2 204` status code.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
title: General troubleshooting steps
|
||||
---
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
## Set the log level to TRACE
|
||||
|
||||
Setting the log level to trace configures the outpost to trace-log all the headers given in forward auth requests.
|
||||
|
||||
This is helpful to confirm that certain required Headers are correctly forwarded from the reverse proxy.
|
||||
|
||||
### When using the embedded Outpost
|
||||
|
||||
Set the authentik log level to `TRACE`:
|
||||
|
||||
<Tabs
|
||||
groupId="platform"
|
||||
defaultValue="docker-compose"
|
||||
values={[
|
||||
{label: 'Docker Compose', value: 'docker-compose'},
|
||||
{label: 'Kubernetes', value: 'kubernetes'},
|
||||
]}>
|
||||
<TabItem value="docker-compose">
|
||||
Add the following block to your `.env` file:
|
||||
|
||||
```shell
|
||||
AUTHENTIK_LOG_LEVEL=trace
|
||||
```
|
||||
|
||||
Afterwards, run `docker compose up -d`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="kubernetes">
|
||||
Add the following block to your `values.yml` file:
|
||||
|
||||
```yaml
|
||||
authentik:
|
||||
log_level: trace
|
||||
```
|
||||
|
||||
Afterwards, upgrade helm release.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### When using a standard outpost
|
||||
|
||||
Edit the outpost settings and set `log_level: trace`. This setting should propagate to the outpost instances within a couple seconds.
|
||||
|
||||
## Ensure `/outpost.goauthentik.io` is accessible
|
||||
|
||||
Everything under `/outpost.goauthentik.io` should be publicly accessible, as URLs under this path are used for authentication.
|
||||
|
||||
To check this, run `curl -v https://app.company/outpost.goauthentik.io/ping`. A correct setup should contain output looking like this:
|
||||
|
||||
```
|
||||
[...]
|
||||
< HTTP/2 204
|
||||
[...]
|
||||
```
|
||||
@@ -1,8 +1,13 @@
|
||||
---
|
||||
title: Capturing logs in authentik
|
||||
title: Capturing authentik logs
|
||||
---
|
||||
|
||||
When troubleshooting issues in authentik, reviewing the [event logs](../sys-mgmt/events/index.md) can be invaluable. These logs provide continuous output, helping to diagnose problems effectively.
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
When troubleshooting issues in authentik, reviewing the logs can be invaluable. These logs provide continuous output, helping to diagnose problems effectively.
|
||||
|
||||
For information on capturing standalone outpost logs, refer to [capturing standalone outpost logs](./outpost_logs.mdx).
|
||||
|
||||
## Adjusting log levels
|
||||
|
||||
@@ -10,9 +15,6 @@ The server and worker containers support multiple log levels: `debug`, `info`, `
|
||||
|
||||
To modify the log level, follow the steps for your platform
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
<Tabs
|
||||
groupId="platform"
|
||||
defaultValue="docker"
|
||||
@@ -70,6 +72,10 @@ To enable `trace` logging, follow the platform-specific steps below:
|
||||
|
||||
2. Recreate your containers to apply the changes.
|
||||
|
||||
:::danger
|
||||
To avoid exposing sensitive information, remember to reduce the log level from `trace` once you finish troubleshooting.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="kubernetes">
|
||||
|
||||
@@ -82,6 +88,10 @@ To enable `trace` logging, follow the platform-specific steps below:
|
||||
|
||||
2. Recreate your containers to apply the changes.
|
||||
|
||||
:::danger
|
||||
To avoid exposing sensitive information, remember to reduce the log level from `trace` once you finish troubleshooting.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
@@ -95,7 +105,7 @@ For more details, see the [`docker logs` documentation](https://docs.docker.com/
|
||||
groupId="platform"
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'docker', value: 'docker'},
|
||||
{label: 'Docker', value: 'docker'},
|
||||
{label: 'Kubernetes', value: 'kubernetes'},
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
@@ -126,7 +136,7 @@ To continuously monitor logs, use the `--follow` (`-f`) option. This will stream
|
||||
groupId="platform"
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'docker', value: 'docker'},
|
||||
{label: 'Docker', value: 'docker'},
|
||||
{label: 'Kubernetes', value: 'kubernetes'},
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
@@ -0,0 +1,172 @@
|
||||
---
|
||||
title: Capturing outpost logs
|
||||
---
|
||||
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
|
||||
This guide only applies to standalone [outposts](../../add-secure-apps/outposts/index.mdx), the [embedded outpost](../../add-secure-apps/outposts/embedded/embedded.mdx) outputs to the same place as the server, refer to [Capturing authentik logs](./logs.mdx) for more information.
|
||||
|
||||
Standalone outposts continually output logs that can be helpful when troubleshooting issues. Just like when capturing authentik logs, the log level can be adjusted.
|
||||
|
||||
## Adjusting log levels
|
||||
|
||||
Outpost containers support multiple log levels: `debug`, `info`, `warning`, and `error`. By default, the log level is set to `info`.
|
||||
|
||||
To modify the log level, follow the instructions below depending on your outpost deployment method:
|
||||
|
||||
<Tabs
|
||||
groupId="outpost-type"
|
||||
defaultValue="admin"
|
||||
values={[
|
||||
{label: 'admin Interface', value: 'admin'},
|
||||
{label: 'Manually Deployed Outposts', value: 'manual'},
|
||||
]}>
|
||||
<TabItem value="admin">
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Applications** > **Outposts** and click the **Edit** icon of the outpost that you're troubleshooting.
|
||||
3. Under **Advanced settings** > **Configuration**, set `log_level` to `debug`, `info`, or `warning`.
|
||||
4. Click **Update**.
|
||||
|
||||
The outpost will be redeployed with the new log level.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="manual">
|
||||
|
||||
Outpost can be manually deployed via [Docker Compose](../../add-secure-apps/outposts/manual-deploy-docker-compose.md) or [Kubernetes](../../add-secure-apps/outposts/manual-deploy-kubernetes.md).
|
||||
|
||||
In each case, you need to add the following environment variable to the outpost container:
|
||||
|
||||
```yaml title="Docker Compose"
|
||||
AUTHENTIK_LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
```yaml title="Kubernetes"
|
||||
env:
|
||||
- name: AUTHENTIK_LOG_LEVEL
|
||||
value: "debug"
|
||||
```
|
||||
|
||||
Then, redeploy the outpost container for the change to take effect.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Enabling `trace` mode
|
||||
|
||||
:::danger
|
||||
The trace log level provides deeper insights, but be aware that using trace logs can expose sensitive information, including session cookies. Handle these logs with extreme caution and avoid using trace unless absolutely necessary.
|
||||
:::
|
||||
|
||||
To enable `trace` logging, follow the instructions below depending on your outpost deployment method:
|
||||
|
||||
<Tabs
|
||||
groupId="outpost-type"
|
||||
defaultValue="managed"
|
||||
values={[
|
||||
{label: 'authentik-Managed Outpost', value: 'managed'},
|
||||
{label: 'Manually Deployed Outposts', value: 'manual'},
|
||||
]}>
|
||||
<TabItem value="managed">
|
||||
|
||||
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
||||
2. Navigate to **Applications** > **Outposts** and click the **Edit** icon of the outpost that you're troubleshooting.
|
||||
3. Under **Advanced settings** > **Configuration**, set `log_level` to `trace`.
|
||||
4. Click **Update**.
|
||||
|
||||
The outpost will be redeployed with the `trace` log level.
|
||||
|
||||
:::danger
|
||||
To avoid exposing sensitive information, remember to reduce the log level from `trace` once you finish troubleshooting.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="manual">
|
||||
|
||||
Outpost can be manually deployed via [Docker Compose](../../add-secure-apps/outposts/manual-deploy-docker-compose.md) or [Kubernetes](../../add-secure-apps/outposts/manual-deploy-kubernetes.md).
|
||||
|
||||
In each case, you need to add the following environment variable to the outpost container:
|
||||
|
||||
```yaml title="Docker Compose"
|
||||
AUTHENTIK_LOG_LEVEL=trace
|
||||
```
|
||||
|
||||
```yaml title="Kubernetes"
|
||||
env:
|
||||
- name: AUTHENTIK_LOG_LEVEL
|
||||
value: "trace"
|
||||
```
|
||||
|
||||
Then redeploy the outpost container for the change to take effect.
|
||||
|
||||
:::danger
|
||||
To avoid exposing sensitive information, remember to reduce the log level from `trace` once you finish troubleshooting.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Viewing past logs
|
||||
|
||||
To review historical logs, you can use the `--since` option with both `docker logs` and `kubectl logs`. This option allows you to specify either a duration (e.g., `1m30s`, `3h`) or a specific timestamp (e.g., `2006-01-02T07:00`, `2006-01-02`) to view logs generated after that point in time.
|
||||
|
||||
For more details, see the [`docker logs` documentation](https://docs.docker.com/reference/cli/docker/container/logs/) and [`kubectl logs` documentation](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_logs/).
|
||||
|
||||
<Tabs
|
||||
groupId="platform"
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'Docker', value: 'docker'},
|
||||
{label: 'Kubernetes', value: 'kubernetes'},
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
|
||||
To retrieve logs from a specific timeframe, use:
|
||||
|
||||
```shell
|
||||
docker logs <container_name_or_id> --since 5m
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="kubernetes">
|
||||
|
||||
To fetch logs from a Kubernetes pod:
|
||||
|
||||
```shell
|
||||
kubectl logs --since 5m <pod_name>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Streaming logs in real-time
|
||||
|
||||
To continuously monitor logs, use the `--follow` (`-f`) option. This will stream log output to your terminal until manually stopped (`Ctrl + C` or closing the terminal).
|
||||
|
||||
<Tabs
|
||||
groupId="platform"
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'Docker', value: 'docker'},
|
||||
{label: 'Kubernetes', value: 'kubernetes'},
|
||||
]}>
|
||||
<TabItem value="docker">
|
||||
|
||||
To follow logs in real time:
|
||||
|
||||
```shell
|
||||
docker logs <container_name_or_id> -f
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="kubernetes">
|
||||
|
||||
To stream logs from a Kubernetes pod:
|
||||
|
||||
```shell
|
||||
kubectl logs -f <pod_name>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
Reference in New Issue
Block a user