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

website: latest migration to new structure (#11522)

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

---------

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-08 14:07:19 -05:00
committed by GitHub
parent 9200a598ec
commit 9a89a5f94b
336 changed files with 2624 additions and 871 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)"
```

30
website/docs/customize/brands.md Normal file
View File

@ -0,0 +1,30 @@
---
title: Brands
slug: /brands
---
You can configure several differently "branded" options depending on the associated domain, even though objects such as applications, providers, etc, are still global. This can be handy to use the same authentik instance, but branded differently for different domains.
The main settings that brands influence are flows and branding.
## Flows
authentik picks a default flow by selecting the flow that is configured in the current brand, otherwise any flow that:
- matches the required designation
- comes first sorted by slug
- is allowed by policies
This means that if you want to select a default flow based on policy, you can leave the brand default empty.
## Branding
The brand configuration controls the branding title (shown in website document title and several other places), the sidebar/header logo that appears in the upper left of the product interface, and the favicon on a browser tab.
:::info
Starting with authentik 2024.6.2, the placeholder `%(theme)s` can be used in the logo configuration option, which will be replaced with the active theme.
:::
## External user settings
You can use the **Default application** configuration on the **System -> Brands** page of the Admin interface to redirect external users to a default application when they successfully authenticate without being sent from a specific application.

57
website/docs/customize/interfaces/_global/customcss.mdx Normal file
View File

@ -0,0 +1,57 @@
### Custom CSS
To further modify the look of authentik, a custom CSS file can be created. Creating such a file is outside the scope of this document.
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs
defaultValue="docker-compose"
values={[
{label: 'docker-compose', value: 'docker-compose'},
{label: 'Kubernetes', value: 'kubernetes'},
]}>
<TabItem value="docker-compose">
Create a `docker-compose.override.yml` file and add this block to mount the custom CSS file:
```yaml
services:
server:
volumes:
- ./my-css-file.css:/web/dist/custom.css
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
<TabItem value="kubernetes">
Create a ConfigMap with your css file:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: authentik-custom-css
namespace: authentik
data:
custom.css: |
...
```
Then, in the helm chart add this to your `values.yaml` file:
```yaml
volumes:
- name: custom-css
configMap:
name: authentik-custom-css
volumeMounts:
- name: custom-css
mountPath: /web/dist/custom.css
subPath: custom.css
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
</Tabs>

5
website/docs/customize/interfaces/_global/global.mdx Normal file
View File

@ -0,0 +1,5 @@
## Global customization
import CustomCSS from "./customcss.mdx";
<CustomCSS />

17
website/docs/customize/interfaces/admin/customization.mdx Normal file
View File

@ -0,0 +1,17 @@
# Customization
### `settings.pagination.perPage`
How many items should be retrieved per page. Defaults to 20.
### `settings.defaults.userPath`
Default user path which is opened when opening the user list. Defaults to `users`.
### `settings.theme.base`
Configure the base color scheme. Defaults to `automatic`, which switches between dark and light mode based on the users' browsers' preference. Choices: `automatic`, `dark`, `light`.
import Global from "../_global/global.mdx";
<Global />

11
website/docs/customize/interfaces/flow/customization.mdx Normal file
View File

@ -0,0 +1,11 @@
# Customization
Since flows can be executed authenticated or unauthenticated, the default settings can be set via brands _attributes_.
### `settings.theme.base`
Configure the base color scheme. Defaults to `automatic`, which switches between dark and light mode based on the users' browsers' preference. Choices: `automatic`, `dark`, `light`.
import Global from "../_global/global.mdx";
<Global />

64
website/docs/customize/interfaces/user/customization.mdx Normal file
View File

@ -0,0 +1,64 @@
# Customization
The user interface can be customized through attributes, and will be inherited from a users' groups.
## Enabling/disabling features
The following features can be enabled/disabled. By default, all of them are enabled:
- `settings.enabledFeatures.apiDrawer`
API Request drawer in navbar
- `settings.enabledFeatures.notificationDrawer`
Notification drawer in navbar
- `settings.enabledFeatures.settings`
Settings link in navbar
- `settings.enabledFeatures.applicationEdit`
Application edit in library (only shown when user is superuser)
- `settings.enabledFeatures.search`
Search bar
## Other configuration
### `settings.navbar.userDisplay`
Configure what is shown in the top right corner. Defaults to `username`. Choices: `username`, `name`, `email`
### `settings.theme.base`
Configure the base color scheme. Defaults to `automatic`, which switches between dark and light mode based on the users' browsers' preference. Choices: `automatic`, `dark`, `light`.
### `settings.theme.background`
Optional CSS which is applied in the background of the background of the user interface; for example
```yaml
settings:
theme:
background: >
background: url('https://picsum.photos/1920/1080');
filter: blur(8px);
background-position: center;
background-repeat: no-repeat;
background-size: cover;
```
### `settings.layout.type`
Which layout to use for the _My applications_ view. Defaults to `row`. Choices: `row`, `2-column`, `3-column`
### `settings.locale`
The locale which can be configured in the user settings by default. This can be used to preset locales for groups of users, but still let them choose their own preferred locale
import Global from "../_global/global.mdx";
<Global />

173
website/docs/customize/policies/expression.mdx Normal file
View File

@ -0,0 +1,173 @@
---
title: Expression Policies
---
Expression policies are perhaps the most flexible way to define specific implementations of flows and stages. With Expression polices, you can provide Python code to enforce custom checks and validation.
The passing of the policy is determined by the return value of the code.
To pass a policy, use:
```python
return True
```
To fail a policy use:
```python
return False
```
**Example**:
Here's a simple policy that you could bind to a MFA validation stage if you want to specify that only certain users should be prompted for MFA validation:
```
if request.context["pending_user"].username == "marie":
return True
return False
```
If the return is `True` that means Yes, use this stage (i.e. the user will get the MFA prompt). A return of `False` means remove this stage from the plan.
## Available Functions
### `ak_message(message: str)`
Add a message, visible by the end user. This can be used to show the reason why they were denied.
Example:
```python
ak_message("Access denied")
return False
```
import Functions from "../../expressions/_functions.md";
<Functions />
## Variables
import Objects from "../../expressions/_objects.md";
<Objects />
- `request`: A PolicyRequest object, which has the following properties:
- `request.user`: The current user, against which the policy is applied. See [User](../../users-sources/user/index.mdx)
:::caution
When a policy is executed in the context of a flow, this will be set to the user initiaing request, and will only be changed by a `user_login` stage. For that reason, using this value in authentication flow policies may not return the expected user. Use `context['pending_user']` instead; User Identification and other stages update this value during flow execution.
If the user is not authenticated, this will be set to a user called _AnonymousUser_, which is an instance of [authentik.core.models.User](https://docs.djangoproject.com/en/4.1/ref/contrib/auth/#django.contrib.auth.models.User) (authentik uses django-guardian for per-object permissions, [see](https://django-guardian.readthedocs.io/en/stable/)).
:::
- `request.http_request`: The Django HTTP Request. See [Django documentation](https://docs.djangoproject.com/en/4.1/ref/request-response/#httprequest-objects).
- `request.obj`: A Django Model instance. This is only set if the policy is ran against an object.
- `request.context`: A dictionary with dynamic data. This depends on the origin of the execution.
- `geoip`: GeoIP dictionary. The following fields are available:
:::info
For basic country matching, consider using a [GeoIP policy](./index.md#geoip-policy).
:::
- `continent`: a two character continent code like `NA` (North America) or `OC` (Oceania).
- `country`: the two character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha code for the country.
- `lat`: the approximate latitude of the location associated with the IP address.
- `long`: the approximate longitude of the location associated with the IP address.
- `city`: the name of the city. May be empty.
```python
return context["geoip"]["continent"] == "EU"
```
- `asn`: ASN dictionary. The following fields are available:
:::info
For basic ASN matching, consider using a [GeoIP policy](./index.md#geoip-policy).
:::
- `asn`: the autonomous system number associated with the IP address.
- `as_org`: the organization associated with the registered autonomous system number for the IP address.
- `network`: the network associated with the record. In particular, this is the largest network where all of the fields except `ip_address` have the same value.
```python
return context["asn"]["asn"] == 64496
```
- `ak_is_sso_flow`: Boolean which is true if request was initiated by authenticating through an external provider.
- `ak_client_ip`: Client's IP Address or 255.255.255.255 if no IP Address could be extracted. Can be [compared](#comparing-ip-addresses), for example
```python
return ak_client_ip in ip_network('10.0.0.0/24')
# or
return ak_client_ip.is_private
```
See also [Python documentation](https://docs.python.org/3/library/ipaddress.html#ipaddress.ip_address)
Additionally, when the policy is executed from a flow, every variable from the flow's current context is accessible under the `context` object.
This includes the following:
- `context['flow_plan']`: The actual flow plan itself, can be used to inject stages.
- `context['flow_plan'].context`: The context of the currently active flow, which differs from the policy context. Some fields of flow plan context are passed to the root context, and updated from it, like 'prompt_data', but not every variable
- `context['flow_plan'].context['redirect']`: The URL the user should be redirected to after the flow execution succeeds. (Optional)
- `context['prompt_data']`: Data which has been saved from a prompt stage or an external source. (Optional)
- `context['application']`: The application the user is in the process of authorizing. (Optional)
- `context['source']`: The source the user is authenticating/enrolling with. (Optional)
- `context['pending_user']`: The currently pending user, see [User](../../users-sources/user/user_ref.md)
- `context['is_restored']`: Contains the flow token when the flow plan was restored from a link, for example the user clicked a link to a flow which was sent by an email stage. (Optional)
- `context['auth_method']`: Authentication method (this value is set by password stages) (Optional)
Depending on method, `context['auth_method_args']` is also set.
Can be any of:
- `password`: Standard password login
- `auth_mfa`: MFA login (this method is only set if no password was used)
Sets `context['auth_method_args']` to
```json
{
"mfa_devices": [
{
"pk": 1,
"app": "otp_static",
"name": "Static Token",
"model_name": "staticdevice"
}
]
}
```
- `auth_webauthn_pwl`: Password-less WebAuthn login
- `jwt`: OAuth Machine-to-machine login via external JWT
- `app_password`: App password (token)
Sets `context['auth_method_args']` to
```json
{
"token": {
"pk": "f6d639aac81940f38dcfdc6e0fe2a786",
"app": "authentik_core",
"name": "test (expires=2021-08-23 15:45:54.725880+00:00)",
"model_name": "token"
}
}
```
- `ldap`: LDAP bind authentication
Sets `context['auth_method_args']` to
```json
{
"source": {} // Information about the source used
}
```

63
website/docs/customize/policies/index.md Normal file
View File

@ -0,0 +1,63 @@
---
title: Policies
---
Policies provide customization and flexibility when defining your users' login and authentication experience.
In effect, policies determine whether or not a specific stage is applied to a flow, or whether certain users can even access the flow.
For example, you can create a policy that, for certain users, skips over a stage that prompts for MFA input. Or, you can define a policy that allows users to access a login flow only if the policy criteria are met. See below for other policies, including the reputation policy and an events-driven policy to manage notifications.
For instructions about creating and binding policies to flows and stages, refer to ["Working with policies](./working_with_policies/working_with_policies.md)".
## Standard policies
The following policies are our standard, out-of-the box policies.
### Event-matcher policy
This policy is used by the events subsystem. You can use this policy to match events by multiple different criteria, to choose when you get notified.
### Expression Policy
See [Expression Policy](./expression.mdx).
### GeoIP policy
Use this policy for simple GeoIP lookups, such as country or ASN matching. (For a more advanced GeoIP lookup, use an [Expression policy](./expression.mdx).)
### Password-Expiry Policy
This policy can enforce regular password rotation by expiring set passwords after a finite amount of time. This forces users to set a new password.
### Password Policy
This policy allows you to specify password rules, such as length and required characters.
The following rules can be set:
- Minimum amount of uppercase characters.
- Minimum amount of lowercase characters.
- Minimum amount of symbols characters.
- Minimum length.
- Symbol charset (define which characters are counted as symbols).
Starting with authentik 2022.11.0, the following checks can also be done with this policy:
- Check the password hash against the database of [Have I Been Pwned](https://haveibeenpwned.com/). Only the first 5 characters of the hashed password are transmitted, the rest is compared in authentik
- Check the password against the password complexity checker [zxcvbn](https://github.com/dropbox/zxcvbn), which detects weak password on various metrics.
### Reputation Policy
authentik keeps track of failed login attempts by source IP and attempted username. These values are saved as scores. Each failed login decreases the score for the client IP as well as the targeted username by 1 (one).
This policy can be used, for example, to prompt clients with a low score to pass a CAPTCHA test before they can continue.
To make sure this policy is executed correctly, set _Evaluate when stage is run_ when using it with a flow.
### Have I Been Pwned Policy
:::info
This policy is deprecated since authentik 2022.11.0, as this can be done with the password policy now.
:::
This policy checks the hashed password against the [Have I Been Pwned](https://haveibeenpwned.com/) API. This only sends the first 5 characters of the hashed password. The remaining comparison is done within authentik.

19
website/docs/customize/policies/working_with_policies/unique_email.md Normal file
View File

@ -0,0 +1,19 @@
---
title: Ensure unique email addresses
---
Due to the database design of authentik, email addresses are by default not required to be unique. This behavior can however be changed by policies.
The snippet below can be used as the expression in policies both with enrollment flows, where the policy should be bound to any stage before the [User write](../../../add-secure-apps/flows-stages/stages/user_write.md) stage, or with the [Prompt stage](../../../add-secure-apps/flows-stages/stages/prompt/index.md).
```python
from authentik.core.models import User
# Ensure this matches the *Field Key* value of the prompt
field_name = "email"
email = request.context["prompt_data"][field_name]
if User.objects.filter(email=email).exists():
ak_message("Email address in use")
return False
return True
```

21
website/docs/customize/policies/working_with_policies/whitelist_email.md Normal file
View File

@ -0,0 +1,21 @@
---
title: Whitelist email domains
---
To add specific email addresses to an allow list for signing in through SSO or directly with default policy customization, follow these steps:
1. In the Admin interface, navigate to **Customization > Policies** and modify the default policy named `default-source-enrollment-if-sso`.
2. Add the following code snippet in the policy-specific settings under **Expression** and then click **Update**.
```python
allowed_domains = ["example.net", "example.com"]
current_domain = request.context["prompt_data"]["email"].split("@")[1]
if current_domain not in allowed_domains:
ak_message("Access denied for this email domain")
return False
return ak_is_sso_flow
```
This configuration specifies the `allowed_domains` list of domains for logging in through SSO, such as Google OAuth2. If your email is not in the available domains, you will receive a 'Permission Denied' message on the login screen.

48
website/docs/customize/policies/working_with_policies/working_with_policies.md Normal file
View File

@ -0,0 +1,48 @@
---
title: Working with policies
---
For an overview of policies, refer to our documentation on [Policies](../index.md).
authentik provides several [standard policy types](../index.md#standard-policies), which can be configured for your specific needs.
We also document how to use a policy to [whitelist email domains](./whitelist_email.md) and to [ensure unique email addresses](./unique_email.md).
## Create a policy
To create a new policy, follow these steps:
1. Log in as an admin to authentik, and go to the Admin interface.
2. In the Admin interface, navigate to **Customization -> Policies**.
3. Click **Create**, and select the type of policy.
4. Define the policy and click **Finish**.
## Bind a policy to a flow or stage
After creating the policy, you can bind it to either a [flow](../../../add-secure-apps/flows-stages/flow/index.md) or to a [stage](../../../add-secure-apps/flows-stages/stages/index.md).
:::info
Bindings are instantiated objects themselves, and conceptually can be considered as the "connector" between the policy and the stage or flow. This is why you might read about "binding a binding", because technically, a binding is "spliced" into another binding, in order to intercept and enforce the criteria defined in the policy. You can edit bindings on a flow's **Stage Bindings** tab.
:::
### Bind a policy to a flow
These bindings control which users can access a flow.
1. Log in as an admin to authentik, and open the Admin interface.
2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
3. In the list of flows, click on the name of the flow to which you want to bind a policy.
4. Click on the **Policy/Group/User Bindings** tab at the top of the page.
5. Here, you can decide if you want to create a new policy and bind it to the flow (**Create and bind Policy**), or if you want to select an existing policy and bind it to the flow (**Bind existing policy/group/user**).
### Bind a policy to a stage
These bindings control which stages are applied to a flow.
1. Log in as an admin to authentik, and open the Admin interface.
2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
3. In the list of flows, click on the name of the flow to which you want to bind a policy.
4. Click on the **Stage Bindings** tab at the top of the page.
5. Click the arrow (**>**) beside the name of the stage to which you want to bind a policy.
The details for that stage displays.
6. Here, you can decide if you want to create a new policy and bind it to the stage (**Create and bind Policy**), or if you want to select an existing policy and bind it to the stage (**Bind existing policy/group/user**).