From 44cc4e77435dff31375044f8a3e76eea72bbc6ae Mon Sep 17 00:00:00 2001 From: "Michiel W. Beijen" Date: Mon, 16 Dec 2024 23:11:51 +0100 Subject: [PATCH] User management: rewording - added indefinite and definite articles - fixed minor typo's or spelling issues --- admin/user-management.rst | 210 +++++++++++++++++++------------------- 1 file changed, 105 insertions(+), 105 deletions(-) diff --git a/admin/user-management.rst b/admin/user-management.rst index 8182470..df55bc8 100644 --- a/admin/user-management.rst +++ b/admin/user-management.rst @@ -9,8 +9,8 @@ User management Introduction ============ -|product_name| has it's own user database. All |product_name| user accounts stored in backend -SQL database. Each account has it's own unique login name and identifier. The +|product_name| has its own user database. All |product_name| user accounts are stored in the backend +SQL database. Each account has its own unique login name and identifier. The account may also have a password. @@ -40,18 +40,18 @@ Not all attributes are mandatory. Superuser ~~~~~~~~~ -|product_name| has built-in superuser with ID ``0``, which always has full access to -the system. Default login name for superuser is ``system``. By default user is -disabled. Superuser account can be renamed or disabled/enabled, but cannot be deleted. +|product_name| has a built-in superuser account with ID ``0``, which always has full access to +the system. The default login name for the superuser account is ``system``. By default this account is +disabled. The superuser account can be renamed or disabled/enabled, but cannot be deleted. -System user can be used to correct access rights to object, that exists, but -no user has access to it. +The system user can be used to correct access rights to objects that exists, but to which +no other users have access to. Groups ------ -Each user can be member of several groups. Groups are the preferred way to +Each user can be a member of several groups. Groups are the preferred way to organize access permissions. You should always grant permission to groups instead of using individual users. That way you will get a much shorter access control list which is easier to handle. Access rights from multiple groups are @@ -65,15 +65,15 @@ to the user. Everyone Group ~~~~~~~~~~~~~~ -|product_name| has built-in virtual group called :guilabel:`Everyone`. This group -always contains all users in the system. It cannot be deleted, and it's members +|product_name| has a built-in virtual group called :guilabel:`Everyone`. This group +always contains all users in the system. It cannot be deleted, and its member list cannot be edited. System Access Rights -------------------- -|product_name| has two types of access rights: system access rights described in +|product_name| has two types of access rights: system access rights as described in this chapter and :ref:`object access rights`. System access rights used to grant access to system-wide configuration (like @@ -89,7 +89,7 @@ The following system access rights can be granted: * - Access Right - Description * - Access server console - - Allow user to access server's debug console. :ref:`server-debug-console` + - Allow user to access the server debug console. :ref:`server-debug-console` * - Configure event templates - Allow user to add, edit and delete event templates. :ref:`event-processing` * - Configure object tools @@ -99,7 +99,7 @@ The following system access rights can be granted: * - Configure SNMP traps - Allow user to configure SNMP trap mapping. * - Control user sessions - - Allow user to see active user sessions and force terminate them. (Not yet implemented) + - Allow user to see active user sessions and forcefully terminate them. (Not yet implemented) * - Edit event processing policy - Allow user to edit Event Processing Policy. :ref:`event-processing` * - Edit server configuration variables @@ -114,7 +114,7 @@ The following system access rights can be granted: * - Login as mobile device - Allows user to login via mobile application. * - Manage agent configurations - - Allow user to create, edit and delete agent configurations stored on + - Allow user to create, edit and delete agent configurations stored on the server. :ref:`stored-agent-configurations-label` * - Manage all scheduled tasks - Allow user to create, edit and delete all :ref:`schedule`, including system ones. @@ -157,7 +157,7 @@ The following system access rights can be granted: * - Manage web service definitions - Allow user to manage system-wide definitions of web services. * - Read server files - - Allow user to read files stored on server and upload to agents (user + - Allow user to read files stored on the server and upload to agents (user still needs appropriate object rights for upload). :ref:`server-files-label` * - Manage agent tunnels - Allow user to list, bind and unbind agent tunnels. @@ -173,7 +173,7 @@ The following system access rights can be granted: * - Send notifications - Allow user to send manual notifications via |product_name| server. * - Unlink helpdesk tickets - - Allow user to unlink alarm from external helpdesk system :ref:`helpdesk-integration`. + - Allow user to unlink alarms from external helpdesk system :ref:`helpdesk-integration`. * - View all alarm categories - Allow user to view all alarms generated by Event Processing Policy rules. If this is off, user will only see alarms for categories he/she has access to. @@ -186,7 +186,7 @@ The following system access rights can be granted: * - View SNMP trap log - Allow user to view SNMP trap log. * - View syslog - - Allow user to syslog. + - Allow user to view syslog. By granting the :guilabel:`View all alarms` access right, the user (or members of the group) will have access to view all generated alarms. Should it be required to configure alarm viewing access @@ -199,8 +199,8 @@ User Authentication Internal Password ----------------- -This is the default method for user authentication. Password provided by user -compared against password stored in |product_name| database. +This is the default method for user authentication. The password provided by the user +when authenticating is compared against the password stored in the |product_name| database. .. _password-policy: @@ -218,19 +218,19 @@ Various restrictions can be put on internal passwords to force users to choose s - Description - Default * - MinPasswordLength - - Default minimum password length for a |product_name| user. The default applied only if per-user setting is not defined. + - Default minimum password length for a |product_name| user. The default applies only if a per-user setting is not defined. - 0 * - PasswordComplexity - - Required password complexity. See table bellow for details. + - Required password complexity. See table below for details. - 0 * - PasswordExpiration - Password expiration time in days. If set to ``0``, password expiration - is disabled. Has no effect on users with :guilabel:`Password never - expired` flag set. + is disabled. This variable has no effect on users with the :guilabel:`Password never + expires` flag set. - 0 * - PasswordHistoryLength - Number of previous passwords to keep. Users are not allowed to set - password if it matches one from previous passwords list. + password if it matches one from their previous passwords list. - 0 Possible flags for ``PasswordComplexity``: @@ -250,28 +250,28 @@ Possible flags for ``PasswordComplexity``: * - 8 - Password must contain special characters * - 16 - - Forbid alphabetical sequences (password considered invalid if it - contains alphabetical sequence of 3 or more letters of same + - Forbid alphabetical sequences (a password is considered invalid if it + contains an alphabetical sequence of 3 or more letters of the same case). * - 32 - - Forbid keyboard sequences (password considered invalid if it - contains sequence of 3 or more characters that are located on + - Forbid keyboard sequences (a password is considered invalid if it + contains a sequence of 3 or more characters that are located on keyboard next to each other, like ``ASDF``). -Complexity flags can be added together to get desired restrictions. For example, to +Complexity flags can be combined to get the desired restrictions. For example, to force passwords to contain uppercase and lowercase letters, ``PasswordComplexity`` variable must be set to ``6`` (``2 + 4``). -Changes to these configuration variables becomes effective immediately and does -not require |product_name| server restart. +Changes to these configuration variables become effective immediately and do +not require an |product_name| server restart. RADIUS ------ -If :guilabel:`RADIUS` authentication method selected password provided by user -sent to RADIUS server for validation. User is granted access if RADIUS server +If :guilabel:`RADIUS` authentication method is selected, the password provided by the user +is sent to a RADIUS server for validation. The user is granted access if the RADIUS server responds with ``Access-Accept``. Communication between |product_name| server and RADIUS -server controlled by the following server configuration variables: +server is controlled by the following server configuration variables: .. list-table:: :header-rows: 1 @@ -305,8 +305,8 @@ server controlled by the following server configuration variables: - Timeout in seconds for requests to RADIUS server - 3 -Changes to these configuration variables becomes effective immediately and does -not require |product_name| server restart. +Changes to these configuration variables become effective immediately and do +not require an |product_name| server restart. Certificate Authentication @@ -315,37 +315,37 @@ Certificate Authentication This type of authentication can be selected manually in user preferences. -Login process using certificate is following: +Login process using a certificate works as follows: -1. Server send random challenge to client -2. Client sign server's challenge with his certificate's private key and send signed challenge along with public part of certificate to server -3. Server validates certificate using CA certificate -4. If certificate is valid, server validates challenge signature using certificate's public key -5. If signature is valid, server compares certificate subject with mapping data from user record -6. If mapping data match with certificate subject, access is granted +1. The server sends a random challenge to the client +2. The client signs the servers challenge with their certificates' private key and send a signed challenge along with the public part of their certificate to the server +3. The server validates the certificate using its CA certificate +4. If the certificate is valid, the server validates the challenge signature using the certificates' public key +5. If the signature is valid, the server compares the certificate subject with mapping data from the user record +6. If the mapping data matches with the certificate subject, access is granted -So, to login successfully, user must posses valid certificate with private key. +So, to login successfully, the user must posses a valid certificate with a private key. Authentication by certificate also allows smart card login - you just need to store -certificate used for login on smart card instead of local certificate store. +the certificate used for login on a smart card instead of in a local certificate store. Certificate management ~~~~~~~~~~~~~~~~~~~~~~ -CA certificates are searched in the list configured by "TrustedCertificate" configuration parameter in server configuration file. +CA certificates are looked up in the list configured by the "TrustedCertificate" configuration parameter in the server configuration file. Link certificate and user ~~~~~~~~~~~~~~~~~~~~~~~~~ -In "User Manager" view select user properties for required user. -Then go to "Authentication" part. +In the "User Manager" view select the user properties for the required user. +Then go to the "Authentication" section. .. figure:: _images/user_prop_auth.png -In "Authentication Method" section: "Certificate", "Certificate or Password", +In the "Authentication Method" section: "Certificate", "Certificate or Password", "Certificate or RADIUS". | -Next two fields in combinations: +The next two fields in combination: Certificate mapping method: "Subject" @@ -361,35 +361,35 @@ Next two fields in combinations: Certificate mapping method: "Common name" - Certificate mapping data: if no mapping data set, then linking certificate CN = user name, otherwise CN = mapping data + Certificate mapping data: if no mapping data is set, then the linking certificate CN = user name, otherwise CN = mapping data CAS authentication ------------------ -Central Authentication Service (CAS) single sign-on is supported in web +Central Authentication Service (CAS) single sign-on is supported in the web interface only. The following server configuration parameters control CAS operation: CAS.AllowedProxies, CAS.Host, CAS.Port, CAS.Service, CAS.TrustedCACert, CAS.ValidateURL. See :ref:`server_configuration_parameters` -for the expanation of mentioned parameter meaning. +for the expanation of the meaning of the mentioned parameters. -Changes to these configuration variables becomes effective immediately and does -not require |product_name| server restart. +Changes to these configuration variables become effective immediately and do +not require a |product_name| server restart. Two-factor authentication ------------------------- -In addition to above authentication methods, two-factor authentication using +In addition to the above authentication methods, two-factor authentication using `TOTP `_ -or via notification channel can be set up. +or via a notification channel can be set up. TOTP configuration is done in two places - in system-wide :guilabel:`Two-factor authentication methods` and in properties of specific users. -First of all it's necessary to configure a method in :guilabel:`Two-factor -authentication methods`. For TOTP select driver name :guilabel:`TOTP`, no driver -configuration is necessary. For notification channel select driver name +First of all it is necessary to configure a method in :guilabel:`Two-factor +authentication methods`. For TOTP, select the driver name :guilabel:`TOTP`. No driver +configuration is necessary. For using a notification channel, select the driver name :guilabel:`Message` and in driver configuration the name of notification channel should be specified, e.g.: @@ -398,24 +398,24 @@ should be specified, e.g.: ChannelName=NotificationChannelName -The second step is to add two-factor authentication method in properties of a +The second step is to add the two-factor authentication method in properties of a user. -For message method it's necessary to specify recipient for the message. This +For message method it is necessary to specify the recipient for the message. This concludes the configuration - on login the user will receive a message with numeric code. -For TOTP method no additional configuration is necessary. On the following login -user will be presented with a dialog containing qr code and secret as text. -After entering the secret into TOTP application in will generate numeric code +For the TOTP method no additional configuration is necessary. On the following login +the user will be presented with a dialog containing a qr code and a secret as text. +After entering the secret into the users TOTP application, it will generate a numeric code that should be entered to confirm TOTP initialization. -To repeat initialization it's possible to perform reset for TOTP method in user -properties. After that on next login of the user the dialog with qr code and +To repeat initialization it is possible to perform a reset for the TOTP method in the user +properties. After that, on next login of the user the dialog with qr code and secret will be presented again. -It is possible to specify several two-factor authentication methods, in this -case user will be presented a menu on login, allowing to choose which method to +It is possible to specify several two-factor authentication methods. In this +case the user will be presented with a menu on login, allowing to choose which method to use. @@ -424,7 +424,7 @@ use. Integration with LDAP ===================== -|product_name| can perform one-way synchronization of users and groups with external LDAP server. User list replica is refreshed automatically. +|product_name| can perform one-way synchronization of users and groups with an external LDAP server. The user list replica is refreshed automatically. Already existing |product_name| users or groups will not be modified during initial synchronization (e.g. user "admin" or group "Everyone"). @@ -444,8 +444,8 @@ Server parameters controlling LDAP synchronization: - Comma- or whitespace-separated list of URIs in a format `schema://host:port`. Supported schemas: `ldap://`, `ldaps://` (LDAP over TLS), `ldapi://` (LDAP over IPC), and `cldap://` (connectionless LDAP). - **Windows specific**\ : for server based on Windows system this - parameter should be set according to this rules: empty string(attempts + **Windows specific**\ : for servers based on Windows this + parameter should be set according to these rules: empty string attempts to find the "default" LDAP server), a domain name, or a space-separated list of host names or dotted strings that represent the IP address of hosts running an LDAP server to which to connect. Each host name in the @@ -468,34 +468,34 @@ Server parameters controlling LDAP synchronization: - The LdapSearchFilter is a string representation of the filter to apply in the search. - * - LdapUserDeleteAction ``*`` - - This parameter specifies what should be done while synchronization with deleted from LDAP user/group. 0 - if user should be just deleted from |product_name| DB. 1 - if it should be disabled. If it is chosen to disable user, then on LDAP sync user will be disabled and it's description will be change on "LDAP entry was deleted." Afterwards this user/group can be detached from LDAP and enabled if it is required or just deleted manually. + - This parameter specifies what should be done while synchronization with users deleted from the LDAP user/group. 0 - if user should be deleted from |product_name| DB. 1 - if the user should be disabled but kept in the database. If 1 is chosen, then on LDAP sync the user will be disabled and its description will be changed to "LDAP entry was deleted." Afterwards this user/group can be detached from LDAP and enabled or deleted manually. - 1 * - LdapUserMappingName ``*`` - - There should be specified name of attribute that's value will be used as a user's login name + - The name of the attribute which value will be used as a users' login name - * - LdapGroupMappingName ``*`` - - There should be specified name of attribute that's value will be used as a group's login name + - The name of the attribute which value will be used as a group's identifier - * - LdapMappingFullName - - There should be specified name of attribute that's value will be used as a user full name + - The name of the attribute which value will be used as the user full name - * - LdapMappingDescription - - There should be specified name of attribute that's value will be used as a user description + - The name of the attribute which value will be used as a user description - * - LdapGroupClass - - There is specified which object class represents group objects. If found entry will not be of a user ot group class, it will be just ignored. + - The object class which represents group objects. If the found entry is not of a user or group class, it will be simply ignored. - * - LdapUserClass ``*`` - - There is specified which object class represents user objects. If found entry will not be of a user ot group class, it will be just ignored. + - The object class that represents user objects. If the found entry is not of a user or group class, it will be simply ignored. - * - LdapGroupUniqueId - - Unique identifier for LDAP group object. By default LDAP groups are identified by DN. If in your configuration DN can be changed any time it is useful to choose other attribute as unique group identifier. + - Unique identifier for the LDAP group object. By default LDAP groups are identified by DN. If in your configuration the DN can be changed at any time it is useful to choose another attribute as a unique group identifier. - * - LdapUserUniqueId - - Unique identifier for LDAP user object. By default LDAP users are identified by DN. If in your configuration DN can be changed any time it is useful to choose other attribute as unique user identifier. + - Unique identifier for the LDAP user object. By default LDAP users are identified by DN. If in your configuration the DN can be changed at any time it is useful to choose another attribute as a unique user identifier. - * - LdapSyncInterval ``*`` - - This parameter is for setting synchronization interval in minutes between |product_name| server and LDAP server. If synchronization parameter is set to 0 - synchronization will not be done. + - This parameter is for setting a synchronization interval in minutes between the |product_name| server and the LDAP server. If the synchronization parameter is set to 0 the synchronization will not be done. - 0 * - LdapPageSize ``*`` - Limit of records that can be returned in one search page. @@ -503,25 +503,25 @@ Server parameters controlling LDAP synchronization: ``* Required fields`` -Synchronization also can be done manually with `ldapsync` or just `ldap` command in server debug console. +Synchronization also can be done manually with `ldapsync` or the `ldap` command in the server debug console. LDAP users/groups relationships with native |product_name| users/groups ----------------------------------------------------------------------- -LDAP users and groups are handled in exactly the same was as users from internal database. Only difference is that LDAP group membership is refreshed on each synchronisation and any non-LDAP user will be removed from the group. +LDAP users and groups are handled in exactly the same way as users from the internal database. The only difference is that for LDAP group membership is refreshed at each synchronisation and any non-LDAP user then will be removed from the group. Login with help of LDAP user ---------------------------- -Login process is completely transparent for the user - user name should match attribute set by `LdapMappingName` and password should be current LDAP password for that user. +The login process is completely transparent for the user - their user name should match the attribute set by `LdapMappingName` and their password should be the current LDAP password for that user. LDAP configuration debugging ---------------------------- -If users are not synchronized the reason can be found by running manually `ldapsync` or just `ldap` -command in server debug console on debug lever 4. +If users are not synchronized, the reason can be found by running `ldapsync` manually or by the `ldap` +command in the server debug console on debug lever 4. Log when LDAP sync passed correctly: @@ -551,7 +551,7 @@ Login credentials incorrect: [11-Sep-2014 15:49:39.896] [DEBUG] LDAPConnection::loginLDAP(): LDAP could not login. Error code: Invalid credentials [11-Sep-2014 15:49:39.896] [DEBUG] LDAPConnection::syncUsers(): Could not login. -Search base is set incorrectly or sync user does not have access to it: +Search base is set incorrectly or sync user does not have access: :: @@ -599,8 +599,8 @@ Active Directory * - LdapSyncInterval - 1440 -Open LDAP -~~~~~~~~~ +OpenLDAP +~~~~~~~~ .. list-table:: :header-rows: 1 @@ -640,26 +640,26 @@ Open LDAP Managing User Accounts ====================== -All |product_name| user accounts can be managed from :guilabel:`User Manager` +All |product_name| user accounts can be managed from the :guilabel:`User Manager` view available at :menuselection:`Configuration --> User Manager` in |product_name| Management Client. Only users with granted system right :guilabel:`Manage users` can access :guilabel:`User Manager`. -- To create new user account, select :guilabel:`Create new user` from view menu or context menu. -- To create new group, select :guilabel:`Create new group` from view menu or context menu. +- To create a new user account, select :guilabel:`Create new user` from the view menu or context menu. +- To create a new group, select :guilabel:`Create new group` from the view menu or context menu. - To delete user account, select it in the list, right-click, and select :guilabel:`Delete` from pop-up menu. You can delete multiple accounts at a time. -- To modify properties of user or group, select it in the list, right-click, and select :guilabel:`Properties` from pop-up menu. -- To reset user's password, select user account in the list, right-click, and select :guilabel:`Change password` from pop-up menu. +- To modify properties of a user or group, select it in the list, right-click, and select :guilabel:`Properties` from the pop-up menu. +- To reset the password of a user, select the user account in the list, right-click, and select :guilabel:`Change password` from the pop-up menu. Audit ===== -All important user actions are written to audit log. There are two audit -logging modes - internal and external. Internal audit logging is on by default -and writes audit records into table in |product_name| database. External audit logging -allows sending audit records to external system via syslog protocol. External -audit logging is off by default. Audit logging controlled by the following +All important user actions are written to the audit log. There are two audit +logging modes: internal and external. Internal audit logging is on by default +and writes audit records into a table in the |product_name| database. External audit logging +allows sending audit records to an external system via the syslog protocol. External +audit logging is off by default. Audit logging is controlled by the following server configuration variables: .. list-table:: @@ -670,8 +670,8 @@ server configuration variables: - Description - Default value * - AuditLogRetentionTime - - Retention time in days for the records in internal audit log. All - records older than specified will be deleted by housekeeping process. + - Retention time in days for the records in the internal audit log. All + records older than specified will be deleted by the housekeeping process. - 90 * - EnableAuditLog - Enable (``1``) or disable (``0``) audit logging. @@ -680,15 +680,15 @@ server configuration variables: - Syslog facility to be used in audit log records sent to external server. - 13 * - ExternalAuditPort - - UDP port of external syslog server to send audit records to. + - UDP port of the external syslog server to send audit records to. - 514 * - ExternalAuditServer - External syslog server to send audit records to. If set to none, external audit logging is disabled. - none * - ExternalAuditSeverity - - Syslog severity to be used in audit log records sent to external server. + - Syslog severity to be used in audit log records sent to the external server. - 5 * - ExternalAuditTag - - Syslog tag to be used in audit log records sent to external server. + - Syslog tag to be used in audit log records sent to the external server. - netxmsd-audit