mirror of
https://github.com/goauthentik/authentik
synced 2026-04-27 18:07:15 +02:00
85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
---
|
|
title: File picker values
|
|
authentik_version: "2025.12"
|
|
---
|
|
|
|
Many fields in the authentik Admin interface use the same file picker. You can use it to select an uploaded file, reference a built-in static asset, point at an external URL, or use a Font Awesome icon.
|
|
|
|
This applies to:
|
|
|
|
- **System** > **Brands** > **Logo**
|
|
- **System** > **Brands** > **Favicon**
|
|
- **System** > **Brands** > **Default flow background**
|
|
- **Flows and Stages** > **Flows** > **Background**
|
|
- **Applications** > **Applications** > **Icon**
|
|
- **Applications** > **New Application** wizard > **Icon**
|
|
- **Directory** > **Federation and Social login** > source **Icon** fields for SAML, OAuth, Plex, and Kerberos sources
|
|
|
|
## Accepted values
|
|
|
|
The file picker accepts the following value types.
|
|
|
|
| Value type | Example | Notes |
|
|
| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Uploaded file path | `branding/company-logo.svg` | Relative path to a file stored in authentik's media storage. You can upload these from **Customization** > **Files**. When authentik serves these files, it uses a short-lived protected URL rather than a fixed public path. |
|
|
| Built-in static asset | `/static/dist/assets/icons/icon_left_brand.svg` | Absolute path to a built-in asset shipped with authentik. |
|
|
| External URL | `https://cdn.example.com/branding/logo.svg` | Useful when files are hosted outside authentik. |
|
|
| Font Awesome icon | `fa://fa-circle-user` | Supported for icon fields. This is not useful for background image fields. |
|
|
|
|
When you open the picker, authentik lists uploaded files and built-in static assets. You can also type a custom value directly into the field.
|
|
|
|
## Theme-aware values with `%(theme)s`
|
|
|
|
Some assets can change based on whether the active theme is light or dark. For those cases, you can use the placeholder `%(theme)s` in the path or URL.
|
|
|
|
Examples:
|
|
|
|
- `branding/logo-%(theme)s.svg`
|
|
- `branding/background-%(theme)s.jpg`
|
|
- `/static/dist/assets/icons/icon-%(theme)s.svg`
|
|
- `https://cdn.example.com/assets/logo-%(theme)s.svg`
|
|
|
|
authentik resolves `%(theme)s` to:
|
|
|
|
- `light`
|
|
- `dark`
|
|
|
|
`automatic` is not substituted directly. When a user is set to automatic theme selection, authentik chooses either the light or dark asset first and then uses the matching resolved URL.
|
|
|
|
This resolution happens on the backend, which means it also works with storage backends that need signed URLs, such as S3.
|
|
|
|
The `%(theme)s` placeholder is supported in all current Admin UI fields that use the shared file picker:
|
|
|
|
- Brand **Logo**
|
|
- Brand **Favicon**
|
|
- Brand **Default flow background**
|
|
- Flow **Background**
|
|
- Application **Icon**
|
|
- Source **Icon**
|
|
|
|
## Upload and path rules
|
|
|
|
When uploading a file in **Customization** > **Files**, or when typing a relative media path manually, use these rules:
|
|
|
|
- If a file exists at `/data/media/public/branding/logo.svg`, enter `branding/logo.svg` in the picker field - without a leading slash. Do not enter `/data/media/public/branding/logo.svg` or `/branding/logo.svg`.
|
|
- Files uploaded through **Customization** > **Files** are always served through a temporary protected URL
|
|
- On S3 storage, authentik generates a presigned S3 URL
|
|
- On local file storage, authentik generates an authentik `/files/...` URL with a unique signed token
|
|
- Uploaded files can be up to 25 MB each
|
|
- Allowed characters are letters, numbers, `.`, `_`, `-`, and `/`
|
|
- `%(theme)s` is also allowed anywhere in the path
|
|
- Paths must be relative, not absolute
|
|
- Parent directory references such as `..` are not allowed
|
|
- Duplicate slashes such as `//` are not allowed
|
|
- Paths cannot start with `.`
|
|
- The full path can be up to 1024 characters long
|
|
- Each path segment can be up to 255 characters long
|
|
|
|
Examples of valid upload names:
|
|
|
|
- `branding/logo.svg`
|
|
- `branding/logo-%(theme)s.svg`
|
|
- `sources/oauth/company-icon.png`
|
|
|
|
If you rename a file during upload, authentik keeps the original file extension.
|