As announced in Delegate365 changelog version 8.1-Many new features, this version brings PowerShell support for administrators. All Delegate365 admins can use the PowerShell module if the access is granted by Portal Admins. See the How-To here.
Note that for using the Delegate365 PowerShell module, Delegate365 version 8.1 (or higher) is required. The version number can be found in the status line at the end of the page in the Delegate365 portal, see the screenshot below.
PowerShell description at GitHub
To see the available PowerShell commands and to get the description, open GitHub.com/Delegate365/PowerShell.
Installation of the Delegate365 PowerShell module
The Delegate365 module must be downloaded and installed once on a client computer from the PowerShell Gallery. The Delegate365 module can be used on any platform supporting the .NET standard 2.0 library. To overwrite an existing Delegate365 PowerShell module with the latest version, add the -Force parameter.
Install-Module Delegate365 -Force
Once installed on a client machine, the Delegate365 command lets can be used. In case of any errors when installing, please see the Prerequisites.
Get the Administrator's key from Delegate365
Every Administrator can use the Delegate365 PowerShell commands if the Portal Admins hand over the personal access key to the admin. As Portal Admin, you get that key for an admin in the Administration / Administrators menu. Select the desired user and open Edit admin as shown here.
In the Admin panel, scroll down to the bottom. Here you find the WebAPIKey. That works like a password for that specific admin. Hand over that password to the admin who wants to use the Delegate365 PowerShell module (or the Delegate365 API). Ensure that the admin is set to Active = Yes and that there is a WebAPIKey existing.
You can re-generate an new API key anytime. If you want to disable PowerShell access for an admin who already has access, regenerate a new WebAPIKey (and don't hand it over to the admin…), that's it. If an admin left the organization, and you completely want to disable him or her, set the Active switch to No (or delete that admin). Click Save afterwards.
Again, you can generate a new WebAPIKey anytime. This key works as a password for a Delegate365 admin when working with the PowerShell module or the API.
Connect to Delegate365
After the Delegate365 PowerShell module is installed, it can be used as here. Hand over the WebAPIKey to the admin. An admin needs his WebAPIKey and the URL of the Delegate365 portal. Replace the values of $baseUrl and $apikey in the script below with your own data. Then, use the Connect-Delegate365 command to connect to your Delegate365 instance and use the cmdlets afterwards. The following script connects to an Delegate365 instance and reads all users of OU Seattle with Get-DUser. Then, the connection is closed with Disconnect-Delegate365.
# Ensure that the module is loaded Import-Module Delegate365 # Connect to your Delegate365 instance $baseUrl = "https://<your company name>.delegate365.com" $apiKey = "<your administrator's API key>" Connect-Delegate365 -WebApiSasKey $apiKey -WebApiBaseUrl $baseUrl # Run commands Get-DUser -OU 'Seattle' # Close the session Disconnect-Delegate365
If you run a script like above, the output should look similar as here within Visual Studio Code (with installed PowerShell extension).
The Delegate365 commands can be combined with any other PowerShell commands. So, you could output all (entitled) users to a CSV file and then work with these users and other Office 365 commands as needed. New-DAdministrator-Sample.ps1 shows another sample how to work with the Delegate365 PowerShell.
Permissions
It's important to understand that every Admin could use Delegate365 PowerShell with his WebAPIKey, but only within his scope (OU's). There exists a switch "Is PowerShell Administrator" in the Permission Policies that distinguishes, if an admin can see and use all data from Delegate365, or just "his own" data. The following screenshot shows that setting in the Policies / Permission Policies menu (see more about these policies at New permission policies).
If the switch "Is PowerShell Administrator" is set to Yes, all admins that are assigned to that permission policy see all data in Delegate365. If that switch is set to No, the OU scoping is active, and these admins see only data that is assigned to their OU's. So, the PowerShell commands check, what data may be delivered to that admin, in the same way as the Delegate365 web portal. Portal Admins define, if scope admins shall have full access or not by defining the underlying permission policy for their admins. Usually, the OU restrictions make sense for scope admins and the permission policy should be set to "Scope Admin" (click that button and adapt then if needed) which sets the "Is PowerShell Administrator" to No.
Logging
Another benefit of using Delegate365 PowerShell is, that the operations of admins made though PowerShell are protocolled in the Audit Logs as well. Again, this is consistent with the Delegate365 web portal and operations can be tracked.
Get-Help
Check out GitHub.com/delegate365/PowerShell for the latest news and documentation regarding Delegate365 PowerShells. This is the place where all PS-documentation will be done and updated.
Within PowerShell, execute Get-Command -Module Delegate365 to see a list of available commands in this module. All Delegate365 commands have a "D"-character (or the word Delegate365) included after the method to be not confusable with other PowerShell commands, e.g. Get-DUser for Get-Delegate365User.
Get-Help command-name delivers for information about a specific command, as this example: Get-Help Get-DResource
Add the "-Examples" parameter as Get-Help command-name -examples for samples how to use a specific command as here.
More Delegate365 PowerShell
Advanced PowerShell users will find out the functionality quickly. The Delegate365 cmdlets work in the same way as other PowerShell modules. More samples of using Delegate365 PowerShell will follow in the next weeks. We also plan to extend that if needed in future. We hope you like this new functionality to automate with scripts.
Happy automating with Delegate365!