One Identity open source projects are supported through One Identity GitHub issues and the One Identity Community. This includes all scripts, plugins, SDKs, modules, code snippets or other solutions. For assistance with any One Identity GitHub project, please raise a new Issue on the One Identity GitHub project page. You may also visit the One Identity Community to ask questions. Requests for assistance made through official One Identity Support will be referred back to GitHub and the One Identity Community forums where those requests can benefit all users.
A Powershell library for One Identity Manager interaction.
- Supported Versions
- Requirements
- Basic usage
- Advanced usage
- Contributing
- License
This library is known to work with One Identity Manager version 8.0x, 8.1x, 8.2x, 9.0x, 9.1x and 9.2x
- Windows PowerShell 5.1
This version is not compatible with Powershell Versions 6 or 7!
The Identity Manager product DLLs
-
By default, the Powershell module with try to load all referenced DLLs from a valid Identity Manager client component installation. This is typically at the default path '
C:\Program Files\One Identity\One Identity Manager'. -
As an alternative method, the referenced DLLs can be placed relative to the Powershell module or you can specify a folder that contains all needed DLLs with parameter
ProductFilePath. -
For a successful connection through the application server you need the following product DLLs:
- Newtonsoft.Json.dll
- NLog.dll
- QBM.AppServer.Client.dll
- QBM.AppServer.Interface.dll
- QBM.AppServer.JobProvider.Plugin.dll
- QER.AppServer.Plugin.dll
- QER.Customizer.dll
- QER.DB.Plugin.dll
- QER.Interfaces.dll
- ServiceStack.Client.dll
- ServiceStack.Common.dll
- ServiceStack.dll
- ServiceStack.Interfaces.dll
- ServiceStack.Text.dll
- System.Memory.dll
- System.Numerics.Vectors.dll
- System.Runtime.CompilerServices.Unsafe.dll
- VI.Base.dll
- VI.DB.dll
For convenience there is a script "handle_deps.ps1" that will assist with collecting or cleanup of product dependent DLLs.
It is recommended to use the Application Server connection!
Import-Module .\PSIdentityManagerUtils -Force
After the import, a list of supported authentication modules can be shown. You can find more information about authentication modules in the documentation. Later, a first session can be established by choosing one of the supported authentication modules.
$connectionString = 'url=https://<URL>/AppServer/'
Get-Authentifier -ConnectionString $connectionString
After the module is imported, a first connection (session) can be established. As this is the first connection, it will take some seconds to generate the internal wrapper functions.
The generation for wrapper functions ("New-", "Get-", "Set-" and "Remove-") will be skipped for every disabled table / object type. If an object may have disabled columns, these columns either won't be added as possible parameters.
It may happen that errors occur during the function generation Function ... cannot be created because function capacity 4096 has been exceeded for this scope.. This is a limitation by Powershell. You can workaround this error by skipping the function generation for specific modules by using the parameter -ModulesToSkip during the call of New-IdentityManagerSession. An alternative for that is overwriting the limitation for the maximum function capacity by setting a new value like $MaximumFunctionCount = 10000 just before you import the PSIdentityManagerUtils module.
As opposite, there is a parameter called ModulesToAdd that only adds the corresponding wrapper functions that belongs to the list of given modules.
To completly disable the wrapper function generation use SkipFunctionGeneration.
$connectionString = "User ID=<DBUser-Name>;initial Catalog=<DB-Name>;Data Source=<Server-Name>;Password=<DBUser-Password>;pooling= 'false'"
$authenticationString = 'Module=DialogUser;User=viadmin;Password=<Password>'
New-IdentityManagerSession -ConnectionString $connectionString -AuthenticationString $authenticationString
$connectionString = 'url=https://<URL>/AppServer/'
$authenticationString = 'Module=DialogUser;User=viadmin;Password=<Password>'
New-IdentityManagerSession -ConnectionString $connectionString -AuthenticationString $authenticationString
To deal with special certificate requirements you can provide some extra arguments to the connection string:
$connectionString = 'url=https://<URL>/AppServer/;AcceptSelfSigned=true;AllowServerNameMismatch=true'
As an example to skip wrapper function generation for certain tables / objects use:
New-IdentityManagerSession -ConnectionString $connectionString -AuthenticationString $authenticationString -ModulesToSkip 'EBS','CSM','UCI','AAD'
To get the number of objects in a table use the Get-TableCount method:
Get-TableCount -Name 'DialogDatabase'
To filter the objects to be counted, specify the -Filter property with an approbate sql where clause.
To create a new entity in a generic way use:
$person = New-Entity -Type 'Person' -Properties @{'FirstName' = 'Fritz'; 'LastName' = 'Fuchs' }
Next, a first object can be created. In this example we are going to create a person entry by using one of the generated wrapper functions.
$p1 = New-Person -FirstName 'Fritz' -LastName 'Fuchs'
To get some more details about the person, just call the assigned variable with $p1.
You can get some more details about the available properties by issuing Get-Help New-Person. Also all mandatory fields will be marked by only [<parameter>] and every optional with [[<parameter>]].
An entity can be loaded directly either by the corresponding XObjectKey or by its UID in combination with specifying its type.
$x = Get-Entity -Identity "<Key><T>Person</T><P>0f4de334-38e5-4bdf-bfe0-4ae9690c4f2b</P></Key>"
$y = Get-Entity -Identity "0f4de334-38e5-4bdf-bfe0-4ae9690c4f2b" -Type Person
Instead of loading only one entity, it's also possible to query more of them and get a collection. In the next example, all entities in the Person table that have the same last name "Lustig" are retrieved.
Get-Entity -Type 'Person' -Filter "Lastname = 'Lustig'"
To limit the number of returned entities, you can specify a value for the Parameter -ResultSize. The default value is 1.000 records.
Beside the generic method of loading entities it's also possible to use the typed wrapper functions.
To load an entity by its unique identity keys (UID or XObjectKey) use:
$p = Get-Person -Identity '4782235b-f606-4c2b-9e3e-b95727b61456'
$p.Display
$p = Get-Person -Identity '<Key><T>Person</T><P>4782235b-f606-4c2b-9e3e-b95727b61456</P></Key>'
$p.Display
Also the retrieving of several entities is possible:
# Retrieve all persons with first name Peter and last name Lustig
Get-Person -FirstName 'Peter' -LastName 'Lustig' | Sort-Object -Property Display | Format-Table Display
# Retrieve 15 persons
Get-Person -ResultSize 15 | Sort-Object -Property Display | Format-Table Display
# Retrieve all Departments there name starts with letter V
Get-Department -FilterClause "DepartmentName like 'V%'" | Sort-Object -Property Display | Format-Table Display
To limit the number of returned entities, you can specify a value for the Parameter -ResultSize. The default value is 1.000 records.
You can modify a value of an entity like that.
Set-Entity -Type Person -Identity "0f4de334-38e5-4bdf-bfe0-4ae9690c4f2b" -Properties @{'LastName' = 'Schmidt'}
To change or modify an object you have to use the "Set-" functions. This can be used for single object operations as well as for pipeline operations.
For example to add a value to column CustomProperty01 of every Department:
Get-Department |Set-Department -CustomProperty01 'xyz'
Foreign keys can be handled either by the string representation of the primary key or directly with an entity:
# Assign a manager to a department / the UID_Person must be known
Get-Department -DepartmentName 'D1' |Set-Department -UID_PersonHead 'a5a169ab-eac3-4292-9b05-20eeba990379'
# Assign a manager to a department by its entity
$p1 = Get-Person -CentralAccount 'marada'
Get-Department -DepartmentName 'D1' |Set-Department -UID_PersonHead $p1
It's even possible to modify a loaded entity directly. In the following sample a person entity is loaded, the last name as well as the direct department assignment is changed:
# Load person with last name Lustig
$p1 = Get-Person -Lastname 'Lustig'
# Modify the last name of that loaded person
$p1.Lastname = 'Lustiger'
# Load Accounting department
$d1 = Get-Department -FilterClause "DepartmentName = 'Accounting'"
# Set Accounting department
$p1.UID_Department = $d1
To delete an entity from the database you have to call the Remove-Entity method. In the first place, this will only mark the entity for deletion and not delete it directly. For a direct deletion you have to specify the parameter -IgnoreDeleteDelay as well.
Remove-Entity -Type Person -Identity "0f4de334-38e5-4bdf-bfe0-4ae9690c4f2b"
Objects can be removed by there corresponding Remove- function. You have to specify either an identity (UID or XObjectKey) or an entity directly. Pipeline operations are supported.
Remove-Person -Identity '4307b156-3c48-4153-b0de-89e79bba06ee'
Remove-Person -Identity '<Key><T>Person</T><P>1b3441fa-c2d3-4a18-9fc2-40d364039234</P></Key>'
Get-Entity -Type 'Person' -Filter "Lastname = 'Lustig'" |Remove-Person -IgnoreDeleteDelay
Both methods support pipelining for entities.
To get a list of possible events to trigger for a specific entity use:
Get-ImEvent -Entity $p1
After you know the name for the event to trigger, you can fire it like:
Invoke-ImEvent -Entity $p1 -EventName "CHECK_EXITDATE"
It's possible to pass certain event parameters if needed. Use EventParameters as hash table for that.
The identity manager supports object as well as customizer methods. The following functions support the handling of entities within pipelines.
Get-EntityMethod -Entity $p1
Invoke-EntityMethod -Entity $p1
It's also possible to pass certain method parameters if needed. Use Parameters for that.
The Identity Manager allows you to execute scripts.
Invoke-IdentityManagerScript -Name 'QBM_GetTempPath'
It's good practice to close any database session after usage.
Remove-IdentityManagerSession
Within Identity Manager the usage of session based variables is supported. You can find more information in the documentation.
If you define a custom session variable, you must remove it again afterward. Otherwise it remains for the rest of the session and, in certain circumstances, the wrong processes can be generated.
# Get the session
$sessionToUse = $Global:imsessions[$Global:imsessions.Keys[0]].Session
# Add variable
$sessionToUse.Variables.Put('Variable_1', 'Value of variable 1')
# Query a variable
$sessionToUse.Variables['Variable_1']
# Remove a variable
$sessionToUse.Variables.Remove('Variable_1')
The Identity Manager powershell utils allows you to deal with multiple database connections at the same time. For every session you have to specify a unique prefix for that specific connection:
New-IdentityManagerSession -ConnectionString $connectionString -AuthenticationString $authenticationString -Prefix db1
With that, the automatically generated functions will get there prefix as well. E.g.: New-Person will become New-db1Person.
Using different versions of Identity Manager is not supported and the Identity Manager powershell utils must not be used as a transport tool.
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are highly appreciated.
- Fork this project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
It may happen that errors occur. In this case it's possible to activate debug messages. This can be activated in file Private\common.ps1. Change line three from $DebugPreference = 'SilentlyContinue' to $DebugPreference = 'Continue'. If you open a GitHub issue please add any Debug messages as well.
Tests can be started by the command: Invoke-Pester -Output Detailed
Distributed under the One Identity - Open Source License. See LICENSE for more information.