This blog post is part of a series of posts that describe how to build an Active Directory Help Desk tool with PowerShell Universal. Here is a listing of other posts in this series.
The full source code can be found on our template repository.
In this post, we will look at how to reset passwords with PowerShell Universal. This post will cover how to integrate Universal Dashboard with Universal Automation. We will create a new Universal Automation script that takes several parameters. We will create a new form on our Active Directory Help Desk portal and start a Universal Automation job using the form. We will also look at how to layout controls on the page using a grid.
Creating a Universal Automation Script
Universal Automation enables the ability to run scripts either ad hoc or on a schedule. In this section, we will create a new Universal Automation script with four parameters used for resetting a password.
To define parameters in Universal Automation, you need to define a param block at the top of the script. You can choose to define the parameter types and additional metadata that may be used to running the script. In this example, we have a parameter for the identity of the account, the new password, whether to unlock the account and whether to require the user change their password on next logon.
The identity and password are defined as strings and the unlock and ChangePasswordOnLogon parameters are defined as switch parameters. Universal 1.2 does not yet support SecureString parameters but will be available in a future version.
Once you have created your script, you can now run it by clicking the run button.
Universal Management API Integration
In order to run a script from a dashboard we need to integrate with the Universal Management API. The Management API is used to configure Universal as well as start scripts and report progress. We will need to ensure that our users have access to the API so that they can call the API from our dashboard.
To access the API, users will require an App Token. App Tokens can be granted manually on the App Token page underneath the Security settings.
Alternatively, you can assign App Tokens, if the user does not already have an active token, during logon to a dashboard. This value currently isn’t available in the UI but can be set on the Add-PSUDashboard cmdlet in the configuration script dashboards.ps1. The App Token will automatically have the roles that have been either assigned or granted via Policies.
Updating the Help Desk Dashboard
Now that the user has an app token to access the Universal Management API, we can update the dashboard to include a new form to invoke our script. The first step is to layout our page using the Grid component of Universal Dashboard v3. The grid allows you to organize components based on a 12-column system that allows you to define column sizes and rows using the New-UDGrid component.
Rows of the grid use the Container switch parameter while columns will specify a Size. The Size needs to be between 1 and 12. For our grid, we will specify a size of 6 which will take up half of the page.
For our second input form control, we will put it into another grid column taking up the other half of the page. The next input form will be slightly more complex than our View User form. This form will take the four parameters that are required by our Reset Password script. We will pass these parameters to Invoke-UAScript. Invoke-UAScript supports dynamic parameters so you can just specify the parameters to the script as additional parameters to the cmdlet call.
We will use Tee-Object to store the job object for checking status after waiting for the job to complete.
Wait-UAJob will wait for the job to complete and then continue on executing the OnSubmit scriptblock. After the job completes, we will use Get-UAJob to return the status of the job. Then we will check it. If it succeeds we will toast the user with that information. If it fails, we will gather the job output and show it to the user in a toast.
Using the Reset Password Tool
Now that our tool has been completed, you users can now login and reset passwords using the Universal Dashboard web page we created.
Although it would be possible to achieve the same functionality with Universal Dashboard alone, since we are using Universal Automation, we can audit each invocation of the job. Viewing the jobs will show you the output from each run as well as the user that was attempting to run the jobs.
In this post, we looked at how to integrate Universal Dashboard with Universal Automation to create a Reset Password tool for Active Directory. You can download the full script on our template repository.