SamAccountName and UserPrincipalName attributes

User accounts in Active Directory have various attributes, among which there are two interesting and critical attributes: samAccountName and UserPrincipalName (usually it is called UPN), the differences between which are not understood by many Windows administrators. This article will examine the differences between the samAccountName and UserPrincipalName AD attributes.

The userPrincipalName and sAMAccountName attributes can log users into computers in the AD domain.

The samAccountName attribute was used in the pre-Windows 2000 environment and defined the user name to authorize users on the domain or standalone workstations. But, in Windows 2000, the new attribute UserPrincipalName has appeared, which can also be used to log in to the AD workstations. So you can now authorize on a computer in the AD domain using both samAccountName and UserPrincipalName.

The samAccountName Attribute

The samAccountName attribute has the following format:

NETBIOS\USERNAME

For example, if the domain is org870.ga, the NetBIOS domain name would be ORG870B. Thus, the aten.stig username in the samAccountName format should look like ORG870B.stig.

Particulars of the samAccountName attribute:

• The samAccountName length is fixed to 20 characters only and cannot contain any of these characters: “/ \ : ; | = , + * ? < >. The field will not accept when you try to type more than 20 characters in the user login name.
• The value of samAccountName must be unique for all domain objects.
• The environment variable on a Windows computer %USERNAME% would contain the samAccountName attribute value, not UserPrincipalName, even if you logged on to the computer using the UPN.
• The value of samAccountName on the user’s computer can be obtained using the USERNAME environment variable. It can be displayed using the **set** command in cmd or gci env: in PowerShell.

The UserPrincipalName Attribute

The userPrincipalName or UPN was introduced on Windows 2000. This came with the introduction of the Lightweight Directory Access Protocol (LDAP). The format widely differs from samAccountName. The UPN follows this format:

username@domain.tld

The above example shows that the account belongs to the parent domain. For accounts in subdomains, the format will be as follows:

username@subdomain.domain.tld.

Features of the UserPrincipalName attribute:

• The value of the UserPrincipalName attribute can correspond to the user’s e-mail (extremely convenient during migrations, profile settings, etc.)
• The value of the samAccountName attribute must be unique in the entire domain forest.
• The identifier format conforms to RFC 822 standards.
• Unlike the samAccountName, the UPN character limit is up to 1024 characters—comprised of the username, the @ sign, and the domain/subdomain name. For example, if the domain is @org870b.ga, that alone is already 11 characters long. So that username has a 1013-character limit left.
  
• The UserPrincipalName attribute is optional, but it is recommended to fill it in. Especially when you’re integrating with Azure AD or preparing for migration, the UPN will be required.

When creating a new user in AD, you specify the value of the UserPrincipalName attribute in the “User logon name” and the value samAccountName in the “User logon name (pre-Windows 2000)” field.

You can change the values of this field in the future using the Active Directory Users and Computer snap-in in the user properties in the Account tab.

UserPrincipalName vs. SamAccountName: Handling in PowerShell

The PowerShell Active Directory module is already installed on a server with the Active Directory role. This module enables managing the aspects of the Active Directory objects using PowerShell cmdlets.

You can install the Remote Server Administration Tools (RSAT) on client computers to enable that computer to manage AD in PowerShell.

Creating Active Directory Users

You can create an AD user in PowerShell while specifying the UserPrincipalName and SamAccountName attributes. But keep in mind the limitations, particularly the length and disallowed characters.

For example, the command below will fail because the SamAccountName is beyond the 20-character limit.

$newADUser = @{ 
Name = 'dummy_user' 
DisplayName = 'Dummy User Account' 
SamAccountName = 'dummy6789067890678900' 
UserPrincipalName = 'dummy6789067890678900@org870b.ga' 
}

But the error could be more specific. The exception shows only “The name provided is not a properly formed account name”. The error is categorically correct but vague.

So if you’re automating the account creation process, implement a safeguard, perhaps automatically truncate the given SamAccountName value. Here’s a basic example:

# truncate the SamAccountName if the current length if > 20 
if (($newADUser['SamAccountName']).Length -gt 20){ 
$newADUser['SamAccountName'] = 
($newADUser['SamAccountName']).Substring(0,20) 
} 

New-ADUser @newADUser

What about the UPN character limit?

It would be trickier since you must truncate the username part without affecting the domain part. There’s an example of keeping the UPN within the 1024-character limit:

# truncate the UserPrincipalName if the current length if > 1024 
if (($newADUser['UserPrincipalName']).Length -gt 20){ 
# split the username and domain part. 
$username = ($newADUser['UserPrincipalName']).Split('@')[0] 
$domain = "@$(($newADUser['UserPrincipalName']).Split('@')[-1])" 
$newADUser['UserPrincipalName'] = "$(($username).Substring(0,$(1024 -1 -($domain.Length-1))))$domain" 
} 

New-ADUser @newADUser

Viewing, Deleting, Updating Active Directory Users

The cmdlets to view, delete, and update Active Directory users are Get-ADUser, Remove-ADuser, and Set-ADUser, respectively.

All of these cmdlets have a parameter called Identity, which accepts the following identifier values:

• A distinguished name
• A GUID (objectGUID)
• A security identifier (objectSid)
• A SAM account name (sAMAccountName)

So, to get an AD User, you can run:

Get-ADUser -Identity <SamAccountName>

But as you may have noticed, the Identity parameter does not accept the UPN value as valid.

Get-ADUser -Identity <UserPrincipalName>

But if you must use the UserPrincipalName as the identifier when running these cmdlets, you could use the Filter parameter instead.

Get-ADUser -Filter 'userPrincipalName -eq "<UPN>"'

UserPrincipalName vs. SamAccountName: Side-by-Side Comparison

Now that we’ve covered the SamAccountName and UserPrincipalName attributes, here’s the summary table to compare them.