Remapping principal names during legacy platform migration

This article describes how to use the Convert-1EPrincipal cmdlet to remap principal names when performing a migration of a legacy on-premises version of the 1E Platform.

About legacy on-premises versions

Up to and including version 8.1 of the 1E Platform, all versions ran in an on-premises environment. Version 8.2 and subsequent versions operate in a SaaS environment. Consequently, the authentication mechanism for the SaaS versions was modified from the native Windows authentication used in version 8.1 and earlier versions to platform-neutral authentication using an external identity provider.

Version 9.0 of the 1E Platform is available for on-premises upgrades of existing 8.1 or earlier versions. This version of the platform uses the same platform-neutral authentication mechanisms as the SaaS offerings. This means that the format of principal names (account names) changes in version 9.0. This is because the format for principal names in platform-neutral authentication is in the User Principal Name (UPN) format. This format looks similar to an email address, for example, John.Doe@corellianengineering.onmicrosoft.com.

Previously, an account principal would have been in the Windows-specific format, which consists of the domain and user names separated by a backslash, for example, corellian\John.Doe.

When migrating from an earlier version of the platform to version 9.0, you will be asked to define a new principal that will be granted full administrator rights on the platform during installation. While this principal will then be able to add new groups and principals to the platform, existing principals that existed in the platform RBAC database will not be able to authenticate until their names are remapped to UPN format.

They must also exist on the identity provider which has been defined for use with the platform after migration.

The 1E PowerShell Toolkit provides a cmdlet to assist in this process. You must run this cmdlet in the context of a principal with full administrator rights in order to remap existing principals. To learn about the cmdlet syntax, refer to Role-Based Access Control cmdlets. Some examples of the usage of the cmdlet are discussed below.

Scenario 1: Remapping all principals to a fixed UPN suffix

The simplest scenario is where you want to map all principals to a fixed UPN suffix. For example, if the fixed suffix was megacorp.com then the following remapping will take place:

  • Principal domain\Fred.Smith will be remapped to Fred.Smith@megacorp.com.
  • Principal domain\Joe.Bloggs will be remapped to Joe.Bloggs@megacorp.com.
  • Principal anotherdomain\Mary.Jones will be remapped to Mary.Jones@megacorp.com.

The cmdlet arguments to perform this mapping are the following:

Copy 
Convert-1EPrincipal -DomainMapping megacorp.com

Scenario 2: Remapping different domains to different UPN suffixes

Some organizations map multiple domains into a single identity provider directory and also handle name collisions by using different UPN suffixes for each domain.

For example, if the same user name exists in different domains, we might want to assign them a different UPN suffix so that they remain globally unique when remapped to a new shared identity provider directory.

For example:

  • Principal domain\Mary.Jones will be remapped to Mary.Jones@megacorp.com.
  • Principal domain\Joe.Bloggs will be remapped to Joe.Bloggs@megacorp.com.
  • Principal anotherdomain\Mary.Jones will be remapped to Mary.Jones@largecorp.com.

The cmdlet arguments to perform this mapping are the following:

Copy 
Convert-1EPrincipal -DomainMapping @{"domain1"="megacorp.com"; "anotherdomain"="largecorp.com"}

The parameter @{.....} is a Powershell Hash object, which is just a set of key and value pairs. In this case we have specified two such pairs, with the first key (domain1) having a value megacorp.com and the second key (anotherdomain) having a value largecorp.com.

Note that any domain that doesn’t match any keys in the hash is not processed, and accounts for those domains are left unchanged.

Scenario 3: Remapping the user name portion

In some cases we may want to transform the user name portion of the UPN.

For example, we might want to remap names to be firstname.lastname:

  • Principal domain\MaryJones might be remapped to Mary.Jones@megacorp.com.
  • Principal domain\JoeBloggs might be remapped to Joe.Bloggs@megacorp.com.

The cmdlet to perform this mapping would be the following:

Copy 
Convert-1EPrincipal -UserMapping @{"MaryJones"="Mary.Jones"; "JoeBloggs"="Joe.Bloggs"}

As with the domain mapping option, user names that don’t match the hash keys are left unchanged.

Scenario 4: Writing the mappings to a file

Instead of actually updating the principals, we can choose to write the mappings that would have been made to a file instead. This lets us review and edit the file before using it as the input to a mapping operation.

To write the mappings to a file, specify the following:

Copy 
-OutPath <path to file>

A mapping file consists of a set of comma-separated lines. The first field in a line is the source mapping and the second field is the destination mapping.

Scenario 5: Using a mapping file to guide the mapping process

You can also specify that a mapping file is to act as the input to the mapping process. To do this, specify the file the following way:

Copy 
-Path <path to file>

When using a mapping file, principals that don’t match a mapping entry are left unchanged.

Scenario 6: Reviewing mappings without implementing them

You can specify that mappings should be output to the console but not implemented. To do this, specify the following as a cmdlet argument:

Copy 
-Whatif

Scenario 7: Combining domain and user mapping

You can use both the -DomainMapping and -UserMapping parameters together to transform both the user name (prefix) portion of the UPN and the domain name (suffix) portion.