Skip to main content

Blueprints

Blueprints provide a way to template, automate, and distribute authentik configuration. Blueprints can be used to automatically configure instances, manage infrastructure-as-code without any external tools, and to distribute application configurations. Blueprints are YAML files, whose format is described further in File structure.

Blueprints are used to manage authentik's default flows and other system objects. authentik's default-authentication-flow is, under the covers, created by a blueprint.

Custom blueprints can be used to replace or modify default blueprints. You can create a new flow that's based on the default-authentication-flow but adds an additional stage or policy.

Apply blueprints​

To apply a blueprint means that the content in the blueprint file is instantiated and then implemented by authentik. Blueprints can be applied in one of two ways:

  • as a blueprint instance (a new instance of any authentik configuration, which you can then further customize)
  • as an imported flow (to add a new flow, or to revert to the default, out-of-box flow)

To learn how to apply, create, modify, and manage blueprints, refer to Working with blueprints.

Blueprint instances​

A Blueprint instance is an instantiation of a blueprint. Each instance refers to a YAML file that's either mounted into the authentik (worker) container, in an OCI registry, or the local database. (See Blueprint storage for more information.)

Multiple instances can be created from a single blueprint file. A blueprint instance populates settings in the blueprint file marked with the !Context tag from the instance's context object. To create a new instance using the Admin UI, select Blueprints > New Blueprint, give the new instance a unique name, choose the blueprint file, and supply your customizations in the Context section. Context objects must parse as JSON or YAML.

authentik watches for file modification/creation events in the blueprint directory. When a new blueprint file is created, authentik will automatically trigger a discovery. A successful discovery will automatically create and apply a new blueprint instance. When a blueprint file is modified, authentik will trigger an apply if an instance using this file exists.

authentik also scans the blueprint directory on an interval and compares each blueprint file to the copy in its database. Files that are new or modified will be discovered and applied. The default interval is 60 minutes. The interval can be changed in System Tasks > Schedules under authentik.blueprints.v1.tasks.blueprints_discovery.

info

To prevent authentik from creating a blueprint instance automatically from a blueprint file, add or edit the YAML metadata/labels block and disable automatic instantiation:

metadata:
  labels:
    blueprints.goauthentik.io/instantiate: "false"

Imported flow​

You can apply an example flow by selecting Import on either the Flows page or the Blueprints page. Then, on the Import Flow Blueprint modal, select Local path to choose one of the example blueprints bundled with authentik, or select File upload to import a downloaded or exported .yaml file from your local file system. After applying the flow, you can decide if you want to further customize the flow, or just use it as it is.

This YAML file is validated and applied directly after having been uploaded or selected from an available local path. The file is not monitored afterward or automatically applied on startup like blueprint instances.

info

Be aware that if you modify and save an existing default flow, what you get is a merged version of the two: the original flow (which is based on the blueprint) plus any changes you made to the flow. If you want to revert any modifications that you made to the default flow and get a fresh start with the original default flow, you have to first delete the modified flow, and then apply the flow's blueprint again.

Flow imports

Flow imports are blueprint files, which may contain objects other than flows (such as policies, users, groups, etc).

You should only import files from trusted sources and review blueprints before importing them.

Blueprint execution​

When a blueprint is applied, all entries are processed within a single atomic database transaction. This means:

  • If any entry fails validation or encounters an error, the entire blueprint is rolled back
  • No partial changes are committed - it's all-or-nothing
  • This ensures database consistency and prevents incomplete configurations

Additionally, all blueprints have access to built-in context variables:

  • goauthentik.io/enterprise/licensed: boolean indicating if an enterprise license is active
  • goauthentik.io/rbac/models: dictionary of available RBAC models

When you create or edit a blueprint instance, these context variables can be accessed using the !Context tag in the YAML file (or in the UI under Advanced settings on the Create/Edit page).

Example:

conditions:
    - !Context goauthentik.io/enterprise/licensed

Blueprint storage​

When you add a new blueprint instance you can define from where the .yaml file is accessed and read by authentik: as a local file, in an OCI registry, or internally in authentik's database.

As a local file​

The authentik container by default looks for blueprints in /blueprints. Underneath this directory, there are a couple of default subdirectories:

  • /blueprints/default: default blueprints for default flows, tenants, etc
  • /blueprints/example: example blueprints for common configurations and flows
  • /blueprints/system: system blueprints for authentik managed Property mappings, etc

Any additional .yaml file in /blueprints will be discovered and automatically instantiated, depending on their labels.

To disable existing blueprints, an empty file can be mounted over the existing blueprint.

File-based blueprints are automatically removed when they become unavailable. However, none of the objects created by those blueprints are affected.

info

Please note that, by default, blueprint discovery and evaluation is not guaranteed to follow any specific order.

If you have dependencies between blueprints, you should use meta models to make sure that objects are created in the correct order.

In an OCI registry​

Blueprints can also be stored in remote OCI compliant registries. This includes GitHub Container Registry, Docker hub, and many other registries.

To download a blueprint via OCI, set the path to oci://ghcr.io/<username>/<package-name>:<ref>. This will fetch the blueprint from an OCI package hosted on GHCR.

To fetch blueprints from a private registry with authentication, credentials can be embedded in the address.

Blueprints are re-fetched each execution, so when using changing tags, blueprints will automatically be updated.

To push a blueprint to an OCI-compatible registry, ORAS can be used with this command

oras push ghcr.io/<username>/blueprint/<blueprint name>:latest <yaml file>:application/vnd.goauthentik.blueprint.v1+yaml

Internally in authentik's database​

Blueprints can be stored in authentik's database, which allows blueprints to be managed via external configuration management tools like Terraform.

Modifying the contents of a blueprint will trigger its reconciliation. Blueprints are validated on submission to prevent invalid blueprints from being saved.