Using the "authz-doctor" tool to identify vCenter permission issues

Products

• VMware vCenter Server

Issue/Introduction

Environment has configuration issues, related to global and/or inventory permissions in the vCenter Server. The "authz-doctor" tool was implemented to identify such misconfigurations

The purpose of this article is to provide information on the use of the 'authz-doctor' tool to identify permission configuration issues within the vCenter environment.

Environment

VMware vCenter Server 7.x

VMware vCenter Server 8.x 

Resolution

The Authz Doctor

The authz-doctor aims to aid in resolving common authorization issues when interacting with a VCSA.

 

Installation

1. Check if the authz-doctor is not already preinstalled on the VCSA instance:

   /usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py help

2. Download and install the authz-doctor, if not already present:

   authz-doctor RPM installation

   # Download the authz-doctor RPM to the VCSA instance # Execute (on the VCSA instance): rpm -i --force authz-doctor-<version>.rpm

 

Using the authz-doctor

The executable is located at /usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py 

Usage: authz-doctor.py CMD ARGS CMD in ['vsr_compare', 'permission_check', 'solution_users', 'all']

Executing the default behavior of a single command can be done by invoking:

authz-doctor.py CMD

where CMD is one of the commands listed in the usage info.

Command specific help can be retrieved by invoking

authz-doctor.py CMD --help

where CMD is one of the commands listed in the usage info. For example:

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py permission_check --help usage: permission_check [-h] [-u USER] [-e ENTITY] [-f FILENAME]   options:   -h, --help            show this help message and exit   -u USER, --user USER  User to perform the checks for   -e ENTITY, --entity ENTITY                         Entity with missing privileges   -f FILENAME, --filename FILENAME                         Path to a custom authz-data.json file

 

If all is specified instead of CMD, e.g. authz-doctor.py all, then all of the commands are run in series, using their default behavior.

Additional arguments can be specified also when executing all commands, e.g.

authz-doctor.py all --entity 'domain-c8'

In that case, the additional arguments will be forwarded to each of the commands executed.

 

Use cases

The permission_check command

Default usage

The permission_check command is intended to help troubleshooting permissions problems. By default, the command can run without any arguments, but note that this would produce limited results, such as:

Default permission_check usage

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py permission_check authz-doctor version: 8.0.3.00000-00000 Argument --user is not provided. Results will be limited. Permission Check results: 1. Permissions list: +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+ | Principal                                                               | Group | Role Id   | Role Name                         | Propagate | Entity     | +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+ | VSPHERE.LOCAL\Administrator                                             | False | -1        | Admin                             | True      | group-d1   | | VSPHERE.LOCAL\Administrator                                             | False | -1        | Admin                             | True      | Global     | | VSPHERE.LOCAL\Administrators                                            | True  | 366991159 | vCLSAdmin                         | True      | group-v9   | | VSPHERE.LOCAL\Administrators                                            | True  | -1        | Admin                             | True      | Global     | | VSPHERE.LOCAL\AutoUpdate                                                | True  | 11        | AutoUpdateUser                    | True      | Global     | | VSPHERE.LOCAL\NsxAdministrators                                         | True  | 949063425 | NsxAdministrator                  | True      | Global     | | ...                                                                     | ...   | ...       | ...                               | ...       | ...        | +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+

 

Usage with parameters

If the --entity  and --user arguments are specified, the command can produce a more meaningful results, regarding the user and entity for which the problems are observed. For example:

Using permission_check with arguments

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py permission_check --user [email protected] --entity domain-c10 authz-doctor version: 8.0.3.00000-123321 Permission Check results: 1. List of VSPHERE.LOCAL\demouser's privileges on entity domain-c10: ['System.Anonymous', 'System.View', 'System.Read']   2. Permissions set on parent entities of domain-c10: +-------------------------+-------+---------+-----------+-----------+------------+ | Principal               | Group | Role Id | Role Name | Propagate | Entity     | +-------------------------+-------+---------+-----------+-----------+------------+ | VSPHERE.LOCAL\demogroup | True  | -2      | ReadOnly  | True      | Global     | | VSPHERE.LOCAL\demouser  | False | -1      | Admin     | False     | Global     | | VSPHERE.LOCAL\demouser  | False | -2      | ReadOnly  | True      | domain-c10 | | VSPHERE.LOCAL\demouser  | False | -1      | Admin     | False     | group-d1   | +-------------------------+-------+---------+-----------+-----------+------------+   3. Inherited permissions for domain-c10: +-------------------------+-------+---------+-----------+-----------+------------+ | Principal               | Group | Role Id | Role Name | Propagate | Entity     | +-------------------------+-------+---------+-----------+-----------+------------+ | VSPHERE.LOCAL\demogroup | True  | -2      | ReadOnly  | True      | group-d1   | | VSPHERE.LOCAL\demouser  | False | -2      | ReadOnly  | True      | domain-c10 | +-------------------------+-------+---------+-----------+-----------+------------+ 4. Permissions list: +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+ | Principal                                                               | Group | Role Id   | Role Name                         | Propagate | Entity     | +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+ | VSPHERE.LOCAL\Administrator                                             | False | -1        | Admin                             | True      | group-d1   | | VSPHERE.LOCAL\Administrator                                             | False | -1        | Admin                             | True      | Global     | | VSPHERE.LOCAL\Administrators                                            | True  | 366991159 | vCLSAdmin                         | True      | group-v9   | | ...                                                                     | ...   | ...       | ...                               | ...       | ...        | | VSPHERE.LOCAL\vsphere-ui-3188fcea-0158-4839-a24f-92553db0470d           | False | 1003      | vSphere Client Solution User      | True      | Global     | | VSPHERE.LOCAL\vsphere-webclient-3188fcea-0158-4839-a24f-92553db0470d    | False | 1003      | vSphere Client Solution User      | True      | Global     | +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+   Warnings: -------------------------------------------------------------------------------------------------------------------------- 1. Found non-propagating root folder and/or global permissions for user VSPHERE.LOCAL\demouser and/or their parent groups +------------------------+-------+---------+-----------+-----------+----------+ | Principal              | Group | Role Id | Role Name | Propagate | Entity   | +------------------------+-------+---------+-----------+-----------+----------+ | VSPHERE.LOCAL\demouser | False | -1      | Admin     | False     | Global   | | VSPHERE.LOCAL\demouser | False | -1      | Admin     | False     | group-d1 | +------------------------+-------+---------+-----------+-----------+----------+ It is a common user error to define a non-propagating global/toplevel permission when they need privileges on an inventory object. Such permissions are not propagated to the vCenter inventory objects and therefore do not add any privileges to the user on those entities.

 

The solution_users command

The solution_users command checks for inconsistencies in the group membership of vpxd-* solution users and provides the ability to remediate such issues.

 

Checking solution users' group membership 

Checking solution users' group membership

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py solution_users # --check is the default behavior authz-doctor version: 8.0.3.00000-123321 Following users are direct or indirect members of Administrators group and should be fixed vpxd-3188fcea-0158-4839-a24f-92553db0470d: Administrators

 

Fixing solution users group membership

Fixing solution users' group membership

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py solution_users --action fix authz-doctor version: 8.0.3.00000-123321 -- Checking direct members of Administrators group... Removing direct members of Administrators group Fix Administrators group: True -- Checking indirect members of Administrators group... -- Checking vpxd-extension-XXXX user vpxd-extension-XXXX user is OK -- Result: Group membership changed, please restart VCSA services. E.g: # service-control --stop --all # service-control --start --all

 

The authz_manager command

The authz_manager command allows for command line usage of the Get/List APIs of the vCenter's AuthorizationManager. Refer to the following examples:

RetrieveAllPermissions

RetrieveAllPermissions

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py authz_manager --method RetrieveAllPermissions authz-doctor version: 8.0.3.00000-123321 Please enter password for user [email protected]: +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+ | Principal                                                               | Group | Role Id   | Role Name                         | Propagate | Entity     | +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+ | VSPHERE.LOCAL\Administrator                                             | False | -1        | Admin                             | True      | group-d1   | | VSPHERE.LOCAL\Administrator                                             | False | -1        | Admin                             | True      | group-d1   | | VSPHERE.LOCAL\Administrators                                            | True  | -1        | Admin                             | True      | group-d1   | | ...                                                                     | ...   | ...       | ...                               | ...       | ...        | | VSPHERE.LOCAL\Administrators                                            | True  | 366991159 | vCLSAdmin                         | True      | group-v9   | +-------------------------------------------------------------------------+-------+-----------+-----------------------------------+-----------+------------+

 

FetchUserPrivilegeOnEntities

FetchUserPrivilegeOnEntities

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py authz_manager \     --method FetchUserPrivilegeOnEntities \     --user [email protected] \     --entities group-d1 authz-doctor version: 8.0.3.00000-00000 Please enter password for user [email protected]: (vim.AuthorizationManager.UserPrivilegeResult) [    (vim.AuthorizationManager.UserPrivilegeResult) {       dynamicType = <unset>,       dynamicProperty = (vmodl.DynamicProperty) [],       entity = 'vim.Folder:group-d1',       privileges = (str) [          'System.Anonymous',          'System.View',          'System.Read'       ],       fault = <unset>    } ]

 

The vsr_compare command

The vsr_compare command is used to compare the group membership of all solution users and service accounts to the predefined system configuration and detect drifts.

vsr_compare command

/usr/lib/vmware-vpx/scripts/authz-doctor/authz-doctor.py vsr_compare authz-doctor version: 8.0.3.00000-00000 +------------------------+---------------------------------------------+------------------------------------+--+---------------------------------------------+----------------------+-----------------------------------+ | Solution user          | Current state                               | Desired state                      |  | Extra groups                                | Missing groups       | Status                            | +------------------------+---------------------------------------------+------------------------------------+--+---------------------------------------------+----------------------+-----------------------------------+ | autodeploy             |                                             | CAAdmins                           |  |                                             | CAAdmins             | Solution user missing             | |                        |                                             | ServiceProviderUsers               |  |                                             | ServiceProviderUsers |                                   | +------------------------+---------------------------------------------+------------------------------------+--+---------------------------------------------+----------------------+-----------------------------------+ | certificateauthority   | ActAsUsers                                  |                                    |  | ActAsUsers                                  |                      | Group membership drift            | |                        | Everyone                                    |                                    |  | Everyone                                    |                      |                                   | |                        | SolutionUsers                               |                                    |  | SolutionUsers                               |                      |                                   | +------------------------+---------------------------------------------+------------------------------------+--+---------------------------------------------+----------------------+-----------------------------------+ | cms                    | ActAsUsers                                  | CAAdmins                           |  | ActAsUsers                                  |                      | Group membership drift            | |                        | CAAdmins                                    | ServiceProviderUsers               |  | Everyone                                    |                      |                                   | |                        | Everyone                                    |                                    |  | SolutionUsers                               |                      |                                   | |                        | ServiceProviderUsers                        |                                    |  |                                             |                      |                                   | |                        | SolutionUsers                               |                                    |  |                                             |                      |                                   | +------------------------+---------------------------------------------+------------------------------------+--+---------------------------------------------+----------------------+-----------------------------------+ ...