Users & Permissions plugin documentation (#294)

* Add Users and Permissions plugin in Strapi plugins list

* Write documentation for Email templates + Providers + Advanced settings

* Fix links

* Improve users and permissions plugin settings doc

* Start documenting end-users accounts and roles management

* Update TOC

* Finish documenting end-users roles configuration

* Finish documentation end-users accounts management

* Add links + Update TOC

* Improve content + Fix typos and links

* Improve after reviews

* Improve content + Add screenshots

* Improve content after more reviews

* Add SEO titles + descriptions

Co-authored-by: Pierre Wizla <[email protected]>

Author: meganelacheny

docs/.vuepress/config.js

@@ -321,6 +321,14 @@ const sidebar = {
           '/user-docs/latest/users-roles-permissions/managing-administrators',
           'Managing administrator accounts',
         ],
+        [
+          '/user-docs/latest/users-roles-permissions/configuring-end-users-roles',
+          'Configuring end-users roles',
+        ],
+        [
+          '/user-docs/latest/users-roles-permissions/managing-end-users',
+          'Managing end-users accounts',
+        ],
       ],
     },
     {
@@ -346,6 +354,7 @@ const sidebar = {
       title: 'General settings',
       children: [
         ['/user-docs/latest/settings/managing-global-settings', 'Managing global settings'],
+        ['/user-docs/latest/settings/configuring-users-permissions-plugin-settings', 'Configuring Users & Permissions plugin settings'],
       ],
     },
   ],

docs/user-docs/latest/assets/plugins/icon_up-plugin.png

@@ -29,4 +29,24 @@ The Internationalization plugin impacts several parts of the admin panel. The ta
 |------------------|---------------------------------------------------------------------------------------------------------|
 | Settings         | <ul><li>Addition of a new "Internationalization" setting sub-section, from which to add, edit or delete locales available for the application (see [Configuring Internationalization locales](../settings/managing-global-settings.md#configuring-internationalization-locales)). <br> 👉 Path reminder: *General > Settings > Global Settings > Internationalization* </li> <br> <li>Addition of new permissions for administator roles: access to content-types, as well as possible actions on the content-types, can be defined depending on the locale (see [Configuring role's permissions](/user-docs/latest/users-roles-permissions/configuring-administrator-roles.md#configuring-role-s-permissions)). <br> 👉 Path reminder: *General > Settings > Administration panel*</li></ul> |
 | Content-Types Builder | <ul><li>Addition of a new setting at content-type level, to allow or not localisation/translation of the content-type (see [Creating a new content-type](/user-docs/latest/content-types-builder/creating-new-content-type.md#creating-a-new-content-type)).</li> <li>Addition of a new setting at field level, to allow or not localisation/translation of the content-type (see [Configuring fields for content types](/user-docs/latest/content-types-builder/configuring-fields-content-type.md#regular-fields)).</li></ul> |
-| Content Manager | <ul><li>Addition of new *Locales* filter in collection types list view, to manage entries per locale (see [Introduction to the Content Manager](/user-docs/latest/content-manager/introduction-to-content-manager.md#collection-types)).</li> <li>Addition of new options in content-types edit view, to translate content and manage it per locale (see [Translating content](/user-docs/latest/content-manager/translating-content.md)).</li></ul> |
+| Content Manager | <ul><li>Addition of new *Locales* filter in collection types list view, to manage entries per locale (see [Introduction to the Content Manager](/user-docs/latest/content-manager/introduction-to-content-manager.md#collection-types)).</li> <li>Addition of new options in content-types edit view, to translate content and manage it per locale (see [Translating content](/user-docs/latest/content-manager/translating-content.md)).</li></ul> |
+
+
+### <img width="28" src="../assets/plugins/icon_up-plugin.png"> Users & Permissions plugin
+
+The Users & Permissions plugin is installed by default on all Strapi applications.
+
+This plugin allows to manage end-users, who consume the content that is created and managed with a Strapi application and displayed on a front-end application (e.g. website, mobile application, connected device etc.). With the Users & Permissions plugin, it is possible to:
+
+- manage end-users accounts, based on a "User" collection type available through the plugin,
+- define the available end-users roles and their related permissions,
+- manage available providers to enable end-users to login through third-party providers,
+- configure available email templates aimed at the end-users (e.g. password reset, email address confirmation).
+
+The Users & Permissions plugin impacts several parts of the admin panel. The table below lists all the additional options and settings that are added to a Strapi application once the plugin has been installed.
+
+| Section impacted | Options and settings                                                                                    |
+|------------------|---------------------------------------------------------------------------------------------------------|
+| Settings         | <ul>Addition of a "Users & Permissions plugin" setting section, which contains 4 sub-sections: Roles (see [Configuring end-users roles](../users-roles-permissions/configuring-end-users-roles.md)), Providers, Email Templates, and Advanced Settings (see [Configuring Users & Permissions plugin](../settings/configuring-users-permissions-plugin-settings.md)). <br> 👉 Path reminder: *General > Settings > Users & Permissions plugin* </ul> |
+| Content-Types Builder | <ul>Creation of 3 default collection types: "User", "Role" and "Permission". They respectively allow to manage the end-users, the end-users roles and their permissions. These collection types cannot be deleted and their composing fields cannot be edited, but addition of new fields is possible. Out of the 3, only the "User" collection type is then available via the Content Manager.</ul> |
+| Content Manager | <ul>Addition of the default "User" collection type that allows to manage end-user accounts (see [Managing end-users accounts](../users-roles-permissions/managing-end-users.md)). <ul><li>By default, the following fields are available: Username, Email, Password, as well as Confirmed and Blocked as boolean fields.</li> <li>The "User" collection type has a relation established with the "Role" collection type. All end-user accounts must indeed be attributed a role: by default, the end-user is attributed the end-user role set as default, but that role can be changed via the end-users entries directly in the Content Manager.</li></ul> </ul> |

docs/user-docs/latest/assets/settings/up_email-templates.png

@@ -0,0 +1,69 @@
+---
+title: Users & Permissions plugin settings - Strapi User Guide
+description: Instructions to configure the Users & Permissions plugin
+---
+
+# Configuring Users & Permissions plugin settings
+
+The Users & Permissions plugin is managed from the *Users & Permissions plugin* settings section, accessible from *General > Settings* in the main navigation of the admin panel. This settings section allows to configure the available providers, email templates and the advanced settings of the plugin. It also allows to define the end-users roles and their related permissions (see [Configuring end-users roles](../users-roles-permissions/configuring-end-users-roles.md)).
+
+## Configuring providers
+
+The Users & Permissions plugin allows to enable and configure providers, for end-users to login via a third-party provider to access the content of a font-end application through the Strapi application API. By default, a list of providers is available including one, "Email", enabled by default for all Strapi applications with the Users & Permissions plugin installed.
+
+![Providers interface](../assets/settings/up_providers.png)
+
+To enable and configure a provider:
+
+1. Go to the *Users & Permissions plugin > Providers* sub-section of the settings interface.
+2. Click on the provider to enable and configure.
+3. In the provider edition window, click on the **ON** button of the *Enable* option.
+4. Fill in the provider's configurations. Each provider has its own specific set of configurations, detailed in our developer documentation (see [Setting up the provider](https://strapi.io/documentation/developer-docs/latest/development/plugins/users-permissions.html#setting-up-the-provider-examples)).
+5. Click on the **Save** button.
+
+::: tip NOTE
+Other providers that are not proposed by default by Strapi can be added manually through the code of your Strapi application (see [Developer documentation](https://strapi.io/documentation/developer-docs/latest/development/plugins/users-permissions.html#adding-a-new-provider-to-your-project)).
+:::
+
+## Configuring email templates
+
+The Users & Permissions plugin uses 2 email templates, "Email address confirmation" and "Reset password", that are sent to end-users:
+
+- if their account must be confirmed to be activated,
+- if they need to reset the password of their Strapi account.
+
+![Email templates interface](../assets/settings/up_email-templates.png)
+
+To configure and edit email templates:
+
+1. Go to the *Users & Permissions plugin > Email templates* sub-section of the settings interface.
+2. Click on the name of the email template to configure and edit.
+3. Configure the email template:
+
+| Setting name   | Instructions                                                                                     |
+| -------------- | -------------------------------------------------------------------------------------------------|
+| Shipper name   | Indicate the name of the shipper of the email.                                                   |
+| Shipper email  | Indicate the email address of the shipper of the email.                                          |
+| Response email | (optional) Indicate the email address to which responses emails from the end-users will be sent. |
+| Subject        | Write the subject of the email. Variables can be used (see [Developer documentation](https://strapi.io/documentation/developer-docs/latest/development/plugins/users-permissions.html#templating-emails)).             |
+
+4. Edit the content of the email in the "Message" textbox. Email templates content is in HTML and uses variables (see [Developer documentation](https://strapi.io/documentation/developer-docs/latest/development/plugins/users-permissions.html#templating-emails)).
+5. Click on the **Save** button.
+
+## Configuring advanced settings
+
+All settings related to the Users & Permissions plugin are managed from the *Advanced Settings* sub-section, including the choice of a default role for end-users, the enablement of sign-ups and email confirmation, as well as the choice of landing page for resetting a password.
+
+![Advanced settings interface](../assets/settings/up_settings.png)
+
+1. Go to the *Users & Permissions plugin > Advanced settings* sub-section of the settings interface.
+2. Configure the settings:
+
+| Setting name                         | Instructions                                                                                                                                                       |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Default role for authenticated users | Click the drop-down list to choose the default role for new end-users.                                                                                             |
+| One account per email address        | Click on the **ON** button to limit to 1 the number of end-user accounts with the same email address. Click on **OFF** to disable this limitation and allow several end-users accounts to be associated with the same email addess (e.g. `[email protected]` can be used when logging in via several different providers). |
+| Enable sign-ups                      | Click on the **ON** button to enable end-users sign-ups. Click on **OFF** to prevent end-users registration to your front-end application(s).                      |
+| Reset password page                  | Indicate the URL of the reset password page for your front-end application(s).                                                                                     |
+| Enable email confirmation            | Click on the **ON** button to enable end-users account confirmation by sending them a confirmation email. Click on **OFF** to disable account confirmation.        |
+| Redirection url                      | Indicate the URL of the page where end-users should be redirected after confirming their Strapi account.                                                           |

docs/user-docs/latest/assets/settings/up_providers.png

@@ -0,0 +1,76 @@
+---
+title: Configure End-users Roles - Strapi User Guide
+description: Instructions to configure the end-users roles for a front-end application using the Users & Permissions plugin
+---
+
+# Configuring end-users roles
+
+End-users are the users who consume the content that is created and managed with a Strapi application and displayed on front-end applications (e.g. websites, mobile applications, connected devices etc.). Unlike the administrators, they do not have access to the admin panel. End-users are managed with the Users & Permissions plugin (see [Users & Permissions plugin](../plugins/strapi-plugins.md#users-permissions-plugin)). This plugin is however not entirely managed and configured from one same place of the admin panel: end-users accounts are managed from the Content Manager (see [Managing end-user accounts](../users-roles-permissions/managing-end-users.md)) but end-users roles and permissions are managed in the Settings interface.
+
+The configurations of the end-users roles and permissions are available in the *Users & Permissions plugin* section of the Settings interface, accessible from *General > Settings* in the main navigation of the admin panel.
+
+![End-users roles interface](../assets/users-permissions/end-user_roles.png)
+
+The *Roles* sub-section of *Users & Permissions plugin* displays all created roles for the end-users of your Strapi application.
+
+From this interface, it is possible to:
+
+- create a new end-user role (see [Creating a new role](#creating-a-new-role)),
+- delete an end-user role (see [Deleting a role](#deleting-a-role)),
+- or access information regarding an end-user role, and edit it (see [Editing a role](#editing-a-role)).
+
+By default, 2 end-user roles are defined for any Strapi application:
+
+- Authenticated: for end-users to access content only if they are logged in to a front-end application.
+- Public: for end-users to access content without being logged in to a front-end application.
+
+::: tip NOTE
+The end-user role attributed by default to all new end-users can be defined in the *Advanced settings* sub-section of *Users & Permissions plugin* (see [Configuring advanced settings](../settings/configuring-users-permissions-plugin-settings.md#configuring-advanced-settings)).
+:::
+
+## Creating a new role
+
+On the top right side of the *Users & Permissions plugin > Roles* interface, an **Add new role** button is displayed. It allows to create a new role for end-users of your Strapi application.
+
+To create a new role, click on the **Add new role** button.
+Clicking on the **Add new role** button will redirect you to the roles edition interface, where you will be able to edit the role's details and configure its permissions (see [Editing a role](#editing-role-s-details)).
+
+## Deleting a role
+
+Although the 2 default end-users roles cannot be deleted, the other ones can, as long as no end-user still has this role attributed to their account.
+
+To delete a role:
+
+1. Click on the trash button <Fa-TrashAlt /> on the right side of the role's record.
+2. In the deletion window, click on the **Yes, confirm** button to confirm the deletion.
+
+## Editing a role
+
+![Configuring a role for end-users](../assets/users-permissions/end-user_roles-config.png)
+
+The role edition interface allows to edit the details of an end-user role as well as to configure in detail the permissions to access the content of a front-end application. It is accessible from *Users & Permissions plugin > Roles* either after clicking on the edit button <Fa-PencilAlt /> on the right side of a role's record, or after clicking on the **Add new role** button (see [Creating a new role](#creating-a-new-role)).
+
+### Editing role's details
+
+The details area of an end-user role editing interface allows to define the name of the role, and to give it a description that should help administrators understand what the role gives access to.
+
+To edit a role's details, follow the instructions from the table below:
+
+| Role details  | Instructions                                                                                                                     |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Name          | Write the new name of the role in the textbox.                                                                                   |
+| Description   | Write the description of the role in the textbox.          
+
+### Configuring role's permissions
+
+The permissions area of an end-user role editing interface allows to configure all possible actions and accesses for content-types and available plugins of the Strapi application.
+
+To configure permissions for an end-user role:
+
+1. Click on the name of the permission category to configure (e.g. Application, Content-Manager, Email etc.).
+2. Tick the boxes of the actions and permissions to grant for the role.
+3. Click on the **Save** button.
+
+::: tip 💡 TIP
+When ticking an action or permission box, related bound routes of the API are displayed in the right side of the interface.
+:::