mirror of
https://github.com/goauthentik/authentik
synced 2026-04-27 09:57:31 +02:00
111 lines
6.6 KiB
Plaintext
111 lines
6.6 KiB
Plaintext
---
|
|
title: 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](./v1/structure).
|
|
|
|
Blueprints are used to manage authentik's default flows and other system objects. For example, authentik's `default-authentication-flow` is, under the covers, created by a blueprint.
|
|
|
|
Custom blueprints can be used to replace or modify default blueprints in certain circumstances. For example, you could create a new flow that is based on the `default-authentication-flow` but adds an additional stage or policy.
|
|
|
|
## Applying 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](./working_with_blueprints.md).
|
|
|
|
### Blueprint instance
|
|
|
|
A Blueprint _instance_ is an instantiation of a blueprint. Each instance refers to a YAML file that is either mounted into the authentik (worker) container, in an OCI registry or the local database. (See [Blueprint storage](#blueprint-storage) for more information.) This file is read and applied regularly (every 60 minutes). Multiple instances can be created for a single blueprint file, and instances can be given context key:value attributes to configure the blueprint.
|
|
|
|
:::info
|
|
authentik watches for file modification/creation events in the blueprint directory and will automatically trigger a discovery when a new blueprint file is created, and trigger a blueprint apply when a file is modified.
|
|
:::
|
|
|
|
### Imported flow
|
|
|
|
You can apply an example flow, either by importing it from the **Flows** page, or by selecting it from the list of blueprints under **Customization > Blueprints** in the Admin interface and clicking **Apply**. 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 being uploaded, but is not monitored further, nor is it automatically applied on startup like blueprint instances.
|
|
|
|
:::info
|
|
Be aware that if you [modify and save](../../add-secure-apps/flows-stages/flow/#flow-configuration-options) 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](./working_with_blueprints.md#apply-a-new-flow) again.
|
|
:::
|
|
|
|
:::warning 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**:
|
|
|
|
```yaml
|
|
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 once they become unavailable, however none of the objects created by those blueprints are affected by this.
|
|
|
|
:::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](./v1/meta#authentik_blueprintsmetaapplyblueprint) to make sure that objects are created in the correct order.
|
|
:::
|
|
|
|
### In an OCI registry
|
|
|
|
Blueprints can also be stored in remote [OCI](https://opencontainers.org/) 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 into the URL.
|
|
|
|
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](https://oras.land/) 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.
|