When S3 storage for authentik files is worth setting up
S3-compatible storage replaces the local /data volume for icons, flow backgrounds, uploaded files and CSV reports. Everything else authentik holds, including configuration, users, providers and audit data, lives in PostgreSQL. So the decision is about where those four file types live, not about moving authentik's core data. A single server with a persistent local volume may never need the change. A team running more than one authentik server, or one that wants a single store it can back up on its own schedule, usually does. The question to answer first is whether your deployment must share files across instances or simply needs a backup target you already operate.
The authentik backup documentation makes the responsibility split explicit. The /data directory needs backing up only when S3 external storage is not used. When S3 is in use, the bucket becomes the thing to back up, and your backup procedure has to cover it alongside the PostgreSQL database. Confirm with your team who owns that bucket's versioning, retention and restore testing, because a database restore without a matching bucket restore can leave icons and uploads pointing at objects that no longer exist. Read the authentik backup and restore guide before you decide, since it sets out the exact steps for each storage mode.
The file storage model changed in authentik 2025.12. That release reworked file storage to unify media configuration and added new storage settings. If you are planning to adopt S3 on an existing deployment, check the 2025.12 release notes for the settings names and any migration steps that apply to your starting version, and confirm them against the version you intend to run. Before you commit to a bucket, verify that your chosen S3-compatible provider works with authentik's uploads and exports in a test environment, because provider compatibility is the part most likely to differ from the documentation.
Deciding whether multiple servers make S3 necessary
Object storage matters most when more than one authentik server or worker needs to read and write the same uploaded files and exports. The cards below cover the questions that decide whether a single local /data volume is enough or whether a bucket becomes part of the design. Confirm your replica layout against the authentik documentation before you choose.
Single node or replicated servers
On a single Docker Compose host, one local /data volume is usually simple to run and back up. Once you run more than one server or worker container, or spread them across hosts, each container needs access to the same icons, backgrounds, uploads and CSV reports. Write down how many server and worker replicas you plan, where they run, and whether they can all mount the same volume. Confirm the current replica guidance in the authentik docs.
Shared storage on Kubernetes or ECS
On Kubernetes or ECS, the question is whether your platform gives you a shared volume that every pod or task can mount with the access mode you need. A shared network filesystem can work, but its performance, locking behavior and backup tooling become part of authentik's file path. Ask your platform team whether a shared volume is already supported and backed up. If it is not, an S3-compatible bucket may be the simpler shared target.
Disaster recovery expectations
With S3 external storage, the bucket holds the files and is what you back up, while PostgreSQL still holds configuration and data. If your recovery plan restores a database to a new site, you also need a copy of the bucket that matches it. Decide the recovery point and recovery location for both, and test a restore of the full set. Without a bucket, the /data directory needs its own backup routine.
Operational preference for object storage
Some teams already run object storage with its own replication, access keys, monitoring and on-call rotation. Others have no storage platform team and would rather keep files on the same volume as the application. Either choice is valid. Name the team that will own the bucket, its credentials and its lifecycle, and confirm that this owner accepts the added dependency before you move files off the local volume.
Storage options for authentik files and when each fits
This table compares the local /data volume, a shared filesystem, and the S3-compatible providers covered in this cluster for authentik uploads, icons, backgrounds and CSV exports. Read each row against your number of authentik servers and your tolerance for maintaining storage yourself. The main takeaway is that a single server can keep /data, while multiple servers need storage every node can reach, and several S3 options have license or maintenance conditions to check first.
| Option | License and maintenance status | Deployment footprint | Fit for authentik files |
|---|---|---|---|
| Local /data volume | Not applicable, part of your host or container platform | One volume on the authentik server, backed up as files | Fits a single server; the /data directory needs backing up when S3 is not used |
| Shared filesystem | Depends on the product you choose, confirm its license and support terms | Network mount reachable by every authentik server and worker | Possible for several servers, but confirm the file locking and latency behavior with your authentik version |
| MinIO | AGPLv3 community code; the minio/minio, minio/operator and minio/mc repositories are archived and read-only | Single binary or Docker image built from source, Kubernetes operator available | Confirm your support path before choosing; the README points to AIStor Free or AIStor Enterprise as alternatives |
| Garage | AGPL-3.0; main repository on Deuxfleurs Forgejo with a GitHub mirror; v2.4.1 tagged September 7, 2026 | One self-contained binary, at least 3 nodes recommended for three-way replication | Lacks bucket policies and bucket versioning; confirm that authentik's S3 calls work against your Garage version |
| SeaweedFS | Apache-2.0 for the core; paid Enterprise Edition adds data recovery and self-healing | Master, volume and filer servers, with Docker, Helm or bare metal options | Broad S3 surface and filer options; a multi-component cluster to size and monitor |
| Ceph RGW | Most of Ceph is dual licensed under LGPL 2.1 or 3.0 | Full RADOS cluster providing object, block and file storage | Fits organizations already running Ceph; a heavy footprint for a small authentik file set |
How the S3 provider candidates differ in license, support and features
MinIO is the most widely known self-hosted S3 server, but its open-source position has changed. The minio/minio, minio/operator and minio/mc repositories are archived and read-only, and the README says the repository is no longer maintained. The community server is released under the GNU AGPL v3.0, and the README directs commercial or proprietary use to AGPLv3 review or to a commercial license through AIStor. Support for the community code is best effort through GitHub and Slack, and SLA-backed support is available only through AIStor.
- Archived repositories: The last tagged community release is RELEASE.2025-10-15T17-29-55Z, published October 16, 2025, and the community edition is now distributed as source only.
- AGPLv3 obligations: Review how AGPLv3 applies to your use before you embed or offer the service to users outside your organization.
- AIStor Free: A standalone edition under a free license, named in the README as an alternative to the archived code.
- AIStor Enterprise: A distributed edition with commercial support, the only route to SLA-backed support.
- Upgrade path: Confirm with the vendor which edition receives fixes and whether the current build is one you can keep patched.
Before choosing MinIO, ask the vendor to confirm the supported edition, its license terms for your use, and the support commitments in writing.
Garage is an S3-compatible object store built for reliability across several sites linked by ordinary internet connections. It ships as one self-contained binary, is licensed under AGPL-3.0, and is developed by Deuxfleurs. Its main repository is on the Deuxfleurs Forgejo instance, with a read-only GitHub mirror. Its design suits organizations that want replicated storage across locations without a large storage platform, but its S3 surface is narrower than general-purpose servers.
- Multi-site design: Data is stored in three zones, and the deployment guide recommends at least three nodes for three-way replication with copies in different locations.
- Missing features: Garage does not implement bucket versioning, object lock, bucket policies, ACLs, server-side encryption configuration, replication, event notifications or tagging.
- Lifecycle limits: Lifecycle rules support only AbortIncompleteMultipartUpload and Expiration.
- Permissions: Access uses Garage's own per-access-key, per-bucket permission system rather than S3 bucket policies.
- Metadata engine: LMDB is the default, but the guide warns about portability and unclean-shutdown corruption, and offers SQLite as a more robust option.
Check whether authentik's upload and export paths use only the operations Garage implements in your authentik version, and test them against a staging bucket before committing.
SeaweedFS is an Apache-2.0 distributed storage system that exposes an S3 gateway through its filer servers. The open-source project is free to use, while the paid Enterprise Edition adds data recovery and self-healing storage according to its README. Its architecture separates master servers, volume servers and filers, which gives flexibility in how metadata is stored and how the cluster scales.
- Architecture: Master servers, one or a Raft group of three, track volume locations, volume servers store blobs in append-only files, and filer servers manage directories and files.
- Metadata stores: The filer can keep metadata in stores including LevelDB, RocksDB, SQLite, MySQL, PostgreSQL, Redis and etcd, among others, so you can match the store to your database standards.
- Protocols and security: Besides S3, the filer exposes HTTP, WebDAV, SFTP and FUSE, with TLS or mTLS and AES256-GCM encryption at rest.
- Release cadence: Release 4.48 was published September 28, 2026, after 4.47 on September 14, so confirm the release you plan to pin.
- Enterprise features: Confirm whether recovery and self-healing are needed for your recovery targets, since they sit in the paid edition.
Verify S3 API coverage for the specific calls authentik makes, including multipart uploads and presigned URLs, against the version you deploy.
Ceph is a mature distributed storage platform. Most of its code is dual licensed under LGPL version 2.1 or 3.0. It provides object (RGW), block (RBD) and file (CephFS) storage on one RADOS cluster. Its S3 gateway, RGW, sits on the same cluster that serves other storage types, which can justify it for organizations already running Ceph. It is also the heaviest option to operate, so the decision usually depends on existing skills and infrastructure.
- License: Most of the project is under LGPL, so confirm the license of any component you deploy with it, including the operators and tools you choose.
- Unified platform: RGW, RBD and CephFS share one RADOS cluster, which matters when storage is already managed centrally.
- Operational weight: A Ceph cluster needs planning for failure domains, upgrades and capacity that a single-purpose bucket store does not.
- Feature coverage: Confirm RGW's support for the S3 operations authentik uses, including multipart uploads and the bucket settings your backup process needs.
- Support source: Support depends on your Ceph distribution or vendor, so ask for it in writing.
Ask your storage team which Ceph distribution and support contract applies, and test RGW against authentik's upload and export flows before you rely on it.
How to move authentik files to an S3 bucket
This sequence moves authentik's uploaded files, icons, flow backgrounds and CSV reports from a local /data volume into an S3-compatible bucket, and ends with backups pointed at that bucket. Each step closes with a check so you know the move worked before you rely on it.
Confirm the authentik version and storage settings
Before changing anything, record the authentik version your deployment runs and read the file storage section of the 2025.12 release notes, which reworked media configuration and added new storage settings. Your platform or identity team should own this step, because the settings you use depend on the version. Check that your running version includes those settings and note any that differ from your current configuration. Done means you have a written list of the storage keys your version expects and a copy of your current environment or blueprint values for comparison.
Provision the bucket and access keys
Create a dedicated bucket for authentik files on your S3-compatible platform, and create an access key that can read and write only that bucket. Confirm with your storage vendor or operator which endpoint URL, region and addressing style the platform expects, since these differ between providers. Store the access key and secret in your secrets manager rather than in plain files. Done means you can list, write and read a test object in the bucket using only the new credentials.
Configure the authentik storage settings
Set the storage backend in authentik to S3 using the settings your version documents, supplying the bucket name, endpoint, region and credentials. Apply the change in a non-production instance first if you have one, and restart the server and worker containers so both pick up the new configuration. Keep the local /data volume attached during the switch so you can compare behavior. Done means the server and worker start without storage errors in their logs.
Test icon uploads and file access
Upload a test application icon and a flow background through the admin interface, then confirm each one loads in a browser session and that the object appears in the bucket. Verify that the object keys are created under the bucket rather than under /data. Check that the storage access works from every server and worker replica, since a file written by one node must render on the others. Done means the uploaded images display for users on all replicas and the objects are visible in the bucket.
Test CSV exports
Generate a CSV report from the admin interface, then download it and confirm the file is complete and opens correctly. Check the bucket to confirm the report was written there, and confirm that a new export does not write to the local /data volume. If the export fails, review the worker logs first, because report generation runs as a background task. Done means a report downloads from a browser and its object is in the bucket.
Point backups at the bucket
Update your backup runbook so the bucket is part of each backup job, using versioning, replication or snapshot features your storage platform provides and confirming them with your vendor. Once S3 is active, the /data volume backup is no longer the target for uploaded files, so remove it from the job or mark it as legacy only after the cutover is verified. Follow the authentik backup and restore documentation to confirm which data each backup covers. Done means a test restore of a sample file from the backed-up bucket succeeds.
How to back up the bucket once it holds authentik files
When authentik uses S3 external storage, the bucket becomes the backup target for uploaded files, icons, flow backgrounds and CSV reports, and the authentik backup and restore documentation reflects that split. The PostgreSQL database still holds all configuration and data, so it needs its own backup job. Treat the two as a pair: a restore is only complete when both the database dump and the bucket contents come back. Before you finalize the design, confirm with your storage provider how it handles bucket-level backup, replication to a second site, and object retention, because those features differ widely between S3-compatible products.
Retention and versioning deserve a deliberate decision. Versioning lets you recover an overwritten or deleted object, but not every S3-compatible provider offers it. Garage, for example, does not implement bucket versioning or object lock, and its lifecycle rules only cover aborting incomplete multipart uploads and expiring objects. On such a backend, the backup of the bucket has to be a full copy taken on a schedule, stored outside the cluster, with your own retention rules applied to those copies. For any provider, confirm which of these capabilities you have before relying on them, and write down how many generations of bucket copies you keep and for how long.
Consistency and restore testing close the loop. A database dump and a bucket copy taken hours apart can describe different states, for example a CSV report that exists in the bucket but has no matching record, or the reverse. Run both jobs in the same maintenance window or record timestamps for each so you know the pairing. Then test a restore into a separate environment at a regular interval, check that authentik starts against the restored database and bucket, and confirm that an uploaded icon and a recent report both load. A backup that has never been restored is an assumption, not a recovery plan.
Security controls for the file bucket
The bucket holds icons, backgrounds, uploads and CSV exports, so its access path needs the same care as the database. The cards below cover the controls to confirm before go-live: credential scope, transport, encryption at rest, logging and secret handling. Confirm each one against your chosen provider's documentation, because capabilities differ between S3-compatible products.
Scope credentials to one bucket
Create a dedicated access key for authentik and grant it read and write access only to the authentik bucket, not to every bucket on the endpoint. Confirm that the provider can restrict a key to a bucket and to the object actions authentik needs. Garage, for example, uses its own per-access-key, per-bucket permission model, so the grant has to be set in that system rather than through a bucket policy. Keep administrator keys out of the authentik configuration entirely.
Require TLS to the endpoint
Send all file traffic over HTTPS and verify the endpoint certificate from the authentik server and worker containers, including the trust chain for an internal certificate authority. Confirm how the chosen configuration validates certificates and whether a plain HTTP endpoint is accepted on the internal network. Test the connection from inside the containers, since a certificate that works on the host may not be trusted by them.
Confirm encryption at rest per provider
Encryption at rest differs by product. SeaweedFS documents AES256-GCM encryption at rest, and Garage supports SSE-C, where the client supplies the key on each request, but Garage does not offer server-side encryption configuration. Confirm what your provider encrypts on disk, who holds the keys, and how keys are rotated and recovered if lost. If the provider offers no encryption at rest, plan disk-level encryption on the storage hosts instead.
Enable access logging on the bucket
Turn on request logging at the storage layer so that reads, writes and deletes of uploaded files can be traced to an access key and a time. Confirm which log fields the provider records, where they are stored, how long they are kept, and whether they can be forwarded to your central log platform. Authentik's own logs show application activity but not every object request, so the storage logs are the second record to check during an investigation.
Keep secrets out of plain files
In Docker Compose, store the access key and secret in an .env file with restricted file permissions and keep that file out of version control. In Kubernetes, place them in a Secret and reference it from the chart values rather than writing them into a values file committed to Git. Confirm that the secret does not appear in container inspect output, shell history or log lines, and rotate the key if it was ever exposed.
Test restricted access before go-live
Verify that the scoped key works for every action authentik performs, such as uploading a custom icon and generating a CSV export, and that it fails on other buckets and on bucket administration. Run the check after each provider or authentik upgrade, because permission models and required API calls can change. Record the results so the controls can be shown to an auditor or security reviewer.
Questions teams ask before moving authentik files to S3
Do I need S3 storage if authentik runs on a single server?
No. A single server can keep icons, flow backgrounds, uploaded files and CSV exports on the local /data volume, and that is a valid setup. The case for S3 usually comes from needing several authentik servers that must all see the same files, from wanting storage outside the host, or from a storage policy that requires object storage. If none of those apply, the work is mainly keeping the /data volume included in your backup routine, since it is only needed for backups when S3 is not used. Confirm the file layout for your release in the authentik backup and restore documentation before deciding.
What does the effort to move authentik files to S3 depend on?
The effort depends on how many authentik instances share files, how many files already exist on /data, and how your backup and access model is set up. Moving files is the small part. The larger items are the storage settings change, a bucket and access key with the right permissions, a tested restore that reads from the bucket, and updates to your runbooks. Your authentik version also matters, because file storage was reworked in 2025.12 and the settings you write depend on which release you run. Ask for these items to be listed separately in any written scope.
Can our team move authentik files to S3 without outside help?
Yes, if your team already runs authentik and an S3-compatible service, and has capacity to test a restore. The change itself is a configuration update plus a data copy, and the risk sits in the details: permissions on the bucket, network paths from every authentik server, and a backup that has been restored at least once. Teams that lack object storage operations experience often use a partner to write the scope, run the test restore and document the result. DeployOpen plans and implements these changes in infrastructure you control, under a fixed scope agreed in writing before work starts.
What does a partner need from us before starting the work?
Expect to provide three things: bucket access, network paths and a backup policy. For bucket access, that means a bucket name, a dedicated access key scoped to that bucket and an agreement on who holds the secret. For network paths, the authentik server and worker containers must reach the storage endpoint, and firewall rules, DNS and TLS trust must be confirmed. For the backup policy, you need to state retention, who may restore, and where backup copies are kept. You should also name a contact who can approve a test restore in a non-production environment.
Which storage provider should we choose for the bucket?
The right provider depends on your licensing position, your operations capacity and the S3 features authentik actually uses. Check the licence terms of any self-hosted option, including obligations that apply when you modify or offer the software over a network. Some S3-compatible options document gaps in features such as versioning, object lock, bucket policies or lifecycle rules, so confirm with the vendor that the calls authentik makes are supported in your version. Ask for the support model in writing, since community support and SLA-backed support are often different products. Your existing object storage, if you have it, is often the simplest path.
Which parts of the S3 setup keep needing attention after go-live?
Several items recur after the initial move:
- Access key rotation and removal of unused keys
- Backup jobs for the bucket, plus periodic test restores
- Capacity growth and storage cost, which rise with uploaded files and CSV exports
- Upgrades to the storage service and to authentik, especially when file storage settings change between releases
- Monitoring of bucket availability and errors from authentik
One-time costs include the design, the migration, and the first verified restore. Ask any partner to separate these in a quote, and to state which items are included in a retainer.
How do we back up the S3 bucket and confirm the backup works?
With S3 in use, the bucket becomes the copy of your uploaded files that needs backing up, while the database remains the authoritative store for configuration and data. Choose a method your storage service supports, such as replication to a second location or a scheduled copy to another bucket, and document the retention period. A backup is only proven when you restore it into a separate environment and check that icons, backgrounds and exports open correctly in authentik. Schedule that restore test as a recurring task rather than a one-time check.
How DeployOpen scopes and delivers S3 storage for authentik
DeployOpen starts every S3 storage engagement with a written scope that names the authentik version, the deployment method, the bucket layout and the storage provider before any configuration changes. Because most engagements are fixed-scope, the scope document also lists the deliverables, such as the storage settings applied to the server and worker, the bucket and access key arrangement, the test plan for icons, flow backgrounds, uploads and CSV exports, and the backup verification steps. The scope also records which storage settings are changed for your authentik release, since file storage was reworked in 2025.12 and the exact settings should be confirmed against the release notes for your version before the quote is agreed.
Provider selection is decided against your environment rather than a default. DeployOpen reviews whether you already run an S3-compatible service, where the bucket must sit for data residency, how many authentik server and worker replicas need shared access, and what your team can operate afterward. Among the options assessed are MinIO, Garage, SeaweedFS and Ceph, each with different licensing, support and operating models. Each option is checked against current maintenance status and license terms before it is recommended, and the reasoning is written into the scope so your security and procurement teams can review it. Configuration is then carried out inside your own cloud accounts, data centers or air-gapped networks, and credentials stay in your secret management.
Backup verification is treated as a deliverable, not an afterthought. Once S3 is in use, the bucket is what must be backed up, so DeployOpen tests a restore of the bucket into a separate environment and confirms that a restored authentik instance displays its icons, backgrounds and exports correctly. Optional retainer support can cover version upgrades, bucket capacity reviews and periodic restore tests after the initial delivery. DeployOpen prepares configuration, controls and evidence for your compliance work, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments, and your quote should state exactly which artifacts DeployOpen hands over for them.
