NAME
Get
-QADUser
SYNOPSIS
Retrieve all users in a domain or container that match the specified conditions. Supported are both Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS).
This cmdlet is part of the Quest ActiveRoles Server product. Use
-QARSProductInfo to view information about ActiveRoles Server.
SYNTAX
-QADUser [[-Identity] <IdentityParameter>] [-AccountExpiresAfter <DateTime>] [-AccountExpiresBefore <DateTime>] [-AccountNeverExpires] [-Activity <string>] [-Anr <string>] [-AttributeScopeQuery <string>] [-City <string[]>] [-Company <string[]>] [-Connection <ArsConnection>]
[-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-Control <hashtable>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-CreatedOn <DateTime>] [-Credential <PSCredential>] [-Department <string[]>] [-Description <string[]>] [-Disabled] [-DisplayName <string[]>]
[-DontConvertValuesToFriendlyRepresentation] [-DontUseDefaultIncludedProperties] [-Email <string[]>] [-Enabled] [-ExcludedProperties <string[]>] [-ExpiredFor <int>] [-Fax <string[]>] [-FirstName <string[]>] [-HomeDirectory <string[]>] [-HomeDrive <string[]>] [-HomePhone <string[]>] [-Inactive]
[-InactiveFor <int>] [-IncludeAllProperties] [-IncludedProperties <string[]>] [-IndirectMemberOf <IdentityParameter[]>] [-Initials <string[]>] [-LastChangedAfter <DateTime>] [-LastChangedBefore <DateTime>] [-LastChangedOn <DateTime>] [-LastKnownParent <IdentityParameter>] [-LastName
<string[]>] [-LdapFilter <string>] [-Locked] [-LogonScript <string[]>] [-Manager <IdentityParameter>] [-MemberOf <IdentityParameter[]>] [-MobilePhone <string[]>] [-Name <string[]>] [-Notes <string[]>] [-NotIndirectMemberOf <IdentityParameter[]>] [-NotLoggedOnFor <int>] [-NotMemberOf
<IdentityParameter[]>] [-Office <string[]>] [-Pager <string[]>] [-PageSize <int>] [-PasswordNeverExpires] [-PasswordNotChangedFor <int>] [-PhoneNumber <string[]>] [-PostalCode <string[]>] [-PostOfficeBox <string[]>] [-PrimaryProxyAddress <string[]>] [-ProfilePath <string[]>]
[-ProgressThreshold <int>] [-Proxy] [-ProxyAddress <string[]>] [-Recycled] [-ReturnPropertyNamesOnly] [-SamAccountName <string[]>] [-SearchAttributes <
Object
>] [-SearchRoot <IdentityParameter[]>] [-SearchScope {Base | OneLevel | Subtree}] [-SecondaryProxyAddress <string[]>] [-SecurityMask
{None | Owner | Group | Dacl | Sacl}] [-SerializeValues] [-Service <string>] [-ShowProgress] [-SizeLimit <int>] [-StateOrProvince <string[]>] [-StreetAddress <string[]>] [-Title <string[]>] [-Tombstone] [-UseDefaultExcludedProperties <
Boolean
>] [-UseDefaultExcludedPropertiesExcept <string[]>]
[-UseGlobalCatalog] [-UserPrincipalName <string[]>] [-WebPage <string[]>] [-WildcardMode <WildcardMode>] [<CommonParameters>]
DESCRIPTION
Use this cmdlet to search an Active Directory domain or container for user accounts that meet certain search criteria, or to bind to a certain user account by DN, SID, GUID, UPN or Domain\UserName. You can search by user attributes or specify your search criteria by using an LDAP search filter.
The output of the cmdlet is a collection of objects, with each object representing one of the user accounts found by the cmdlet. You can pipe the output into another cmdlet, such as
Set
-QADUser, to make changes to the user accounts returned by this cmdlet.
The cmdlet takes a series of optional, attribute-specific parameters allowing you to search by user attributes. The attribute-specific parameters have effect if SearchRoot is specified whereas Identity is not.
If
you specify SearchRoot only, then the cmdlet returns all users found in the
SearchRoot container.
You can use attribute-specific parameters to search for user accounts that have specific values of certain attributes. Thus, to find all user accounts that have the givenName attribute set to Martin, you may add the following on the command line:
"-FirstName Martin"
.
To
search for user
accounts that have a certain attribute not set specify
'' (empty string) as the parameter value.
a given attribute is referred to by both the ObjectAttributes array and an attribute-specific parameter, the ObjectAttributes setting has no effect on that attribute. The cmdlet searches for the attribute value specified by the attribute-specific parameter.
With
more than one attribute-specific parameter supplied, the search conditions are combined by using the AND operator, so as to find the user accounts that meet all the specified conditions. Thus, if you supply both the -FirstName and -LastName parameters, the cmdlet searches for the user
accounts that have the givenName attribute set to the FirstName parameter value and the sn attribute set to the LastName parameter value.
Each
of the attribute-specific parameters accepts the * wildcard character in the parameter value to match zero or more characters (case-insensitive).
For
instance, a* matches A, ag, Amsterdam, and does not match
New
York.
The cmdlet has optional parameters that determine the server and the security context for the operation. Normally, the connection parameters could be omitted so far as a connection to a server is established prior to using the cmdlet.
In
this case, the server and the security context are
determined by the Connect-QADService cmdlet.
you do not use Connect-QADService and have no connection established prior to using a cmdlet, then the connection settings, including the server and the security context, are determined by the connection parameters of the first cmdlet you use. Subsequent cmdlets will use those settings by
default.
PARAMETERS
-AccountExpiresAfter <DateTime>
Retrieve user accounts that are configured to expire after a certain date. Parameter value is a DateTime object that specifies the date you want.
Required? false
Position? named
Default
value
Accept pipeline input? false
Accept wildcard characters? false
-AccountExpiresBefore <DateTime>
Retrieve user accounts that are configured to expire before a certain date. Parameter value is a DateTime object that specifies the date you want.
-AccountNeverExpires [<SwitchParameter>]
the value of this parameter to
'true' if you want the cmdlet to retrieve only those user accounts that are configured to never expire.
-Activity <string>
Use this parameter to specify the line of text above the progress bar which the cmdlet displays to depict the status of the running command in case of a lengthy operation. This text describes the activity whose progress is being reported (see also ShowProgress and ProgressThreshold).
this parameter is omitted, the name of the cmdlet is displayed above the progress bar.
-Anr <string>
Specify a value to be resolved using ambiguous name resolution (ANR). Which attributes are included in an ANR search depends upon the Active Directory schema. Thus, in Windows Server 2003 based Active Directory, the following attributes are set for ANR by default:
Display-Name (displayName)
Given-Name (givenName)
Legacy-Exchange-DN (legacyExchangeDN)
ms-DS-Additional-Sam-Account-Name (msDS-AdditionalSamAccountName)
Physical-Delivery-Office-Name (physicalDeliveryOfficeName)
Proxy-Addresses (proxyAddresses)
RDN (name)
SAM-Account-Name (sAMAccountName)
Surname (sn)
instance, when you supply
'ann*' as the value of this parameter, the cmdlet searches for objects that have ann at the beginning of the value of at least one of the attributes listed above.
-AttributeScopeQuery <string>
Specify the LDAP display name of an attribute that has DN syntax (for example,
'memberOf'). The cmdlet enumerates the distinguished name values of the attribute on the object specified by the SearchRoot parameter, and performs the search on the objects represented by the distinguished
names. The SearchScope parameter has no effect in this case. The object to search must be specified by using the SearchRoot parameter rather than the Identity parameter.
instance, with the value of this parameter set to
'memberOf', the cmdlet searches the collection of the groups to which the SearchRoot object belongs.
-City <string[]>
Search by the
'l' attribute.
-Company <string[]>
'company' attribute.
-Connection <ArsConnection>
parameter description, see help on the Connect-QADService cmdlet.
-ConnectionAccount <string>
-ConnectionPassword <SecureString>
-Control <hashtable>
Use this parameter to pass request controls (in-controls) to ActiveRoles Server as part of an operation request.
ActiveRoles Server, request controls are used to send extra information along with an operation request, to control how ActiveRoles Server performs the request.
The parameter value is a hash table that defines the names and values of the request controls to be passed to ActiveRoles Server. The parameter syntax is as follows:
-Control @{<name> = <value>; [<name> = <value>] ...}
this syntax, each of the name-value pairs is the name and the value of a single control.
instructions on how to create and use hash tables, see topic
"about_associative_array"
or
"about_hash_tables"
in Windows PowerShell Help.
information about ActiveRoles Server request
controls, refer to ActiveRoles Server SDK documentation.
Note that this parameter only has an effect on the operations that are performed through ActiveRoles Server (connection established using the Proxy parameter); otherwise, this parameter causes an error condition in ActiveRoles Management Shell.
-CreatedAfter <DateTime>
Specify the lower boundary of the object creation date and time by which to filter objects found. The cmdlet returns only the objects that were created after the date and time specified. Supplying both CreatedAfter and CreatedBefore bounds a time interval for the objects
' creation. If you
supply only CreatedAfter, there is no upper boundary on the date. Parameter value is a DateTime object that specifies the date and time you want.
-CreatedBefore <DateTime>
Specify the upper boundary of the object creation date and time by which to filter objects found. The cmdlet returns only the objects that were created before the date and time specified. Supplying both CreatedAfter and CreatedBefore bounds a time interval for the objects
supply only CreatedBefore, there is no lower boundary on the date. Parameter value is a DateTime object that specifies the date and time you want.
-CreatedOn <DateTime>
Specify the object creation date by which to filter objects found, searching for objects created within the date specified. This parameter is mutually exclusive with the CreatedAfter and CreatedBefore parameters. Parameter value is a DateTime object that specifies the date you want.
-Credential <PSCredential>
-Department <string[]>
'department' attribute.
-Description <string[]>
'description' attribute.
-Disabled [<SwitchParameter>]
Supply this parameter on the command line if you want the search results produced by this cmdlet to include only those user accounts that are disabled.
-DisplayName <string[]>
'displayName' attribute.
-DontConvertValuesToFriendlyRepresentation [<SwitchParameter>]
This parameter causes the cmdlet to represent the Integer8 and OctetString attribute values
"as is,"
without converting them to a user-friendly, human-readable form.
this parameter is omitted, the cmdlet performs the following data conversions:
- The values of the Integer8 attributes listed in the
Integer8AttributesThatContainDateTimes array
(see the parameter descriptions for the
-QADPSSnapinSettings and
-QADPSSnapinSettings
cmdlets) are converted from IADsLargeInteger to DateTime
Integer8AttributesThatContainNegativeTimeSpans array
cmdlets) are converted from IADsLargeInteger to TimeSpan
- The values of the other Integer8 attributes are
converted from IADsLargeInteger to Int64
- The values of the OctetString attributes are converted
from byte[] to BinHex strings
Note: This parameter has an effect only on the properties of the output object that have the member type of NoteProperty. Such properties are normally added to the output object in order to provide access to the attribute values of the respective directory object that are loaded to the
local memory cache but cannot be accessed by using properties of the base object (the object for which the output object serves as a wrapper).
-DontUseDefaultIncludedProperties [<SwitchParameter>]
This parameter causes the cmdlet to load only a small set of attributes from the directory to the local memory cache (normally, this set is limited to objectClass and ADsPath). Other attributes are retrieved from the directory as needed when you use the cmdlet
's output objects to read
attribute values. Thus, if you want only to count the objects that meet certain conditions (rather than examine values of particular attributes), then you can use this parameter to increase performance of your search.
examples of how to use this parameter, see help on the
cmdlet.
Note:
a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.
-Email <string[]>
'mail' attribute.
-Enabled [<SwitchParameter>]
Supply this parameter on the command line if you want the search results produced by this cmdlet to include only those user accounts that are enabled (not disabled).
-ExcludedProperties <string[]>
Use this parameter to specify the attributes that you do not want the cmdlet to retrieve from the directory and store in the memory cache on the local computer. Supply a list of the attribute LDAP display names as the parameter value. By default, the cmdlet caches a certain pre-defined set
of attributes, which you can view or modify by using the
-QADPSSnapinSettings or
-QADPSSnapinSettings cmdlet, respectively. Using the ExcludedProperties parameter you can change this default behavior on an ad-hoc basis, in order to prevent certain attributes from being loaded.
Another scenario involves the use of this parameter in conjunction with IncludeAllProperties in order to restrict the set of the cached attributes.
-ExpiredFor <int>
Use this parameter to retrieve accounts that remain in the expired state for at least the number of days specified by the parameter value. This parameter overrides the expiry-related inactivity condition of the Inactive or InactiveFor parameter. Thus, if the ExpiredFor value of 0 is
supplied in conjunction with the InactiveFor value of 30, the cmdlet searches for accounts that are currently expired, or have the password age of 30 or more days, or have not been used to log on for 30 or more days.
-Fax <string[]>
'facsimileTelephoneNumber' attribute.
-FirstName <string[]>
'givenName' attribute.
-HomeDirectory <string[]>
'homeDirectory' attribute.
-HomeDrive <string[]>
'homeDrive' attribute.
-HomePhone <string[]>
'homePhone' attribute.
-Identity <IdentityParameter>
Specify the DN, SID, GUID, UPN or Domain\UserName of the user account you want to find.
The cmdlet attempts to find the user that is identified by the value of this parameter, disregarding the other parameters.
you want other parameters to have effect, do not supply any value of this parameter on the command line.
Position? 1
Accept pipeline input? true (ByValue, ByPropertyName)
-Inactive [<SwitchParameter>]
Supply this parameter to retrieve user accounts that meet the default inactivity conditions. You can view or change the default inactivity conditions by using the
-QADInactiveAccountsPolicy or
-QADInactiveAccountsPolicy cmdlet, respectively.
When
considering whether an account is
inactive, the cmdlet verifies each of these values:
- The number of days that the account remains in the expired state
- The number of days that the password of the account remains unchanged
- The number of days that the account remains unused for logon
any of these values exceeds a certain, default limit, then the account is considered inactive, and thus is retrieved by the Inactive parameter. The default limits can be overridden by supplying other account-inactivity related parameters, such as InactiveFor, ExpiredFor, NotLoggedOnFor,
and PasswordNotChangedFor. Thus, if the NotLoggedOnFor value of 60 is supplied in conjunction with the Inactive parameter, the cmdlet searches for accounts that meet the default expiry-related or password-related inactivity condition, or have not been used to log on for 60 or more days.
retrieve only those accounts that are not inactive, use the following syntax: -Inactive:$false
-InactiveFor <int>
Use this parameter to retrieve user accounts that meet any of the following conditions:
- The account remains in the expired state for at least the number of days specified by the parameter value
- The account does not have its password changed for at least the number of days specified by the parameter value
- The account has not been used to log on for at least the number of days specified by the parameter value
example, the parameter value of 30 causes the cmdlet to search for accounts that are expired for 30 or more days, or have the password age of 30 or more days, or have not been used to log on for 30 or more days.
The value of this parameter overrides the default inactivity conditions, so the Inactive parameter has no effect when used together with this parameter. Similarly, the other account-inactivity related parameters such as ExpiredFor, NotLoggedOnFor and PasswordNotChangedFor override the
corresponding conditions of this parameter. Thus, if the NotLoggedOnFor value of 60 is supplied in conjunction with the InactiveFor value of 30, the cmdlet searches for accounts that are expired for 30 or more days, or have the password age of 30 or more days, or have not been used to log
on for 60 or more days.
-IncludeAllProperties [<SwitchParameter>]
this parameter, the cmdlet retrieves all attributes of the respective directory object (such as a User object), and stores the attribute values in the memory cache on the local computer. Attribute values can be read from the memory cache by using properties of the object returned by
the cmdlet. Thus, when used in conjunction with the SerializeValues parameter, it allows an entire object to be exported from the directory to a text file.
-QADUser or
-QADObject cmdlet.
-IncludedProperties <string[]>
Use this parameter to specify the attributes that you want the cmdlet to retrieve from the directory and store in the memory cache on the local computer. Supply a list of the attribute LDAP display names as the parameter value. By default, the cmdlet caches a certain pre-defined set of
attributes, which you can view or modify by using the
-QADPSSnapinSettings cmdlet, respectively. Using the IncludedProperty parameter you can direct the cmdlet to cache some attributes in addition to the default set.
Note: Caching an attribute guarantees that the value of the attribute can be read by using properties of the output object returned by the cmdlet.
-IndirectMemberOf <IdentityParameter[]>
Retrieve objects that belong to the group or groups specified by this parameter, whether directly or because of group nesting. The cmdlet returns an object if the object has direct or indirect membership in the group specified by this parameter value.
-Initials <string[]>
'initials' attribute.
-LastChangedAfter <DateTime>
Specify the lower boundary of the object modification date and time by which to filter objects found. The cmdlet returns only the objects that have last changed after the date and time specified. Supplying both LastChangedAfter and LastChangedBefore bounds a time interval for the objects
'
last change.
you supply only LastChangedAfter, there is no upper boundary on the date. Parameter value is a DateTime object