New-ADUser

Create a new Active Directory user.

Syntax
      New-ADUser [-Name] string  ADProperties[...]
        [-AccountExpirationDate DateTime] [-AccountNotDelegated bool]
           [-AccountPassword SecureString] [-AllowReversiblePasswordEncryption bool]
              [-AuthType {Negotiate | Basic}] [-CannotChangePassword bool]
                 [-Certificates X509Certificate[]] [-ChangePasswordAtLogon bool]
                    [-Credential PSCredential] [-Enabled bool] [-Instance ADUser] [-PassThru]
                       [-PasswordNeverExpires bool] [-PasswordNotRequired bool]
                          [-Path string] [-ProfilePath string] [-SamAccountName string]
                             [-ScriptPath string] [-Server string] [-ServicePrincipalNames string[]] 
                                [-SmartcardLogonRequired bool] [-TrustedForDelegation bool]
                                   [-Type string] [-UserPrincipalName string]
                                      [-Confirm] [-WhatIf] [CommonParameters] 

Key
   ADProperties
               [-City string] [-Company string] [-Country string]  
               [-Department string] [-Description string] [-DisplayName string] 
               [-Division string] [-EmailAddress string] [-EmployeeID string]
               [-EmployeeNumber string] [-Fax string] [-GivenName string]
               [-HomeDirectory string] [-HomeDrive string] [-HomePage string] 
               [-HomePhone string] [-Initials string] [-LogonWorkstations string] 
               [-Manager ADUser] [-MobilePhone string] [-Office string] [-OfficePhone string]
               [-Organization string] [-OtherAttributes hashtable] [-OtherName string]
               [-POBox string] [-PostalCode string] [-State string] [-StreetAddress string]
               [-Surname string] [-Title string]

   -AccountExpirationDate [System.DateTime]
       The expiry date for the account. (0=never expires)        
       Use PowerShell DateTime syntax
       Time is assumed to be local time unless otherwise specified.
       The default time is 12:00 (Midday) local time.
       The default date is the current date.
       Examples using GMT, UTC and local time:
        -AccountExpirationDate "Mon, 17 Apr 2011 21:22:48 GMT"
        -AccountExpirationDate "2011-04-17T14:22:48.0000000" 
        -AccountExpirationDate "04/17/2011 2:22:48 PM"
       The LDAP provider name (ldapDisplayName) for this property is accountExpires.

   -AccountNotDelegated bool
       Security delegation. When True, the security context of the user is not
       delegated to a service even when the service account is set as trusted for
       Kerberos delegation. Sets the AccountNotDelegated property for an AD account.
       This parameter also sets the ADS_UF_NOT_DELEGATED flag of the AD User Account
       Control (UAC) attribute.
       Values for this parameter: $false or 0, $true or 1

   -AccountPassword SecureString
       A new password value for an account.
       This value is stored as an encrypted string.
       If an empty or $null password is specified a Random password will be set.
       If the password does not meet password policy the account will be disabled
        
       User accounts, by default, are created without a password.
       A valid user account password may also be specified manually.
       User accounts will never be enabled unless a valid password is set
                
       The following example will prompt for a password.
          -AccountPassword (Read-Host -AsSecureString "AccountPassword")

   -AllowReversiblePasswordEncryption bool
       Whether reversible password encryption is allowed for the account.
       This parameter sets the AllowReversiblePasswordEncryption property of the account.
       This also sets the ADS_UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED flag of
       the AD User Account Control (UAC) attribute.
       Values for this parameter: $false or 0, $true or 1

   -AuthType {Negotiate | Basic}
       The authentication method to use: Negotiate (or 0), Basic (or 1)
       A Secure Sockets Layer (SSL) connection is required for Basic authentication.

   -CannotChangePassword bool
       Whether the account password can be changed.
       Sets the 'CannotChangePassword' property of an account.
       Values for this parameter: $false or 0, $true or 1

   -Certificates X509Certificate[]
       Modifies the DER-encoded X.509v3 certificates of the account.
       These certificates include the public key certificates issued to
       this account by the Microsoft Certificate Service. 
       Sets the Certificates property of the account object.
       The LDAP provider Name for this property is "userCertificate".

       Syntax to add/remove/replace/clear:
         -Certificates @{Add=value1,value2,...}
         -Certificates @{Remove=value3,value4,...}
         -Certificates @{Replace=value1,value2,...}
         -Certificates $null

       Multiple operations may be specified by using a list separated by semicolons.
         -Certificates @{Add=value1,value2,...};@{Remove=value3,value4,...}

   -ChangePasswordAtLogon bool
       Whether a password must be changed during the next logon attempt.
       Values for this parameter: $false or 0, $true or 1
       This cannot be set to $true for an account that also has PasswordNeverExpires set.

   -City string
       The user’s town or city.
       The LDAP provider name of the City property is "l".

   -Company string
       The user’s company. 
       The LDAP provider name of the Company property is "company". 

   -Country string
       The country or region code for the user’s language of choice. 
       The LDAP provider Name of the Country property is "c".

   -Credential PSCredential
       A user account that has permission to perform this action.
       The default is the current user unless the cmdlet is run from an AD PowerShell provider drive
       in which case the account associated with the drive is the default.

       "User64" or "Domain01\User64" or a PSCredential object.

   -Department string
       The user’s department. 
       The LDAP provider Name for this property is "department".

   -Description string
       A description of the object.
       The LDAP provider Name for this property is "description".

   -DisplayName string
       The display name of the object.
       The LDAP provider Name for this property is "displayName".

   -Division string
       The user’s division.
       The LDAP provider Name for this property is "division".

   -EmailAddress string
       The user’s email address.
       The LDAP provider Name for this property is "mail".

   -EmployeeID string
       The user’s employee ID. 
       The LDAP provider Name for this property is "employeeID".

   -EmployeeNumber string
       The user’s employee number. 
       The LDAP provider Name for this property is "employeeNumber". 

   -Enabled bool
       Is the account enabled.
       An enabled account requires a password.
       This parameter sets the Enabled property for an account object.
       Also sets the ADS_UF_ACCOUNTDISABLE flag of the AD User Account Control (UAC) attribute.
       Values for this parameter: $false or 0, $true or 1

   -Fax string
       The user’s fax phone number. 
       The LDAP provider Name for this property is "facsimileTelephoneNumber". 

   -GivenName string
       The user’s given name. In western countries this is often the first name. In Eastern
       countries this is often the last name.
       The LDAP provider Name for this property is "givenName".

   -HomeDirectory string
       Specifies a user’s home directory.
       The LDAP provider Name for the 'HomeDirectory' property is "homeDirectory".

   -HomeDrive string
       Specifies a drive that is associated with the UNC path defined by -HomeDirectory.
       The drive letter is specified as "DriveLetter:" where DriveLetter is a single,
       uppercase letter. 
       The LDAP provider Name for this property is "homeDrive". 

   -HomePage string
       The URL of the home page of the object.
       The LDAP provider Name for this property is "wWWHomePage".

   -HomePhone string
       The user’s home telephone number. 
       The LDAP provider Name for this property is "homePhone".

   -Initials string
       The initials that represent part of a user’s name.
       Use this value for the user’s middle initial. 
       The LDAP provider Name for this property is "initials".

   -Instance ADUser
       An instance of a user object to use as a template for a new user object.
        
       Method 1: Use an existing user object as a template for a new object. Retrieve an
       instance of an existing computer object with Get-ADUser. Then provide this object
       to the -Instance parameter of New-ADuser to create a new user object.
       property values may also be overridden for the new object by setting the appropriate parameters. 

          $userInstance = Get-ADuser -Identity TemplateUser64 
          New-ADuser -Name "SAbu64" -samAccountName "SAbu64" -Instance $userInstance -AccountPassword "ChangeMe2"

       Method 2: Create a new ADuser object and pass this object to the -Instance parameter
       of the New-ADuser cmdlet to create the new AD user object. 

          $userInstance = new-object Microsoft.ActiveDirectory.Management.ADObject
          $userInstance.DisplayName = "Sade Abu"
          New-ADUser -Name "SAbu64" -SAMAccountName "SAbu64"  -Instance $userInstance

   -LogonWorkstations string
       The computers that the user can access.
       To specify more than one computer, create a single comma-separated list.
       Identify each computer with a Security Accounts Manager (SAM) account name or the DNS 
       host name of the computer. The SAM account name is the same as the NetBIOS name of the computer.

       Example using SAMAccountName (NetBIOS) and DNSHostName values:
          -LogonWorkstations "pc064,pc065,pc1025.corp.ss64.com"

       The LDAP provider name for this property is "userWorkStations". 

   -Manager ADUser
       The user’s manager. 
       Set this by providing one of the following property values.
          Examples:
          Distinguished Name: CN=JohnDoe,OU=Europe,CN=Users,DC=corp,DC=ss64,DC=com
          GUID (objectGUID) : 599c3d2e-f72d-4d20-8a88-030d99495f20 
          Security Identifier (objectSid) : S-1-5-21-3165297888-301567370-576410423-1103
          SAM Account Name (sAMAccountName): JDoe

       The LDAP provider Name of this property is "manager".

   -MobilePhone string
       The user’s mobile phone number. 
       The LDAP provider Name of this property is "mobile".

   -Name string
       The name of the object. See notes below for some suggested naming conventions.
       The LDAP provider Name of this property is "name".

   -Office string
       The location of the user’s office or place of business. 
       The LDAP provider Name of this property is "office".

   -OfficePhone string
       The user’s office telephone number. 
       The LDAP provider Name of this property is "telephoneNumber".

   -Organization string
       The user’s organization. 
       The LDAP provider Name of this property is "o".

   -OtherAttributes hashtable
        Specifies object attribute values for attributes that are not represented by cmdlet parameters.
        Syntax:
        To specify a single value:
           -OtherAttributes @{'AttributeLDAPName'=value}
        To specify multiple values
           -OtherAttributes @{'AttributeLDAPName'=value1,value2,...}

        e.g.:
           -OtherAttributes @{'ItemPrice'=123; 'favColors'="red","blue"}

   -OtherName string
       A name in addition to a user’s given name and surname, such as the user’s middle name.
       The LDAP provider Name of this property is "middleName".

   -PassThru
       Returns the new or modified object.
       By default (i.e. if -PassThru is not specified), this cmdlet does not generate any output.
        
   -PasswordNeverExpires bool
       Whether the password of an account can expire.
       This parameter also sets the ADS_UF_DONT_EXPIRE_PASSWD flag of the AD UAC attribute.
       Values for this parameter: $false or 0, $true or 1

       This parameter cannot be set to $true for an account that also has the ChangePasswordAtLogon property set.

   -PasswordNotRequired bool
       Whether the account requires a password.
       This parameter also sets the ADS_UF_PASSWD_NOTREQD flag of the AD UAC attribute.
       Values for this parameter: $false or 0, $true or 1

   -Path string
       The X.500 path of the OU or container where the new object is created.         
       In many cases, a default value will be used for -Path.

       Example:
          -Path "ou=test1,dc=demo,dc=ss64,dc=com"

       Note: PowerShell cmdlets, such New-Item, Remove-Item, Remove-ItemProperty, Rename-Item and 
       Set-ItemProperty also contain a -Path property. However, for the AD Provider cmdlets, -Path 
       identifies the path of the actual object and not the container.

   -POBox string
       The user’s post office box number. 
       The LDAP provider Name of this property is "postOfficeBox".

   -PostalCode string
       The user’s postal code or zip code. 
       The LDAP provider Name of this property is "postalCode".

   -ProfilePath string
       A path to the user’s profile.
       This value can be a local absolute path or a UNC path. 
       The LDAP provider Name of this property is "profilePath".

       Examples:  -ProfilePath "E:\users\profiles\GailMoss"
                  -ProfilePath "\\users\profiles\GailMoss"

   -SamAccountName string
       The Security Account Manager (SAM) account name of the user, group, computer, or service account.
       (also known as the pre–Windows 2000 user logon name) is limited to 256 characters in the schema.
       However, for the purpose of backward compatibility the limit is 20 characters. 
       The LDAP provider Name of this property is "sAMAccountName".
       If the value provided is not terminated with a '$' character, the system will add one if needed.

   -ScriptPath string
       A path to the user’s log-on script.
       The default path is the NetLogon share
       The LDAP provider Name of this property is "scriptPath".

       Example:
           -ScriptPath "Logon.cmd"

   -Server string
       The AD Domain Services instance to connect to, this may be a Fully qualified domain name,
       NetBIOS name, Fully qualified directory server name (with or without port number) or AD Snapshot instance.

       Examples: demo.SS64.com  demo  demoDC02.demo.ss64.com  demoDC02.demo.ss64.com:3268

   -ServicePrincipalNames string[]
       The service principal names for the account.
       Use the following syntax to add remove, replace or clear service principal name values:

          -ServicePrincipalNames @{Add=value1,value2,...}
          -ServicePrincipalNames @{Remove=value3,value4,...}
          -ServicePrincipalNames @{Replace=value1,value2,...}
          -ServicePrincipalNames $null

       Multiple operations may be specified by using a list separated by semicolons.
         -ServicePrincipalNames @{Add=value1,value2,...};@{Remove=value3,value4,...}

       Example:
         -ServicePrincipalNames @{Add="SQLservice\NewService.ss64.com:1456"};{Remove="SQLservice\demo.ss64.com:1456"}

   -SmartcardLogonRequired bool
       Whether a smart card is required to logon.
       This parameter also sets the ADS_UF_SMARTCARD_REQUIRED flag of the AD User Account
       Control attribute.
       Values for this parameter: $false or 0, $true or 1

   -State string
       The user’s or Organizational Unit's state or province.
       The LDAP provider Name of this property is "st".

   -StreetAddress string
       The user’s street address.
       The LDAP provider Name of this property is "streetAddress".

   -Surname string
       The user’s Surname. In western countries this is often the last name. In Eastern
       countries this is often the first name.
       The LDAP provider Name of this property is "sn".

   -Title string
       The user’s title.
       The LDAP provider Name of this property is "title".

   -TrustedForDelegation bool
       Whether an account is trusted for Kerberos delegation.
       A service that runs under an account that is trusted for Kerberos delegation can
       assume the identity of a client requesting the service. 
       This value also sets the ADS_UF_TRUSTED_FOR_DELEGATION flag of the AD UAC attribute.
       Values for this parameter: $false or 0, $true or 1

   -Type string
       The type of object to create. If not specified this will default to "User".
       This option exists to support migrating data from other directory services.
       Set string to the LDAP provider name of the AD Schema Class that represents the
       type of object to be created.  The selected type must be a subclass 
of the User schema class. e.g. "InetOrgPerson" or "User".
-UserPrincipalName string Each user account has a user principal name (UPN) in the format user@DNS-domain-name A UPN is a friendly name assigned by an administrator that is shorter than the LDAP distinguished name used by the system and easier to remember. The UPN is independent of the user object's DN, so a user object can be moved or renamed without affecting the user logon name. When logging on using a UPN, users no longer have to choose a domain from a list on the logon dialog box. -Confirm Prompt for confirmation before executing the command. -WhatIf Describe what would happen if you executed the command, without actually executing the command.

New-ADUser creates a new AD user.

Property values that are not associated with cmdlet parameters can be set by using the -OtherAttributes parameter.

You must specify the SAMAccountName parameter to create a user.

New-ADUser can also create different types of user accounts such as iNetOrgPerson accounts. To do this, set the -Type parameter.

The -Path parameter specifies the container or organizational unit (OU) for the new user. If not specified the user object will be created in the default container for user objects in the domain.

There are 3 different ways to create a user object with this cmdlet:

Method 1: Use New-ADUser, specify the required parameters, and set any additional property values by using the cmdlet parameters.

Method 2: Use a template to create the new object. Create a new user object or retrieve a copy of an existing user object and set the -Instance parameter to this object. The object provided to the Instance parameter is used as a template for the new object.

Method 3: Use Import-CSV with the New-ADUser cmdlet to create multiple AD user objects. To do this, use the Import-CSV cmdlet to create the custom objects from a CSV file that contains a list of object properties. Then pass these objects through the pipeline to New-ADUser.

Username Naming Conventions

Most organisations will assign usernames which are based on the user’s real name/initials and/or a numeric ID. This choice is a balance of convenience and security/privacy. Shorter names are faster to type, names based on your actual name are easier to remember.

For maximum compatibility select a Name which matches the SAMAccountName and is 20 characters or less. This allows login without having to append @yourdomain to the login username.

An important point when basing usernames on real names is that characters extracted from a Surname are not random, so extracting more than 3 characters provides little extra benefit. If you have 5 people all called Smith, it makes no difference to put SMIT into the username instead of SMI.

In a small organisation with < 100 user accounts, a 4 digit username with a concatenation of Given name + Surname may be enough
eg: JSMI

In larger organisations, using a full GivenName.Surname will result in some number of duplicates that will have to resolved with something like Jane.Smith2, Jane.Smith3 etc (this typically affects around 2–4% of users).

A good compromise is to combine a concatenation of Given Name initial + 3 characters from the Surname + the last 4 digits of the Employee ID number. This format will result in duplicates for less than 1 in 20,000 users ( 0.01%) and is only 8 digits to type.
eg: JSMI4979

A numeric format with a fixed character prefix avoids all possibility of duplicate names, but at the expense of being much less memorable. This avoids the need to rename accounts for name changes in the future.
eg: UA54979

With all the naming schemes above, the Display Name can be used to display the user’s real full name along with any punctuation.

Using a full Given name + Surname as a username has some disadvantages:

Never use a social security number or other government issued ID number as any part of a username.

Random or sequential characters such as base 36 can be used to build a shorter username than a purely numeric number, but such schemes when applied to larger numbers (>40,000) will occasionally spell out a real word, perhaps a curse word that you will want to filter out.

When choosing a naming scheme, consider that some people may have names that are only 1 or 2 characters long or mononymic.

Leavers and returners:

No username for an ex-staff member should ever be re-assigned to a different person. Ensuring this does not happen will require either retaining all ex-user accounts in a disabled state or maintaining a separate record of all current and ex-staff usernames.

If a staff member leaves and returns to the same role, e.g. after maternity leave or a leave of absence they should be given the same username.
If a staff member leaves and returns to a different role, they should be given a new username to remove any possibility that they retain permissions granted as part of the old role. If you have strict role-based permissions or an equivalent process in place, this rule may not be necessary.

Examples

Create new user account for "John Doe" and provide all the basic details in one command:

PS C:\> New-ADUser -Name "John DOE" -SamAccountName JDOE -DisplayName 'DOE, John' -GivenName "John" `
-Surname "DOE" -AccountPassword 'Secr3t123' -Enabled $true -UserPrincipalName "JDOE@ss64Dom"

An alternative way to write the above using splatting:

PS C:\> $usrArgs = @{
  Name = "John DOE"
  SamAccountName = JDOE
  DisplayName = 'DOE, John'
  GivenName = "John"
  Surname = "DOE"
  AccountPassword = 'Secr3t123'
  Enabled = $true
  UserPrincipalName = "JDOE@ss64Dom"
}
PS C:\> New-ADUser @usrArgs

Create new user account named "User64" and prompt for a password:

PS C:\> $pw = Read-Host -Prompt 'Enter a Password for this user' -AsSecureString 
PS C:\> New-ADUser -Name User64 -SamAccountName user64 -DisplayName 'User 64' -AccountPassword $pw -Enabled $true

Create a new user account named 'GailMoss' and set the title and mail properties on the new object:

PS C:\> New-ADUser GailMoss -OtherAttributes @{title="director";mail="GailMoss@ss64.com"}

Create a new inetOrgPerson named 'GailMoss' on an AD LDS instance.:

PS C:\> New-ADUser GailMoss -Type iNetOrgPerson -Path "DC=AppNC" -server lds.SS64.com:50000

Create user accounts from a CSV formatted spreadsheet, (adjust the items in bold to match the spreadsheet column names):

Import-Csv .\users.csv | foreach-object {

$usrArgs = @{
  Name = $_.name
  SamAccountName = $_.SamAccountName
  UserPrincipalName = $_.SamAccountName + "@EXAMPLE.com"
  GivenName = $_.cn
  Surname = $_.sn
  DisplayName = "$_.sn, $_.cn"
  AccountPassword = 'Secr3t123'
  Enabled = $True
  PasswordNeverExpires = $True
  Department = $_.Department
  Path = "CN=Users,DC=EXAMPLE,DC=com"
  }

New-ADUser @usrArgs -PassThru
}

Create a new user named 'GailMoss' with a certicate imported from the file "export.cer":

PS C:\> New-ADUser GailMoss -Certificate (new-object System.Security.Cryptography.X509Certificates.X509Certificate -ArgumentList "export.cer")

“If there is a sin against life, it consists perhaps not so much in despairing of life as in hoping for another life and in eluding the implacable grandeur of this life” ~ Albert Camus

Related PowerShell Cmdlets

Remove-adUser - Remove an AD user.
Set-adUser - Modify an AD user.


 
Copyright © 1999-2024 SS64.com
Some rights reserved