Why teams manage authentik configuration as code with blueprints
When several authentik environments are changed through the admin UI, they drift apart. A flow tweaked in staging, a provider redirect URI added in production only, and a group created by hand in one tenant all become invisible differences that surface during an incident or an upgrade. Blueprints are YAML files that describe flows, providers and applications, and authentik applies them to the instance. Because the desired state lives in files, a team can review changes in version control, promote them through environments in the same order, and rebuild an instance from a known starting point.
Blueprints fit three situations. The first is multiple environments that must match, such as development, staging and production. The second is audit requirements, where a reviewer needs to see who changed an access path, when, and through which approved change. The third is repeatable rebuilds, for disaster recovery or a new region, where restoring a database alone does not prove the configuration is what the team intended. The admin UI remains sufficient for a single small instance, for exploratory work on a flow before it is captured in a file, and for emergency fixes that are later written back into the repository. Confirm with your team which of these changes must go through review before anyone edits production directly.
DeployOpen plans and implements blueprint-based configuration inside your own infrastructure, including the repository layout, the delivery path into each environment and the rules for who may change what. Before starting, ask your team to list the flows, providers and applications that must be identical across environments and the ones that legitimately differ, such as redirect URIs or branding. That list drives the design. Check whether your license tier covers the features you intend to manage as code, since some enterprise capabilities listed on the authentik pricing page are not part of the open-source edition.
How authentik discovers and applies blueprint files
authentik reads blueprints from a blueprint directory on the server, and the first thing to confirm in your deployment is that the files you version actually sit where authentik looks. According to the authentik blueprints documentation, blueprints are YAML files discovered from that directory, watched for changes, and rescanned every 60 minutes by default. That means an edit saved to a file is picked up without a restart, but not necessarily instantly, so a change you expect to see right away may take up to an hour to appear if the watcher does not catch it. Check the blueprint directory path and the rescan interval for your release in the blueprints documentation before you build a pipeline that depends on timing.
Blueprints can also come from sources other than the local directory. The documentation names an OCI registry and the database as additional sources. An OCI source lets you publish a blueprint as an artifact and have authentik pull it, which suits teams that already promote container images through a registry and want configuration to follow the same path. Database-stored blueprints are managed inside authentik itself, so they are harder to review in Git. Decide early which source is the system of record for each blueprint, and confirm how the server authenticates to an OCI registry in your environment, including any mirror you run in an air-gapped network.
Each blueprint is applied as a single atomic transaction. If any entry in the file fails validation or cannot be written, the whole blueprint rolls back, so you do not end up with half of a flow or provider created. This is the behavior that makes a failed change safe to retry, but it also means one bad entry blocks every other entry in that file. Keep blueprints small enough that a failure is easy to locate in the logs, and test each file against a non-production instance before it reaches production. Rollback protects the database state of one blueprint; it does not undo changes that other blueprints or manual edits have already made, so review the apply logs after each change.
Blueprint sources and when each fits
This table compares the three places authentik can load blueprints from: the blueprints directory, an OCI registry and the database. Read each row as a question you need to answer for your team, such as who edits the files and how changes get reviewed. The main takeaway is that the directory source suits Git-based review, while OCI and database sources suit different release and change-control models.
| Question | Blueprints directory | OCI-hosted blueprints | Database |
|---|---|---|---|
| How it is delivered | YAML files placed in the blueprints directory on the authentik server or worker, discovered and watched for changes | Blueprint packaged and pulled from an OCI registry, so the source is a versioned artifact | Blueprint instance stored in authentik's PostgreSQL and applied from there |
| How it is versioned | Versioned in your Git repository and mounted into the container, with the deployed copy matching a commit | Versioned by image or artifact tag in the registry, which you promote between environments | Not versioned by default; history depends on your own export and backup process |
| How it is reviewed | Standard pull request review of the YAML before merge | Review happens before the artifact is published to the registry | Review is weakest; changes made in the admin interface are not reviewed unless you add a process |
| Who can change it | Anyone with write access to the repository and the deployment mount | Anyone with push access to the registry and pull configuration on authentik | Any administrator with blueprint permissions in the authentik interface |
| Typical fit | Teams already running infrastructure as code who want review and a clear audit trail | Multi-environment rollouts where build pipelines promote one tested artifact | Quick edits or imports during testing, with a separate process to export and commit the result |
| Change timing | Picked up after the directory watch or the rescan interval, which is 60 minutes by default | Applied when authentik loads the blueprint from the registry, which you should confirm for your version | Applied when the blueprint instance is run from the interface or the API |
| Recovery after a bad apply | Revert the commit and redeploy the files; each apply is atomic, so a failing entry rolls back the whole blueprint | Deploy the previous artifact tag; the same atomic rollback applies to each blueprint | Restore from backup or reapply a known good export; confirm the rollback behavior for your setup |
| Main risk | Drift if someone edits the running container or the mounted files outside Git | Registry credentials and access control become part of the change process | Configuration exists only in the database, so it is hard to review, copy or rebuild |
Using context variables across environments
Development is where the blueprint is written and changed most often, so the goal is a single blueprint file that works unchanged on a laptop or test instance. Environment-specific values such as the external hostname, the redirect URIs and the names of test groups should come from context variables rather than being typed into the YAML. That way an engineer can point the same blueprint at a local instance without editing the flow or provider definitions. Keep development values in a local, uncommitted source so they do not leak into the shared repository.
- Hostname and URLs: Pass the local domain through a variable so redirect URIs match the test application.
- Test identities: Use clearly named test groups and users so they cannot be confused with real accounts.
- Relaxed settings: Development can use shorter token lifetimes or looser policies to speed testing, but record each difference.
- Throwaway state: Expect to reapply and reset the instance often, so keep the blueprint idempotent.
- Version pinning: Test against the same authentik version you plan to run in production.
Confirm the exact variable syntax and how context values are supplied in the blueprints documentation before you build the pattern, because the syntax is the part most likely to differ between versions.
Staging should mirror production as closely as the business allows, with the only intended differences being hostnames, scale and identity sources. Use the same blueprint files and the same variable names as production, supplying staging values from its own context. This makes the staging run a real rehearsal: if a blueprint applies cleanly in staging, the production apply is a repeat of a tested change rather than a first attempt. Treat any divergence in blueprint structure between the two environments as a defect to fix.
- Parity of structure: The same blueprint files should apply in both environments with only variable values changing.
- Separate credentials: Staging integrations, such as directory bindings and application client secrets, should be distinct from production.
- Promotion evidence: Keep a record of which blueprint revision passed in staging before it is promoted.
- Rollback test: Deliberately apply a broken blueprint in staging to confirm the atomic rollback behaves as expected.
- Discovery behavior: Check how changes are picked up from the blueprints directory, since the default rescan interval is 60 minutes.
Ask your team to document which values are allowed to differ between staging and production, and review that list whenever a new variable is added.
In production, context variables do the most important work: they keep one reviewed blueprint from being edited by hand for each deployment. Values such as the production domain, the names of approved groups and the allowed redirect URIs should be supplied from the production context, and the change should move through the same review path as code. Restrict who can change the blueprints and the variable sources, because a changed variable can alter who gets access. Recording the blueprint revision alongside each deployment makes audits and incident reviews much easier.
- Secrets excluded: Client secrets, bootstrap credentials, database passwords and API tokens should never be written into blueprint files or variable values committed to version control. Supply them through your secrets management system or the runtime environment, and confirm the supported method in the documentation.
- Approved values only: Keep production variables in a controlled location with limited write access.
- Change review: Route any change to a production variable through the same approval as a blueprint change.
- Audit trail: Record which revision and which variable set were applied, and when.
- Operator access: Limit who can read production context values if some of them reveal internal names or hostnames.
Confirm with your security team which variables are classified as sensitive and how your secrets tooling injects them into the authentik containers.
Air-gapped environments cannot fetch blueprints from a public source or reach external registries, so context variables and blueprint delivery must be planned around that constraint. Blueprints can be placed in the local blueprints directory, and if your organization hosts an internal OCI registry, blueprint delivery can be routed through it. Values that would normally be looked up externally, such as certain endpoints or update settings, should be supplied as explicit variables from a local source. Plan how the bundle is moved into the network, verified and then applied, since no step can rely on a live connection.
- Local delivery: Decide between the blueprints directory and an internal registry, and confirm both work without outbound access.
- Explicit endpoints: Replace any external URL with a variable that points to an internal service.
- Signed bundles: Verify the integrity of blueprint bundles before they cross the boundary, using your own process.
- Offline testing: Validate the blueprint in a connected staging environment, then transfer the same revision.
- Sensitive values: Keep secrets inside the enclave and supply them locally, never inside the transferred bundle.
Confirm with your authentik documentation which update checks and external fetches must be disabled in an air-gapped setup, and test the blueprint apply with networking blocked before go-live.
Setting up your first blueprint repository
This sequence moves a working authentik configuration from a test instance into a Git repository and then into the blueprints directory, so changes are reviewed, versioned and applied the same way every time. It finishes with proof that the blueprints apply and that a broken blueprint leaves the existing configuration untouched.
Export the configuration from a test instance
Start from a test authentik instance where the flows, providers, applications and policies already work. Export the objects you want to manage, either by building a blueprint from the admin interface or by writing YAML that matches the objects you can see there. Keep the export out of production, because it will contain object identifiers and possibly secrets you need to review. Check that the export is complete by listing each flow, provider and application you expect and confirming each one appears in the file set.
Split the export into flows, providers and applications
Divide the exported YAML into separate files by object type, such as one file for flows and stages, one for providers and one for applications. Keep related objects together and use stable identifiers, since other entries refer to them by identifier. Remove anything that should not be versioned, such as client secrets or environment-specific hostnames, and plan to supply those through context variables. Check the split by searching each file for references to objects defined in another file and confirming every reference resolves to an entry in the set.
Store the blueprint files in Git
Create a Git repository for the blueprint files and commit the split files as the first revision. Add a short README that explains the file layout, how environment values are supplied and who approves changes. Protect the main branch so changes arrive through reviewed merge requests, which gives you a history of who changed which flow or provider. Check that a clean clone of the repository contains every file and that the commit history shows the first revision as the baseline.
Deliver the files to the blueprints directory
Mount or copy the repository's blueprint files into the blueprints directory that authentik reads on the server. The path depends on how you deploy: confirm the directory for your Docker Compose, Kubernetes or other setup in the authentik documentation and in your own environment, then decide whether a CI job, a sync agent or a volume mount delivers the files. authentik watches the directory for changes and rescans it every 60 minutes by default, so note that a new file may take up to that interval to be picked up unless you trigger a rescan. Check the directory contents from inside the running container to confirm the files arrived with the expected names.
Confirm the blueprints applied
Watch the server and worker logs for blueprint entries that show successful application, and then open the admin interface and confirm each flow, provider and application shows the values from the files. Open the blueprint status view in the admin interface if your version provides it, and compare the reported state with the files. If an entry is missing, search the logs for the blueprint file name to find the error message. Check that a change made in the Git repository and delivered to the directory produces a matching change in the admin interface.
Test a deliberate failure to confirm atomic rollback
Create a scratch blueprint that changes one harmless value in an existing application and adds a second entry that references a flow identifier that does not exist. Deliver it to the blueprints directory and wait for it to be processed, or trigger a rescan. authentik applies each blueprint in a single atomic transaction, so the valid change should roll back when the invalid entry fails. Check the admin interface and the logs to confirm the first change did not persist and that the error names the failing entry. Then remove the scratch file and confirm the directory returns to the committed state.
Record the verified state and the change process
Fix the broken scratch entry in the repository only if you want to keep it as a regression case, otherwise delete it through a reviewed commit so the repository matches the directory. Document the rollback test result, the delivery path and the rescan behavior in the README so the next engineer can repeat the check. Agree with the approvers which changes must go through blueprints and which may be made in the admin interface, since the restriction policy determines what each team can change. Check that the repository, the directory and the running instance show the same configuration, and record that baseline as the reference for future reviews.
Restricting who can change blueprints
Blueprints apply configuration that can grant access, change providers and place secrets, so the same care you give application code applies here. The four cards below cover the main ways a change reaches production without the right review, and the control that closes each gap.
Write access equals administrative control
Anyone who can write to the blueprints directory or push to the OCI source that authentik reads can change flows, providers and applications. Treat that write path as administrative access. Limit who can write to the mounted directory on the host or in the container volume, and limit registry push rights to the pipeline identity that publishes approved blueprints. Check who holds these rights today, because they often sit with people who only need to read logs.
Secrets stored in YAML
A blueprint is a plain file, so a client secret or API key written into it ends up in version control, backups and shell history. Keep sensitive values out of the YAML and supply them through context variables or the environment at deployment time. Then scan repositories for credential patterns before merge. Confirm with the blueprint documentation which fields accept references, since not every field is suitable for injected values.
Unreviewed changes reaching production
A blueprint edit that is saved to a watched directory is picked up by authentik without a second person looking at it. Require a pull request with at least one reviewer for every change to the blueprint repository, and promote the same reviewed artifact through test and production rather than editing files on the production host. Keep a record of which commit or image digest is live so a rollback has a known target.
Drift from manual UI edits
An administrator who changes a provider in the admin interface creates a state that the YAML no longer describes. The next blueprint run may overwrite that change, or the change may survive and make the repository misleading. Decide which source is authoritative for each object, and make manual edits an exception that is either written back to the repository or reverted. Run a scheduled comparison of the live configuration against the repository to catch differences early.
Questions teams ask before managing authentik with blueprints
How much effort does the initial export and refactor take?
The effort depends mostly on how much configuration already exists in the admin UI and how much of it is shared across applications. A small instance with a handful of providers and flows is a short exercise, while a long-running instance with many custom stages, policies, property mappings and per-application variations needs a careful inventory before any YAML is written. The main drivers are the number of objects, how many are duplicates that should become one reusable entry, how many values are environment-specific (hostnames, client IDs, certificates, group names), and whether the team wants to replace the whole configuration or only new objects. Ask for an object inventory and a refactor plan in the written scope before agreeing on dates.
What does the work need from our internal team?
Your team needs to own the decisions that only your organization can make, and to be available to test the result. In practice that means naming the people who approve changes to flows, providers and applications, identifying the groups and sources that blueprints will reference, and providing a non-production authentik instance where applied blueprints can be checked. Engineers who already run authentik and understand its object model will move faster, because most review time goes to reading how objects relate to each other. Someone also needs to run the Git workflow, including code review, branch protection and how blueprint files are deployed to each environment.
Can our team manage blueprints without outside help?
A team with authentik operations experience and a basic understanding of YAML and Git can usually manage blueprints on its own once the initial structure is in place. Outside help tends to add the most value in the first export and refactor, when decisions about naming, reuse, environment variables and change control set the pattern for years. Ask any partner to state in writing what it will hand over, including the repository layout, the review process, a runbook for applying and rolling back changes, and the knowledge transfer sessions. Whichever path you choose, confirm that the people who will edit blueprints can test them against a staging instance first.
How does rollback work, and what are its limits?
Each blueprint applies in a single atomic transaction, so if any entry in a file fails, the whole file is rolled back and the failure is reported. That protects against half-applied changes, but it does not undo a change that applied successfully. To roll back a working change, you revert the blueprint file in Git and let authentik apply the previous version, which is a new forward change rather than a time machine. Rollback also cannot restore data that users created or changed in the meantime, such as sessions, enrolled devices or accounts, and it does not reverse effects on downstream applications that were already reconfigured. Keep database backups before large changes and test the revert path in staging.
Do blueprints replace the admin UI?
Blueprints do not have to replace the admin UI, but they change who should use it for which changes. Teams that adopt blueprints usually keep the UI for read-only inspection, troubleshooting and one-off emergency work, and send planned configuration changes through version control. If the UI stays open to everyone, drift becomes likely, because a manual change can be overwritten by the next blueprint apply or can leave the repository out of step with the running system. Decide early which objects are managed by blueprints, which remain manual and how you will detect and resolve drift. Restricting who can change blueprints is part of that decision and should be designed alongside the admin access model.
How does blueprint work change across authentik upgrades?
Blueprints need to be checked at every authentik upgrade because the object model and the available fields can change between releases. A blueprint that applied cleanly on one version may fail or behave differently on the next, so the upgrade plan should include applying the blueprints to a staging instance running the target version before production. Read the release notes for each version you pass through and confirm the upgrade path is supported, since authentik publishes a sequential upgrade rule and per-release breaking changes. Pin the version you deploy, keep the blueprints in the same repository as your upgrade records, and treat blueprint validation as a required step in the upgrade checklist.
Where can blueprints be stored, and which option suits us?
authentik discovers blueprint YAML files from its blueprints directory, watches them for changes and rescans them every 60 minutes by default. Blueprints can also be loaded from an OCI registry or stored in the database, so the right choice depends on how your platform team already ships artifacts. Files in a mounted directory suit simple setups managed by a container image or configuration management, while an OCI registry suits teams that already version and promote artifacts across environments. Confirm the exact configuration keys and mounting approach for your deployment method in the authentik blueprints documentation before you commit to a layout.
Limits to confirm in your environment
Blueprints behave differently depending on your authentik version, how the instance is configured and what other tools touch the same objects. The cards below list the points to confirm against the blueprints documentation and your own running deployment before you commit a configuration workflow to them. Each check is cheap to run on a staging instance and expensive to discover after a production change.
Supported blueprint features and models
Not every model type or entry attribute is available in every release, so the set of objects you can express in YAML depends on your authentik version. Before you design a repository layout, list the model types you need (flows, stages, policies, providers, applications, groups, outpost bindings) and confirm each one is supported by the exact version you run. Keep a short compatibility note in the repository so reviewers can see which version the blueprints were written for.
Rescan interval in your deployment
Blueprints are watched for changes and rescanned every 60 minutes by default, but the interval is a setting you should confirm rather than assume. Check the value your deployment uses and whether it is set through configuration or left at the default. Test how long a file change takes to appear in a staging instance, because teams that edit a blueprint and expect immediate effect often misread a pending rescan as a failed apply.
OCI registry authentication and access
Blueprints can be pulled from an OCI registry rather than the local blueprint directory, which suits multiple instances that must run identical configuration. Confirm how the instance authenticates to the registry, where those credentials are stored, and who can push new blueprint artifacts. Also confirm how a pull failure surfaces, since a registry outage or expired credential can leave an instance on its last applied configuration without an obvious alert.
Handling of deleted objects
Removing a YAML entry does not automatically tell you whether authentik deletes the matching object, leaves it in place or marks it as unmanaged. Test removal on a copy of your data for each model type you manage, including applications that users are signed into and providers referenced by other objects. Record the result in your runbook so a cleanup change does not silently remove access in production.
Atomic apply and rollback behavior
Each blueprint applies in a single transaction that rolls back if any entry fails, which protects you from partial updates. Confirm how a failed apply is reported in logs and the admin interface, and whether a rollback also restores the previous state of values edited by hand in the UI. Plan a test that deliberately introduces one invalid entry, so your team knows what a failed change looks like before it happens under pressure.
Interaction with Terraform and manual edits
If your team also manages authentik with Terraform, two tools may write the same objects and fight over their values on every run. Confirm which tool owns each object type, whether manual UI changes get overwritten on the next scan, and how each tool reports drift. Decide ownership in writing before the first apply, because a single shared object can cause a change to revert without anyone touching it.
What a blueprint strategy changes for your operations team
Adopting blueprints moves authentik changes out of the admin console and into your version control system, and that shifts who does the work and how it is checked. A routine change to a provider, flow or application becomes a pull request against the YAML files, reviewed by someone other than the author before merge. Your reviewers need to read the blueprint itself, not the console screen, so the team should agree on a review checklist covering the model and identifiers fields, referenced flows and policies, and any change that touches access bindings. Decide before go-live who can approve changes to providers and bindings, because those are the entries where a small diff has the largest effect on who can sign in.
The on-call process changes as well. When a blueprint fails to apply, the failure is recorded in the apply logs of the server or worker container, and the responder needs to read those logs to find the entry that broke. Because each blueprint applies in a single atomic transaction and rolls back if any entry fails, a bad file leaves the previous configuration in place, but the change you expected is not live either. Your runbook should name where the apply logs are collected, who can read them, and how a responder confirms that the last good state is still active. Test this path in a non-production instance so the first time your team sees a failed apply is not during an incident.
Emergency fixes need a rule of their own. A console change made to restore access during an outage is valid, but if it is not written back to Git, the next blueprint scan can reapply the file and undo the fix, or the repository and the running system drift apart without anyone noticing. Set a time limit for the write-back, make the commit part of the incident closure checklist, and confirm during each review cycle that the repository matches what is running. Ask your implementation partner, or your own platform team, to show how the blueprint directory is rescanned at its default interval of every 60 minutes and how that interval fits your recovery expectations. Make the reconciliation step visible in the same place as other change records so auditors and operators see one history.
How DeployOpen scopes and delivers authentik blueprint work
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including authentik blueprint work. We turn flows, providers and applications into version-controlled YAML that your team can review, apply and roll back.
How we scope
- Inventory which flows, providers, applications and groups should move into blueprints and which stay managed by hand.
- Agree which blueprint sources apply, such as the local blueprints directory, an OCI registry or database entries.
- Record in writing the environments, context variables and change-control rules that the blueprints must respect.
How we build
- Write blueprints for each provider and application, using context variables so the same files work across environments.
- Test each blueprint against a non-production authentik instance to confirm atomic apply and clean rollback on failure.
- Set restrictions on who may change blueprints, so runtime edits in the admin interface do not drift from the repository.
How we hand over
- Deliver the blueprint repository with a README covering layout, variables, apply order and the rescan interval.
- Document the rollback procedure and the steps for promoting a blueprint from staging to production.
- Walk your platform and security engineers through the review workflow so they can own future changes.
How we support
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and blueprint maintenance are available as a retainer for changes after handover.
- Ask your DeployOpen contact to confirm how blueprint changes will be tested against each authentik release.
