Why an authentik 2026.5 upgrade needs a pre-upgrade review of integrations
An authentik 2026.5 upgrade is a planned, sequenced change, and four behaviors need review before anyone runs it: the default listen address, the deprecated PostgreSQL connection options, the automatic SAML issuer, and typed OAuth2 redirect URIs. Each one can break sign-in for applications that worked fine on the previous release, and none of them announces itself until a user tries to log in. The review belongs before the maintenance window, not during it. Start by listing every provider in your instance, its protocol, and the application that depends on it, then check each entry against the four behaviors. Confirm which of your containers set the listen address and the connection options explicitly, since those settings are what the new defaults and deprecations affect.
The upgrade also sits inside a supported sequence. The authentik security policy lists 2026.5.x and 2026.8.x as the versions currently receiving security fixes, so a 2026.5 install is on a supported line only while it stays on that line and keeps applying its patch releases. Treat 2026.5 as one step in your route forward, not a destination. Read the authentik 2026.5 release notes in full before you schedule the change, and confirm your current version first, because the upgrade assumes the instance is already on the release immediately before it. If you are several versions behind, the catch-up path comes before this review, not after it.
For the review itself, record the outcome for each integration in writing: whether the redirect URI needs a type change, whether the SAML issuer must be pinned to its previous value, and whether any reverse proxy or service depends on the listen address. Ask the application owners to confirm their sign-in tests on a staging copy, and keep a tested backup of the PostgreSQL database so that a failed upgrade can be restored rather than reversed. Your own team can run this review with the release notes and your integration inventory, and a partner can take on the same work under a written scope. Either way, the output should be a signed-off list of changes, not a verbal assurance that the upgrade will be fine.
What changes in authentik 2026.5 and what each change touches
This table compares four changes in authentik 2026.5 by what each one affects on a running install and what to do before or after the upgrade. Read each row against your own deployment, starting with the listen address and PostgreSQL settings, then your SAML and OAuth2 integrations. The main takeaway is that the SAML issuer and redirect URI changes can break existing relying parties without any error on the authentik side.
| Change in 2026.5 | Impact on running installs | Action before or after the upgrade |
|---|---|---|
| Default listen IP changes from 0.0.0.0 to [::] | Installs that rely on the default bind address may listen on a different interface family, which can break reverse proxy or container port routing. | Check whether your reverse proxy, Compose port mapping or Helm values set the listen address explicitly, and confirm the IPv6 behavior in your environment before cutover. |
| AUTHENTIK_POSTGRESQL__CONN_OPTIONS is deprecated | The setting still works in 2026.5 but is scheduled for removal in the next version, so configurations kept as-is will fail later. | Find where the variable is set (environment files, Helm values, secrets) and plan to move it to the replacement configuration named in the 2026.5 release notes. |
| SAML provider sets the Issuer automatically | From 2026.5 the Issuer is https://<authentik host>/application/saml/<application_slug>/metadata/. Earlier versions defaulted to authentik, so a relying party that trusts the old value will reject assertions. | Before upgrading, record the current Issuer of each SAML provider and compare it with the new value. Update the trust configuration in each relying party to match, then test sign-in. |
| OAuth2 redirect URIs are typed | Before 2026.5 all redirect URIs were treated as Authorization type, so a Post Logout URI was not configured separately. After the upgrade, the URI type matters for logout behavior. | List every OAuth2 provider with a logout redirect. After upgrading, set the Post Logout URI as its own typed entry and test logout for each application. |
How the listen address and PostgreSQL settings affect container and host deployments
The Docker Compose guide positions Compose for test setups and small-scale production, on a host with at least 2 CPU cores and 2 GB of RAM. In this model, the listen address change matters at the boundary between the host, the container and anything in front of it, because the server process now binds to the IPv6 wildcard by default instead of the IPv4 wildcard.
- Port mappings: A published port only works if the process inside the container accepts connections on the address family the mapping uses. Send a request to each published port from the host after the upgrade.
- IPv4-only hosts: If IPv6 is disabled on the host or in the Docker network, confirm that
[::]still accepts IPv4 traffic on your operating system before you rely on it. Behavior depends on platform and socket settings. - Health checks: A health check that calls
localhostor127.0.0.1inside the container must still reach the listener. Confirm the container reports healthy after restart. - Reverse proxy upstreams: If the proxy forwards to a container address or service name that resolves to IPv4 only, update the upstream or confirm name resolution.
Check the listen setting in your Compose file and the published port list, then restart the stack and test each path from the host and from the proxy.
The Kubernetes guide installs with Helm and states that the PostgreSQL bundled with the chart is for demonstration and test environments. It recommends a separately managed PostgreSQL for production. The listen address change reaches the cluster through Services, probes and ingress, so each of those objects that targets the authentik pods needs a check.
- Service ports and families: The port number does not change, but the pods must accept connections on the address family your Service and cluster networking use. Confirm this in a test cluster first.
- Probes: Liveness and readiness probes that address the pod IP or
localhostmust succeed after rollout. Watch for failing probes and restart loops during the upgrade. - Ingress controllers: The controller forwards to Service endpoints. If your cluster is single-stack IPv4, confirm that the controller can reach the pods on the address family the server now uses.
- Bundled database: If your values enable the bundled PostgreSQL, treat that deployment as a test setup. For production, point the connection settings at an external, separately managed database and plan that move as its own change.
Render the Helm manifests before and after the upgrade, diff them, and confirm probes, Services and ingress targets in a non-production cluster first.
authentik 2026.5 deprecates AUTHENTIK_POSTGRESQL__CONN_OPTIONS, and the option is slated for removal in the next version. The setting can be defined in several places in both deployment models, so checking a single file will miss copies. The 2026.5 release notes are the authority for the replacement setting, and you should read them before you edit anything.
- Compose files: Search Compose files, override files and
.envfiles for the variable. Check the server and worker services, since both connect to PostgreSQL. - Helm values and arguments: Check values files,
--setflags in deployment scripts and any CI pipeline that renders the chart. - Secrets and config objects: Check Kubernetes Secrets and ConfigMaps that supply environment variables, along with entries in external secret managers that sync into the cluster.
- Replacement setting: Confirm the new key and its format in the 2026.5 release notes. Do not take the replacement name from this page or from older guides.
Record every location where the option appears, apply the replacement in a test environment, verify the connection, and remove the old key from production only after that test passes.
Why SAML issuers and OAuth2 redirect URIs change for existing applications
From authentik 2026.5, the SAML provider sets the Issuer automatically to https://<authentik host>/application/saml/<application_slug>/metadata/. Older installs usually did not rely on that default. Integration guides from earlier releases told administrators to set the issuer by hand, typically to the plain string authentik. That means many existing SAML applications were configured with a value that no longer matches what authentik sends after the upgrade. The service provider decides whether to accept an assertion by comparing the issuer it was configured with against the issuer in the response, so a changed value can stop SAML login even though the certificates and endpoints are unchanged.
Redirect URIs change in a similar way. Before 2026.5, every OAuth2 redirect URI was treated as the Authorization type, which is why integration guides told older installs not to configure a Post Logout URI. From 2026.5 each URI carries its own type, so the typed entries must be reviewed application by application. A practical checklist for each existing integration: record the current issuer, entity ID and redirect URIs from the provider settings; compare them with the values the application's own configuration expects; decide whether the issuer should be pinned to the old string or moved to the new metadata URL, and change the service provider to match; confirm that every logout URI is entered as a Post Logout type; and test a full login and logout in a non-production copy of the application. The Keycloak integration guide is a useful comparison point for how a typical integration guide lays out these fields. Confirm the exact field names and defaults for your version in the 2026.5 release notes before you change anything.
What to prepare before you upgrade authentik
Most authentik 2026.5 surprises come from settings and integrations that the release changes silently. The cards below cover what to collect, back up and assign before the upgrade window opens, so that each change is checked against a known baseline.
Tested PostgreSQL backup and restore
Take a full PostgreSQL backup of the authentik database and restore it into a separate instance before the upgrade. authentik keeps all configuration and data in PostgreSQL except uploaded files, so this backup is the rollback point for the whole deployment. Confirm the restore completes and that you can log in to the restored copy. An untested backup gives you no safe way back if a migration fails.
Inventory of SAML and OAuth2 applications
List every SAML and OAuth2/OIDC provider with its current issuer, redirect URIs and whether a Post Logout URI is configured. Before 2026.5, OAuth2 redirect URIs were all treated as Authorization type, so some applications may have logout behavior that depends on that. The 2026.5 release also sets SAML issuers automatically, so record the existing value for each application to compare after the upgrade.
Listen address and connection option settings
Search compose files, Helm values, systemd units and environment files for the listen address setting and for AUTHENTIK_POSTGRESQL__CONN_OPTIONS. The default listen IP changes from 0.0.0.0 to [::] in 2026.5, which matters for hosts or proxies that expect IPv4-only binding. The CONN_OPTIONS key is deprecated and will be removed in a later version, so mark each occurrence for review.
Staging copy of the full stack
Build a staging stack with the same server, worker, PostgreSQL version, reverse proxy configuration and a copy of the production database. Run the 2026.5 upgrade there first and log in with each application type you run. Staging also reveals whether relying parties accept the new SAML issuer value or the typed redirect URIs before any production user is affected.
Freeze window and rollback decision
Agree a change freeze for the period between the database backup and the verified upgrade, and name who can declare a rollback. Changes to applications, flows or users during that window complicate restores. Decide in advance which backup you restore from and who confirms that the restored system is working, so the decision is not made during an incident.
Named owner for each integration
Assign one person per integrated application to confirm sign-in and logout after the upgrade. Owners know which redirect URIs their application expects, whether it validates the SAML issuer, and which users must be tested. Without named owners, a broken SAML trust or logout flow may only be reported by end users after the change window has closed.
The authentik 2026.5 upgrade sequence with checks and rollback points
This sequence moves an authentik deployment to 2026.5 in an order that exposes the three behavior changes (listen address, SAML issuer and typed redirect URIs) in staging before production, and gives each stage a check that must pass before the next one starts.
Confirm the current version and upgrade path
Record the running authentik version for the server and worker, and confirm it is the version immediately before 2026.5 in the release sequence. authentik upgrades are applied one release at a time, so an install that is several versions behind needs its intermediate upgrades first. Check the current version in the admin interface and against the release notes on the releases page. The step is done when you have a written version record for every container and a confirmed path to 2026.5.
Back up PostgreSQL and configuration
Take a logical backup of the authentik PostgreSQL database and copy the environment file, Compose or Helm values, reverse proxy configuration and the media or data directory that holds uploaded files. PostgreSQL stores all configuration and data except uploaded files, so the database backup is the core of the rollback point. Restore the backup into a scratch database to confirm it is readable. The step is done when the restore test completes and the backup location, checksum and date are recorded.
Update listen address and connection options in staging
In a staging copy of the deployment, replace the deprecated AUTHENTIK_POSTGRESQL__CONN_OPTIONS setting with the connection parameters your PostgreSQL setup needs, and set the listen address explicitly. The default listen IP changed from 0.0.0.0 to [::] in 2026.5, so any reverse proxy, health check or container port mapping that reaches authentik by IPv4 needs confirming. Check the 2026.5 release notes for the replacement setting and its removal timing. The step is done when staging starts cleanly with no deprecation warnings and the proxy can reach the listener.
Set explicit SAML issuers on existing providers
List every SAML provider and record the Issuer value each relying party currently trusts. From 2026.5, the Issuer is set automatically to the application metadata URL, while older versions used the value authentik. Where a service provider has that older value in its configuration, set the Issuer explicitly on the provider so it keeps the value it trusts. Review each change against the relying party's configuration. The step is done when every SAML provider that must keep its issuer has a written value, and the list is checked against the relying party settings.
Review typed redirect URIs on OAuth2 providers
Before 2026.5, all OAuth2 redirect URIs were treated as Authorization type. After the upgrade, each redirect URI is typed, so review every OAuth2 and OIDC provider and confirm which entries are authorization callbacks and which are post-logout URIs. Remove any post-logout URI that was added as a workaround and make sure logout flows still match the registered values. The step is done when each provider's redirect list matches the application's registered callbacks in a test login and logout.
Upgrade staging server and worker together
Update the server and worker containers in staging to the same 2026.5 image, and run the database migrations as the upgrade does on start. Keep the server and worker on matching versions, because background tasks and the core share the same database schema. Watch the startup logs for migration errors and confirm the admin interface loads. The step is done when both containers report the new version, migrations complete without error, and no task queue errors appear after a few minutes of normal use.
Test each integration and outpost in staging
Run a login, token refresh, logout and SAML metadata fetch for each application that depends on authentik, and check that any LDAP, RADIUS, proxy or RAC outposts still connect after the core upgrade. Outposts should run the same version as the core, so confirm their version in the admin interface before you test them. Record the result for each integration against the checks you defined in the earlier steps. The step is done when every integration has a recorded pass, and any failure has a cause and a fix or a planned rollback.
Run production upgrade and verify logins
Schedule the production upgrade in an agreed change window, repeat the staging steps in the same order, and take a fresh database backup immediately before the change. After the upgrade, verify a sample login for each protocol, the SAML metadata URLs for providers that must keep their issuer, and outpost health. Define the rollback point as restoring the pre-upgrade backup rather than downgrading the containers, because schema migrations are not reversed by an image rollback. The step is done when the verification checklist is signed off, or the restore has been completed and documented.
What makes an authentik 2026.5 upgrade take longer
This table lists the factors that stretch an authentik 2026.5 upgrade and the direction each one moves effort. Use it to explain a quote: each driver shows what to count in your environment before asking for a fixed-scope estimate.
| Driver | Why it changes effort | How to size it in a quote |
|---|---|---|
| Number of SAML and OAuth2 applications | Each SAML provider now derives its Issuer automatically from 2026.5, and each OAuth2 redirect URI must be reviewed for its typed Authorization or Post Logout kind | Count providers by protocol and list which ones were configured with a hand-set issuer or post logout URI |
| Custom code or scripts reading issuers or redirect URIs | Scripts that hard-code the old issuer value or parse redirect URI lists break silently and need testing against the new values | Ask for an inventory of scripts, CI jobs and relying-party code that read authentik metadata or tokens |
| Use of deprecated PostgreSQL connection options | AUTHENTIK_POSTGRESQL__CONN_OPTIONS is deprecated and slated for removal in the next version, so each environment file or Helm value must be found and migrated | Search every environment file, Compose override and Helm values set for the connection options and count them per environment |
| Separate outposts that must match the core version | LDAP, RADIUS, proxy and RAC outposts need to run the same version as the core, so each one is a separate image update and health check | Count outposts and note whether each one upgrades automatically through an integration or needs a manual image tag change |
| Database size and restore time | A full backup and a tested restore set the rollback window, and larger databases take longer to dump, restore and verify | Ask for the current database size and the time a restore took in a previous rehearsal, not a generic estimate |
| Number of environments | Each environment (development, test, staging, production) repeats the configuration review, the migration run and the verification steps | Count environments and confirm which ones are in scope for the engagement and which are maintained by your team |
| Whether a staging copy exists | A staging copy with recent production data lets the migration and redirect URI tests run before the production window; without one, testing is slower and riskier | Confirm whether a refreshed staging copy with a recent backup exists and who controls access to it |
Questions teams ask before upgrading authentik to 2026.5
How much effort does an authentik 2026.5 upgrade take?
The effort depends mostly on how many applications authentik signs users into, how many of them use SAML or OAuth2 redirect URIs that the 2026.5 changes touch, and how the current deployment is run. A single instance with a few well-documented integrations is a much smaller job than a multi-environment platform with dozens of connected applications, custom flows and outposts. The biggest variables are the number of SAML providers, the state of the existing redirect URI configuration, and whether the team has a tested backup and staging copy to rehearse on. Ask any partner to break the estimate into inventory, staging rehearsal, production cutover and post-upgrade verification, so each phase is visible in the quote.
Can our own team upgrade authentik to 2026.5 without outside help?
Yes, a team with Linux, container and PostgreSQL skills can perform the upgrade using the release notes and its own staging environment. The work is mostly careful inventory and testing rather than specialized tooling. Outside help tends to be valuable when the team lacks time to review every SAML provider, when several environments must move in lockstep, or when changes to listen addresses, reverse proxy rules or database connection options affect systems the team does not fully control. Whichever route you choose, confirm who owns rollback and who signs off on each application after the cutover.
What does the upgrade need from our staff?
The upgrade needs people who know each connected application well enough to test sign-in and sign-out. Application owners should confirm which SAML issuer values, post logout URIs and redirect URIs their integrations use, and they should test login in a staging instance before production changes. Platform engineers need to review the listen address and PostgreSQL connection settings in their deployment files, and a security or identity lead should approve the change window and the rollback plan. Plan time for these reviewers before the work starts, because waiting for application owners is a common cause of delay.
Can we skip versions and jump straight to authentik 2026.5?
No. authentik upgrades must follow the sequential path, moving through each supported release in order rather than jumping to 2026.5 directly. Skipping releases risks migrations that have not run and configuration that no longer matches the running code. Check the release notes for every intermediate version between your current release and 2026.5, and confirm the upgrade order with the authentik documentation before you schedule a window. If your instance is several versions behind, plan the catch-up as its own phase with backups taken before each step.
How do we handle SAML applications that depend on the old issuer?
From 2026.5, the SAML provider sets the Issuer automatically to the metadata URL pattern for each application slug, while older versions defaulted to the value authentik. Before the upgrade, record the issuer currently configured in every SAML service provider and compare it with the new automatic value. Where a service provider has the old issuer hard-coded, either update the service provider to trust the new value or set the issuer explicitly in authentik so existing sign-ins keep working. Test each application in staging, and re-download and re-import metadata where the service provider requires it.
What should a quote for the upgrade include?
A written quote should list the scope in concrete terms: the environments covered, the number of applications and integrations reviewed, the redirect URI and SAML issuer changes to be made, the staging rehearsal, the production cutover window, the backup and rollback steps, and the post-upgrade checks. It should name the deliverables, such as an inventory of changed settings and a verification record, and state which responsibilities sit with your team, such as application owner testing. DeployOpen works on fixed-scope engagements, so scope, deliverables and timelines are agreed in writing before work starts, and ongoing support can be added as a retainer if you want help after the upgrade.
Which authentik versions receive fixes while you plan
The authentik security policy currently lists 2026.5.x and 2026.8.x as the versions receiving security fixes, so a 2026.5 deployment stays inside the supported window only while you run a current patch release of that line. The project announces security releases at least 24 hours in advance. That notice period is short, so the team should subscribe to the release feed and name the person who can schedule a patch window on short notice. Treat the 2026.5 upgrade as a planned change with a named target patch version and a recurring check of the support list on the authentik security policy before you set the cutover date.
Plan the 2026.5 path with the 2026.8 line in view. Both lines are supported today, but 2026.8 changes how trusted proxy headers are accepted and how WebAuthn behaves. Those changes touch the same reverse proxies and passkey enrollments that your 2026.5 integrations depend on, so decide early whether your target is a 2026.5 patch release or a move to 2026.8. The 2026.8 changes are covered on a separate page, so read that page before choosing a target. Record the decision, the target patch version and the date you last checked the policy in your change ticket so the next reviewer can see what was current when you made it.
How DeployOpen scopes and delivers an authentik upgrade
DeployOpen treats the authentik 2026.5 upgrade as a change to the running identity service and to every application that signs users in through it. We start from an inventory of your deployment, the listen address and PostgreSQL settings, and your SAML and OAuth2 integrations, then agree the work in writing before anything changes.
How we scope
- The written scope lists each authentik instance, outpost and integration covered by the 2026.5 upgrade.
- We inventory listen address settings, the deprecated PostgreSQL connection option and every SAML and OAuth2 provider.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- Ask us to confirm which integrations need Post Logout URI or typed redirect URI changes before quoting.
How we build
- We prepare the upgrade in a non-production copy of your deployment inside your own infrastructure.
- We set the listen address explicitly and update the PostgreSQL connection settings to the replacement configuration.
- We record each SAML issuer value and redirect URI before and after the change and test sign-in for every application.
- We verify the upgrade path against the authentik release notes for each version we cross.
How we hand over
- You receive a written record of the configuration changes, test results and the integrations verified after the upgrade.
- The handover includes a runbook covering rollback from backups, since authentik downgrades are not the recovery path.
- We document every integration that required a manual update, so your application owners know what changed.
- Your team keeps full ownership of the environment, credentials and the running authentik deployment.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after the handover.
- A retainer can cover monitoring the authentik security policy and planning the next supported release.
- Ask for the support hours, response channels and escalation path in the written quote.
- Confirm with us which future releases your retainer covers before you sign the scope.
