NITRO-Anmeldung an NetScaler und Console: die zwei Unterschiede
NITRO ist die REST-Schnittstelle der NetScaler und der NetScaler Console. Die Anmeldung sieht an beiden gleich aus: derselbe Pfad /nitro/v1/config/login, dasselbe JSON mit Benutzername und Kennwort. Eine Anmeldefunktion, die an der einen Seite funktioniert, scheitert an der anderen trotzdem sofort. Es sind genau zwei Unterschiede: wie der Body aussieht und wo das Sitzungstoken zurückkommt. Beide habe ich an meiner Testinstanz gemessen, NetScaler 14.1 und NetScaler Console 14.1.
Unterschied 1: der Body der NITRO-Anmeldung
| Ziel | Body | Antwort bei Erfolg |
|---|---|---|
| NetScaler | reines JSON: {"login":{...}} | HTTP 201 |
| NetScaler Console (früher ADM) | object= vor dem JSON: object={"login":{...}} | HTTP 200 |
Der Content-Type ist in beiden Fällen application/json. Die jeweils andere Form beantworten beide Seiten mit einer eindeutigen Meldung im Body:
NetScaler mit object=: HTTP 400 {"errorcode": -1, "message": "Invalid payload format. Default format is json"}
Console ohne object=: HTTP 400 {"errorcode": 10008, "message": "Invalid POST request, payload should start with object="}
Die Regel gilt für jeden Body, nicht nur für die Anmeldung. Auch die Abmeldung an der Console erwartet object={"logout":{}}.
Unterschied 2: wo das Sitzungstoken zurückkommt
Nach der Anmeldung braucht jede weitere Anfrage das Token. Beide Seiten liefern es, aber an anderer Stelle und unter anderem Namen:
| NetScaler 14.1 | NetScaler Console 14.1 | |
|---|---|---|
| Token im Antwort-Body | sessionid | login[0].sessionid |
| Cookie in der Antwort | sessionid, Pfad /nitro/v1 | SESSID, Pfad /, HttpOnly, Secure |
Cookie NITRO_AUTH_TOKEN=<token> von Hand gesetzt | angenommen | angenommen |
Die NITRO-Dokumentation beschreibt als Antwort Set-Cookie: NITRO_AUTH_TOKEN=<token>; path=/nitro/v1. Meine Testinstanz setzt das Cookie unter dem Namen sessionid, nimmt NITRO_AUTH_TOKEN in Anfragen aber an. Für PowerShell spielt der Name keine Rolle: -SessionVariable übernimmt jedes Cookie, das der Server setzt, und schickt es bei -WebSession wieder mit.
Für ein Skript heißt das: den Body je Ziel wählen und das Cookie von -SessionVariable verwalten lassen. Den Cookienamen muss es dann nicht kennen.
Beide Anmeldungen in PowerShell
Der folgende Ablauf läuft unverändert in Windows PowerShell 5.1 und PowerShell 7. Der Benutzername geht ohne Domänenanteil an NITRO, deshalb Split('\')[-1].
$cred = Get-Credential
$login = @{ login = @{
username = $cred.UserName.Split('\')[-1]
password = $cred.GetNetworkCredential().Password
} } | ConvertTo-Json -Compress
# NetScaler: reines JSON
$adc = Invoke-RestMethod -Method Post -Uri 'https://netscaler.example.local/nitro/v1/config/login' `
-Body $login -ContentType 'application/json' -SessionVariable adcSitzung
# Console: object= vor dem JSON
$con = Invoke-RestMethod -Method Post -Uri 'https://console.example.local/nitro/v1/config/login' `
-Body "object=$login" -ContentType 'application/json' -SessionVariable conSitzung
Was dabei zurückkommt, zeigt dieser Vergleich:
'NetScaler: Token unter .sessionid = {0}, Cookie {1}' -f [bool]$adc.sessionid,
($adcSitzung.Cookies.GetCookies([uri]'https://netscaler.example.local/nitro/v1/') | ForEach-Object { "$($_.Name) (Pfad $($_.Path))" })
'Console: Token unter .login[0].sessionid = {0}, Cookie {1}' -f [bool]$con.login[0].sessionid,
($conSitzung.Cookies.GetCookies([uri]'https://console.example.local/nitro/v1/') | ForEach-Object { "$($_.Name) (Pfad $($_.Path))" })
NetScaler: Token unter .sessionid = True, Cookie sessionid (Pfad /nitro/v1)
Console: Token unter .login[0].sessionid = True, Cookie SESSID (Pfad /)
Ab hier sind beide Seiten gleich zu bedienen:
(Invoke-RestMethod -Uri 'https://netscaler.example.local/nitro/v1/config/nsversion' -WebSession $adcSitzung).nsversion.version.Split(':')[0]
(Invoke-RestMethod -Uri 'https://console.example.local/nitro/v1/config/mps' -WebSession $conSitzung).message
NetScaler NS14.1
Done
Für Werkzeuge außerhalb von PowerShell reicht das Token aus dem Body als Cookie NITRO_AUTH_TOKEN:
$token = $adc.sessionid
curl.exe -s -H "Cookie: NITRO_AUTH_TOKEN=$token" https://netscaler.example.local/nitro/v1/config/nsversion
Ohne Sitzung: Anmeldung im Header
Für einzelne Abfragen geht es auch ohne Anmeldung vorab. NITRO nimmt Benutzername und Kennwort in den Headern X-NITRO-USER und X-NITRO-PASS an, das Kennwort geht dann mit jeder Anfrage über die Leitung. An meiner Testinstanz funktionierte das an NetScaler und Console gleichermaßen:
$kopf = @{
'X-NITRO-USER' = $cred.UserName.Split('\')[-1]
'X-NITRO-PASS' = $cred.GetNetworkCredential().Password
}
(Invoke-RestMethod -Uri 'https://netscaler.example.local/nitro/v1/config/nsversion' -Headers $kopf).nsversion.version.Split(':')[0]
Eine Grenze gibt es: Über den API-Proxy der Console geht das nicht. Dort kam mit Header-Anmeldung und Proxy-Header HTTP 401 mit Invalid Session ID in APIProxy request. Der Proxy braucht die Sitzung.
Über die Console zur Instanz: der Proxy-Header
Die Console reicht NITRO-Anfragen an verwaltete Instanzen weiter, wenn ein Header die Instanz benennt. Dessen Schreibweise hat sich zwischen den Releases geändert; die Einzelheiten und die Fehlerbilder stehen im Beitrag Instanz nicht verfügbar beim ADM-Proxy. An meiner Testinstanz mit Console 14.1 Build 72.57 und nach dem Update auf 74.34 ergab sich, jeweils in einer frischen Sitzung:
| Header | Ergebnis |
|---|---|
MPS-API-PROXY-MANAGED-INSTANCE-IP | Antwort der Instanz |
_MPS_API_PROXY_MANAGED_INSTANCE_IP allein | HTTP 200 mit errorcode 10005, Invalid Resource im Body |
| beide zusammen | Antwort der Instanz |
Der Fehler kommt hier mit HTTP 200. Invoke-RestMethod löst dabei keine Ausnahme aus; erkennbar ist er nur am errorcode im Body.
Beim Proxy in PowerShell ist eine Eigenheit zu beachten: Header, die zusammen mit -WebSession übergeben werden, speichert PowerShell im Sitzungsobjekt und schickt sie bei jeder weiteren Anfrage mit. Ohne Gegenmaßnahme landen danach auch Anfragen, die an die Console selbst gehen sollen, bei der Instanz. Deshalb die Proxy-Header nach dem Aufruf wieder entfernen:
$proxy = @{
'MPS-API-PROXY-MANAGED-INSTANCE-IP' = '192.0.2.10' # NSIP der verwalteten Instanz
'_MPS_API_PROXY_MANAGED_INSTANCE_IP' = '192.0.2.10'
}
(Invoke-RestMethod -Uri 'https://console.example.local/nitro/v1/config/nsversion' `
-WebSession $conSitzung -Headers $proxy).nsversion.version.Split(':')[0]
# Die Header bleiben im Sitzungsobjekt haengen: vor dem naechsten Konsolenaufruf entfernen
foreach ($name in @($proxy.Keys)) { $null = $conSitzung.Headers.Remove($name) }
Abmelden
Auch die Abmeldung folgt Unterschied 1. Beide Seiten nehmen POST auf /nitro/v1/config/logout an, die Console wieder mit object=:
$null = Invoke-RestMethod -Method Post -Uri 'https://netscaler.example.local/nitro/v1/config/logout' `
-Body '{"logout":{}}' -ContentType 'application/json' -WebSession $adcSitzung
$null = Invoke-RestMethod -Method Post -Uri 'https://console.example.local/nitro/v1/config/logout' `
-Body 'object={"logout":{}}' -ContentType 'application/json' -WebSession $conSitzung
'abgemeldet'
An der Console beendet nur das Cookie SESSID die Sitzung, und genau das schickt -WebSession mit. Mit dem Cookie NITRO_AUTH_TOKEN antwortet die Console auf die Abmeldung mit HTTP 400 und Invalid Request, die Sitzung bleibt dann gültig. Abfragen nimmt sie mit NITRO_AUTH_TOKEN dagegen an. Gemessen an Console 14.1 Build 72.57 und 74.34.
Alle Beispiele verbinden sich über HTTPS mit dem vollständigen Namen und regulärer Zertifikatsprüfung. Kommt dabei „Verbindung abgelehnt“ statt einer Antwort, liegt es am Port und nicht an der Anmeldung; wie sich das eingrenzen lässt, zeigt der Beitrag Verbindung abgelehnt heißt falscher Port, nicht Zertifikat.
Was du dir merkst
NetScaler will reines JSON, die Console
object=davor. Das Token steht beim NetScaler untersessionid, bei der Console unterlogin[0].sessionid.Mit
-SessionVariableund-WebSessionist der Cookiename egal. Header-Anmeldung reicht für Einzelabfragen, der Proxy der Console braucht eine Sitzung, und Proxy-Header gehören nach dem Aufruf wieder aus dem Sitzungsobjekt.
Quellen
- Performing Basic NetScaler Operations, NITRO-API-Referenz 14.1: Anmeldung,
NITRO_AUTH_TOKEN,X-NITRO-USER/X-NITRO-PASS, Abmeldung - NetScaler Console als API-Proxy-Server, Citrix-Dokumentation: Proxy-Header

Hinterlasse einen Kommentar
An der Diskussion beteiligen?Hinterlasse uns deinen Kommentar!