Come and Check our BETA Alpha version of Powershellcenter.net
Send me your comment to Powershell@powershellcenter.com

Synopsis

Modify attributes of a user account in Active Directory. 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 Get-QARSProductInfo to view information about ActiveRoles Server.

Syntax

Set-QADUser [-Identity] <IdentityParameter> [-AccountExpires <System.Nullable`1[System.DateTime]>] [-City <string>] [-Company <string>] [-Connection <ArsConnection>] [-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-Control <hashtable>] [-Credential <PSCredential>] [-Department <string>] [-Description <string>] [-DeserializeValues] [-DisplayName <string>] [-Email <string>] [-ExcludedProperties <string[]>] [-Fax <string>] [-FirstName <string>] [-HomeDirectory <string>] [-HomeDrive <string>] [-HomePhone <string>] [-IncludedProperties <string[]>] [-Initials <string>] [-LastName <string>] [-LogonScript <string>] [-Manager <IdentityParameter>] [-MobilePhone <string>] [-Notes <string>] [-ObjectAttributes <ObjectAttributesParameter>] [-Office <string>] [-Pager <string>] [-PasswordNeverExpires <Boolean>] [-PhoneNumber <string>] [-PostalCode <string>] [-PostOfficeBox <string>] [-ProfilePath <string>] [-Proxy] [-SamAccountName <string>] [-Service <string>] [-StateOrProvince <string>] [-StreetAddress <string>] [-Title <string>] [-TsAllowLogon <Boolean>] [-TsBrokenConnectionAction <int>] [-TsConnectClientDrives <Boolean>] [-TsConnectPrinterDrives <Boolean>] [-TsDefaultToMainPrinter <Boolean>] [-TsHomeDirectory <string>] [-TsHomeDrive <string>] [-TsInitialProgram <string>] [-TsMaxConnectionTime <TimeSpan>] [-TsMaxDisconnectionTime <TimeSpan>] [-TsMaxIdleTime <TimeSpan>] [-TsProfilePath <string>] [-TsReconnectionAction <int>] [-TsRemoteControl <int>] [-TsWorkDirectory <string>] [-UseDefaultExcludedProperties <Boolean>] [-UseGlobalCatalog] [-UserMustChangePassword <Boolean>] [-UserPassword <string>] [-UserPrincipalName <string>] [-WebPage <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

Detailed Description

Use this cmdlet to change or remove values of attributes of a user account in Active Directory. The cmdlet takes a series of optional, attribute-specific parameters allowing you to make changes to user attributes in Active Directory. Thus, to modify the value of the 'givenName', 'sn', or 'l' attribute, you can use the -FirstName, -LastName, or -City parameter, respectively. If 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 sets the attribute to the value specified by the attribute-specific parameter. 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. If 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

-AccountExpires [<System.Nullable`1[System.DateTime]>]

Set the account expiration date on the user account. Parameter value is a DateTime object that specifies the date you want. A null DateTime object configures the user account to never expire.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-City [<string>]

Set or clear the 'l' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Company [<string>]

Set or clear the 'company' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Connection [<ArsConnection>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-ConnectionAccount [<string>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-ConnectionPassword [<SecureString>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Control [<hashtable>]

Use this parameter to pass request controls (in-controls) to ActiveRoles Server as part of an operation request. In 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>] ...}

In this syntax, each of the name-value pairs is the name and the value of a single control. For instructions on how to create and use hash tables, see topic "about_associative_array" or "about_hash_tables" in Windows PowerShell Help. For 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.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Credential [<PSCredential>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Department [<string>]

Set or clear the 'department' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Description [<string>]

Set or clear the 'description' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-DeserializeValues [<SwitchParameter>]

Supply this parameter on the command line if the input you pass to the cmdlet contains serialized attribute values (for instance, when importing a directory object from a text file that was created using the Serialize parameter). For examples of how to export and import an object, see help on the Get-QADUser cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-DisplayName [<string>]

Set or clear the 'displayName' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Email [<string>]

Set or clear the 'mail' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-ExcludedProperties [<string[]>]

Use this parameter to specify the attributes that you do not want the cmdlet to update in the directory. Supply a list of the attribute LDAP display names as the parameter value. You could use this parameter when importing attribute values from a text file, in order to prevent some attributes found in the file from being set in the directory.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Fax [<string>]

Set or clear the 'facsimileTelephoneNumber' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-FirstName [<string>]

Set or clear the 'givenName' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-HomeDirectory [<string>]

Set or clear the 'homeDirectory' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-HomeDrive [<string>]

Set or clear the 'homeDrive' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-HomePhone [<string>]

Set or clear the 'homePhone' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Identity [<IdentityParameter>]

Specify the DN, SID, GUID, UPN or Domain\UserName of the user account you want to modify.

This parameter is optional since you can pipe into this cmdlet the object returned by the Get-QADUser cmdlet, to have that object identify the user account to act upon.

The first argument on the cmdlet is assumed to be the value of the -Identity parameter when no parameter name is specified.

Required?   true
Position?   1
Default value?  
Accept pipeline input?   true (ByValue)
Accept wildcard characters?   false

-IncludedProperties [<string[]>]

Use this parameter to specify explicitly the attributes that you want the cmdlet to update in the directory. Supply a list of the attribute LDAP display names as the parameter value. When used together with UseDefaultExcludedProperties, this parameter allows you to have the cmdlet update some attributes that would not be updated otherwise.

Note: If a particular attribute is listed in both ExcludedProperties and IncludedProperties, the cmdlet does not set the value of that attribute the directory.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Initials [<string>]

Set or clear the 'initials' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-LastName [<string>]

Set or clear the 'sn' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-LogonScript [<string>]

Set or clear the 'scriptPath' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Manager [<IdentityParameter>]

Set or clear the 'manager' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-MobilePhone [<string>]

Set or clear the 'mobile' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Notes [<string>]

Set or clear the 'info' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-ObjectAttributes [<ObjectAttributesParameter>]

Specify an associative array that defines the attributes to set. The array syntax:

@{attr1='val1';attr2='val2';...}

In this syntax, each of the key-value pairs is the LDAP display name and the value of an attribute to set. Thus, passing the @{title='Associate';l='Paris'} array to the ObjectAttributes parameter causes the cmdlet to set the 'Job Title' attribute to 'Associate' and the 'City' attribute to 'Paris'.

For information about associative arrays, type the following command at the PowerShell command-prompt:

help about_associative_array

Required?   false
Position?   named
Default value?  
Accept pipeline input?   true (ByValue, ByPropertyName)
Accept wildcard characters?   false

-Office [<string>]

Set or clear the 'physicalDeliveryOfficeName' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Pager [<string>]

Set or clear the 'pager' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PasswordNeverExpires [<Boolean>]

Set the value of this parameter to 'true' to configure the user account so that its password never expires.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PhoneNumber [<string>]

Set or clear the 'telephoneNumber' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PostalCode [<string>]

Set or clear the 'postalCode' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PostOfficeBox [<string>]

Set or clear the 'postOfficeBox' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-ProfilePath [<string>]

Set or clear the 'profilePath' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Proxy [<SwitchParameter>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-SamAccountName [<string>]

Set or clear the 'sAMAccountName' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Service [<string>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-StateOrProvince [<string>]

Set or clear the 'st' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-StreetAddress [<string>]

Set or clear the 'streetAddress' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Title [<string>]

Set or clear the 'title' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsAllowLogon [<Boolean>]

Specify whether the user is allowed to log on to the Terminal Server. Parameter value can be 'true' or 'false':

'true' if logon is allowed

'false' if logon is not allowed

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsBrokenConnectionAction [<int>]

Specify the action to take when a Terminal Services session limit is reached. Parameter value can be one of these integers:

1 (The client session should be terminated.)

0 (The client session should be disconnected.)

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsConnectClientDrives [<Boolean>]

Specify whether to reconnect to mapped client drives at logon. Parameter value can be 'true' or 'false':

'true' if reconnection is enabled

'false' if reconnection is disabled

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsConnectPrinterDrives [<Boolean>]

Specify whether to reconnect to mapped client printers at logon. Parameter value can be 'true' or 'false':

'true' if reconnection is enabled

'false' if reconnection is disabled

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsDefaultToMainPrinter [<Boolean>]

Specify whether to print automatically to the client's default printer. Parameter value can be 'true' or 'false':

'true' if printing to the client's default printer is enabled

'false' if printing to the client's default printer is disabled

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsHomeDirectory [<string>]

Set the path to the Terminal Server home directory for the user. To set a home directory on the local computer, specify a local path; for example, C:\Path. To set a home directory in a network environment, set the TsHomeDrive parameter and specify a UNC path.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsHomeDrive [<string>]

Set a Terminal Server home drive for the user in a network environment. Parameter value is a string containing a drive letter followed by a colon, to which the UNC path for the Terminal Server home directory is mapped. To set a home directory in a network environment, set both this parameter and the TsHomeDirectory parameter.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsInitialProgram [<string>]

Set the path and file name of the application that starts automatically when the user logs on to the Terminal Server. To set an initial application to start when the user logs on, set both this parameter and the TsWorkDirectory parameter.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsMaxConnectionTime [<TimeSpan>]

Set maximum duration of the Terminal Services session. After the specified time span has elapsed, the session can be disconnected or terminated. Parameter value is a TimeSpan object that specifies the duration you want.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsMaxDisconnectionTime [<TimeSpan>]

Set maximum amount of time that a disconnected Terminal Services session remains active on the Terminal Server. After the specified time span has elapsed, the session is terminated. Parameter value is a TimeSpan object that specifies the amount of time you want.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsMaxIdleTime [<TimeSpan>]

Set maximum amount of time that the Terminal Services session can remain idle. After the specified time span has elapsed, the session can be disconnected or terminated. Parameter value is a TimeSpan object that specifies the amount of time you want.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsProfilePath [<string>]

Set a roaming or mandatory profile path to use when the user logs on to the Terminal Server. A valid parameter value is a string in the following network path format: \\ServerName\ProfilesFolderName\UserName

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsReconnectionAction [<int>]

Specify whether to allow reconnection to a disconnected Terminal Services session from any client computer. Parameter value can be one of these integers:

1 (Reconnection is allowed from the original client computer only.)

0 (Reconnection from any client computer is allowed.)

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsRemoteControl [<int>]

Specify whether to allow remote observation or remote control of the user's Terminal Services session. Parameter value can be one of these integers:

0 (Remote control is disabled.)

1 (The user of remote control has full control of the user's session,

with the user's permission.)

2 (The user of remote control has full control of the user's session;

the user's permission is not required.)

3 (The user of remote control can view the session remotely,

with the user's permission; the remote user cannot actively control

the session.)

4 (The user of remote control can view the session remotely,

but not actively control the session; the user's permission

is not required.)

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-TsWorkDirectory [<string>]

Set the Terminal Server working directory path for the user. To set an initial application to start when the user logs on to the Terminal Server, set both this parameter and the TsInitialProgram parameter.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-UseDefaultExcludedProperties [<Boolean>]

When set to 'true', this parameter causes the cmdlet not to update a certain pre-defined set of attributes in the directory. This pre-defined set of attributes (referred to as "default excluded properties") can be viewed or modified by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-UseGlobalCatalog [<SwitchParameter>]

For parameter description, see help on the Connect-QADService cmdlet.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-UserMustChangePassword [<Boolean>]

Set the value of this parameter to 'true' to configure the user account so that the user is required to change the password upon the next logon.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-UserPassword [<string>]

Set the user password.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-UserPrincipalName [<string>]

Set or clear the 'userPrincipalName' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-WebPage [<string>]

Set or clear the 'wWWHomePage' attribute.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Confirm [<SwitchParameter>]

Prompts you for confirmation before executing the command.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-WhatIf [<SwitchParameter>]

Describes what would happen if you executed the command without actually executing the command.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

Input Type

Return Type

Notes

Examples

EXAMPLE 1

PS> set-QADUser 'CN=John Smith,OU=CompanyOU,DC=company,DC=com' -description 'Sales person'

Description

-----------

Connect to any available domain controller with the credentials of the locally logged on user, bind to a specific user account by DN, and modify the user description.

EXAMPLE 2

PS> $pw = read-host "Enter password" -AsSecureString C:\PS>connect-QADService -service 'server.company.com' -ConnectionAccount 'company\administrator' -ConnectionPassword $pw C:\PS>set-QADUser -identity 'S-1-5-21-1279736177-1630491018-182859109-1305' -description 'Service account' C:\PS>disconnect-QADService

Description

-----------

Connect to a specific domain controller with the credentials of a specific user, bind to a certain user account by SID, modify the user description, and then disconnect.

EXAMPLE 3

PS> $pw = read-host "Enter password" -AsSecureString C:\PS>connect-QADService -service 'localhost' -proxy -ConnectionAccount 'company\administrator' -ConnectionPassword $pw C:\PS>set-QADUser -identity 'company\jsmith' -ObjectAttributes @{l='New York';description=''} -UserPassword 'P@ssword' C:\PS>disconnect-QADService

Description

-----------

Connect to the local Administration Service with the credentials of a specific user, bind to a certain user account by Domain\Name, set or clear certain attributes, and then disconnect.

EXAMPLE 4

PS> Set-QADUser 'mycompany.com/usersOU/User1' -objectAttributes @{otherTelephone=@('555-34-67','555-34-68')}

Description

-----------

Assign two values to a multi-valued attribute such as "otherTelephone". This replaces the current values of the attribute with the specified values.

EXAMPLE 5

PS> Set-QADUser 'mycompany.com/usersOU/User1' -objectAttributes @{otherTelephone=@{Append=@('555-34-67','555-34-68')}}

Description

-----------

Add two values to a multi-valued attribute such as "otherTelephone". This appends the specified values to the existing values of the attribute. The existing values are not removed.

EXAMPLE 6

PS> Set-QADUser 'mycompany.com/usersOU/User1' -objectAttributes @{otherTelephone=@(Delete=@('555-34-67','555-34-68'))}

Description

-----------

Delete the specified values from a multi-valued attribute such as "otherTelephone", leaving the other attribute values intact.

EXAMPLE 7

PS> Set-QADUser 'mycompany.com/usersOU/User1' -objectAttributes @{otherTelephone=''}

Description

-----------

Delete all values from a multi-valued attribute such as 'otherTelephone' (clear the attribute on the user object).

EXAMPLE 8

PS> set-QADUser '<DN of user object>' -Service 'server.domain.local:389' -description 'My AD LDS user object'

Description

-----------

Connect to the AD LDS instance on 'server.domain.local:389' with the credentials of the locally logged on user, bind to a specific AD LDS user object by DN, and modify the description of the AD LDS user object.