Create and manage custom AD attributes with PowerShell

• Author
• Recent Posts

Surender Kumar

Surender Kumar has more than twelve years of experience in server and network administration. His fields of interest are Windows Servers, Active Directory, PowerShell, web servers, networking, Linux, virtualization, and penetration testing. He loves writing for his blog.

Latest posts by Surender Kumar (see all)

• Configure a private DNS server in Docker - Fri, Mar 24 2023
• Store secrets in AWS Secrets Manager - Fri, Mar 17 2023
• Install Windows 10 / 11 22H2 without Microsoft account - Tue, Feb 28 2023

The default Active Directory schema contains most of the attributes that an organization would normally require in its AD infrastructure. However, default attributes are not always enough when it comes to larger organizations. When I was managing Active Directory for a large school, I was asked to set a few attributes for users who were not available in AD by default. In this case, I had to expand the AD schema to define the custom attributes and set those attributes for users.

The attributes could be anything, but for the sake of this article, let's assume we are adding two attributes named "Campus Name" and "Campus ID."

A word of caution

Please note that making changes to the AD schema is like doing brain surgery. Any change, good or bad, that you make in the AD schema will affect your entire AD forest. In addition, schema changes are irreversible and cannot be undone. Please do not try these commands directly in a production environment. Even if you're an AD expert, bad things can happen. I highly recommend performing these steps in a test lab first.

Requirements

To perform the steps mentioned in this article, you must meet the following requirements:

• You must be a member of the Active Directory Schema Admins group.
• The Active Directory module for Windows PowerShell must be installed on the DC.
• You can perform these steps directly on a DC or via an interactive PowerShell session (Enter-PSSession) to a DC.

Generate the OIDs for AD objects

All AD objects have a unique identifier called the Object Identifier (OID). First, we'll create a script to generate the OIDs for the custom attributes (Campus Name and Campus ID) that we will be adding to our AD schema. We will create a script and name it "Generate-OID.ps1."

To create the script:

Copy the following code and save it in a file named "Generate-OID.ps1."

$Prefix = "1.2.840.113556.1.8000.2554"
$GUID = [System.Guid]::NewGuid().ToString()
$GUIDPart = @()
$GUIDPart += [UInt64]::Parse($GUID.SubString(0,4), "AllowHexSpecifier")
$GUIDPart += [UInt64]::Parse($GUID.SubString(4,4), "AllowHexSpecifier")
$GUIDPart += [UInt64]::Parse($GUID.SubString(9,4), "AllowHexSpecifier")
$GUIDPart += [UInt64]::Parse($GUID.SubString(14,4), "AllowHexSpecifier")
$GUIDPart += [UInt64]::Parse($GUID.SubString(19,4), "AllowHexSpecifier")
$GUIDPart += [UInt64]::Parse($GUID.SubString(24,6), "AllowHexSpecifier")
$GUIDPart += [UInt64]::Parse($GUID.SubString(30,6), "AllowHexSpecifier")
$OID = [String]::Format("{0}.{1}.{2}.{3}.{4}.{5}.{6}.{7}", $Prefix, $GUIDPart[0], $GUIDPart[1], $GUIDPart[2], $GUIDPart[3], $GUIDPart[4], $GUIDPart[5], $GUIDPart[6])
Write-Host $OID -ForegroundColor Green 

Save this script in the desired location, and remove the .txt file extension. I am saving it into my Z: drive for easier accessibility.

Once the Generate-OID.ps1 script is ready, you can run it to generate OIDs. The following image shows how to run it.

Running the Generate OID.ps1 script

Make sure the PowerShell console is running with elevated privileges. To run the script downloaded from the Internet, you need to temporarily change ExecutionPolicy for the current PowerShell process. When you run this script, you will see the OID generated in green. Every time you run it, a new OID is generated. You need to copy the generated OID and use it in the next section so you can keep this PowerShell session open for the next section.

Create custom attributes in AD

Before actually adding the attributes, let me show you that they do not already exist in my AD. I will run the Get-ADUser command for user student1.

Get ADUser custom attributes error Get ADUser One or more properties are invalid

Look at the output of the Get-ADUser command. It says, "One or more properties are invalid," which means the "Campus Name" and "Campus ID" properties do not exist in my AD environment yet.

To add the "Campus Name" and "Campus ID" custom attributes to the AD schema, we will use Windows PowerShell ISE.

1. To launch the ISE from a PowerShell console that is already open, just type "ise" without quotes, and press Enter. The PowerShell ISE launches in the same working directory.
2. Click the new script icon to open the script pane.
3. Copy and paste the following code in the ISE's script pane:

# get AD schema path
$adSchema = (Get-ADRootDSE).schemaNamingContext
 
# get user schema
$userSchema = Get-ADObject -SearchBase $adSchema -Filter "Name -eq 'User'"

# set the short name for custom attribute with no spaces
$attributeName = "CampusName"

# set the short description for custom attribute
$attributeDesc = "Campus Name"

# paste the OID generated by "Generate-OID.ps1" script
$OID = "1.2.840.113556.1.8000.2554.56779.46056.47028.16885.40810.7627542.10407433"

# oMSyntax is "64" for String (Unicode). Refer this link for other types: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/7cda533e-d7a4-4aec-a517-91d02ff4a1aa
$oMSyntax = 64

# attributeSyntax is "2.5.5.12" for String (Unicode). Refer this link for other types: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/7cda533e-d7a4-4aec-a517-91d02ff4a1aa
$attributeSyntax = "2.5.5.12"

# set the indexable value to "1" if you want AD to index this attribute. set this only if you would be querying this AD attribute a lot.
$indexable = 0

# build custom attributes hashtable
$adAttributes = @{
  lDAPDisplayName = $attributeName;
  adminDescription = $attributeDesc;
  attributeId = $OID;
  oMSyntax = $oMSyntax;
  attributeSyntax = $attributeSyntax;
  searchflags = $indexable
}

# create the custom attribute in AD schema
New-ADObject -Name  $attributeName -Type attributeSchema -Path $adSchema -OtherAttributes $adAttributes
 
# add the custom attribute to user class
$userSchema | Set-ADObject -Add @{mayContain = $attributeName} 

The script is also attached for reference.

1. Each line of this code has a comment to help explain what that line is doing. Please don't execute this code straightaway. There are certain sections that you need to change according to your requirements before you can execute this code.
   

   Modifying the PowerShell script

• At a minimum, you need to change the values of the attributeName, attributeDesc, and OID variables, which are marked in red in the image above. You can set these values as needed.
• The value of the OID variable will be generated by the Generate-OID.ps1 script that we created in the previous section.
• You can also change the values of oMSyntax, attributeSyntax, and indexable variables. See the inline comments for more help on the supported attribute values.

2. After making the changes shown above, you can click the "Run Script" button or press the "F5" key to execute the script.
3. If you do not get any errors, your custom attribute (Campus Name) has been added.
4. To create the second attribute (Campus ID), change the values of the attributeName, attributeDesc, and OID variables in the script and execute it again.
5. After creating the attributes in the AD schema, wait a bit so that the changes can replicate to other domain controllers in your forest. It could take a while, depending on the size of your Active Directory infrastructure.
6. Now that the custom attributes are created, you need to restart the Active Directory Domain Services for the changes to take effect. To restart the services using PowerShell, run the following command:
   Get-Service NTDS -DependentServices | Restart-Service -Force -Verbose
7. Once the AD services are restarted successfully, repeat the same command that we ran at the start of this section.
   Get-ADUser student1 -Properties Name, CampusName, CampusID
   

   Get ADUser custom attributes

See? We no longer got the "One or more properties are invalid" error. But wait a minute! Where are the custom attributes that we just created?

These attributes are not normally visible. To see these custom attributes, we need to run the PowerShell command, as shown below:

Get-ADUser student1 -Properties * | Select -Property Name, CampusName, CampusID

Get ADUser custom attributes filter

We just need to tell the AD PowerShell module to get all the properties for the selected user, and then pipe the results to the Select-Object cmdlet to filter and show the selected properties (Name, CampusName, and CampusCode) only.

If you want, you can download this PowerShell script to create multiple custom attributes using a CSV file (the sample CSV file). I know it is not a good looking script but it gets the job done. The following image shows how to use this script:

Create multiple custom attributes using a CSV file

In the next section, we will discuss how to manage these custom attributes via Windows PowerShell.

Manage custom attributes via PowerShell

At this point, we have our custom attributes available for use in Active Directory. You could either use GUI tools or Windows PowerShell to manage (set, modify, or delete) these custom attributes for AD users. Since we've been doing everything via PowerShell, let's stick to that.

Set custom attributes

To set the value for custom attributes, run the following command in the PowerShell console:

Set-ADUser student1 -Add @{CampusName="NewYorkISD"; CampusID="NYISD001"}

We used a PowerShell hashtable format with the -Add parameter to assign the values to custom attributes.

Get the custom attributes

To get the value of custom attributes, run the following command:

Get-ADUser student1 -Properties * | Select -Property Name, CampusName, CampusID

Set ADUser add custom attributes

You can see that the values are now assigned to our custom attributes.

Modify the custom attributes

Once we set the attributes, you will no longer be able to use the -Add parameter along with the Set-ADUser command. This is because we have created custom attributes that can hold single values only. To modify the value of custom attributes, we need to use the -Replace parameter. The updated command would be:

Set-ADUser student1 -Replace @{CampusName="LAISD"; CampusID="LAISD001"}

Set ADUser replacing custom attributes

Delete the custom attribute values

To delete the value of custom attributes, run the following command:

Set-ADUser student1 -Remove @{CampusName="LAISD"; CampusID="LAISD001"}

To remove the attribute values, we use the -Remove parameter and the attribute values are gone.

Set ADUser removing custom attributes

That was all for this article. We learned how to extend the Active Directory schema to add custom attributes and manage those custom attributes using Windows PowerShell.

The schema changes are not something an AD admin would be doing regularly, but it is a good thing to learn and practice, at least in a test lab. As mentioned above, the attributes, once added, will remain in your AD schema forever.