blog.atwork.at

news and know-how about microsoft, technology, cloud and more.

Delegate365 PowerShell

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.

image

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.

image

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.

image

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).

image

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).

image

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.

SNAGHTML49a6797b

Get-Help command-name delivers for information about a specific command, as this example: Get-Help Get-DResource

image

Add the "-Examples" parameter as Get-Help command-name -examples for samples how to use a specific command as here.

image 

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!

Comments (1) -

  • Toni Pohl

    10/22/2019 8:01:10 AM |

    Hi Stanislav,
    thanks for your input and the offline communication.
    As discussed, any secret should be stored in a safe place, e.g. when using Azure, Key Vault would be the best place to save passwords or API keys. The user is responsible for a for a trusting handling and usage of the data.
    A Delegate365 Rest API is currently not available, but it will be in the near future. ;) Here, we like to get use cases that make sense, such as provision a user or a group.
    hth & br, Toni

Loading