Managing authentik with Terraform: provider setup and services

Why teams manage authentik with the Terraform provider

A platform team that has built SSO by hand in the authentik admin UI usually reaches a point where every change to a provider, application, flow or group needs review, a repeatable path to another environment and a record of who changed what. The goauthentik Terraform provider answers that need. It manages authentik configuration (applications, providers, flows and groups) as Terraform resources, so a change becomes a reviewed pull request, a plan that shows the effect before apply, and a state file that tracks what the provider owns. The provider is licensed under GPL-3.0, and its repository, goauthentik/terraform-provider-authentik on GitHub, is the place to confirm the license terms your legal team will ask about.

The admin UI remains the right tool for exploring settings, testing a flow in a browser and handling a one-off recovery during an incident. Terraform fits when the same configuration must exist in more than one environment, when several people or pipelines change it, or when auditors expect changes to be traceable to an approved commit. Blueprints are the other option: they are YAML files that authentik itself discovers and applies, which suits teams that want configuration to live inside the product and not in a separate toolchain. Choosing between them is a decision about who owns the change path, not about which one is more capable. Most teams should write that decision down before they write the first resource.

Before adopting the provider, confirm three things: which authentik release your environment runs, which provider version is tested against that release, and whether your team already has a Terraform or OpenTofu workflow with remote state. The provider is versioned to the authentik release it is tested against, so a mismatch is the most common source of avoidable failures. Ask who will hold the state file, where it is stored and who can run apply against production. Those answers determine whether Terraform will reduce risk for your platform team or add a second source of truth that drifts from the admin UI.

Choosing between Terraform, blueprints and the admin UI

This table compares the admin UI, the goauthentik Terraform provider and authentik blueprints on who makes changes, how they are reviewed, how objects are tracked and how they fit existing pipelines. Read each row against the objects you plan to manage, because whichever tool creates an object is the one that should keep changing it. Mixing tools on the same object is the main risk to avoid.

Decision factor	Admin UI	Terraform provider	Blueprints
Who makes changes	Administrators clicking in the web interface	Platform or identity engineers running plans from a repository	Engineers committing YAML files, or operators loading blueprints from the blueprints directory or a database-stored instance
Review and approval	Usually none unless you add a separate change process	Pull request review and plan output before apply	Pull request review of YAML, with changes applied by reconciliation
How objects are tracked	Only in the live database, with no external record unless you export it	Terraform state file, which must be stored and protected carefully	Blueprint files and their metadata, with reconciliation keeping database objects aligned
Fit with existing pipelines	Poor fit for automated delivery, suited to one-off or emergency changes	Good fit where Terraform already manages cloud and SaaS resources	Good fit for teams that version everything as code and deploy with the server
Ownership of each object	Object owned by whoever last edited it, which drifts over time	Object owned by one Terraform configuration, so confirm no blueprint also manages it	Object owned by the blueprint that defines it, so confirm no Terraform resource also manages it
Drift handling	Manual changes are not detected	Plan shows drift from the recorded state	Changes trigger reconciliation, so confirm how manual edits interact with the next run
Version alignment	Matches the running authentik release by default	Confirm the provider release matches your authentik version	Confirm blueprint schema matches your authentik version

Matching the provider version to your authentik release

The provider is tied to the authentik release it is tested against, so the Terraform provider version is a compatibility decision, not a free choice. The cards below cover the version rule, the supported lines, upgrade sequencing and what to check before you pin.

Provider versions follow authentik releases

The provider is versioned to the authentik release it is tested against. The README's example pairs provider 2021.8.1 with authentik 2021.8.x, so the minor line of the provider should match the minor line of your server. A provider pinned to a different line may fail on resources, fields or API behavior that changed between releases. Check the release line before you write the first required_providers block.

Supported authentik lines

The authentik security policy lists 2026.5.x and 2026.8.x as the supported lines receiving security fixes. A Terraform configuration that targets an unsupported server line carries the same exposure as the server itself, so confirm your server line is in that list before you invest in provider work. Note that a provider pinned to a line that is no longer supported may still need fixes that only exist on a newer release.

Plan provider and server upgrades together

Every authentik server upgrade is a candidate for a provider upgrade, because new fields and changed defaults appear in the same release. Schedule the provider bump in the same change window, in a staging environment first, and run terraform plan against the upgraded server before applying anything. Treat a plan that shows unexpected updates to existing applications or flows as a stop signal, not as noise.

Read the compatibility notes before pinning

Before you pin a version, read the provider's release notes and README for the authentik line you run. Confirm which resources are covered, which arguments were renamed or removed, and whether any resource depends on behavior from a specific server release. Record the pair of versions in your repository so that a future reviewer can see which provider was tested against which server.

Pin exact versions in code

Use a version constraint that stays within the minor line you tested, rather than an open range that can pull in a newer provider during a routine terraform init. Commit the dependency lock file so every operator and CI runner resolves the same provider build. Pair the pin with the authentik server image tag in your deployment repository, so one review covers both sides of the match.

Validate the pair in staging first

Run the matched provider and server pair in a non-production authentik instance before promoting it. Apply the configuration, confirm that no resource drifts on a second plan, and test a login through one application created by Terraform. Document the outcome so that the production change repeats a path that has already passed, not a guess about compatibility.

Terraform or OpenTofu: what changes for your workflow

Teams that already run HashiCorp Terraform across their infrastructure usually keep it for authentik. The goauthentik provider is published as a Terraform provider, so existing workflows, pipelines and state backends can stay in place. The change is limited to adding the provider block, pinning its version, and reviewing how it is tested against authentik.

Pin the provider version: The provider repository ties each provider release to the authentik release it is tested against, so pin both the provider and the authentik version you run.
Review the license for your use: The provider is GPL-3.0 licensed according to its repository. Confirm with your legal team how that license applies to your internal tooling.
Keep existing state backends: Your current remote backend and locking setup can hold authentik resources alongside other stacks, but separate state files per authentik environment reduce blast radius.
Track HashiCorp licensing changes: Confirm the current terms for your Terraform version with HashiCorp before standardizing on it for the long term.

Before you commit, check the exact provider version against your authentik version in a non-production environment and run a plan against a copy of your configuration.

How to set up the authentik Terraform provider in order

This sequence takes a team from an unmanaged authentik instance to a Terraform configuration that manages one application and provider pair, with a clean plan proving the code matches the live system. Each step closes with a check you can run before moving on.

Pin the authentik release and provider version
Record the exact authentik server version running in your non-production instance, then choose the goauthentik/terraform-provider-authentik release that is tested against that same authentik version. The provider is versioned to the authentik release it targets, so the two must line up. Store both versions in your repository, for example in the version constraint of the provider block and in a note beside your deployment configuration. Done when a reviewer can read the pinned server version and provider version from the repository without asking anyone.
Create a dedicated service account with narrow scope
Have an authentik administrator create a service account used only by Terraform, then generate an API token for it. Grant it only the permissions needed for the object types you plan to manage, rather than a superuser role, and document which groups and roles it holds. Keep the token out of version control and record who owns the account and how it is rotated. Verify by logging in as that account in a test session and confirming it can read the objects in scope but cannot perform unrelated administrative actions.
Configure a remote state backend with locking and encryption
Set up a remote backend for Terraform or OpenTofu state that supports locking and encrypts data at rest, so two runs cannot write state at the same time and state is never stored in plain form on a laptop. Because state holds configuration that can include sensitive values, confirm with your platform team which encryption keys and access controls apply. If you use OpenTofu, its documentation describes state and plan encryption with several key providers, and you should check which of them your environment supports. Done when a test run acquires and releases a lock on the backend without error.
Declare the provider with URL and token from variables
In the root module, declare the authentik provider with the instance URL and the API token supplied as input variables marked sensitive. Pass the token through your CI secret store or an environment variable, never as a literal value in a .tf file. Run initialization so the provider downloads at the version you pinned, and check the lock file for that version. Verify by running a validate command, which should pass without contacting configuration you have not written yet.
Import or create one application and provider pair
Choose a single application and its provider in your non-production instance as the first managed object. If the pair already exists, import both resources into state using their identifiers so Terraform adopts them without recreating them. If it does not exist, create the provider and application in code. Keep the first object small, because it proves the workflow before you add flows and groups. Confirm the import succeeded by checking that state lists both resources with the identifiers you expected.
Run plan and review the diff
Run a plan against the non-production instance and read every proposed change before approving it. A clean import should show no changes to the resources you adopted, while any update or replacement needs an explanation, since replacing a provider can break the applications that depend on it. Check that secrets, client identifiers and redirect URIs in the diff match what the live application uses. Do not apply until the diff is understood by the person who owns the application.
Confirm an empty plan on a second run
Apply the configuration once, then run the plan again with no code changes. The second plan should report no changes, which shows that the code describes the live state and that the provider does not perpetually drift on a field. If the second plan proposes changes, investigate the field before expanding scope. Record the result in your change log and keep this check in your pipeline so each future change starts from a known baseline.
Decide how Terraform and blueprints divide ownership
Before adding more objects, write down which authentik objects Terraform manages and which, if any, are delivered as blueprints. authentik documents that blueprints stored in the database can be managed through external tools such as Terraform, and changes trigger reconciliation, so two systems writing the same object will fight each other. Assign each object type to one owner, and make the choice visible to everyone who edits authentik. Done when the ownership list is committed next to the Terraform code and the team has reviewed it.

Combining Terraform with blueprints without fighting over objects

The main risk of running Terraform and blueprints together is that both can write the same object. If a flow, provider or application is declared in a Terraform configuration and also in a blueprint, the two tools will keep pulling it toward different states. Blueprints stored in the database are reconciled when they change, so a blueprint that still describes an object can overwrite a value Terraform set, and a manual edit in the admin interface can be reverted the next time reconciliation runs. The fix starts with a written ownership map: for every flow, provider, application and group, name exactly one tool that is allowed to change it.

A split by object type is usually the simplest to enforce. For example, one team could manage applications and providers in Terraform while blueprints own the flows, stages and policies that the platform team maintains. A split by environment works differently: Terraform owns everything in a development or staging tenant, and blueprints own production, or the reverse. Either pattern only holds if the boundary is recorded in the repository, reviewed in pull requests and reflected in who has permission to edit objects in the admin interface. Avoid any arrangement where a single object is referenced by both tools, even as a lookup, unless you have confirmed how the reference behaves on apply.

Blueprint apply and rollback also interact with Terraform state. Terraform records the objects it created by their identifiers, so a blueprint that deletes or recreates one of those objects can leave state pointing at something that no longer matches the live configuration. Plan a test in a non-production instance: apply a blueprint that touches a Terraform-managed object, observe whether the value is reverted, then run a plan and confirm what Terraform reports. Confirm the exact reconciliation behavior in the authentik version you run, using the authentik blueprints documentation, before you adopt any split. Record the result so that rollback steps for each object type are agreed in advance.

Protecting the admin token, state and pipeline

Managing authentik with Terraform depends on three controls working together: protecting the state that records your configuration, limiting the credential that changes it, and making every change visible before it reaches the live instance. The cards below pair each risk in that chain with the control that addresses it.

State files hold secrets

Terraform state records the attributes of every authentik object it manages, and some of those attributes are sensitive, including client secrets for OAuth2/OIDC providers. Use an encrypted remote backend with locking so two runs cannot write state at the same time, and restrict read access to the people and pipelines that need it. OpenTofu can encrypt state and plan files at rest, but the key providers you can use depend on the backend and key provider you choose, so confirm that combination before you rely on it.

Admin token with broad rights

The provider authenticates to authentik with an API token, and a token created during initial setup often has rights across the whole instance. A long-lived administrator token stored as a CI variable lets anyone who can read pipeline settings change flows, providers and groups. Use a token created for Terraform only, with the narrowest permissions your authentik version supports, store it in the pipeline's secret store, and rotate it on a schedule. Confirm which token types and permissions your version offers before you design the pipeline.

Drift from UI edits

Administrators can still change applications, flows or groups in the authentik admin interface, and Terraform will not know until the next plan. Run a scheduled plan against the live instance, alert on any difference, and treat each result as a review item that someone must resolve before a fix is applied. Decide per object whether the UI or the code is the source of truth. Blueprints stored in the database also reconcile when changed, so two tools managing the same object will overwrite each other.

Changes applied without review

A local apply from an engineer's laptop skips the record of who changed what and why. Protect the main branch, require the plan output to be posted on every merge request, and allow only the pipeline to run apply after approval. Save the plan file as an artifact so the reviewed plan is the one applied. Restrict who can approve changes to authentication flows and access groups, since those changes affect who can sign in.

Unpinned provider and tool versions

The provider is versioned to the authentik release it is tested against, so a mismatch between provider and server can produce plan errors or unexpected diffs. Pin both sides: the provider version and the OpenTofu version in your pipeline. Change those pins in the same reviewed change as an authentik upgrade, and confirm the pairing in the provider repository before you upgrade either side.

Questions teams ask before managing authentik with Terraform

What does a Terraform rollout for authentik cost in effort, and which parts are one-time?

Most of the effort is front-loaded: designing the module layout, building the pipeline, and setting up state storage and access. These are one-time costs, although they are rarely small because each team's naming, groups, flows and application catalog has to be mapped into code. Recurring costs are provider upgrades, which must match the authentik release you run, periodic drift review, and onboarding of new applications into the code base. Cost rises with the number of applications, custom flows and review gates your organization requires. A quote from DeployOpen follows the written scope, which lists the object types, environments and pipeline targets to cover. Ask for the one-time and recurring split to be stated separately.

Can one in-house engineer manage authentik with Terraform alone?

One engineer with solid Terraform and authentik knowledge can run a small, single-environment setup, but it is risky to depend on one person for state, provider upgrades and incident response. The work spans three skill areas: Terraform structure and state handling, authentik's object model for providers, flows and groups, and the review and change process your security team expects. A second reviewer is useful for changes to authentication flows and privileged groups, where a mistake can lock users out. Ask whether the internal team can cover on-call and upgrade windows before deciding to build alone. DeployOpen can plan the work so that knowledge is documented and handed over in the written scope.

How long does a first Terraform pilot for authentik usually take?

The duration depends mainly on how many objects the pilot covers and how long your review process takes, not on the Terraform syntax itself. A pilot that imports a few providers, applications and groups into code on a test instance moves faster than one that also models every flow, policy and branding setting. Approval steps, change advisory boards and security sign-off often take longer than the code. Ask for a timeline in the written scope that lists the object count, the test environments, and the review gates, so you can see which factor drives the schedule. DeployOpen does not publish durations; estimates come from the agreed scope.

What does the team need to provide before a Terraform engagement starts?

Plan for four inputs before work begins:

A dedicated authentik test instance, matching the production release, where changes can be applied and checked.
An API token policy that grants only the permissions the Terraform identity needs, with a named owner and a rotation process.
A chosen state backend and access model, including who may read or write state, and where backups are kept.
A list of the applications, providers, flows and groups in scope, along with the source of truth for each.

Missing any of these usually extends the pilot. Confirm the backend options with your platform team, and confirm token handling against your own security policy.

Can Terraform replace authentik blueprints?

Terraform can manage most of the same objects as blueprints, but the two are not interchangeable in every case. authentik documents that blueprints stored in the database can be managed through external tools such as Terraform, and that changes trigger reconciliation. This means Terraform works as an external controller of authentik configuration, while blueprints remain the in-product mechanism for YAML-based configuration files. Choose one primary source of truth per object to avoid conflicting reconciliation. Many teams keep Terraform for identity objects they already manage across other systems and use blueprints for bootstrap or self-contained deployment content. The right split should be decided during scoping.

Which provider version should match my authentik version?

The Terraform provider is versioned to the authentik release it is tested against. The provider README gives the pattern with an example: provider 2021.8.1 is tested against authentik 2021.8.x. Pin the provider to the version that matches your running authentik release, and plan an update of both together during an upgrade. Check the provider's releases and README before each authentik upgrade, because a mismatch can cause unexpected plan changes or failed applies. Confirm the current compatibility table with the provider repository rather than relying on older documentation.

Is OpenTofu a suitable alternative to Terraform for this work?

OpenTofu is a practical option if your organization prefers an open-source licensed tool. It is licensed under the Mozilla Public License 2.0, is under the Linux Foundation's stewardship, and its website describes it as a drop-in replacement for Terraform that preserves existing workflows and configurations. The project was accepted to the CNCF at the Sandbox maturity level on April 23, 2025. Its FAQ does not guarantee compatibility with future Terraform releases, so verify provider and feature support against the version you choose. Check the OpenTofu migration guide if you already have shared state through the terraform_remote_state data source, since that case needs extra care.

Limits to confirm before committing to Terraform

The goauthentik provider moves with authentik releases, so coverage, upgrade behavior and tool support all depend on the exact versions you run. Treat each card below as a check to complete against the provider repository and a test instance before you commit production configuration to Terraform.

Object type coverage

Confirm which authentik object types the provider manages at the version you run. Applications, providers, flows, stages, policies and groups are the core objects most teams need, but support for a given type can differ between provider releases. Check the provider's resource list against the objects in your design, then apply a sample of each on a test instance. Any object type without a resource needs to be managed another way, such as a blueprint.

Changes made in the UI

Confirm what happens when an administrator edits or creates an object in the web interface that Terraform also manages. Drift can appear on the next plan, or Terraform can overwrite a manual change on apply. Decide now whether the UI is read-only for managed objects, and document the rule your team will follow during incidents.

Provider behavior across server upgrades

Confirm how a provider release lines up with the authentik server you run, since the provider is versioned to the authentik release it is tested against. Plan to upgrade the provider and the server together, and test a plan against the new server version before applying it to production. Record which provider version each environment uses.

Import of existing objects

Confirm that the provider supports importing the objects you already have, so you do not recreate applications or flows that users depend on. Test the import of one representative object of each type, then check that a follow-up plan shows no changes. Without a clean import, the first apply can alter live sign-in behavior.

State storage and secrets

Confirm where state lives and how it is encrypted, because state can contain provider credentials and configuration values. Use a remote backend with access controls and encryption, and keep the API token out of version control. Check how your chosen backend handles locking so two runs cannot change the same objects at once.

Supported tool for your provider version

Confirm whether Terraform or OpenTofu is the tool the provider release is tested with, and whether your chosen tool is supported for it. The provider repository is GPL-3.0 licensed, and OpenTofu offers a compatibility path, but its compatibility with future Terraform releases is not guaranteed. Pin the tool version alongside the provider version in your repository.

How DeployOpen scopes and delivers Terraform management for authentik

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside the client's own infrastructure, and this work follows the same pattern. Each engagement starts with a written scope that sets which authentik objects Terraform will own, which versions are pinned, and how the state is stored and protected.

How we scope

Inventory which authentik objects Terraform will own and which stay under manual or blueprint control.
Confirm the authentik release in use and the matching provider version before any code is written.
Agree in writing how state storage, locking, encryption and access will be handled in your environment.

How we build

Write Terraform modules for applications, providers, flows, groups and bindings against your agreed object list.
Test plans against a non-production authentik instance and review each diff before it reaches production.
Decide with you whether Terraform or OpenTofu is the execution tool, and verify the chosen version against your configuration.

How we hand over

Deliver the code repository, module documentation, pinned version matrix and the state backend setup.
Document the upgrade sequence for authentik and the provider, including how to rerun plans after each change.
Walk your platform and security teams through the review, apply and rollback procedure.

How we support

Offer ongoing support, provider upgrades and continuous testing as a retainer, separate from the fixed-scope build.
Re-test Terraform plans when a new authentik security release or minor version changes object schemas.
Keep the agreed runbooks current so your team can operate Terraform-managed authentik without outside help.