User Directory Retrieve User Groups

User Directory Retrieve User Groups

Returns a list of UserSearchResult objects describing the users and groups defined for the server.

  • On Windows, the search for users and groups is restricted to the given domain. If you omit the domain argument, then the search is performed on local users and groups.
  • On ESX Server (or Linux systems), the method returns the list of users and groups that are specified in the /etc/passwd file. If the password file contains Sun NIS or NIS+ users and groups, the returned list includes information about those as well.

You must hold the Authorization.ModifyPermissions privilege to invoke this method. If you hold the privilege on any ManagedEntity, you will have access to user and group information for the server.

As of vSphere API 5.1:

  • Local user groups on ESXi are not supported and this method will not return information about local groups on the ESXi host. Information about Active Directory groups is not affected.
  • Some special system users on ESXi like 'nfsnobody' and 'daemon' will be filtered out by this method.
Request
URI
POST
https://{vcenter-host}/sdk/vim25/{release}/UserDirectory/{moId}/RetrieveUserGroups
COPY
Path Parameters
string
moId
Required

The unique identifier for the managed object to which the method attaches; the serialized managed object reference for a request has the form moType/moId, in this case UserDirectory/{moId}.

string
release
Required

The vSphere release schema. The current specification covers vSphere 8.0.2.0 APIs.


Request Body
RetrieveUserGroupsRequestType of type(s) application/json
Required
{
    "domain": "string",
    "searchStr": "string",
    "belongsToGroup": "string",
    "belongsToUser": "string",
    "exactMatch": false,
    "findUsers": false,
    "findGroups": false
}
string
domain
Optional

Domain to be searched. If not set, then the method searches the local machine.

string
searchStr
Required

Case insensitive substring used to filter results; the search string is compared to the login and full name for users, and the name and description for groups. Leave this blank to match all users.

string
belongsToGroup
Optional

If present, the returned list contains only users or groups that directly belong to the specified group. Users or groups that have indirect membership will not be included in the list.

string
belongsToUser
Optional

If present, the returned list contains only groups that directly contain the specified user. Groups that indirectly contain the user will not be included in the list.

boolean
exactMatch
Required

Indicates the searchStr passed should match a user or group name exactly.

boolean
findUsers
Required

True, if users should be included in the result.

boolean
findGroups
Required

True, if groups should be included in the result.

Authentication
This operation uses the following authentication methods.
Responses
200

OK

Returns Array of UserSearchResult of type(s) application/json
[
    {
        "_typeName": "string",
        "principal": "string",
        "fullName": "string",
        "group": false
    }
]

500

NotSupported: If you specify a domain for systems that do not support domains, such as an ESX Server. The method also throws NotSupported if you specify membership (belongsToGroup or belongsToUser) and the server does not support by-membership queries.

NotFound: If any of the domain, belongsToGroup, or belongsToUser arguments refer to entities that do not exist.

Returns NotFound of type(s) application/json
This response body class contains all of the following: VimFault
{
    "_typeName": "string",
    "faultCause": "MethodFault Object",
    "faultMessage": [
        {
            "_typeName": "string",
            "key": "string",
            "arg": [
                {
                    "_typeName": "string",
                    "key": "string",
                    "value": {
                        "_typeName": "string"
                    }
                }
            ],
            "message": "string"
        }
    ]
}