Creating a SID Mapping File with Windows PowerShell

Before I became a “Deployment Guy”, I used to be an “Active Directory Guy” and worked on quite a few Active Directory deployments and migrations.  When users, groups, and computers are migrated to a new domain, the resources (files, shares, user profiles, etc.) need to have the permissions on them changed so that the migrated accounts can access them as before.  If users/groups are migrated before the resources, they can be migrated with SID History (the SID of the old accounts are placed in the sIDHistory attribute of the new account) to allow access to resources before the “security translation” of permissions is completed.

Many domain migration tools like Microsoft’s Active Directory Migration Tool (ADMT) can perform both the object migration and the security translation.  They use their database of migrated objects to do the security translation.  I was brought in on one engagement where a customer had contracted with a vendor to perform their account domain migration with SID History.  However, the resource domains were not migrated at the same time.  They then wanted to collapse their resource domains after the vendor was finished.  Unfortunately, the customer did not own the migration tool that the vendor used and did not have access to the migration database either.

ADMT has the ability to do the security translation using what is called a SID Mapping File.  This is a text file that contain entries that maps the source account to the destination account in either Windows NT account name (domain\name) format or SID format.  The entries look like this:

S-1-5-21-1944836006-1508872116-1651741082-1000,CONTOSO\jsmith

However, this functionality would be of no use without a way of generating the mapping file.  This could be done manually but would be a tremendous task if the account names were changed.  The MCS lead consultant on the project, Alan von Weltin, hit upon the idea of using the SID History information already present in Active Directory to generate the mapping file.  The accounts in AD had the the SIDs of the source accounts in the sIDHistory attribute.  I was asked to write the script that would query for all security principals that had SID History and for each object write a line to the file that mapped each source SID to the Windows NT account name of the new account.

When I first did this, I used VBScript as the scripting language.  Because SIDs in AD are stored as octet strings, converting them to a readable string is not easy in VBScript.  So I used a DLL available in the old ADSI Resource Kit (ADsSecurity.dll) that provided a COM object (ADsSID) for this conversion.  This ADSI Resource Kit has since been discontinued.  Because of this I wanted to create a new version that did not depend on this DLL.

So in my spare time I worked on a version written in Windows PowerShell.  This allows access to the .NET Framework which has classes in the System.DirectoryServices and System.Security namespaces that make searching AD and translating the SIDs to strings relatively easy.  A customer case recently arose where the SID Mapping was needed again.  This inspired me to finally finish this script and publish it here.

Get-SidMappingAD.ps1 will dump a SID mapping from Active Directory.  You must be logged on with an account that has read access to AD.  Use the -help switch for usage.  Note that the mapping from Get-SidMappingAD.ps1 can be generated from objectSid (not useful for  ADMT security translation but useful for documenting source domain SIDs) or sIDHistory.  You have to use the -sidhistory switch to generate the mapping file from sIDHistory.  (You can also dump the “name” field as the object DN.  Not useable by ADMT but useful for documentation.)

I also created a script (Get-SidMappingSAM.ps1) to dump an objectSid,comutername\name mapping file for a local computer SAM database or a Windows NT domain.

 

Disclaimer: The information on this site is provided "AS IS" with no warranties, confers no rights, and is not supported by the authors or Microsoft Corporation. Use of included script samples are subject to the terms specified in the Terms of Use .

This post was contributed by Michael Murgolo a Senior Consultant with Microsoft Services, U.S. East Region.

Get-SidMapping.zip