habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website: latest PR for new Docs structure (#11639)

Browse Source 
* first pass

* dependency shenanigans

* move blueprints

* few broken links

* change config the throw errors

* internal file edits

* fighting links

* remove sidebarDev

* fix subdomain

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* fix relative URL

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* fix mismatched package versions

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* fix api reference build

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* test tweak

* links hell

* more links hell

* links hell2

* yep last of the links

* last broken link fixed

* re-add cves

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* add devdocs redirects

* add dir

* tweak netlify.toml

* move latest 2 CVES into dir

* fix links to moved cves

* typoed title fix

* fix link

* remove banner

* remove committed api docs

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* integrations: remove version dropdown

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update Makefile

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* change doc links in web as well

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix some more docs paths

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix more docs paths

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* ci: require ci-web.build for merging

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Revert "ci: require ci-web.build for merging"

This reverts commit b99a4842a9.

* remove sluf for Application

* put slug back in

* minor fix to trigger deploy

* Spelled out Documentation in menu bar

* remove image redirects...

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* remove explicit index.md

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* remove mdx first

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* then remove .md

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* add missing prefix

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
This commit is contained in:
Tana M Berry
2024-10-09 09:33:40 -05:00
committed by GitHub
parent 6b2fced1b9
commit 6d5172d18a
336 changed files with 2138 additions and 872 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
website/docs/customize/blueprints/export.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Export
---
## Global export <span class="badge badge--version">authentik 2022.8.2+</span>
To migrate existing configurations to blueprints, run `ak export_blueprint` within any authentik Worker container. This will output a blueprint for most currently created objects. Some objects will not be exported as they might have dependencies on other things.
Exported blueprints don't use any of the YAML Tags, they just contain a list of entries as they are in the database.
Note that fields which are write-only (for example, OAuth Provider's Secret Key) will not be added to the blueprint, as the serialisation logic from the API is used for blueprints.
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.
This export can be triggered via the API or the Web UI by clicking the download button in the flow list.
## Cleaning up
Exports from either method will contain a (potentially) long list of objects, all with hardcoded primary keys and no ability for templating/instantiation. This is because currently, authentik does not check which primary keys are used where. It is assumed that for most exports, there'll be some manual changes done regardless, to filter out unwanted objects, adjust properties, etc.

65
website/docs/customize/blueprints/index.md Normal file
View File

@ -0,0 +1,65 @@
---
title: Blueprints
---
<span class="badge badge--version">authentik 2022.8+</span>
---
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.
## Types
Blueprints are yaml files, whose format is described further in [File structure](./v1/structure). Blueprints can be applied in one of two ways:
- 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.
:::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.
:::
- 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.
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.
## Storage - File
The authentik container by default looks for blueprints in `/blueprints`. Underneath this directory, there are a couple 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 afre 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.
:::
## Storage - OCI
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
```
## Storage - Internal <span class="badge badge--version">authentik 2023.1+</span>
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.

66
website/docs/customize/blueprints/v1/example.md Normal file
View File

@ -0,0 +1,66 @@
---
title: Example
---
This is one of the default packaged blueprints to create the default authentication flow.
```yaml
version: 1
metadata:
name: Default - Authentication flow
entries:
# Order of entries is important when using !KeyOf, as tags are evaluated in order they are in
# the document
- attrs:
# Only options that are required should be set here. Default values should not be stated
# here, as they will prevent anyone from overwriting the value
designation: authentication
name: Welcome to authentik!
title: Welcome to authentik!
identifiers:
slug: default-authentication-flow
model: authentik_flows.flow
id: flow
- attrs:
configure_flow:
!Find [authentik_flows.flow, [slug, default-password-change]]
identifiers:
name: default-authentication-password
id: default-authentication-password
model: authentik_stages_password.passwordstage
- identifiers:
name: default-authentication-mfa-validation
# If we're fine with all defaults, `attrs` can be omitted
id: default-authentication-mfa-validation
model: authentik_stages_authenticator_validate.authenticatorvalidatestage
- identifiers:
name: default-authentication-identification
id: default-authentication-identification
model: authentik_stages_identification.identificationstage
- attrs:
session_duration: seconds=0
identifiers:
name: default-authentication-login
id: default-authentication-login
model: authentik_stages_user_login.userloginstage
- identifiers:
order: 10
stage: !KeyOf default-authentication-identification
target: !KeyOf flow
model: authentik_flows.flowstagebinding
- identifiers:
order: 20
stage: !KeyOf default-authentication-password
target: !KeyOf flow
model: authentik_flows.flowstagebinding
- identifiers:
order: 30
stage: !KeyOf default-authentication-mfa-validation
target: !KeyOf flow
model: authentik_flows.flowstagebinding
- identifiers:
order: 100
stage: !KeyOf default-authentication-login
target: !KeyOf flow
model: authentik_flows.flowstagebinding
```

25
website/docs/customize/blueprints/v1/meta.md Normal file
View File

@ -0,0 +1,25 @@
# Meta models
Since blueprints have a pretty strict mapping of each entry mapping to an instance of a model in the database, _meta models_ exist to trigger other actions within authentik that don't directly map to a model.
### `authentik_blueprints.metaapplyblueprint`
This meta model can be used to apply another blueprint instance within a blueprint instance. This allows for dependency management and ensuring related objects are created.
See [examples](https://github.com/search?q=repo%3Agoauthentik%2Fauthentik+path%3A%2F%5Eblueprints%5C%2F%2F+metaapplyblueprint&type=code) in the default blueprints for more information.
#### Attributes
- `identifiers`: Key-value attributes used to match the blueprint instance
Example:
```yaml
attrs:
identifiers:
name: Default - Password change flow
```
- `required`: (Default: `true`) Configure if the blueprint instance must exist
If this is set to `true` and no blueprint instance matches the query above, an error will be thrown. Otherwise, execution will continue without applying anything extra.

136
website/docs/customize/blueprints/v1/models.md Normal file
View File

@ -0,0 +1,136 @@
# Models
Some models behave differently and allow for access to different API fields when created via blueprint.
## `authentik_core.token`
### `key` <span class="badge badge--version">authentik 2023.4+</span>
Via the standard API, a token's key cannot be changed, it can only be rotated. This is to ensure a high entropy in it's key, and to prevent insecure data from being used. However, when provisioning tokens via a blueprint, it may be required to set a token to an existing value.
With blueprints, the field `key` can be set, to set the token's key to any value.
For example:
```yaml
# [...]
- model: authentik_core.token
state: present
identifiers:
identifier: my-token
attrs:
key: this-should-be-a-long-value
user: !KeyOf my-user
intent: api
```
## `authentik_core.user`
### `password` <span class="badge badge--version">authentik 2023.6+</span>
Via the standard API, a user's password can only be set via the separate `/api/v3/core/users/<id>/set_password/` endpoint. In blueprints, the password of a user can be set using the `password` field.
Keep in mind that if an LDAP Source is configured and the user maps to an LDAP user, this password change will be propagated to the LDAP server.
For example:
```yaml
# [...]
- model: authentik_core.user
state: present
identifiers:
username: test-user
attrs:
name: test user
password: this-should-be-a-long-value
```
### `permissions` <span class="badge badge--version">authentik 2024.8+</span>
The `permissions` field can be used to set global permissions for a user. A full list of possible permissions is included in the JSON schema for blueprints.
For example:
```yaml
# [...]
- model: authentik_core.user
identifiers:
username: test-user
attrs:
permissions:
- authentik_blueprints.view_blueprintinstance
```
## `authentik_core.application`
### `icon` <span class="badge badge--version">authentik 2023.5+</span>
Application icons can be directly set to URLs with the `icon` field.
For example:
```yaml
# [...]
- model: authentik_core.application
identifiers:
slug: my-app
attrs:
name: My App
icon: https://goauthentik.io/img/icon.png
```
## `authentik_sources_oauth.oauthsource`, `authentik_sources_saml.samlsource`, `authentik_sources_plex.plexsource`
### `icon` <span class="badge badge--version">authentik 2023.5+</span>
Source icons can be directly set to URLs with the `icon` field.
For example:
```yaml
# [...]
- model: authentik_sources_oauth.oauthsource
identifiers:
slug: my-source
attrs:
name: My source
icon: https://goauthentik.io/img/icon.png
```
## `authentik_flows.flow`
### `icon` <span class="badge badge--version">authentik 2023.5+</span>
Flow backgrounds can be directly set to URLs with the `background` field.
For example:
```yaml
# [...]
- model: authentik_flows.flow
identifiers:
slug: my-flow
attrs:
name: my-flow
title: My flow
designation: authentication
background: https://goauthentik.io/img/icon.png
```
## `authentik_rbac.role`
### `permissions` <span class="badge badge--version">authentik 2024.8+</span>
The `permissions` field can be used to set global permissions for a role. A full list of possible permissions is included in the JSON schema for blueprints.
For example:
```yaml
# [...]
- model: authentik_rbac.role
identifiers:
name: test-role
attrs:
permissions:
- authentik_blueprints.view_blueprintinstance
```

82
website/docs/customize/blueprints/v1/structure.md Normal file
View File

@ -0,0 +1,82 @@
# File structure
Blueprints are YAML files, which can use some additional tags to ease blueprint creation.
## Schema
The blueprint schema is available under `https://goauthentik.io/blueprints/schema.json`. It is also possible to target a specific version's blueprint schema by using `https://version-2023-4.goauthentik.io/blueprints/schema.json`.
To use the schema with Visual Studio code and the YAML extension, add this comment at the top of your blueprint files:
```yaml
# yaml-language-server: $schema=https://goauthentik.io/blueprints/schema.json
```
## Example
```yaml
# yaml-language-server: $schema=https://goauthentik.io/blueprints/schema.json
# The version of this blueprint, currently 1
version: 1
# Optional block of metadata, name is required if metadata is set
metadata:
# Arbitrary key=value store, special labels are listed below
labels:
foo: bar
name: example-blueprint
# Optional default context, instance context is merged over this.
context:
foo: bar
# List of entries (required)
entries:
- # Model in app.model notation, possibilities are listed in the schema (required)
model: authentik_flows.flow
# The state this object should be in (optional, can be "present", "created" or "absent")
# Present will keep the object in sync with its definition here, created will only ensure
# the object is created (and create it with the values given here), and "absent" will
# delete the object
state: present
# An optional list of boolean-like conditions. If all conditions match (or
# no conditions are provided) the entry will be evaluated and acted upon
# as normal. Otherwise, the entry is skipped as if not defined at all.
# Each condition will be evaluated in Python to its boolean representation
# bool(<condition>). Furthermore, complex conditions can be built using
# a special !Condition tag. See the documentattion for custom tags for more
# information.
conditions:
- true
- text
- 2
- !Condition [AND, ...] # See custom tags section
# Key:value filters to uniquely identify this object (required)
identifiers:
slug: initial-setup
# Optional ID for use with !KeyOf
id: flow
# Attributes to set on the object. Only explicitly required settings should be stated
# as these values will override existing attributes
attrs:
denied_action: message_continue
designation: stage_configuration
name: default-oobe-setup
title: Welcome to authentik!
# Optionally set object-level permissions on the object
# Requires authentik 2024.8
permissions:
- permission: inspect_flow
user: !Find [authentik_core.user, [username, akadmin]]
```
## Special Labels
#### `blueprints.goauthentik.io/system`:
Used by authentik's packaged blueprints to keep globals up-to-date. Should only be removed in special cases.
#### `blueprints.goauthentik.io/instantiate`:
Configure if this blueprint should automatically be instantiated (defaults to `"true"`). When set to `"false"`, blueprints are listed and available to be instantiated via API/Browser.
#### `blueprints.goauthentik.io/description`:
Optionally set a description, which can be seen in the web interface.

301
website/docs/customize/blueprints/v1/tags.md Normal file
View File

@ -0,0 +1,301 @@
# YAML Tags
To use the custom tags with your preferred editor, you must make the editor aware of the custom tags.
For VS Code, for example, add these entries to your `settings.json`:
```
{
"yaml.customTags": [
"!Condition sequence",
"!Context scalar",
"!Enumerate sequence",
"!Env scalar",
"!Find sequence",
"!Format sequence",
"!If sequence",
"!Index scalar",
"!KeyOf scalar",
"!Value scalar"
]
}
```
#### `!KeyOf`
Example:
```yaml
policy: !KeyOf my-policy-id
```
Resolves to the primary key of the model instance defined by id _my-policy-id_.
If no matching entry can be found, an error is raised and the blueprint is invalid.
#### `!Env`
Example:
```yaml
password: !Env my_env_var
```
Returns the value of the given environment variable. Can be used as a scalar with `!Env my_env_var, default` to return a default value.
#### `!Find`
Examples:
```yaml
configure_flow: !Find [authentik_flows.flow, [slug, default-password-change]]
```
```yaml
configure_flow:
!Find [
authentik_flows.flow,
[!Context property_name, !Context property_value],
]
```
Looks up any model and resolves to the the matches' primary key.
First argument is the model to be queried, remaining arguments are expected to be pairs of key=value pairs to query for.
#### `!Context`
Example:
```yaml
configure_flow: !Context foo
```
Find values from the context. Can optionally be called with a default like `!Context [foo, default-value]`.
#### `!Format`
Example:
```yaml
name: !Format [my-policy-%s, !Context instance_name]
```
Format a string using python's % formatting. First argument is the format string, any remaining arguments are used for formatting.
#### `!If`
Minimal example:
```yaml
# Short form
# !If [<condition>]
required: !If [true]
```
```yaml
# Longer form
# !If [<condition>, <when true>, <when false>]
required: !If [true, true, false]
```
Full example:
```yaml
attributes: !If [
!Condition [...], # Or any valid YAML or custom tag. Evaluated as boolean in Python
{
# When condition evaluates to true
dictionary:
{
with: { keys: "and_values" },
and_nested_custom_tags: !Format ["foo-%s", !Context foo],
},
},
[
# When condition evaluates to false
list,
with,
items,
!Format ["foo-%s", !Context foo],
],
]
```
Conditionally add YAML to a blueprint.
Similar to a one-line if, the first argument is the condition, which can be any valid yaml or custom tag. It will be evaluated as boolean in python. However, keep in mind that dictionaries and lists will always evaluate to `true`, unless they are empty.
The second argument is used when the condition is `true`, and the third - when `false`. The YAML inside both arguments will be fully resolved, thus it is possible to use custom YAML tags and even nest them inside dictionaries and lists.
#### `!Condition`
Minimal example:
```yaml
required: !Condition [OR, true]
```
Full example:
```yaml
required: !Condition [
AND, # Valid modes are: AND, NAND, OR, NOR, XOR, XNOR
!Context instance_name,
!Find [authentik_flows.flow, [slug, default-password-change],
"My string",
123
]
```
Converts one or more arguments to their boolean representations, then merges all representations together.
Requires at least one argument after the mode selection.
If only a single argument is provided, its boolean representation will be returned for all normal modes and its negated boolean representation will be returned for all negated modes.
Normally, it should be used to define complex conditions for use with an `!If` tag or for the `conditions` attribute of a blueprint entry (see [the blueprint file structure](./structure.md)). However, this is essentially just a boolean evaluator so it can be used everywhere a boolean representation is required.
#### `!Enumerate`, `!Index` and `!Value`
These tags collectively make it possible to iterate over objects which support iteration. Any iterable Python object is supported. Such objects are sequences (`[]`), mappings (`{}`) and even strings.
1. `!Enumerate` tag:
This tag takes 3 arguments:
```yaml
!Enumerate [<iterable>, <output_object_type>, <single_item_yaml>]
```
- **iterable**: Any Python iterable or custom tag that resolves to such iterable
- **output_object_type**: `SEQ` or `MAP`. Controls whether the returned YAML will be a mapping or a sequence.
- **single_item_yaml**: The YAML to use to create a single entry in the output object
2. `!Index` tag:
:::info
This tag is only valid inside an `!Enumerate` tag
:::
This tag takes 1 argument:
```yaml
!Index <depth>
```
- **depth**: Must be >= 0. A depth of 0 refers to the `!Enumerate` tag this tag is located in. A depth of 1 refers to one `!Enumerate` tag above that (to be used when multiple `!Enumerate` tags are nested inside each other).
Accesses the `!Enumerate` tag's iterable and resolves to the index of the item currently being iterated (in case `!Enumerate` is iterating over a sequence), or the mapping key (in case `!Enumerate` is iterating over a mapping).
For example, given a sequence like this - `["a", "b", "c"]`, this tag will resolve to `0` on the first `!Enumerate` tag iteration, `1` on the second and so on. However, if given a mapping like this - `{"key1": "value1", "key2": "value2", "key3": "value3"}`, it will first resolve to `key1`, then to `key2` and so on.
3. `!Value` tag:
:::info
This tag is only valid inside an `!Enumerate` tag
:::
This tag takes 1 argument:
```yaml
!Value <depth>
```
- **depth**: Must be >= 0. A depth of 0 refers to the `!Enumerate` tag this tag is located in. A depth of 1 refers to one `!Enumerate` tag above that (to be used when multiple `!Enumerate` tags are nested inside each other).
Accesses the `!Enumerate` tag's iterable and resolves to the value of the item currently being iterated.
For example, given a sequence like this - `["a", "b", "c"]`, this tag will resolve to `a` on the first `!Enumerate` tag iteration, `b` on the second and so on. If given a mapping like this - `{"key1": "value1", "key2": "value2", "key3": "value3"}`, it will first resolve to `value1`, then to `value2` and so on.
Minimal examples:
```yaml
configuration_stages: !Enumerate [
!Context map_of_totp_stage_names_and_types,
SEQ, # Output a sequence
!Find [
!Format [
"authentik_stages_authenticator_%s.authenticator%sstage",
!Index 0,
!Index 0,
],
[name, !Value 0],
], # The value of each item in the sequence
]
```
The above example will resolve to something like this:
```yaml
configuration_stages:
- !Find [
authentik_stages_authenticator_<stage_type_1>.authenticator<stage_type_1>stage,
[name, <stage_name_1>],
]
- !Find [
authentik_stages_authenticator_<stage_type_2>.authenticator<stage_type_2>stage,
[name, <stage_name_2>],
]
```
Similarly, a mapping can be generated like so:
```yaml
example: !Enumerate [
!Context list_of_totp_stage_names,
MAP, # Output a map
[
!Index 0, # The key to assign to each entry
!Value 0, # The value to assign to each entry
],
]
```
The above example will resolve to something like this:
```yaml
example:
0: <stage_name_1>
1: <stage_name_2>
```
Full example:
:::caution
Note that an `!Enumeration` tag's iterable can never be an `!Item` or `!Value` tag with a depth of `0`. Minimum depth allowed is `1`. This is because a depth of `0` refers to the `!Enumeration` tag the `!Item` or `!Value` tag is in, and an `!Enumeration` tag cannot iterate over itself.
:::
```yaml
example: !Enumerate [
!Context sequence, # ["foo", "bar"]
MAP, # Output a map
[
!Index 0, # Use the indexes of the items in the sequence as keys
!Enumerate [
# Nested enumeration
# Iterate over each item of the parent enumerate tag.
# Notice depth is 1, not 0, since we are inside the nested enumeration tag!
!Value 1,
SEQ, # Output a sequence
!Format [
"%s: (index: %d, letter: %s)",
!Value 1,
!Index 0,
!Value 0,
],
],
],
]
```
The above example will resolve to something like this:
```yaml
"0":
- "foo: (index: 0, letter: f)"
- "foo: (index: 1, letter: o)"
- "foo: (index: 2, letter: o)"
"1":
- "bar: (index: 0, letter: b)"
- "bar: (index: 1, letter: a)"
- "bar: (index: 2, letter: r)"
```