Why an authentik 2025.12 upgrade needs planning before the image changes
An existing authentik instance cannot move to 2025.12 by simply changing the image tag, because the migration fails while duplicate group names exist, and permissions must be attached to roles rather than granted directly. Both changes touch the data model, so the work starts with an inventory of groups and permissions in the running instance, not with the container update. Identify every group whose name appears more than once, decide the new unique names, and check which permissions are currently assigned outside roles so you know which access paths will change when the release is applied.
The supported path is a sequential upgrade through each release in order, not a jump from an older version straight to 2025.12. That makes 2025.12 a stop on the way, not an end state. The authentik security policy currently lists 2026.5.x and 2026.8.x as the supported versions receiving security fixes, so a production instance left on 2025.12 would fall outside that support window. Plan the 2025.12 step as one milestone in a longer program, and confirm the current supported versions and the release notes for each intermediate version on the project's security policy and release pages before you set the target.
Plan a backup and a staging rehearsal before the production change. The rehearsal should run the migration against a copy of the production PostgreSQL database, because that is where the duplicate-group failure appears, and it should include a test of the storage path change for uploaded files. Ask your team to record the rename map, the role assignments created for each permission, and the reverse proxy changes needed for the new file paths, so that the production window contains only steps that have already been run once.
What 2025.12 changes for existing deployments
This table lists the four 2025.12 changes that affect existing configuration, with the impact on your current setup, the action to take before upgrading, and the team that should own each action. Read each row against your current groups, roles and reverse proxy rules before scheduling the upgrade window.
| Change | Impact on existing configuration | Action before upgrading | Owner |
|---|---|---|---|
| Unique group names enforced by migration | The database enforces unique group names, and the migration fails while duplicate names exist. Deployments that reused a name across parent groups or synced the same name from two sources will stop mid-upgrade. | Find duplicate group names in the admin interface, rename them, and update any integration, policy or SCIM filter that matches on the old name. Confirm the renames in a staging copy first. | Identity admin |
| Permissions inherited from ancestors | Groups inherit all permissions from their ancestor groups. Access that was granted narrowly may now reach more users than before, which is a risk to review rather than a failure to fix. | Map each parent group and its permissions, then list which child groups and members will gain access after the upgrade. Remove or restructure inherited grants that should not apply. | Identity admin |
| Multiple group parents | A group can now have more than one parent, so a group may pick up permissions from several branches of the hierarchy. Hierarchies that assumed a single tree need a review of their membership logic. | Check each group for its current parents and decide whether any new parent relationships are intended. Document the expected inherited access for audit purposes. | Identity admin |
| Permissions carried only by roles | Permissions must be attached to roles. Permissions assigned directly to users or groups outside roles will not carry over as expected, so access can change after the upgrade. | Inventory every direct permission assignment, move each one to a role, assign the role to the same groups or users, and test representative logins before the upgrade. | Identity admin |
| Storage moves from /media to /data/media | authentik expects local storage at /data, so uploaded files move to /data/media. Volumes, backup jobs and container mounts that point at the old /media path will no longer match the running application. | Plan the volume mapping for /data, copy existing files into /data/media, and update backup scripts and container definitions. Restore a test backup to confirm files resolve after the change. | Platform engineer |
| Files served from /files instead of /media | The URL path that serves uploaded files changes from /media to /files. Existing links, branding references and cached assets that use the old path will return errors after the upgrade. | Search configuration, branding settings and proxy rules for references to /media and update them to /files. Confirm the path change with the reverse proxy owner before the maintenance window. | Reverse proxy owner |
What to inventory and back up before the migration runs
authentik 2025.12 changes how groups, permissions and file storage behave, so the migration depends on what you inventory and copy first. The four items below cover the data you must be able to restore, the group names that will block the migration, the permissions that must be re-attached to roles, and a staging rehearsal that proves the whole sequence works before production is touched.
Full PostgreSQL backup and media copy
PostgreSQL stores all authentik configuration and data except uploaded files, so a database dump alone does not capture everything. Take a full, restorable PostgreSQL backup and, separately, a copy of the media storage directory that holds uploaded files such as application icons and branding assets. Confirm that you can restore both to a clean host and that the restored instance starts before you change any version or path. Keep the copy until the upgraded instance has run through your normal login and provider tests.
Duplicate group name inventory
authentik 2025.12 enforces unique group names in the database, and the migration fails until duplicates are renamed. Query for groups that share a name, record each group's identifier, parent groups and full member list, and decide on a new unique name for each duplicate. Update any application policy, SCIM filter, LDAP mapping or custom script that refers to the old name, because renaming a group breaks references that match on the name. Plan the renames as a change window of their own so the migration runs against a clean group table.
Direct permission assignments to move
In authentik 2025.12, permissions must be attached to roles, so any permission assigned directly to a user or group needs a new home before or during the upgrade. Export the list of direct assignments and group them by the access they grant, then design one role per access pattern and map each assignment to it. Because groups now inherit permissions from ancestors and can have multiple parents, review inherited access as well, since a role attached to a parent group may grant more than the old direct grants did. Confirm the role model with the people who approve access before the change is applied.
Staging rehearsal from production
Restore a recent production backup, including the media copy, into an isolated staging instance that matches production's version, reverse proxy and storage layout. Run the duplicate group renames and the permission-to-role changes there first, then perform the upgrade and the move from /media to /data/media. Test sign-in for each provider type you run, confirm that uploaded files still render, and check that users keep the access they had before. Record every failure and the exact fix so the production runbook reflects what actually happened in staging.
How group inheritance and roles change who can do what
In authentik 2025.12, groups inherit all permissions from their ancestors, and a group can now have multiple parents. Before the upgrade, a group nested under a narrow parent could be assumed to carry only narrow access. After the upgrade, every member of a child group also receives whatever its parents hold, through every parent path. A group that was harmless in its old position can suddenly reach applications, flows or admin functions it never reached before. Treat the upgrade as an access change, not only a schema change, and review the effective access of each group before users resume normal sign-in.
Start by exporting or listing the full group tree, including every parent link. Look for groups with more than one parent, since each parent adds a path of inherited permissions. For each group, record which permissions it holds directly and which it inherits, then decide whether the inheritance is intended. Where a permission is held by a group only for convenience, move it to a role and attach that role to the group that should own it. Permissions must be attached to roles in this release, so any direct permission that was set on a group needs a role before the access model is final. Confirm the exact admin screens and export options for your version in the authentik 2025.12 release notes and in your own test instance.
Verify the result with representative users rather than trusting the group tree alone. Choose a small set of accounts that cover each team, a contractor or external account, an administrator, and a user who sits in several groups. For each one, compare what the account can open, which applications it sees and which admin functions it can use, against the access your access policy requires. Record the outcome before and after the upgrade in a test environment. Any account that gained access it should not have is a blocking finding. Plan this review as part of the upgrade window, and ask your DeployOpen contact or your own identity team to sign off on the access matrix before production is migrated.
How to sequence the upgrade from backup to verified login
This sequence moves a running authentik deployment to 2025.12 in an order that keeps a clean restore point at every stage, so each change can be verified before the next one starts.
Take backups and stop writes
Freeze administrative changes and user-facing writes, then take a consistent PostgreSQL dump and a copy of the media storage volume, including the existing /media directory. The platform team owns this step, and the output is a dump file and a storage copy that have both been restored once to a scratch database to confirm they are readable. Record the running authentik version, the image tags and the reverse proxy configuration alongside the backup. This backup is your rollback point for the entire upgrade: if something fails later, you restore it rather than attempting a downgrade.
Rename duplicate groups on the current version
Before changing any image, search the directory for group names that appear more than once, since authentik 2025.12 enforces unique group names and the migration fails until duplicates are renamed. Rename them in the admin interface on your current version, update any LDAP, SCIM or application policies that reference the old names, and confirm that the query returns no duplicates. The identity administrator performs this, and the check is a clean duplicate search plus a test login for one user from each affected group. Renaming while still on the old version keeps the change reversible from the backup.
Confirm the inventory of direct permissions
List every permission currently assigned directly to a user or group rather than through a role, and every group that has a parent. Under 2025.12, permissions must be attached to roles, groups inherit all permissions from their ancestors, and groups can have multiple parents, so both lists affect who gets access after the migration. Export the inventory and mark each entry with the role that should carry it. The output is a reviewed spreadsheet or export that the application owners have signed off, and it becomes the checklist for the next step.
Move permissions to roles on the current version
Create roles for each access pattern in the inventory, attach the permissions to those roles, and assign the roles to the groups or users that need them. Remove the direct grants once the role assignments are in place. Work on the current version so you can compare access before and after using the same admin views. The check is an access comparison for a sample of users in each group, where the effective permissions match the inventory. Keep a copy of the before and after exports with the backup set.
Update the storage path and reverse proxy routes
Move the uploaded files from /media to /data/media in the storage location that authentik reads, because authentik 2025.12 serves files from /files and expects local storage at /data. Update the volume mounts in your Compose or Helm values, and change the reverse proxy rules so that the file-serving path matches the new /files route. The platform engineer owns this change. The check is that the staged configuration mounts the copied files at the expected location and that a test request for a known uploaded file resolves through the proxy after startup.
Run the 2025.12 migration on staging
Deploy the 2025.12 server and worker images against a restored copy of production data on a staging environment. Watch the migration log from start to finish, since it fails if any duplicate group names remain. Once it completes, check that the server and worker containers are healthy and that the admin interface loads. Any migration error at this point is handled by discarding the staging copy, fixing the cause, and restoring again, which keeps production untouched.
Verify logins, flows, files and outposts
On staging, test a login through each provider type your organization relies on, run the enrollment and recovery flows, open a previously uploaded file, and confirm that proxy and LDAP outposts connect and report the expected state. Compare the results with the test list you wrote before the upgrade. Confirm the outpost versions with the outpost health view, since outposts must match the core version. The output is a signed-off test record. Any failed check blocks promotion and returns the team to the staging restore point.
Promote to production and confirm sign-in
Schedule the production cutover in a window your users have been told about, repeat the backup and stop writes, apply the same tested configuration and images, run the migration, and repeat the verification test list against production with a small set of pilot accounts. The cutover is complete when those logins, the file downloads and the outpost connections pass. If the migration or the checks fail, restore the backup taken at the start of this sequence to return to the previous version, and do not attempt to run the older images against the migrated database.
What makes this upgrade take longer than expected
This table lists the factors that most often stretch an authentik 2025.12 upgrade beyond a simple version bump, what each factor changes in the work, and what to ask for in a scoped quote. Read each row against your own environment, since the largest drivers are usually the group tree and the reverse proxy paths rather than the migration itself.
| Driver | Why it changes the work | What to ask for in a scoped quote |
|---|---|---|
| Duplicate group names | The 2025.12 migration fails until every duplicate is renamed, and renames can break LDAP bindings, SCIM mappings and claim rules that match on the old name. | An inventory of duplicate names, the owner of each group, and a list of downstream references to update before cutover. |
| Depth and breadth of the group tree | Groups now inherit permissions from every ancestor and can have several parents, so each parent link must be reviewed for unintended access. | A review of inherited permissions per group, with a test matrix covering representative users in each branch. |
| Direct permissions to convert to roles | Permissions must be attached to roles in 2025.12, so each direct grant has to be mapped, assigned and verified before the old grant is removed. | A count of direct permissions, a proposed role model, and the verification approach used to confirm access is unchanged. |
| Reverse proxy and custom routes referencing /media | Requests to /media must move to the new file path and proxy configurations, rewrites and health checks need updating in every environment. | An inventory of every proxy config, ingress rule and custom script that references /media, with changes tested on staging. |
| Size of the uploaded file store | Local storage moves to /data/media, so the existing files must be copied or relocated and checked before the new version reads them. | The current size and location of the media directory, the planned copy method, and the rollback point for the file store. |
| Applications and outposts depending on group claims | Changes to group membership and inheritance alter the claims issued to each application, which can change authorization in downstream systems. | A list of applications and outposts that consume group claims, with a test login plan and an owner to sign off each one. |
| Availability of a staging copy | Without a restored staging copy built from recent production data, the migration and RBAC changes can only be rehearsed on a clean install, which misses real data problems. | Confirmation that a staging environment with a recent database restore exists, plus the time and access needed to run the rehearsal. |
Questions teams ask before upgrading authentik to 2025.12
What drives the cost and effort of an authentik 2025.12 upgrade?
The main drivers are how many groups you have with duplicate names, how many groups sit under other groups, how many permissions are attached directly to users or groups instead of roles, and how your reverse proxy and storage are configured. Duplicate-name cleanup and the permission rework are the largest variables because they touch identity data that applications depend on. If you engage a partner, the cost comes from a fixed scope agreed in writing before work starts, covering assessment, rename and role planning, staging rehearsal, production cutover and verification. Ask for each item to be priced separately so you can see which parts you could take on yourself. Confirm your current group and permission inventory first, since it sets the scope.
Can our own team complete the authentik 2025.12 upgrade without outside help?
Yes, if your team has administrators who can read and change authentik groups, roles and permissions and someone who can edit the reverse proxy configuration. The release notes describe concrete changes: unique group names are enforced and the migration fails until duplicates are renamed, permissions must come from roles, groups can have multiple parents and inherit permissions from ancestors, and files move from /media to /data/media. These are documented steps, so the question is capacity and risk tolerance rather than feasibility. A partner is most useful when group hierarchies are large or when many applications rely on permissions that will change meaning after the upgrade.
How long does the authentik 2025.12 upgrade take, and what sets that?
Duration depends on the number of duplicate groups to resolve, the size of the permission model to move onto roles, the number of environments you must test in, and how many applications need verification after cutover. Each of these scales independently, so a small directory with a simple hierarchy takes far less time than a deployment with many nested groups and dozens of connected applications. No fixed timeline applies to every environment. Ask any provider for a schedule tied to your inventory, and confirm your change windows, since the move to /data/media also requires a reverse proxy path change that must be coordinated with the proxy owner.
What does the authentik 2025.12 upgrade require from our internal team?
Three roles are typically needed. An identity administrator owns the group and role model, decides which duplicate names survive and signs off on the new permission structure. A proxy owner updates the reverse proxy so that files are served from the new location and the path change for /media to /data/media is applied without breaking uploads or downloads. A database administrator confirms PostgreSQL backups, restore testing and capacity before the migration runs. Ask your team to confirm these people are available for the whole window, not just the cutover day, because duplicate-group decisions often need input from application owners.
Can we roll back authentik after the 2025.12 upgrade, and how?
Plan rollback around restoring from backup rather than downgrading the running software. Take a consistent PostgreSQL backup and a copy of the file storage before the migration starts, and verify that you can restore both into a separate environment. Because the migration changes data, the safe path back is a restore to the pre-upgrade state, followed by a check that users, applications and sessions behave as before. Record the exact restore steps and time them during rehearsal. Confirm with your provider and your own environment how file storage is backed up, because files live outside the database and must match the restored data.
Does our authentik license or edition change how we perform this upgrade?
The upgrade steps in this release do not depend on the edition. authentik's repository places most code under the MIT license, while code in the authentik/enterprise/ directory is under a separate enterprise license. The Enterprise features listed on the pricing page, such as Google Workspace and Microsoft Entra ID integrations, mTLS client certificate authentication, privileged access management, password history, enhanced audit logging and ticket-based support, are separate from this upgrade. Confirm which features you use before the upgrade, because an integration that depends on an Enterprise feature needs its own license check and planning.
Should we confirm our PostgreSQL and storage setup before starting?
Yes. authentik stores configuration and data in PostgreSQL, but uploaded files live in local storage, so the storage path change is separate from the database work. On Docker Compose, the install guide positions Compose for test setups and small-scale production, and on Kubernetes, the chart's bundled PostgreSQL is intended for demonstration and test use, with a separately managed PostgreSQL recommended for production. Confirm where your files and database live, whether backups cover both, and who owns each volume before you plan the path change.
What to confirm with authentik and in your own environment
Before you start the 2025.12 upgrade, check the official 2025.12 release notes against your own setup, because the duplicate-group rule and the storage move are the changes this page covers, not necessarily the only ones that affect your deployment. Read the full release notes page and list every breaking change that applies to your version path, then mark which ones touch your identity sources, providers, custom code, outposts or reverse proxy. Ask authentik to confirm any item you cannot map to your environment. Also record the exact output of the migration run in a staging copy of your database. A failing migration on duplicate group names should print the names involved, and you should capture that output in full so you can match each duplicate to a group that a directory sync, SCIM feed or admin team owns.
Next, confirm the file path and outpost details in your own infrastructure. Find every reverse proxy rule, load balancer or ingress setting that refers to /media and check whether it needs to point at the new location under /data/media, and test uploads and downloads of branding and other files in staging before cutover. Then confirm that the core, worker and every outpost you run are on the same release, and note which outposts are managed by integrations and which use manually pinned image tags. A mismatch can look like a broken login flow rather than a version problem, so confirm the version of each container before you declare the upgrade complete.
How DeployOpen scopes and delivers an authentik upgrade
DeployOpen treats the authentik 2025.12 upgrade as a written, fixed-scope change to your running identity platform, starting with an inventory of duplicate group names, role assignments and reverse proxy paths. The work is planned, rehearsed on a copy of your data and documented before anything changes in production.
How we scope
- Inventory duplicate group names and the parent-child group tree before the migration is attempted.
- Map which applications rely on direct permissions that must move to roles in 2025.12.
- Record every reverse proxy and forward auth rule that references /media so the /data change is covered.
How we build
- Rename duplicate groups in a staging copy first, then run the migration and confirm it completes.
- Reattach permissions to roles and test access for each affected group and application.
- Update reverse proxy configuration and file storage paths, then verify uploaded files still load.
How we hand over
- Deliver a written runbook with the exact rename list, role changes, proxy diffs and rollback steps.
- Document the verification results for each application and each group that changed.
- Walk your platform and security teams through the runbook and the post-upgrade checks.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm with your own team and the release notes which later releases affect your deployment.
- Agree in the written scope who owns backups, restore tests and change approvals during the upgrade window.
