diff --git a/docs/flow/examples/login.md b/docs/flow/examples/login.md new file mode 100644 index 000000000..1c141e8d1 --- /dev/null +++ b/docs/flow/examples/login.md @@ -0,0 +1,36 @@ +# Login Flow + +This document describes how a simple authentication flow can be created. + +This flow is created automatically when passbook is installed. + +1. Create an **Identification** stage + + > Here you can select whichever fields the user can identify themselves with + > Select the Template **Default Login**, as this template shows the (optional) Flows + > Here you can also link optional enrollment and recovery flows. + +2. Create a **Password** stage + + > Select the Backend you want the password to be checked against. Select "passbook-internal Userdatabase". + +3. Create a **User Login** stage + + > This stage doesn't have any options. + +4. Create a flow + + > Create a flow with the delegation of **Authentication** + > Assign a name and a slug. The slug is used in the URL when the flow is executed. + +5. Bind the stages to the flow + + > Bind the **Identification** Stage with an order of 0 + > Bind the **Password** Stage with an order of 1 + > Bind the **User Login** Stage with an order of 2 + +  + +!!! notice + + This flow can used by any user, authenticated and un-authenticated. This means any authenticated user that visits this flow can login again. diff --git a/docs/flow/examples/login.png b/docs/flow/examples/login.png new file mode 100644 index 000000000..5e5306d3b Binary files /dev/null and b/docs/flow/examples/login.png differ diff --git a/docs/flow/flows.md b/docs/flow/flows.md index 954eee93d..5c429db15 100644 --- a/docs/flow/flows.md +++ b/docs/flow/flows.md @@ -2,7 +2,7 @@ Flows are a method of describing a sequence of stages. A stage represents a single verification or logic step. They are used to authenticate users, enroll them, and more. -Upon Flow execution, a plan is generated, which contains all stages. This means upon execution, all attached policies are evaluated. This behaviour can be altered by enabling the `Re-evaluate Policies` option on the binding. +Upon Flow execution, a plan is generated, which contains all stages. This means upon execution, all attached policies are evaluated. This behaviour can be altered by enabling the **Re-evaluate Policies** option on the binding. To determine which flow is linked, passbook searches all Flows with the required designation and chooses the first instance the current user has access to. @@ -18,28 +18,28 @@ Flows are designated for a single Purpose. This designation changes when a Flow This is designates a flow to be used for authentication. -The authentication flow should always contain a `user_login` stage, which attaches the staged user to the current session. +The authentication flow should always contain a [**User Login**](stages/user_login.md) stage, which attaches the staged user to the current session. ### Invalidation This designates a flow to be used for the invalidation of a session. -This stage should always contain a `user_logout` stage, which resets the current session. +This stage should always contain a [**User Logout**](stages/user_logout.md) stage, which resets the current session. ### Enrollment -This designates a flow for enrollment. This flow can contain any amount of Prompt stages, E-Mail verification or Captchas. At the end to create the user, you can use the `user_write` stage, which either updates the currently staged user, or if none exists, creates a new one. +This designates a flow for enrollment. This flow can contain any amount of Prompt stages, E-Mail verification or Captchas. At the end to create the user, you can use the [**User Write**](stages/user_write.md) stage, which either updates the currently staged user, or if none exists, creates a new one. ### Unenrollment -This designates a flow for unenrollment. This flow can contain any amount of verification, like `email` or captcha. To finally delete the account, use the `user_delete` stage. +This designates a flow for unenrollment. This flow can contain any amount of verification, like [**E-Mail**](stages/email/index.md) or [**Captcha**](stages/captcha/index.md). To finally delete the account, use the [**User Delete**](stages/user_delete.md) stage. ### Recovery -This designates a flow for recovery. This flow normally contains an `identification` stage to find the user. Then it can contain any amount of verification, like `email` or captcha. -Afterwards, use the `prompt` stage to ask the user for a new password and use `user_write` to update the password. +This designates a flow for recovery. This flow normally contains an [**Identification**](stages/identification/index.md) stage to find the user. Then it can contain any amount of verification, like [**E-Mail**](stages/email/index.md) or [**Captcha**](stages/captcha/index.md). +Afterwards, use the [**Prompt**](stages/prompt/index.md) stage to ask the user for a new password and use [**User Write**](stages/user_write.md) to update the password. ### Change Password -This designates a flow for password changing. This flow can contain any amount of verification, like `email` or captcha. -Afterwards, use the `prompt` stage to ask the user for a new password and use `user_write` to update the password. +This designates a flow for password changing. This flow can contain any amount of verification, like [**E-Mail**](stages/email/index.md) or [**Captcha**](stages/captcha/index.md). +Afterwards, use the [**Prompt**](stages/prompt/index.md) stage to ask the user for a new password and use [**User Write**](stages/user_write.md) to update the password. diff --git a/docs/flow/stages/captcha/captcha.md b/docs/flow/stages/captcha/index.md similarity index 100% rename from docs/flow/stages/captcha/captcha.md rename to docs/flow/stages/captcha/index.md diff --git a/docs/flow/stages/dummy/dummy.md b/docs/flow/stages/dummy/index.md similarity index 100% rename from docs/flow/stages/dummy/dummy.md rename to docs/flow/stages/dummy/index.md diff --git a/docs/flow/stages/email/email.md b/docs/flow/stages/email/index.md similarity index 100% rename from docs/flow/stages/email/email.md rename to docs/flow/stages/email/index.md diff --git a/docs/flow/stages/identification/identification.md b/docs/flow/stages/identification/index.md similarity index 100% rename from docs/flow/stages/identification/identification.md rename to docs/flow/stages/identification/index.md diff --git a/docs/flow/stages/invitation/invitation.md b/docs/flow/stages/invitation/index.md similarity index 100% rename from docs/flow/stages/invitation/invitation.md rename to docs/flow/stages/invitation/index.md diff --git a/docs/flow/stages/otp/otp.md b/docs/flow/stages/otp/index.md similarity index 100% rename from docs/flow/stages/otp/otp.md rename to docs/flow/stages/otp/index.md diff --git a/docs/flow/stages/password/password.md b/docs/flow/stages/password/index.md similarity index 100% rename from docs/flow/stages/password/password.md rename to docs/flow/stages/password/index.md diff --git a/docs/flow/stages/prompt/prompt.md b/docs/flow/stages/prompt/index.md similarity index 100% rename from docs/flow/stages/prompt/prompt.md rename to docs/flow/stages/prompt/index.md diff --git a/mkdocs.yml b/mkdocs.yml index 8580a57c4..c05718b4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,10 @@ nav: - Installation: - docker-compose: installation/docker-compose.md - Kubernetes: installation/kubernetes.md - - Flows: flow/flows.md + - Flows: + Overview: flow/flows.md + Examples: + - Login: flow/examples/login.md - Stages: - Captcha Stage: flow/stages/captcha/captcha.md - Dummy Stage: flow/stages/dummy/dummy.md diff --git a/passbook/admin/templates/administration/stage/list.html b/passbook/admin/templates/administration/stage/list.html index 624f5374e..9ca46266a 100644 --- a/passbook/admin/templates/administration/stage/list.html +++ b/passbook/admin/templates/administration/stage/list.html @@ -62,6 +62,8 @@ <ul> {% for flow in stage.flow_set.all %} <li><a href="{% url 'passbook_admin:flow-update' pk=flow.pk %}">{{ flow.slug }}</a></li> + {% empty %} + <li>-</li> {% endfor %} </ul> </td>