SamAccountName and UserPrincipalName attributes

6.7K

This article will examine the differences between the samAccountName and UserPrincipalName AD attributes.

Overview of Active Directory User 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.

Importance of samAccountName and UserPrincipalName

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

What Is the samAccountName Attribute?

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.

samAccountName format

The samAccountName attribute stores only the username (for example, aten.stig).

During logon, the DOMAIN\USERNAME format is used (however, is not a part of the attribute itself).

For example, if the NetBIOS domain name is ORG870B and the username is aten.stig, the logon name would be:

ORG870B\aten.stig

Character limitations and restrictions

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 within a domain.
• 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.

Security note. The sAMAccountName attribute has also been involved in the AD privilege escalation vulnerabilities CVE-2021-42278 and CVE-2021-42287 (often referred to as the noPac attack). CVE-2021-42278 involved spoofing the sAMAccountName of a computer account, while CVE-2021-42287 affected Kerberos authentication. Microsoft addressed these vulnerabilities through security updates and subsequent hardening changes. Don’t forget to keep DCs and Active Directory systems fully patched to protect against these attacks.

What Is the UserPrincipalName (UPN) Attribute?

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.

UPN format

The UserPrincipalName first appeared in Windows 2000 as part of the AD authentication model. The format widely differs from samAccountName. The UPN follows this format:

username@domain.tld

Subdomain example

For a user account in the parent domain, the UPN can look like this:

username@domain.tld

For a user account in a subdomain, the UPN can include the subdomain:

username@subdomain.domain.tld

Advantages of using UPN

Features of the UserPrincipalName attribute:

• The UserPrincipalName can match the user’s email address, but this is not required. In hybrid Microsoft Entra ID environments, the UPN and email address may use different domains. If changing the AD UPN is not desirable, Microsoft Entra ID also supports Alternate Login ID, which can allow users to sign in with another attribute, such as mail, depending on the identity config.
• To ensure proper authentication, the value of the UserPrincipalName (UPN) should be unique within the AD forest.
• The UPN uses an email-style format and follows naming conventions similar to Internet email addresses.
• AD allows UserPrincipalName values up to 1024 characters, although practical limits may be lower depending on apps and identity platforms. 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 in AD, but we strongly recommend to populate it. UPN values are commonly used for Microsoft Entra ID sign-in and hybrid identity cases, but the sign-in identifier does not always have to match the user’s email address.

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 Computers snap-in in the user properties in the Account tab.

UPN Suffixes

The UPN suffix matches the Active Directory domain name by default (for example, corp.local). However, you should note that internal domain names (like .local) are not routable on the internet and you can’t use them with Microsoft Entra ID.

You can add alternative UPN suffixes to prepare for cloud integration or migration (e.g. corp.com) in AD Domains and Trusts. Then you need to assign them to users.

You can add an alternative UPN suffix with PowerShell:

Get-ADForest | Set-ADForest -UPNSuffixes @{Add="corp.com"}

You can update a user’s UPN to use the new suffix:

Set-ADUser -Identity "aten.stig" -UserPrincipalName "aten.stig@corp.com"

You can also bulk-update user UPNs with PowerShell. The following example uses -WhatIf, so it only previews the changes and does not modify AD. In a production environment, you need to narrow the scope to the users you actually want to change and verify that the generated UPNs are unique before applying the changes.

Get-ADUser -Filter * | ForEach-Object {
    $newUPN = $_.SamAccountName + "@corp.com"
    Set-ADUser $_ -UserPrincipalName $newUPN -WhatIf
}

Note. The UPN suffix used in AD must be equal to a verified domain in Microsoft Entra ID. Otherwise, users can’t authenticate to cloud services.

Which Login Format Should You Use?

In modern AD environments, we generally recommend using UserPrincipalName (UPN) for user sign-in. The UPN format is easier for users to remember, resembles an email address, and integrates better with Microsoft Entra ID, Microsoft 365, and other cloud services.

The samAccountName attribute remains important for backward compatibility with legacy apps, scripts, and older authentication mechanisms. Because of this, both attributes are still commonly populated in AD environments.

As a best practice, you should use UPN for end-user sign-in and keep samAccountName for compatibility with legacy systems and admin tasks.

UserPrincipalName vs. SamAccountName: Handling in PowerShell

Working with samAccountName and UPN in PowerShell

In order to use the commands that I will share below in this section, you need the AD PowerShell module:

• On a Domain Controller, the module is installed automatically with the AD DS role.
• On a Windows client, you need to install RSAT with PowerShell using the following command:
  

  Add-WindowsCapability -Online -Name "Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0"

  When it is installed, you should import the module if needed:
  

  Import-Module ActiveDirectory

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.

Before creating the account, you need to validate the SamAccountName length instead of automatically truncating it. Automatic truncation can create duplicate names and cause account creation/automation conflicts.

Here is an example:

if ($newADUser['SamAccountName'].Length -gt 20) {
throw "SamAccountName must not exceed 20 characters."
}

New-ADUser @newADUser

This forces the script to stop and lets you choose an appropriate SamAccountName instead of silently modifying the requested value. You should also verify that the SamAccountName is unique within the domain before creating the account.

What about the UPN character limit?

If the generated UPN exceeds the 1024-character limit, it is better to validate the value and stop the account creation process rather than automatically truncate it. Automatic truncation can produce duplicate UPNs and cause account creation/update conflicts.

Here is an example:

if ($newADUser['UserPrincipalName'].Length -gt 1024) {
throw "UserPrincipalName must not exceed 1024 characters."
}

New-ADUser @newADUser

This forces the script to stop and lets you choose an appropriate UPN instead of silently modifying the requested value. You should also verify that the UPN is unique within the AD forest before creating the account.

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. This limitation still exists in current versions of the AD PowerShell module, including those available with Windows Server 2025 and modern RSAT releases.

The -Identity parameter does not accept a UserPrincipalName. To find a user by UPN, you can use the -Filter parameter:

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

This is the correct way to query an AD user by UserPrincipalName with Get-ADUser.

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.

	SamAccountName	UserPrincipalName
Mandatory Attribute	Yes. Required.	Optional, but recommended. Especially when planning migration/integration with Microsoft Entra ID.
Maximum Length	Fixed at 20 characters maximum.	1024 characters consisting of the username and domain parts.
Compatibility	Backwards compatible.	Introduced in Windows 2000 and supported in all modern AD environments.
Format	NETBIOS	USERNAME@DOMAIN.TLD or USERNAME@SUB.DOMAIN.TLD. The UPN often matches the user’s email address in Microsoft 365 environments, but the two values can be different.
PowerShell Usage	It can be used to query the AD User object as an identifier.	It cannot be used to query the AD User object as an identifier but can be used as a filter value.
Scope of Uniqueness	Domain	Forest