205hlab-mirrors/authentik
2
0
Fork 0
mirror of https://github.com/goauthentik/authentik.git synced 2026-06-17 19:09:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

website/docs: enhance blueprint docs (#15984)

Browse Source 
* draft of note about bp behviour when modified

* Update website/docs/customize/blueprints/index.mdx

Co-authored-by: Dewi Roberts <dewi@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* clarify title

* more tweaks

* tweaks

* more content, rearranged headings

* tweak

* more content about creating a bp instance

* create new page for procedures

* tweaks

* add to sidebar, tweaks

* fixed conflict

* add link to procedurals

* typo

* more content

* more links, more tips

* wip

* Apply suggestion from @dominic-r

Signed-off-by: Dominic R <dominic@sdko.org>

* Apply suggestion from @dominic-r

Signed-off-by: Dominic R <dominic@sdko.org>

* final tweaks

* jens and dewi edits

* tweaks

* more Dewi and Jens edits yay

---------

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Dominic R <dominic@sdko.org>
Co-authored-by: Dewi Roberts <dewi@goauthentik.io>
Co-authored-by: Dominic R <dominic@sdko.org>
This commit is contained in:
Tana M Berry
2025-11-20 14:00:57 -05:00
committed by GitHub
parent 64965e3750
commit d4d6c466a9
7 changed files with 114 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/docs/add-secure-apps/flows-stages/flow/index.md
+11 -5
View File
@@ -22,19 +22,19 @@ By default, policies are evaluated dynamically, right before the stage (to which
This default behaviour can be altered by enabling the **Evaluate when flow is planned** option on the stage binding. With this setting a _flow plan_ containing all stages is generated upon flow execution. This means that all attached policies are evaluated upon execution. For more information about flow plans, read our [flow context documentation](./context/index.mdx).
## Permissions
## Policies and permissions
Flows can have [policies](../stages/index.md) assigned to them. These policies determine if the current user is allowed to see and use this flow.
Keep in mind that in certain circumstances, policies cannot match against users and groups as there is no authenticated user yet.
## Import & Export
## Import or export a flow
Flows can be imported and exported to share with other people, the community, and for troubleshooting. Flows can be imported to apply new functionality and apply existing workflows.
Flows can be imported and exported (as [blueprints](../../../customize/blueprints/working_with_blueprints)) to share with other people, the community, and for troubleshooting. Flows can be imported to apply new functionality to existing flows, or to add a new, custom flow.
Download our [Example flows](./examples/flows.md) and then import them into your authentik instance.
You can create your own flow or download our [Example flows](./examples/flows.md) and then import them into your authentik instance.
Starting with authentik 2022.8, flows will be exported as YAML, but JSON-based flows can still be imported.
Starting with authentik 2022.8, flows are exported as YAML, but JSON-based flows can still be imported.
## Create a custom flow
@@ -88,3 +88,9 @@ import Defaultflowlist from "../flow/flow_list/\_defaultflowlist.mdx";
- **Layout**: select how the UI displays the flow when it is executed; with stacked elements, content left or right, and sidebar left or right.
- **Background**: optionally, select a background image for the UI presentation of the flow. This overrides any default background image configured in the [Branding settings](../../../sys-mgmt/brands.md#branding-settings).
## Edit or delete a flow
- To edit a flow, navigate to **Flows and Stages > Flows** in the Admin interface, and then click **Edit** for the flow that you want to modify.
- To delete a flow, navigate to **Flows and Stages > Flows** in the Admin interface, select the checkbox in front of the flow instance that you want to delete, and then click **Delete** at the top of the list. You can retrieve and re-apply that flow by following the steps above to create a new flow.
website/docs/customize/blueprints/export.mdx
+3 -3
View File
@@ -1,5 +1,5 @@
---
title: Export
title: Export configurations to blueprints
---
## Global export
@@ -14,9 +14,9 @@ Additionally, default values will be skipped and not added to the blueprint.
## Flow exports
Instead of exporting everything from a single instance, there's also the option to export a single flow with it's attached stages, policies and other objects.
A specific flow with its attached stages, policies, and other objects can be exported.
This export can be triggered via the API or the Web UI by clicking the download button in the flow list.
This export can be triggered via the API or the Admin interface by clicking the **Export** button (download icon) next to the flow in the flow list.
## Cleaning up
website/docs/customize/blueprints/index.mdx
+38 -15
View File
@@ -2,23 +2,40 @@
title: Blueprints
---
Blueprints offer a new way to template, automate and distribute authentik configuration. Blueprints can be used to automatically configure instances, manage config as code without any external tools, and to distribute application configs.
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).
## Types
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.
Blueprints are yaml files, whose format is described further in [File structure](./v1/structure). Blueprints can be applied in one of two ways:
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.
- As a Blueprint instance, which is a YAML file mounted into the authentik (worker) container. 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.
## Applying blueprints
:::info
Starting with authentik 2022.12.1, 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.
:::
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 Flow import, which is a YAML file uploaded via the Browser/API. This file is validated and applied directly after being uploaded, but is not further monitored/applied.
- 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)
Starting with authentik 2022.8, blueprints are used to manage authentik default flows and other system objects. These blueprints can be disabled/replaced with custom blueprints in certain circumstances.
To learn how to apply, create, modify, and manage blueprints, refer to [Working with blueprints](./working_with_blueprints.md).
## Blueprint Execution
### 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.
:::
## Blueprint execution
When a blueprint is applied, all entries are processed within a single **atomic database transaction**. This means:
@@ -31,16 +48,22 @@ 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
These can be accessed using the `!Context` tag, for example:
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
```
## Storage - File
## Blueprint storage
The authentik container by default looks for blueprints in `/blueprints`. Underneath this directory, there are a couple default subdirectories:
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
@@ -58,7 +81,7 @@ Please note that, by default, blueprint discovery and evaluation is not guarante
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.
:::
## Storage - OCI
### 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.
@@ -74,7 +97,7 @@ To push a blueprint to an OCI-compatible registry, [ORAS](https://oras.land/) ca
oras push ghcr.io/<username>/blueprint/<blueprint name>:latest <yaml file>:application/vnd.goauthentik.blueprint.v1+yaml
```
## Storage - Internal
### 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.
website/docs/customize/blueprints/working_with_blueprints.md
+57
View File
@@ -0,0 +1,57 @@
---
title: Working with blueprints
---
For an overview of what blueprints are, how they're executed, and where they are stored, see the [Blueprints overview](./index.mdx) documentation.
To export configurations (including custom flows) to create a blueprint, read our [Export](./export.mdx) documentation.
The docs below cover applying, creating, editing, and managing blueprints.
## Apply a blueprint
To _apply_ a blueprint is to have authentik read and execute the contents of a blueprint file. authentik provides many out-of-the-box blueprints, which can be applied either as a [blueprint instance](./index.mdx#blueprint-instance) or as an [imported flow](./index.mdx#imported-flow).
### Add and apply a new blueprint instance
1. Log in as an administrator to authentik and open the Admin interface.
2. Navigate to **Customization** > **Blueprints**.
3. Click **Create** and define the new blueprint instance.
- **Name**: provide a descriptive name.
- **Enabled**: toggle on or off. Disabled blueprints cannot be applied.
- **Blueprint**: select the source for this instance. You can choose a file from a **Local path**, an **OCI registry**, or **Internal** (paste file contents directly, stored in database).
- **Additional Settings**:
- **Context**: add any [`key:value` context variable](./index.mdx#blueprint-execution) used in the blueprint instance.
4. Click **Create** to save the new blueprint instance. This file is read and applied regularly by authentik.
### Apply a new flow
You can apply a new flow from either the **Flows** page or the **Blueprints** page.
#### Flows page
1. Log in as an administrator to authentik and open the Admin interface.
2. Navigate to **Flows and Stages > Flows**, then click **Import**.
3. Under **Flow**, select the YAML file to import. Typically this is a file you [exported](./export.mdx) and saved to your local file system.
#### Blueprints page
1. Log in as an administrator to authentik and open the Admin interface.
2. Navigate to **Customization > Blueprints**.
3. Select the blueprint, and, under **Actions**, click the **Apply** icon.
:::info Download example flows
You can download our [example flows](../../add-secure-apps/flows-stages/flow/examples/flows.md) and import them into your authentik instance.
:::
## Edit a blueprint instance or flow
- To edit a blueprint instance, navigate to **Customization** > **Blueprints** in the Admin interface and click the **Edit** icon of the instance. Alternatively, edit the YAML file directly.
- To edit a flow, navigate to **Flows and Stages > Flows** in the Admin interface and click **Edit** next to the flow you want to modify.
## Delete a blueprint instance or flow
- To delete a blueprint instance, go to **Customization** > **Blueprints**, select the checkbox next to the instance, and click **Delete**. You can recreate and apply it by creating a new blueprint instance and selecting the file in the **Create** page, under **Path**..
- To delete a flow, navigate to **Flows and Stages** > **Flows**, select the checkbox next to the flow, and click **Delete**. You can re-import the flow later by repeating the import steps in the previous section.
website/docs/security/security-hardening.md
+3 -3
View File
@@ -25,7 +25,7 @@ However, for further hardening, it is possible to prevent any user (even super-u
- `/api/v3/propertymappings*`
- `/api/v3/managed/blueprints*`
With these restrictions in place, expressions can only be edited using [Blueprints on the file system](../customize/blueprints/index.mdx#storage---file). Take care to restrict access to the file system itself.
With these restrictions in place, expressions can only be edited using [Blueprints on the file system](../customize/blueprints/index.mdx#as-a-local-file). Take care to restrict access to the file system itself.
### Blueprints
@@ -35,7 +35,7 @@ To prevent any user from creating/editing blueprints, block API requests to this
- `/api/v3/managed/blueprints*`
With these restrictions in place, Blueprints can only be edited via [the file system](../customize/blueprints/index.mdx#storage---file).
With these restrictions in place, Blueprints can only be edited via [the file system](../customize/blueprints/index.mdx#as-a-local-file).
### CAPTCHA Stage
@@ -46,7 +46,7 @@ To prevent any user from creating/editing CAPTCHA stages block API requests to t
- `/api/v3/stages/captcha*`
- `/api/v3/managed/blueprints*`
With these restrictions in place, CAPTCHA stages can only be edited using [Blueprints on the file system](../customize/blueprints/index.mdx#storage---file).
With these restrictions in place, CAPTCHA stages can only be edited using [Blueprints on the file system](../customize/blueprints/index.mdx#as-a-local-file).
### Content Security Policy (CSP)
website/docs/sidebar.mjs
+1
View File
@@ -433,6 +433,7 @@ const items = [
id: "customize/blueprints/index",
},
items: [
"customize/blueprints/working_with_blueprints",
"customize/blueprints/export",
"customize/blueprints/v1/structure",
"customize/blueprints/v1/tags",
website/docs/sys-mgmt/ops/worker.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Worker
slug: /worker
---
The authentik worker runs [background tasks](../background-tasks.md). The worker also watches for [blueprints](../../customize/blueprints/index.mdx#storage---file) and [certificates](../certificates.md#external-certificates) that are added to the file system. It runs in a separate container from the server to handle these tasks.
The authentik worker runs [background tasks](../background-tasks.md). The worker also watches for [blueprints](../../customize/blueprints/index.mdx#as-a-local-file) and [certificates](../certificates.md#external-certificates) that are added to the file system. It runs in a separate container from the server to handle these tasks.
## How it works