Overview
For users just getting started writing PowerShell scripts utilizing Privilege Secure for Access Management’s PowerShell module and API, I wanted to post a simple script that teaches the basics. All we’re going to be doing here is a GET to find the version of the software we’re running.
For scripts planned to run on a schedule, configuring an Application User in NPS to run the script is advised. This guide uses an NPS admin user for the sake of demonstration and simplicity.
Install the PowerShell Module
On the primary NPS server, install SbPAMPowershellModules.msi from the Extras folder included with the NPS download.
Executing the Script to Get the NPS Version
You can run the script as an NPS admin from any workstation that can reach NPS’s API.
A simple test is, while logged-in to NPS, is to navigate to https://localhost:6500/api/v1/version in your web browser (replacing “localhost” with the hostname or IP you use to access NPS).
If you see the version number, then you can access the API as needed.
Now we’re going to do the same thing, but via PowerShell.
The script below is a good framework to start on any NPS scripting project, although in this example we’re running PowerShell outside of NPS (PowerShell can also be used as a custom pre/post-session action in NPS activities).
Here’s a summary of what the script is doing, from top to bottom:
-
A
paramblock to collect necessary info on script execution, such as the URL to access NPS, an NPS admin’s credentials, and the NPS admin’s MFA code (if the user does not use MFA, a placeholder value must still be supplied) -
An import for the NPS PowerShell module (
SbPAMAPI) -
A function to renew the granted token (this should be run at the top of any loops that continuously call NPS’ API)
-
The meat of the script:
- Create a web session
- Get a user token
- Renew the token
- Call the API endpoint:
/api/v1/version - Write the result to the PowerShell console
param(
[Parameter(Mandatory)]
[string]$npsUri,
[Parameter(Mandatory)]
[PSCredential]$userCred,
[Parameter(Mandatory)]
[string]$userCode
)
Import-Module SbPAMAPI -Force
# FUNCTION: Token renewal
function Get-RenewToken {
param(
[Parameter(Mandatory)]
[string]$token,
[Parameter(Mandatory)]
[string]$npsUri
)
$tokenObj = Convert-SbPAMToken $token
$expiration = Get-Date -UnixTimeSeconds $tokenObj.exp
if ($expiration -lt (Get-Date).AddMinutes(7)) {
Write-Host "$(Get-Date) Refreshing token"
$token = Invoke-SbPAMRest -Uri "$($npsUri)/api/v1/UserToken" -Token $token -ErrorAction Stop -SkipCertificateCheck
}
return $token
}
# Create web session
$webSession = New-Object Microsoft.PowerShell.Commands.WebRequestSession
# Get user token
$global:token = Get-SbPAMToken -Credential $userCred -Uri $npsUri -WebSession $webSession -SkipCertificateCheck -ErrorAction Stop
$global:token = Get-SbPAMMfaToken -Uri $npsUri -Token $token -Code $userCode -WebSession $webSession -SkipCertificateCheck -ErrorAction Stop
# API call
$global:token = Get-RenewToken -token $global:token -npsUri $npsUri
$result = Invoke-SbPAMRest -Uri "$($npsUri)/api/v1/Version" -Token $global:token -ErrorAction Stop -SkipCertificateCheck
Write-Host "Privilege Secure for Access Management Version: $($result)"