Using the new Granfeldt FIM/MIM PowerShell Management Features

Last week Søren Granfeldt released the first update to his hugely popular Granfeldt FIM/MIM PowerShell Management in over 2 years. This post looks at the latest release and using the new Granfeldt FIM/MIM PowerShell Management Features.

The new features are:

  • A new option to specify an auxiliary set of credentials that is passed to scripts.
  • An option for a new parameter to support additional configuration parameters that are also passed to scripts.

Upgrading the Granfeldt PowerShell Management Agent to v5.6.3.2022

There are a few items to note if you are considering upgrading an existing FIM/MIM Sync Server for the updated Granfeldt PowerShell Management Agent.

  • You will need to refresh any existing Granfeldt PowerShell MA’s (open the Properties of the MA) using the Synchronization Server Manager.
    • This will show your previous settings along with the new configuration options
    • Changing any of these parameters will require you to also re-enter any password(s) configured in the ‘password(s)’ field in the ‘Connectivity‘ section of the PSMA Management Agent

Back up your existing PowerShell Management Agents

Before you install the latest version here are the precautionary steps that should be performed.

  • Backup your existing PSMA’s by exporting them using the Synchronization Server Manager.
  • Make sure you know the credentials associated with the PSMA(s).

Installing v5.6.3.2022 of the PowerShell Management Agent

  • Download the psma.5.6.3.2022.zip file from GitHub here. Unblock the zip file and expand the archive on your FIM/MIM Synchronization Server.
  • Stop the Synchronization Service Manager Service

Run the installation script from the location you expanded the PSMA setup

  • using an Administrator PowerShell session run
    .\Install-PowerShellManagementAgent.ps1
  • Verify the installation.
    • check the Granfeldt.PowerShell.ManagementAgent.dll file was updated/installed in the Synchronization Server Extensions Directory.
      • the default location is C:\Program Files\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions
      • the version of the updated file is 5.6.3.2022
  • Start the FIMSynchronizationService

Refreshing Existing PowerShell Management Agents

Start the Synchronization Service Manager and open an existing Granfeldt PowerShell Management Agent.

You will see the new Username (auxiliary), Password (auxiliary) and Configuration parameters options on the Connectivity page of the PowerShell Management Agent Configuration Options.

If you add configuration values for these new parameters you will also need to provide the credentials for the other password configuration options (if they were previously populated).

Using the new Granfeldt FIM/MIM PowerShell Management Features

I will show creating a new PowerShell Management Agent but focus on the new Granfeldt FIM/MIM PowerShell Management Features.

For this example, I have created a folder under the C:\Program Files\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions directory name PSMAExample. The PSMAExample folder contains four files. schema.ps1, import.ps1, export.ps1 and password.ps1.

PSMA Files (Scripts)

Both the password.ps1 and export.ps1 for this example are empty files containing no text/script.

Schema.ps1

The example schema script below will provide the configuration for a ‘Person’ Object Class using Employee ID as the anchor and a bunch of typical employee style person attributes.

Import.ps1

The example import.ps1 script below is configured to pass the input parameters from the configuration of the MA and the Run Profile to a series of output files. This is an example to show the formatting and how to acquire the values that you can then use in an Import, Export, Schema or Password Script.

With a folder and scripts for our Management Agent configuration created we can now create a new Granfeldt FIM/MIM PowerShell Management.

Create a Granfeldt FIM/MIM PowerShell Management

Using the Microsoft Identity Manager Synchronization Server Manager, from the Management Agents section select Create. Choose PowerShell.

Give your new Granfeldt FIM/MIM PowerShell Management a name and description.

Provide the path and name for your schema script and values for the Username, Password, Username (auxiliary), Password (auxiliary) fields.

Scroll down the Connectivity page and provide some values for the Configuration parameters. You can separate the name of the configuration item and its value with either ‘=‘ or ‘,‘ and even a combination of both. Use “Cntrl + Enter” to got to a new line in the Configuration parameters text box.

Provide the path to the Import, Export and Password scripts. Even though we aren’t using the Export and Password features the files need to exist even though they contain no configuration.

We can skip the Partitions and Hierarchies tab.

Our schema script has been imported and identified we have defined a ‘person’ object type.

And our attributes list from the schema script is shown and we can select which attributes to bring into the connector space.

The anchor from our schema script is the Employee ID attribute and is shown here.

For the remainder of the Management Agent creation select ‘Next‘.

Next

and ‘Next

and ‘Next‘ again.

Uncheck Enable Password Management and select ‘Finish‘.

Create a Run Profile

Select your new PowerShell Management Agent and from the Actions menu select Configure Run Profiles. Create a Run Profile for a Full Import (Stage Only).

Create the c:\psma\csv path (or if you changed the path in the Import script, create that path) so that the configuration items can be exported when the Import is run.

Execute the Full Import Run Profile

Executing the Full Import Run Profile will then create the series of txt files configured in the import script. The import script shows how to obtain the values from the MA and Run Profile configuration as well as the values returned.

Granfeldt FIM/MIM PowerShell Management Configuration Parameters

In the Import script we have the $ConfigurationParameter variable specified in the param section.

In the body of the import script, we are obtaining the values passed from the MA and outputting them to the csv_config.txt file.

$ConfigurationParameter | out-file "c:\psma\csv_config.txt"
$ConfigurationParameter["Environment"] | out-file "c:\psma\csv_config.txt" -append

The resultant file contents for my example shows the Environment, TenantID and TenantName configuration items with their values. The second line in the above example shows getting the value of the Environment configuration item $ConfigurationParameter[“Environment”]

Key Value
--- -----
Environment Dev
TenantID bf4d615f-0a7e-41ed-9a4d-24f42689239a,=1
TenantName ourtenant.onmicrosoft.com

Dev

Granfeldt FIM/MIM PowerShell Management Auxiliary Credentials

The Auxiliary Credentials configuration items are a secondary set of credentials just like the primary credentials on previous versions of the PowerShell Management Agent. The _creds-uname-password-aux.txt output file contains the values with the password as plain text.

Username Aux: MyUserID2
Password Aux: H#llo2

and _creds-aux.txt contains the values with the password as secure string.

UserName Password
-------- --------
MyUserID2 System.Security.SecureString

Username, Password, Credentials, Operation Type, Pagesize, PagedImport and Schema Configuration Items

The Username, Password, Credentials, Operation Type, Pagesize, PagedImport and Schema parameters are all the same as they always have been. In my example I have included them to output their values in case you aren’t familiar with them.

Summary

Having a second set of credentials configured on the Management Agent is very beneficial in environments that are connection to SaaS or PasS services. Having the ability to also provide additional Configuration options provides flexibility to parameterize scripts that can then be used across multiple environments, with the values provided from the Management Agent configurations. Enjoy.