website/docs: Balok pr for User docs (#7139)

* procedrual docs

* restructure

* new image, edit tweaks

* more tweaks

* edits

* edits for new button labels

* more content in invitations

* tweaks

* Optimised images with calibre/image-actions

* fixed link

* links

* ken's edits

* changed label name

* spelling checks

* fix links

* links again

* fighting with imports

* ugh

* add extensions back

* fix link

* tweak

* rename file again

* more links

* added punctuation

* use generated index

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: Tana Berry <tana@goauthentik.io>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>

website/docs/expressions/_functions.md

@@ -66,7 +66,7 @@ return ak_is_group_member(request.user, name="test_group")
 
 Fetch a user matching `**filters`.
 
-Returns "None" if no user was found, otherwise [User](/docs/user-group/user)
+Returns "None" if no user was found, otherwise returns the [User](/docs/user-group/user) object.
 
 Example:
 

website/docs/expressions/_user.md

@@ -1,4 +1,4 @@
--   `user`: The current user. This may be `None` if there is no contextual user. See ([User](../user-group/user.md#object-attributes))
+-   `user`: The current user. This may be `None` if there is no contextual user. See [User](../user-group/user/user_ref.md#object-properties).
 
 Example:
 

website/docs/flow/context/index.md

@@ -22,7 +22,7 @@ Keys prefixed with `goauthentik.io` are used internally by authentik and are sub
 
 ### Common keys
 
-#### `pending_user` ([User object](../../user-group/user.md))
+#### `pending_user` ([User object](../../user-group/user/user_ref.md#object-properties))
 
 `pending_user` is used by multiple stages. In the context of most flow executions, it represents the data of the user that is executing the flow. This value is not set automatically, it is set via the [Identification stage](../stages/identification/).
 

website/docs/policies/expression.mdx

@@ -41,7 +41,7 @@ import Objects from "../expressions/_objects.md";
 
 -   `request`: A PolicyRequest object, which has the following properties:
 
-    -   `request.user`: The current user, against which the policy is applied. See [User](../user-group/user.md#object-attributes)
+    -   `request.user`: The current user, against which the policy is applied. See [User](../user-group/user/user_ref.md#object-properties)
 
         :::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.
@@ -77,7 +77,7 @@ This includes the following:
 -   `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](../user-group/user.md#object-attributes)
+-   `context['pending_user']`: The currently pending user, see [User](../user-group/user/user_ref.md#object-properties)
 -   `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)
 

website/docs/user-group/user/index.mdx

@@ -0,0 +1,12 @@
+---
+title: About users
+---
+
+import DocCardList from "@theme/DocCardList";
+import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
+
+In authentik you can create and manage users with fine-tuned access control, session and event details, group membership, super-user rights, impersonation, and password management and recovery.
+
+To learn more about working with users in authentik, refer to the following topics:
+
+<DocCardList items={useCurrentSidebarCategory().items} />

website/docs/user-group/user/invitations.md

@@ -0,0 +1,49 @@
+---
+title: Invitations
+description: "Learn how to create an invitation URL for new users to enroll."
+---
+
+Invitations are another way to create a user, by inviting someone to join your authentik instance, as a new user. With invitations, you can either email an enrollment invitation URL to one or more specific recipients with pre-defined credentials, or you can email a URL to users, who can then log in and define their own credentials.
+
+:::info
+You can also create a policy to see if the invitation was ever used.
+:::
+
+## Create an invitation
+
+The fastest way to create an invitation is to use our pre-defined `default-enrollment-flow` that has the necessary stages and prompts already included.
+
+**Step 1. Download the `default-enrollment-flow` file**
+
+To download the `default-enrollment-flow` file, run this command:
+
+```
+wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/blueprints/example/flows-enrollment-2-stage.yaml
+```
+
+Alternatively, use this [link](/blueprints/example/flows-enrollment-2-stage.yaml) to view and save the file. For more details, refer to the [documentation](https://goauthentik.io/docs/flow/examples/flows#enrollment-2-stage).
+
+**Step 2. Import the `default-enrollment-flow` file**
+
+In authentik, navigate to the Admin UI, and then click **Flows** in the left navigation pane.
+
+At the top of the Flows page, click **Import**, and then select the `flows-enrollment-2-stage.yaml` file that you just downloaded.
+
+**Step 3. Create the invitation object**
+
+In the Admin UI, navigate to **Directory --> Invitations**, and then click **Create** to open the **Create Invitation** modal. Define the following fields:
+
+-   **Name**: provide a name for your invitation object.
+-   **Expires**: select a date for when you want the invitation to expire.
+-   **Flow**: in the drop-down menu, select the **default-enrollment-flow** Flow.
+-   **Custom attributes**: (_optional_) enter optional key/value pairs here, to pre-define any information about the user that you will invite to enroll. The data entered here is considered as a variable, specifically the `context['prompt_data']` variable. This data is read by the context flow's [prompt stage](../../flow/stages/prompt/index.md) in an expression policy.
+
+![Create an invitation modal box](./create_invite.png)
+
+-   **Single use**: specify whether or not you want the invitation to expire after a single use.
+
+Click **Save** to save the new invitation and close the modal and return to the **Invitations** page.
+
+**Step 3. Email the invitation**
+
+On the **Invitations** page, click the chevron beside your new invitation, to expand the details. The **Link to use the invitation** displays with the URL. Copy the URL and send it in an email to the people you want to invite to enroll.

website/docs/user-group/user/user_basic_operations.md

@@ -0,0 +1,117 @@
+---
+title: Manage users
+---
+
+The following topics are for the basic management of users: how to create, modify, delete or deactivate users, and using a recovery email.
+
+### Create a user
+
+> If you want to automate user creation, you can do that either by [invitations](./invitations.md), [`user_write` stage](../../flow/stages/user_write), or [using the API](/developer-docs/api/browser).
+
+1. In the Admin interface of your authentik instance, select **Directory > Users** in the left side menu.
+
+2. Select the folder where you want to create a user.
+
+3. Click **Create** (for a default user).
+
+4. Fill in the required fields:
+
+-   **Username**: This value must be unique across your user folders.
+-   **Path**: The path where the user will be created. It will be automatically populated with the folder you selected in the previous step.
+
+5. Fill the **_optional_** fields if needed:
+
+-   **Name**: The display name of the user.
+-   **Email**: The email address of the user. That will be used if there is a [notification rule](../../events/notifications) triggered or for [email stages](../../flow/stages/email).
+-   **Is active**: Define is the newly created user account is active. Selected by default.
+-   **Attributes**: Custom attributes definition for the user, in YAML or JSON format. These attributes can be used to enforce additional prompts on authentication stages or define conditions to enforce specific policies if the current implementation does not fit your use case. The value is an empty dictionary by default.
+
+6. Click **Create**
+
+You should see a confirmation pop-up on the top-right of the screen that the user has been created, and see the new user in the user list. You can directly click the username if you want to [modify your user](./user_basic_operations#modify-a-user).
+
+### View user details
+
+In the **Directory > Users** menu of the Admin interface, you can browse all the users in your authentik instance.
+
+To view details about a specific user:
+
+1. In the list of all users, click on the name of the user you want to check.
+
+    This takes you to the **Overview** tab, with basic information about the user, and also quick access to perform basic actions to the user.
+
+2. To see further details, click any of the other tabs:
+
+-   **Session** shows the active sessions established by the user. If there is any need, you can clean up the connected devices for a user by selecting the device(s) and then clicking **Delete**. This forces the user to authenticate again on the deleted devices.
+-   **Groups** allows you to manage the group membership of the user. You can find more details on [groups](../group).
+-   **User events** displays all the events generated by the user during a session, such as login, logout, application authorisation, password reset, user info update, etc.
+-   **Explicit consent** lists all the permissions the user has given explicitly to an application. Entries will only appear if the user is validating an [explicit consent flow in an OAuth2 provider](../../providers/oauth2/). If you want to delete the explicit consent (because the application is requiring new permissions, or the user has explicitly asked to reset his consent on third-party apps), select the applications and click **Delete**. The user will be asked to again give explicit consent to share information with the application.
+-   **OAuth Refresh Tokens** lists all the OAuth tokens currently distributed. You can remove the tokens by selecting the applications and then clicking **Delete**.
+-   **MFA Authenticators** shows all the authentications that the user has registered to their user profile. You can remove the tokens if the user has lost their authenticator and want to enroll a new one.
+
+## Modify a user
+
+After the creation of the user, you can edit any parameter defined during the creation.
+
+To modify a user object, go to **Directory > Users**, and click the edit icon beside the name.
+
+You can also go into [user details](#view-user-details), and click **Edit**.
+
+## User recovery
+
+If a user has lost their credentials, there are several options.
+
+### Email them a recovery link
+
+1. In the Admin interface, navigate to **Directory > Users** to display all users.
+
+2. Either click the name of the user to display the full User details page, or click the chevron (the › symbol) beside their name to expand the toptions.
+
+3. To generate a recovery link, which you can then copy and paste into an email, click **View recovery link**.
+
+    A pop-up will appear on your browser with the link for you to copy and to send to the user.
+
+### Automate email to a user
+
+You can use our automated email to send a link with the URL for the user to reset their password. This option will only work if you have properly [configured a SMTP server during the installation](../../installation/docker-compose#email-configuration-optional-but-recommended) and set an email address for the user.
+
+1. In the Admin interface, navigate to **Directory > Users** to display all users.
+
+2. Either click the name of the user to display the full User details page, or click the chevron beside their name to expand the toptions.
+
+3. To send the automated email to the user, click **Email recovery link**.
+
+If the user does not receive the email, check if the mail server parameters [are properly configured](../../troubleshooting/emails).
+
+### Reset the password for the user
+
+As an Admin, you can simply reset the password for the user.
+
+1. In the Admin interface, navigate to **Directory > Users** to display all users.
+
+2. Either click the name of the user to display the full User details page, or click the chevron beside their name to expand the toptions.
+
+3. To reset the user's password, click **Reset password**, and then define the new value.
+
+## Deactivate or Delete user
+
+#### To deactivate a user:
+
+1. Go into the user list or detail, and click **Deactivate**.
+
+2. Review the changes and click **Update**.
+
+The active sessions are revoked and the authentication of the user blocked. You can reactivate the account by following the same procedure.
+
+#### To delete a user:
+
+:::caution
+This deletion is not reversible, so be sure you do not need to recover any identity data of the user.
+You may instead deactivate the account to preserve identity data.
+:::
+
+1. Go into the user list and select one (or multiple users) to delete and click **Delete** on the top-right of the page.
+
+2. Review the changes and click **Delete**.
+
+The user list refreshes and no longer displays the removed users.

website/docs/user-group/user/user_ref.md

@@ -1,5 +1,5 @@
 ---
-title: User
+title: User properties and attributes
 ---
 
 ## Object properties
@@ -19,15 +19,15 @@ The User object has the following properties:
 -   `group_attributes()` Merged attributes of all groups the user is member of and the user's own attributes.
 -   `ak_groups` This is a queryset of all the user's groups.
 
-    You can do additional filtering like
+    You can do additional filtering like:
 
     ```python
     user.ak_groups.filter(name__startswith='test')
     ```
 
-    see [here](https://docs.djangoproject.com/en/3.1/ref/models/querysets/#id4)
+    For Django field lookups, see [here](https://docs.djangoproject.com/en/4.2/ref/models/querysets/#id4).
 
-    To get the name of all groups, you can do
+    To get the name of all groups, you can use this command:
 
     ```python
     [group.name for group in user.ak_groups.all()]
@@ -72,7 +72,7 @@ Only applies when the token creation is triggered by the user with this attribut
 
 ### `goauthentik.io/user/debug`:
 
-See [Troubleshooting access problems](../troubleshooting/access.md), when set, the user gets a more detailed explanation of access decisions.
+See [Troubleshooting access problems](../../troubleshooting/access), when set, the user gets a more detailed explanation of access decisions.
 
 ### `additionalHeaders`:
 

website/sidebars.js

@@ -260,7 +260,22 @@ const docsSidebar = {
         {
             type: "category",
             label: "Users & Groups",
-            items: ["user-group/user", "user-group/group"],
+            items: [
+                {
+                    type: "category",
+                    label: "Users",
+                    link: {
+                        type: "doc",
+                        id: "user-group/user/index",
+                    },
+                    items: [
+                        "user-group/user/user_basic_operations",
+                        "user-group/user/user_ref",
+                        "user-group/user/invitations",
+                    ],
+                },
+                "user-group/group",
+            ],
         },
         {
             type: "category",