Christoph Biesinger hat ein Script erarbeitet, welches in einer Art Tutorial ein paar Konzepte der Nitro API, Powershell und des Arbeitsprozesses verdeutlich. Das Script „unlockAAAUser.ps1“ entsperrt einen User am NetScaler und fragt vorher die notwendigen Parameter der NetScaler IP, Credentials und des zu entsperrenden Users ab. Im Folgenden wird das Schritt für Schritt erklärt. Das komplette Script findet ihr am Ende des Beitrags.
1.)
Um die Nitro API zu verwenden, brauchen wir zuerst die Nitro Bibliothek, welche von jedem NetScaler unter Downloads geladen werden kann. Da wir ein PowerShell-Script schreiben, nehmen wir die Version „NITRO API SDK for C#“. Die im Subordner lib befindlichen Bibliotheken brauchen wir für unser Script.
2.)
Der erste Abschnitt des Scripts beinhaltet die Parameterabfrage, weshalb wir mit [CmdletBinding()] das PowerShell Parameter Binding aktivieren. Dadurch übergeben wir die Werte der Parameter direkt an Variablen. Diese legen wir wegen unserem Anwendungsfall als Pflichtfelder fest und definieren ihren Datentyp. Für das Passwort verwenden wir den Datentyp SecureString um die Sicherheit etwas zu erhöhen.
[CmdletBinding()] param( [Parameter(Mandatory=$True)][String]$IPAddress, [Parameter(Mandatory=$True)][String]$Username, [Parameter(Mandatory=$True)][SecureString]$Password, [Parameter(Mandatory=$True)][String]$AAAUserName )
3.)
Als nächstes legen wir eine Funktion Main und das Exception Handling an, dadurch könnten wir den Code später erweitern und haben allgemein sauberen Code.
function Main {
try {
} catch {
$ErrorMessage = $_.Exception.Message
$FailedItem = $_.Exception.ItemName
LogWrite "[-] Error while unlocking user! ErrorMessage: $ErrorMessage"
Break
}
}
Main
4.)
Nun importieren wir die Nitro API in unser Powershell Script. Da die Nitro Bibliothek und unser Script im gleichen Ordner sind, benötigen wir nur diesen einfachen Befehl.
Add-Type -Path "nitro.dll"
5.)
Im nächsten Abschnitt wandeln wir den Datentyp des Passworts von einem SecureString in einen String um, damit wir diesen zum späteren Anmelden nutzen können. Dafür wandeln wir in einem Zwischenschritt den SecureString in einen Binary String und anschließend in einen String um.
$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($Password) $password = [Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
6.)
Nachdem wir diese Vorarbeit geleistet haben, melden wir uns am NetScaler an. Dafür definieren wir in der Variablen $nitrosession ein nitro_service Object, welches die IP Adresse des NetScalers beinhaltet. Da das Nitro Protokol die REST API verwendet, ist die Kommunikation per http. Nun können wir das Objekt mit unseren Credentails nutzen um uns am NetScaler anzumelden indem wir die Methode login verwenden. Nach dem Abschluss dieser Zeilen sind wir am NetScaler angemeldet und können Befehle ausführen.
$nitrosession = New-Object com.citrix.netscaler.nitro.service.nitro_service($IPAddress, "http") $session = $nitrosession.login($Username, $password)
7.)
Wie im vorherigen Punkt bereits angeschnitten, ist Powershell und die Nitro API objektbasiert. Das bedeutet, dass wir immer ein vordefiniertes Objekt am NetScaler oder lokal verändern oder erstellen. Da wir in unserem Anwendungsfall einen existierenden User entsperren wollen, brauchen wir die genaue Spezifikation des entsprechenden Objekts. Da die Nitro API quelloffen ist, können wir im Sourcecode nach einem passenden vordefinieren Objekt suchen. Tatsächlich werden wir dabei unter src/com/citrix/netscaler/nitro/resource/config/aaa fündig und können das Objekt aaauser betrachten.
Dabei sehen wir, dass das Objekt das Attribut username und die Methode unlock besitzt, welche für uns nützlich sind. Mit diesen Informationen erstellen wir nun ein neues lokales aaauser Objekt in der Variablen $aaauser und setzen das username Attribut auf den zu entsperrenden User.
$aaauser = New-Object com.citrix.netscaler.nitro.resource.config.aaa.aaauser $aaauser.username = $AAAUserName
8.)
Um den User schlussendlich zu entsperren, nutzen wir die Methode unlock mit der Session und dem aaauser Objekt. Anschließend geben wir das Ergebnis der Aktion auf der Konsole aus.
$result = [com.citrix.netscaler.nitro.resource.config.aaa.aaauser]::unlock($nitrosession, $aaauser) Write-Host $result.message
9.)
Im letzten Schritt schließen wir die vorher erstellte Session.
$session = $nitrosession.logout()
[CmdletBinding()]
param(
[Parameter(Mandatory=$True)][String]$IPAddress,
[Parameter(Mandatory=$True)][String]$Username,
[Parameter(Mandatory=$True)][SecureString]$Password,
[Parameter(Mandatory=$True)][String]$AAAUserName
)
function Main {
try {
Add-Type -Path "nitro.dll"
$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($Password)
$password = [Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
$nitrosession = New-Object com.citrix.netscaler.nitro.service.nitro_service($IPAddress, "http")
$session = $nitrosession.login($Username, $password)
# Create aaauser resource
$aaauser = New-Object com.citrix.netscaler.nitro.resource.config.aaa.aaauser
$aaauser.username = $AAAUserName
$result = [com.citrix.netscaler.nitro.resource.config.aaa.aaauser]::unlock($nitrosession, $aaauser)
Write-Host $result.message
$session = $nitrosession.logout()
} catch {
$ErrorMessage = $_.Exception.Message
$FailedItem = $_.Exception.ItemName
LogWrite "[-] Error while unlocking user! ErrorMessage: $ErrorMessage"
Break
}
}
Main
