From 77c913bfd35c5de9f737eae50a2c6cc344a3659b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcelo=20Elizeche=20Land=C3=B3?= Date: Mon, 24 Feb 2025 09:54:06 -0300 Subject: [PATCH] stages/authenticator_email: Email Authenticator Stage Documentation (#12853) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * stages/authenticator_email: Add initial documentation for Email Authenticator Stage * fix linting/styling * Apply suggestions from code review Co-authored-by: Tana M Berry Signed-off-by: Marcelo Elizeche Landó * Apply suggestions from code review Co-authored-by: Tana M Berry Signed-off-by: Marcelo Elizeche Landó * rearranged to match the UI * fix my broken links * Tweak Emil Authenticator stage, also capitalize names of other stages * final tweaks * Add authenticator_validate for Email Authenticator in authenticator_validate documentation * add version badge * Fix broken links (.md -> .mdx) --------- Signed-off-by: Marcelo Elizeche Landó Co-authored-by: Tana M Berry Co-authored-by: Tana M Berry --- .../stages/authenticator_duo/index.mdx | 2 +- .../stages/authenticator_email/index.md | 48 +++++++++++++++++++ .../stages/authenticator_sms/index.mdx | 2 +- .../stages/authenticator_static/index.md | 2 +- .../stages/authenticator_totp/index.md | 2 +- .../stages/authenticator_validate/index.mdx | 3 +- .../stages/authenticator_webauthn/index.mdx | 2 +- website/sidebars.js | 3 +- 8 files changed, 57 insertions(+), 7 deletions(-) create mode 100644 website/docs/add-secure-apps/flows-stages/stages/authenticator_email/index.md diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_duo/index.mdx b/website/docs/add-secure-apps/flows-stages/stages/authenticator_duo/index.mdx index f0a749b7f9..ea479c3f7a 100644 --- a/website/docs/add-secure-apps/flows-stages/stages/authenticator_duo/index.mdx +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_duo/index.mdx @@ -1,5 +1,5 @@ --- -title: Duo authenticator setup stage +title: Duo Authenticator Setup stage --- This stage configures a Duo authenticator. To get the API Credentials for this stage, open your Duo Admin dashboard. diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_email/index.md b/website/docs/add-secure-apps/flows-stages/stages/authenticator_email/index.md new file mode 100644 index 0000000000..9db811a933 --- /dev/null +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_email/index.md @@ -0,0 +1,48 @@ +--- +title: Email Authenticator Setup stage +--- + +authentik 2025.2+ + +This stage configures an email-based authenticator that sends a one-time code to a user's email address for authentication. + +When a user goes through a flow that includes this stage, they are prompted for their email address (if not already set). The user then receives an email with a one-time code, which they enter into the authentik Login panel. + +The email address will be saved and can be used with the [Authenticator validation](../authenticator_validate/index.mdx) stage for future authentications. + +## Flow integration + +To use the Email Authenticator Setup stage in a flow, follow these steps: + +1. [Create](../../flow/index.md#create-a-custom-flow) a new flow or edit an existing one. +2. On the flow's **Stage Bindings** tab, click **Create and bind stage** to create and add the Email Authenticator Setup stage. (If the stage already exists, click **Bind existing stage**.) +3. Configure the stage settings as described below. + + - **Name**: provide a descriptive name, such as Email Authenticator Setup. + - **Authenticator type name**: define the display name for this stage. + - **Use global connection settings**: the stage can be configured in two ways: global settings or stage-specific settings. + + - Enable (toggle on) the **Use global connection settings** option to use authentik's global email configuration. Note that you must already have configured your environment variables to use the global settings. See instructions for [Docker Compose](../../../../install-config/install/docker-compose#email-configuration-optional-but-recommended) and for [Kubernetes](../../../../install-config/install/kubernetes#optional-step-configure-global-email-credentials). + + - If you need different email settings for this stage, disable (toggle off) **Use global connection settings** and configure the following options: + + - **Connection settings**: + + - **SMTP Host**: SMTP server hostname (default: localhost) + - **SMTP Port**: SMTP server port number(default: 25) + - **SMTP Username**: SMTP authentication username (optional) + - **SMTP Password**: SMTP authentication password (optional) + - **Use TLS**: Enable TLS encryption + - **Use SSL**: Enable SSL encryption + - **Timeout**: Connection timeout in seconds (default: 10) + - **From Address**: Email address that messages are sent from (default: system@authentik.local) + + - **Stage-specific settings**: + + - **Subject**: Email subject line (default: "authentik Sign-in code") + - **Token Expiration**: Time in minutes that the sent token is valid (default: 30) + - **Configuration flow**: select the flow to which you are binding this stage. + +4. Click **Update** to complete the creation and binding of the stage to the flow. + +The new Email Authenticator Setup stage now appears on the **Stage Bindings** tab for the flow. diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_sms/index.mdx b/website/docs/add-secure-apps/flows-stages/stages/authenticator_sms/index.mdx index 52421a7792..fcc1a6b1a9 100644 --- a/website/docs/add-secure-apps/flows-stages/stages/authenticator_sms/index.mdx +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_sms/index.mdx @@ -1,5 +1,5 @@ --- -title: SMS authenticator setup stage +title: SMS Authenticator Setup stage --- This stage configures an SMS-based authenticator using either Twilio, or a generic HTTP endpoint. diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_static/index.md b/website/docs/add-secure-apps/flows-stages/stages/authenticator_static/index.md index d0d39e692a..60cf64f0bc 100644 --- a/website/docs/add-secure-apps/flows-stages/stages/authenticator_static/index.md +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_static/index.md @@ -1,5 +1,5 @@ --- -title: Static authenticator setup stage +title: Static Authenticator Setup stage --- This stage configures static Tokens, which can be used as a backup method to time-based OTP tokens. diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_totp/index.md b/website/docs/add-secure-apps/flows-stages/stages/authenticator_totp/index.md index cade40a794..69967cde0c 100644 --- a/website/docs/add-secure-apps/flows-stages/stages/authenticator_totp/index.md +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_totp/index.md @@ -1,5 +1,5 @@ --- -title: TOTP authenticator setup stage +title: TOTP Authenticator Setup stage --- This stage configures a time-based OTP Device, such as Google Authenticator or Authy. diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_validate/index.mdx b/website/docs/add-secure-apps/flows-stages/stages/authenticator_validate/index.mdx index 4d1ddc5dca..5b595c4887 100644 --- a/website/docs/add-secure-apps/flows-stages/stages/authenticator_validate/index.mdx +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_validate/index.mdx @@ -1,10 +1,11 @@ --- -title: Authenticator validation stage +title: Authenticator Validation stage --- This stage validates an already configured Authenticator Device. This device has to be configured using any of the other authenticator stages: - [Duo authenticator stage](../authenticator_duo/index.mdx) +- [Email authenticator stage](../authenticator_email/index.md) - [SMS authenticator stage](../authenticator_sms/index.mdx) - [Static authenticator stage](../authenticator_static/index.md) - [TOTP authenticator stage](../authenticator_totp/index.md) diff --git a/website/docs/add-secure-apps/flows-stages/stages/authenticator_webauthn/index.mdx b/website/docs/add-secure-apps/flows-stages/stages/authenticator_webauthn/index.mdx index 805d2e0122..8b2da6dbec 100644 --- a/website/docs/add-secure-apps/flows-stages/stages/authenticator_webauthn/index.mdx +++ b/website/docs/add-secure-apps/flows-stages/stages/authenticator_webauthn/index.mdx @@ -1,5 +1,5 @@ --- -title: WebAuthn authenticator setup stage +title: WebAuthn Authenticator Setup stage --- This stage configures a WebAuthn-based Authenticator. This can either be a browser, biometrics or a Security stick like a YubiKey. diff --git a/website/sidebars.js b/website/sidebars.js index a1da29ad01..bb85ef043c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -297,11 +297,12 @@ export default { items: [ "add-secure-apps/flows-stages/stages/authenticator_duo/index", "add-secure-apps/flows-stages/stages/authenticator_endpoint_gdtc/index", + "add-secure-apps/flows-stages/stages/authenticator_email/index", "add-secure-apps/flows-stages/stages/authenticator_sms/index", "add-secure-apps/flows-stages/stages/authenticator_static/index", "add-secure-apps/flows-stages/stages/authenticator_totp/index", - "add-secure-apps/flows-stages/stages/authenticator_validate/index", "add-secure-apps/flows-stages/stages/authenticator_webauthn/index", + "add-secure-apps/flows-stages/stages/authenticator_validate/index", "add-secure-apps/flows-stages/stages/captcha/index", "add-secure-apps/flows-stages/stages/deny", "add-secure-apps/flows-stages/stages/email/index",