docs(NET-1508): add docs for new user management

examplecode/netmaker.default.env

@@ -68,3 +68,14 @@ FRONTEND_URL=
 AZURE_TENANT=
 # https://oidc.yourprovider.com - URL of oidc provider
 OIDC_ISSUER=
+# config for sending emails
+# mail sender type (smtp or resend)
+EMAIL_SENDER_TYPE=smtp
+# mail server host
+SMTP_HOST=smtp.gmail.com
+# mail server port
+SMTP_PORT=587
+# sender email
+EMAIL_SENDER_ADDR=
+# sender email auth
+EMAIL_SENDER_AUTH=

pro/pro-users.rst

@@ -1,53 +1,105 @@
-=================================
-Users in Netmaker Professional
-=================================
+========================================
+User Management in Netmaker Professional
+========================================
 
-Netmaker Professional offers advanced user management features. The super admin can create users with either a user or admin role. Only Admins can access the dashboard, the normal users can use remote access client to join the network through a gateway.
-Admins can add users and assign them to remote access gateways, which includes managing the user's access to different remote access gateways.
+Since v0.25.0, the User Management feature is designed to streamline the administration of user roles, permissions, and access levels within a platform.
+This robust system allows super admins to create and manage user accounts with varying levels of access, ensuring that each user has the appropriate permissions to perform their tasks effectively.
+The feature supports multiple user types, including super admins, admins, service users, and platform users, each with distinct capabilities tailored to their roles within the organization.
 
-Here is a breakdown of the different user types and their permissions:
+At its core, the User Management feature enables the creation of user accounts through both invitation and direct addition methods.
+Super admins can assign Platform Access Levels (PAL) to users, determining their access to various functionalities across the platform.
+For instance, admins can manage user roles, invite new users, and oversee network configurations, while service users are limited to specific tasks without dashboard access, focusing instead on remote access via the RAC app.
+This hierarchical structure promotes security and efficiency, allowing organizations to maintain control over their user base while facilitating collaboration.
 
-* User: Users do not have access to the Netmaker dashboard. They can only use the remote access client to connect to a gateway.
+Additionally, the feature includes functionalities for managing network roles and groups, enhancing the granularity of access control.
+Admins can create network-specific roles and assign them to users, ensuring that they only have access to the resources necessary for their work.
+Groups can be formed to bundle roles, simplifying the management of permissions for multiple users at once.
+This flexibility is crucial for organizations with diverse teams and projects, as it allows for a tailored approach to user management that can adapt to changing needs and workflows.
 
-* Admin: They can create and manage users, networks, and gateways. They cannot create/manage other admins
 
-* Super Admin: Super admins have full access to Netmaker. They can create and manage users, admins, networks, and gateways. They can also manage user and admin permissions.
+Here is a breakdown of the different user types and their permissions (platform access levels):
+
+- Super Admin: Possesses complete control over the platform, including creating and managing all other user types and their permissions.
+- Admin: Has significant privileges to manage user accounts, assign roles, and oversee network configurations, but with limitations compared to the Super Admin (eg: cannot create other admins).
+- Platform User: Has access to the dashboard and can interact with assigned resources based on granted permissions, suitable for team members needing specific functionalities.
+- Service User: Designed for operational tasks without dashboard access, with permissions adjustable by Super Admins or Admins. The classic use case for this user type is remote access via the RAC app.
 
 
 Adding users
 ============
 
-To add a user, go to the Users section and click the Add User button. Fill in the user's details, including their name, password, and role.
+There are two ways to create a user:
 
-* As a super admin, you can add users with the role of admin or user.
-* As an admin, you can only add users with the role of user.
+1. **Basic Auth:** Fill in the user's details and click **Create User**.
+2. **User Invite:** Enter the different email addresses of the users you want to invite. They will receive an email with a link to create their account (Ensure you have set up the SMTP client for emailing).
 
-.. image:: /pro/images/users/add-user.png
-   :width: 80%
-   :alt: Add User
-   :align: center
 
-The credentials will need to be shared with the added user.
+Basic Auth
+-----------
 
-Attaching or removing user from a remote access gateway
-=======================================================
+This method is more suited for creating individual users directly. The admin just types a username and password for the user, then specifies any group or additional custom roles they should have.
+
+.. image:: /images/usr-mgmt/create-user-modal-groups.png
+   :width: 80%
+   :alt: create user basic auth
+   :align: center
 
-To attach users to a remote access gateway or remove users from a gateway, you will need to have the gateway set up. 
-Once the remote access gateway is set up, you will see an option to attach or remove users from the gateway's dropdown menu on the table row.
 
-.. image:: /pro/images/users/gateway-dropdown.png
+.. image:: /images/usr-mgmt/create-user-modal-custom-roles.png
    :width: 80%
-   :alt: Add Remove User dropdown
+   :alt: create user basic auth
    :align: center
 
-You can click the button to either attach or remove a user
 
-.. image:: /pro/images/users/attach-remove-users.png
+User Invite
+-------------
+
+This method is more suited for inviting multiple users at once. The admin types in the email addresses of the users they want to invite, then specifies any group or additional custom roles they should have.
+
+Users will receive an email with a link to create their account. They will have whatever roles and groups the admin assigned to them during the invite process.
+Ensure you have set up the SMTP client config for emailing.
+
+.. image:: /images/usr-mgmt/invite-user.png
    :width: 80%
-   :alt: Attach Remove User Modal
+   :alt: invite users
    :align: center
 
 
+Network Roles
+==============
+
+Network roles are roles that are specific to a network. They are used to manage a user's access to a network. Network roles are signifact to platform and service users since admins can already access the entire Netmaker platform.
+
+Network roles come in two flavors: *specific network roles* that affect particular networks, and *global network roles* that affect all networks.
+There are only two global network roles: *global-network-admin*, which gives a user admin privileges over all networks and *global-network-user*, which gives a user basic view and connect only privileges across all networks.
+
+The specific network roles follow the naming pattern of *<network id>-network-admin*, *<network id>-network-user* and *netID-<network id>-rag-<RAG name>*.
+
+Breakdown
+
+1. *<network id>-network-admin* gives a user admin privileges over that specific network.
+2. *<network id>-network-user* gives a user basic view and connect only privileges over that specific network.
+3. *netID-<network id>-rag-<RAG name>* gives a user connect-only access to a specific RAG in that network. If the user has *platform-user* access level, they would also be able to view the corresponding network.
+
+The system provides a choice: administrators can opt for the precision of network-specific roles or the efficiency of global network roles. However, if a global network role isn't assigned, meticulous management is required to ensure consistent permissions across all networks, involving updates to individual network roles as needed.
+
+In addition to the global network roles, default network roles are automatically created for any new network (admin and user), and default RAG roles are created for any new RAG created under a network. This eliminates the extra step of having to manually create such roles for user assignment.
+
+Permissioning in Netmaker is additive. This implies if a user for instance has both global-network-admin and netID-mynet-rag-defaultgw, the user would not be restricted to defaultgw under the mynet network, but would instead have admin access to all RAGs and networks since the global-network-admin role gives them that right.
+
+Managing user access to a remote access gateway (RAG)
+=======================================================
+
+From version 0.25.0, Netmaker Professional allows you to manage user access to a remote access gateway/network via roles.
+
+- An *admin* or *super admin* user can access all gateways and all networks.
+- A *platform user* or *service user* (does not have dashboard access) can only access the gateways they are assigned to.
+
+To give a user access to an RAG, first ensure the gateway is already created. Then go to the User management page, click on the user you want to assign a gateway to, and assign them a role for the gateway.
+
+To remove a user from a gateway, click on the user and remove the role for the gateway.
+
+
 Transferring super admin rights
 ===============================
 

server-installation.rst

@@ -243,6 +243,37 @@ ENDPOINT_DETECTION
 
     **Description** if turned on netclient checks if peers are reachable over private/LAN address, and choose that as peer endpoint
 
+EMAIL_SENDER_TYPE
+
+    **Default** smtp
+
+    **Description** smtp or resend
+
+SMTP_HOST
+
+    **Default** ""
+
+    **Description** The address of the host SMTP service
+
+SMTP_PORT
+
+    **Default** 587
+
+    **Description** The port of the SMTP service
+
+EMAIL_SENDER_ADDR
+
+    **Default** ""
+
+    **Description** The email address to send from
+
+EMAIL_SENDER_AUTH
+
+    **Default** ""
+
+    **Description** The auth token or password for the email sender
+
+
 Compose File - Annotated
 --------------------------------------
 

troubleshoot.rst

@@ -72,8 +72,8 @@ Please follow this Gist if you are encountering issues with 0.13+: https://gist.
 UI
 ----
 **I want to make a separate network and give my friend access to only that network.**
-  Simply navigate to the UI (as an admin account). Select users in the top left and create an account for them.
-  Select the network(s) to give them and they should be good to go! They are an admin of that network(s) only now.
+  Simply navigate to the UI (as an admin account). Create an account for (username/password) or invite your friend via email.
+  Assign a network administrator role, for the network you want them to have access to. This would give your friend full access to the assigned network.
 
 **I'm done with an access key, can I delete it?**
   Simply navigate to the UI (as an admin account). Select your network of interest, then select the ``Access Keys`` tab.

ui-reference.rst

@@ -20,7 +20,6 @@ When you start Netmaker for the first time, you will be prompted to create a sup
 (1) **Username:** Enter a unique username for the admin user.
 (2) **Password:** Enter a secure password for your new user.
 (3) **Password Confirmation:** Repeat the password for verification.
-(4) **Signup with OAuth:** Button to signup with OAuth. From v0.23.1, OAuth users will need further approval from a server admin to gain access.
 
 Login
 --------
@@ -33,7 +32,8 @@ Login
 (1) **Username:** Enter your username.
 (2) **Password:** Enter your password.
 (3) **Login:** Button to login.
-(4) **Login with OAuth:** Button to login with OAuth.
+
+**Signup/Login with OAuth:** Users have the option to sign in or sign up via OAuth. New users however will require apporval from a server admin to gain access.
 
 Dashboard
 =================
@@ -274,3 +274,183 @@ Access Control Lists
 (4) **(allowed):** Click to switch a connection to "deny." Note that node names are higlighted on the side and top to track location.
 (5) **(blocked):** Click to switch a connection to "allow."
 (6) **Submit Changes:** Click once you are ready to submit. Will send message to update relevant nodes in network.
+
+
+User Management
+=====================
+
+Netmaker v0.25.0 comes with a revamped user management, for easy onboarding of users (including bulk onboarding) and fine-grained permissioning.
+
+Under the **User Management** section, available for *super admins* and *admins* only, you will see all active users, groups (Pro), roles (Pro), invites and pending users. Ypu can manage users from this section of the dashboard.
+
+.. image:: images/user-mgmt/users.png
+   :width: 80%
+   :alt: Users
+   :align: center
+
+All active users are listed here. You can search for a user by name or email. You can also see the different groups the user belongs to and their platform access level.
+
+You can view and update a user's details by clicking on the user's name.
+From this modal, you can change user details including: password, groups, network roles, and platform access level.
+
+.. image:: images/user-mgmt/user-details.png
+   :width: 80%
+   :align: center
+   :alt: User details of a user. You can update the user's details, change their password, ...
+
+
+Create User
+------------
+
+Creating a new user is easy. Click on the **Add a User** button at the top right to begin the process.
+
+There are two ways to create a user:
+1. **Basic Auth:** Fill in the user's details and click **Create User**.
+2. **User Invite:** Enter the different email addresses of the users you want to invite. They will receive an email with a link to create their account (Ensure you have set up the SMTP client for emailing).
+
+
+Basic Auth
+------------
+
+.. image:: images/user-mgmt/create-user-modal-groups.png
+   :width: 80%
+   :alt: Create User Basic Auth
+   :align: center
+
+.. image:: images/user-mgmt/create-user-modal-custom-roles.png
+   :width: 80%
+   :alt: Create User Basic Auth
+   :align: center
+
+(1) **Username:** Enter a unique username of the user.
+(2) **Password:** Choose a password for the user. User's are advised to change their password after logging in.
+(3) **Confirm Password:** Confirm the password for the user.
+(4) **Platform Access Level:** Select the platform access level for the user. The platform access level determines the user's access to the platform as a whole, rather than a specific network. Admin/Superadmins are able to access all networks and server-level settings. Platform users are able to access a limited set of the dasboard. Service users are not able to access the dashboard: they are only able to access networks via our RAC app.
+(5) **Groups:** Select the groups the user will belong to.
+(6) **Additional Roles Per Network:** Select the network roles the user will have per network.
+
+
+User Invite
+------------
+
+.. image:: images/user-mgmt/invite-users.png
+   :width: 80%
+   :alt: Invite Users
+   :align: center
+
+(1) **Email Address(es):** Enter the email addresses of the users you want to invite. Separate multiple email addresses with a comma. **No spaces**
+(2) **Platform Access Level:** Select the platform access level for the user. The platform access level determines the user's access to the platform as a whole, rather than a specific network.
+(3) **Groups:** Select the groups the users will belong to.
+(4) **Additional Roles Per Network:** Select the network roles the users will have per network.
+
+
+After inviting a user, they will receive an email with a link to create their account. The user will be prompted to create a password or continue via OAuth, and will be able to access the platform with the permissions you have set. See screenshots below:
+
+.. image:: images/user-mgmt/continue-invite-basic-auth.png
+   :width: 80%
+   :alt: Invite Email
+   :align: center
+
+.. image:: images/user-mgmt/continue-invite-sso.png
+   :width: 80%
+   :alt: Invite Email
+   :align: center
+
+
+User Roles
+============
+
+Netmaker v0.25.0 introduces user roles, which allow you to assign specific permissions to users on a per-network basis. This feature is available for Pro users only.
+
+Under the **User Management** section, you will see the **Roles** tab. Here, you can create, edit, and delete roles.
+
+.. image:: images/user-mgmt/network-roles.png
+   :width: 80%
+   :alt: Network Roles
+   :align: center
+
+
+Create Network Role
+---------------------
+
+To create a new role, click on the **Create Network Role** button at the top right.
+
+.. image:: images/user-mgmt/create-network-role.png
+   :width: 80%
+   :alt: Create Network Role
+   :align: center
+
+(1) **Role Name:** Enter a unique name for the role.
+(2) **Network:** Select the network the role will apply to.
+(3) **Assign Admin Access To Network:** Check this box to give the user admin access to the network. This will make any user with this role a "network administrator" for the selected network.
+(4) **Permissions (VPN Access):** Select the different RAGs (gateways) a user with this role will be able to connect to.
+(5) **Create Role:** Click to create the role.
+
+A created network role can be viewed and edited by clicking on the role name in the roles list.
+It can also be deleted from the list/table view.
+
+
+User Groups
+============
+
+Netmaker v0.25.0 re-introduces user groups, which allow you to group users together and assign permissions to the group. This feature is available for Pro users only.
+A group, in theory, is simply a collection or network roles. A group can have multiple users (members) and multiple roles.
+
+Under the **User Management** section, you will see the **Groups** tab. Here, you can create, edit, and delete groups.
+
+.. image:: images/user-mgmt/groups.png
+   :width: 80%
+   :alt: Groups
+   :align: center
+
+
+Create Group
+----------------
+
+To create a new group, click on the **Create Group** button at the top right.
+
+.. image:: images/user-mgmt/create-group.png
+   :width: 80%
+   :alt: Create Group
+   :align: center
+
+(1) **Group Name:** Enter a unique name for the group.
+(2) **Description:** Enter a description for the group.
+(3) **Associated Network Roles:** Select the roles the group will have, for each network. A group can have multiple roles.
+(4) **Group Members:** Select the users that will be members of the group.
+(5) **Create Group:** Click to create the group.
+
+A created group can be viewed and edited by clicking on the group name in the groups list.
+It can also be deleted from the list/table view.
+
+
+User Invites
+===============
+
+Under the **User Management** section, you will see the **Invites** tab. Here, you can view all invites and send new invites.
+
+.. image:: images/user-mgmt/invites.png
+   :width: 80%
+   :alt: Invites
+   :align: center
+
+Each invite has a unique magic link that can be used to create an account. This link can be sent to the invitee via email or other means.
+
+You can clear all invites by clicking on the **Clear All Invites** button at the top right, or delete individual invites by clicking on the **Delete** button next to the invite.
+
+
+Pending Users
+===============
+
+Under the **User Management** section, you will see the **Pending Users** tab. Here, you can view all pending users and approve or reject them.
+
+.. image:: images/user-mgmt/pending-users.png
+   :width: 80%
+   :alt: Pending Users
+   :align: center
+
+Pending users automatically join the platform as *service users* by default. This means they can only access networks via the RAC app.
+Their permissions can be changed by an admin or superadmin after approval.
+
+You can approve or reject pending users by clicking on the **Approve** or **Reject** button next to the user.
+You can also deny all pending users by clicking on the **Deny All Users** button at the top right.