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

Revert "website: latest migration to new structure" (#11634)

Browse Source 
Revert "website: latest migration to new structure (#11522)"

This reverts commit 9a89a5f94b.
This commit is contained in:
Tana M Berry
2024-10-08 17:30:50 -05:00
committed by GitHub
parent 9a89a5f94b
commit 6b2fced1b9
336 changed files with 883 additions and 2636 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,66 +0,0 @@
---
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
View File

@ -1,25 +0,0 @@
# 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
View File

@ -1,136 +0,0 @@
# 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
View File

@ -1,82 +0,0 @@
# 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
View File

@ -1,301 +0,0 @@
# 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)"
```