From 070714abe4a6d06b97762e35c88d44cadcd2df2b Mon Sep 17 00:00:00 2001 From: Jens Langhammer Date: Fri, 19 Aug 2022 12:01:01 +0100 Subject: [PATCH] website/docs: add more blueprint docs Signed-off-by: Jens Langhammer --- .../10-flow-default-authentication-flow.yaml | 23 +------ ...ow-default-authenticator-static-setup.yaml | 1 - ...-default-authenticator-webauthn-setup.yaml | 1 - website/developer-docs/blueprints/export.md | 27 ++++++++ .../developer-docs/blueprints/v1/example.md | 66 +++++++++++++++++++ website/sidebarsDev.js | 9 ++- 6 files changed, 102 insertions(+), 25 deletions(-) create mode 100644 website/developer-docs/blueprints/export.md create mode 100644 website/developer-docs/blueprints/v1/example.md diff --git a/blueprints/default/10-flow-default-authentication-flow.yaml b/blueprints/default/10-flow-default-authentication-flow.yaml index b6b4f95d9..743b4b153 100644 --- a/blueprints/default/10-flow-default-authentication-flow.yaml +++ b/blueprints/default/10-flow-default-authentication-flow.yaml @@ -4,7 +4,6 @@ metadata: entries: - attrs: designation: authentication - layout: stacked name: Welcome to authentik! title: Welcome to authentik! identifiers: @@ -12,34 +11,16 @@ entries: model: authentik_flows.flow id: flow - attrs: - backends: - - authentik.core.auth.InbuiltBackend - - authentik.sources.ldap.auth.LDAPBackend - - authentik.core.auth.TokenBackend - - authentik.core.auth.TokenBackend configure_flow: !Find [authentik_flows.flow, [slug, default-password-change]] - failed_attempts_before_cancel: 5 identifiers: name: default-authentication-password id: default-authentication-password model: authentik_stages_password.passwordstage -- attrs: - device_classes: - - static - - totp - - webauthn - - duo - - sms - not_configured_action: skip - identifiers: +- identifiers: name: default-authentication-mfa-validation id: default-authentication-mfa-validation model: authentik_stages_authenticator_validate.authenticatorvalidatestage -- attrs: - user_fields: - - email - - username - identifiers: +- identifiers: name: default-authentication-identification id: default-authentication-identification model: authentik_stages_identification.identificationstage diff --git a/blueprints/default/20-flow-default-authenticator-static-setup.yaml b/blueprints/default/20-flow-default-authenticator-static-setup.yaml index 825ca458a..7f3173e24 100644 --- a/blueprints/default/20-flow-default-authenticator-static-setup.yaml +++ b/blueprints/default/20-flow-default-authenticator-static-setup.yaml @@ -5,7 +5,6 @@ entries: - attrs: designation: stage_configuration name: default-authenticator-static-setup - policy_engine_mode: any title: Setup Static OTP Tokens identifiers: slug: default-authenticator-static-setup diff --git a/blueprints/default/20-flow-default-authenticator-webauthn-setup.yaml b/blueprints/default/20-flow-default-authenticator-webauthn-setup.yaml index 91d907c53..26b5a64c7 100644 --- a/blueprints/default/20-flow-default-authenticator-webauthn-setup.yaml +++ b/blueprints/default/20-flow-default-authenticator-webauthn-setup.yaml @@ -5,7 +5,6 @@ entries: - attrs: designation: stage_configuration name: default-authenticator-webauthn-setup - policy_engine_mode: any title: Setup WebAuthn identifiers: slug: default-authenticator-webauthn-setup diff --git a/website/developer-docs/blueprints/export.md b/website/developer-docs/blueprints/export.md new file mode 100644 index 000000000..aa4f4ea07 --- /dev/null +++ b/website/developer-docs/blueprints/export.md @@ -0,0 +1,27 @@ +--- +title: Export +--- + +## Global export + +:::info +Requires authentik 2022.8.2 +::: + +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 now 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. diff --git a/website/developer-docs/blueprints/v1/example.md b/website/developer-docs/blueprints/v1/example.md new file mode 100644 index 000000000..3501f52dc --- /dev/null +++ b/website/developer-docs/blueprints/v1/example.md @@ -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 +``` diff --git a/website/sidebarsDev.js b/website/sidebarsDev.js index 7ea5d1c6d..bc7302f1a 100644 --- a/website/sidebarsDev.js +++ b/website/sidebarsDev.js @@ -11,7 +11,12 @@ module.exports = { type: "doc", id: "blueprints/index", }, - items: ["blueprints/v1/structure", "blueprints/v1/tags"], + items: [ + "blueprints/export", + "blueprints/v1/structure", + "blueprints/v1/tags", + "blueprints/v1/example", + ], }, { type: "category", @@ -28,7 +33,7 @@ module.exports = { }, { type: "category", - label: "Setup", + label: "Development", items: [ "setup/full-dev-environment", "setup/frontend-only-dev-environment",