OS4X Enterprise user import via Microsoft Active Directory
Active Directory user synchronization
OS4X offers a script to export user information from the connected Microsoft Active Directory and export the data into an XML file which is then supported by the user import function of OS4Xapi.
The functionality consists of two partners:
- Export of user data from AD, written to an XML file.
- Import of the given XML file via OS4Xapi.
You can skip the export of the AD data for crafting an own user data export.
Requirements
PowerShell requirements
In order to be able to run unsigned PowerShell scripts from OS4X, you must change the execution policy in a PowerShell started in administrative mode:
Set-ExecutionPolicy -ExecutionPolicy Unrestricted
The module for Active Directory is required for execution of the script. If not installed, you can install it in an administrative PowerShell:
Get-WindowsCapability -Online | Where-Object {$_.Name -like "*ActiveDirectory.DS-LDS*"} | Add-WindowsCapability -Online
On Linux, it may be required to install the AD module. For this, you must be able to download either directly or via HTTPS proxy:
pwsh -Command 'Install-Module -Name PSWSMan' pwsh -Command 'Install-WSMan'
OS4X
- The server running the import script must have PHP installed for CLI.
- A defined "own company" must be set.
Export of AD data
Configuration
The header of the PowerShell script contains variables to be changed. These are:
$GroupNames: A list of group for export. All members of these groups are exported.$OutputFilename: Absolute path to the output XML file.$Debug: Write more debug output to the console.
In case of specialities in Active Directory schema, you can define with the following variables which field matches the required OS4X field. The defaults are (names are self-explaining):
$OS4X_Firstname = "GivenName"$OS4X_Lastname = "Surname"$OS4X_Telephone = "telephoneNumber"$OS4X_Email = "mail"$OS4X_Username = "SamAccountName"$OS4X_Street = "StreetAddress"$OS4X_ZIPCode = "PostalCode"$OS4X_City = "l"$OS4X_Department = "Department"$OS4X_CountryAlpha2 = "Country"$OS4X_ObjectGUID = "objectGUID"
The country field referred by OS4X_CountryAlpha2 follows the ISO 3166-1 alpha-2 definition of countries and is supported by at least Windows Server 2022 AD schema.
Execute command
On a client connected to the target AD, execute the PowerShell script as a user who is allowed to crawl the AD data:
powershell -File "\\tsclient\Active Directory\OS4X AD-Export.ps1"
Import of user data via XML
Use the OS4Xapi in command line mode:
php /var/www/html/os4x/os4xapi/index.php admin usersync "file=/opt/os4x/tmp/AD-user-export.xml"
Parameters
file: Path of the user XML file (either absolute or available from relative path).disableUnavailable: "true" or (default) "false": Deactivate all users with a UUID in the reference field of the own company. Manually created users are not affected.
Logging
All logs are being added to the configured OS4Xapi CLI logfile.