mirror of
https://github.com/goauthentik/authentik
synced 2026-04-27 09:57:31 +02:00
78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
---
|
|
title: Files
|
|
---
|
|
|
|
Image files are used in authentik to add icons to new applications or sources, and to define the ["branded" look](../sys-mgmt/brands/index.md#branding-settings) of the authentik interface, with your company's logo and title, a favicon, or a background image for the flows.
|
|
|
|
authentik provides a centralized file management system for storing and organizing these files. Files can be uploaded and managed from **Customization** > **Files** in the Admin interface. By default, files are stored on disk in the `/data` directory, but [S3 storage](../sys-mgmt/ops/storage-s3.md) can also be configured.
|
|
|
|
If file uploads are missing or unavailable after an upgrade, see [Errors when uploading icons](../troubleshooting/image_upload.md).
|
|
|
|
## Upload and manage files
|
|
|
|
To upload and use image files, follow these steps:
|
|
|
|
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
|
2. Navigate to **Customization** > **Files**.
|
|
|
|
Here you can upload a new file, delete a file, and search for a file that you already uploaded.
|
|
|
|
:::info Accepted values in picker fields
|
|
Fields such as brand logos, favicons, flow backgrounds, application icons, and source icons all use the same file picker. Those fields can accept uploaded files, built-in static assets, external URLs, Font Awesome icons, and theme-aware paths using `%(theme)s`.
|
|
|
|
See [File picker values](./file-picker.md) for the full list of supported values and path rules.
|
|
:::
|
|
|
|
## Technical deep dive
|
|
|
|
You can skip this section if you only need to upload or reference files.
|
|
|
|
The shared file picker is a UI on top of the files API and the storage backends. The frontend stores the selected value as a string such as a relative media path, a static asset path, an external URL, or a `fa://...` icon reference.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A["Admin user"] --> B["Admin UI<br/>ak-file-search-input / ak-file-upload-form"]
|
|
B --> C["authentik server router<br/>(lightweight Go router / proxy)"]
|
|
C --> D["authentik Core backend"]
|
|
D --> E["FileView API<br/>/api/v3/admin/file/"]
|
|
E --> F["FileManager"]
|
|
F --> G["StaticBackend"]
|
|
F --> H["PassthroughBackend"]
|
|
F --> I["FileBackend"]
|
|
F --> J["S3Backend"]
|
|
I --> K["Local media storage<br/>/data/..."]
|
|
J --> L["S3-compatible object storage"]
|
|
|
|
E -. "returns file list with name, url,<br/>mime_type, themed_urls" .-> B
|
|
B -. "selected value saved on object<br/>(brand, flow, application, source)" .-> D
|
|
```
|
|
|
|
- The frontend calls the files API to list selectable entries
|
|
- The files API asks the `FileManager` to list files and resolve each file into a `url`
|
|
- The `FileManager` picks the first backend that supports the value
|
|
- For uploaded files, the management backend is either local file storage or S3
|
|
- For built-in assets, the static backend returns `/static/...` paths
|
|
- For external URLs and `fa://...` values, the passthrough backend returns the value unchanged
|
|
- For uploads, the backend validates the file size and path rules before writing to local storage or S3
|
|
|
|
When a value contains `%(theme)s`, authentik can return both a single `url` and a `themed_urls` map:
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A["Stored value<br/>branding/logo-%(theme)s.svg"] --> B["FileManager"]
|
|
B --> C["file_url(name)<br/>raw URL for stored value"]
|
|
B --> D["themed_urls(name)"]
|
|
D --> E["light -> .../logo-light.svg"]
|
|
D --> F["dark -> .../logo-dark.svg"]
|
|
|
|
C --> G["API response"]
|
|
E --> G
|
|
F --> G
|
|
```
|
|
|
|
- The files API can return `themed_urls` for picker entries
|
|
- The current-brand/config response and the flow, application, and source APIs expose themed URL fields for assets that support them
|
|
- Those fields include `branding_logo_themed_urls`, `branding_favicon_themed_urls`, `background_themed_urls`, `meta_icon_themed_urls`, and `icon_themed_urls`
|
|
- The frontend uses those pre-resolved themed URLs to pick the correct asset for light or dark mode
|
|
- This is especially important for S3-backed media, where each themed variant may need its own presigned URL
|