App-Tokens

Sie können PowerShell Universal App-Token sowohl mit benutzerdefinierten API-Endpunkten als auch mit der Management-API verwenden. Die Management-API verwendet die Standardrollen Administrator, Operator und Reader. Die benutzerdefinierten API-App-Token können sowohl benutzerdefinierte als auch integrierte Rollen nutzen.

Sie können App-Token über die Admin-Konsole gewähren oder die Management-API direkt verwenden.

Admin-Konsole

Um ein Token in der Admin-Konsole zu gewähren, navigieren Sie zu Security \ Tokens. Klicken Sie auf die Schaltfläche Create App Token, um ein App-Token zu gewähren.

Wenn Sie auf Create App Token klicken, können Sie in einem Dialogfeld die Identität, Rolle und Ablaufzeit des Tokens angeben.

App-Token-Dialog

Management-API

Sie können Benutzern App-Token auch über die Management-API gewähren. Um ein App-Token programmgesteuert über die API zu gewähren, können Sie wie folgt vorgehen:

PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/api/v1/signin -Method POST -Body (@{ username = 'admin'; password = 'test' } | ConvertTo-Json) -SessionVariable Session -ContentType 'application/json'
PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/api/v1/apptoken/grant  -WebSession $Session

id          : 3
token       : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2Ns
              YWltcy9uYW1lIjoiYWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoI
              joiYjJlOGM4MDktMjE0NS00NjhhLWI4NTEtYjU0MjVhZDgzOTQ2Iiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2
              hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6WyJBZG1pbmlzdHJhdG9yIiwiT3BlcmF0b3I
              iLCJSZWFkZXIiXSwibmJmIjoxNTkzMTkyMjY1LCJleHAiOjE2MjQ3MjgyNjUsImlzcyI6Iklyb25tYW5Tb2Z0d2FyZSIsImF1ZCI6IlBv
              d2VyU2hlbGxVbml2ZXJzYWwifQ.hnKyXe8C4kbrmkeeUFr-LUDjVr-xP7fRWwgClcrnxfc
identity    : @{id=3; name=admin; source=0; role=}
revoked     : False
role        : Administrator, Operator, Reader
created     : 26/06/2020 17:24:25
expiration  : 26/06/2021 17:24:25
revokedDate : 01/01/0001 00:00:00

Administratoren können jedem Benutzer App-Token gewähren, indem sie die Identitäts-ID des Benutzers angeben. Um ein App-Token über die REST-API an eine Identität zu vergeben, benötigt der Benutzer eine definierte Rolle. Die Operator-Rolle definiert den Benutzer, und sein App-Token erhält den Zugriff basierend auf dieser Rolle.

PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/api/v1/apptoken/grant/2  -WebSession $Session

id          : 4
token       : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2Ns
              YWltcy9uYW1lIjoiYWRhbUBpcm9ubWFuc29mdHdhcmUub25taWNyb3NvZnQuY29tIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd
              3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvaGFzaCI6IjhhYWM2NWFmLTA2NmItNDYwNy1hMGJjLTNlYTM2ZDY2YjJmMSIsInN1YiI6Il
              Bvd2VyU2hlbGxVbml2ZXJzYWwiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3J
              vbGUiOiJPcGVyYXRvciIsIm5iZiI6MTU5MzE5MjM2MCwiZXhwIjoxNjI0NzI4MzYwLCJpc3MiOiJJcm9ubWFuU29mdHdhcmUiLCJhdWQi
              OiJQb3dlclNoZWxsVW5pdmVyc2FsIn0.9VYiRFOojFyZMH0E5rwdfFcOkoasXFrrWJDNtYk0PIw
identity    : @{id=2; name=[e-mail]; source=0; role=}
revoked     : False
role        : Operator
created     : 26/06/2020 17:26:00
expiration  : 26/06/2021 17:26:00
revokedDate : 01/01/0001 00:00:00

Rollen

App-Token-Rollen werden direkt im Token selbst zugewiesen. Rollen geben an, was das Token ausführen kann. Sie werden nicht während der Verwendung berechnet, daher funktioniert die Zuordnung von Rollen zu Claims nicht mit App-Token.

Wir empfehlen außerdem, die Anzahl der Rollen innerhalb eines App-Tokens zu begrenzen. Je mehr Rollen dem Token hinzugefügt werden, desto größer wird das Token, was die Leistung verringert oder Probleme mit bestimmten Werkzeugen verursacht, die keine längeren Token-Werte zulassen.

Sie können benutzerdefinierte Rollen mit einem benutzerdefinierten Satz von Berechtigungen verwenden, um die Anzahl der Rollen zu begrenzen und gleichzeitig benutzerdefinierten Zugriff auf die PowerShell Universal-Plattform bereitzustellen. Berechtigungen werden ausgewertet, wenn die Rolle verwendet wird. Das bedeutet, dass die Zuweisung einer benutzerdefinierten Rolle zu einem Token flexibler ist als eine integrierte Rolle, da Berechtigungen zu einer Rolle hinzugefügt oder daraus entfernt werden können, ohne ein neues Token zu generieren.

Migrieren von App-Token

Sie können App-Token mithilfe der Management-API zwischen Systemen migrieren. Dies ist hilfreich bei der Entwicklung für Hochverfügbarkeitsszenarien.

Nachfolgend ein Beispiel für den POST, der erforderlich ist, um ein vorhandenes App-Token in einer beliebigen PSU-Instanz zu erstellen. Beachten Sie, dass der Signaturschlüssel zwischen den Instanzen identisch sein muss. Sie benötigen ein gültiges App-Token im Zielsystem, um die migrierten Token zu erstellen.

Invoke-RestMethod http://localhost:5000/api/v1/apptoken -Method POST -Body (@{
        Token      = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMDhiYTFlMTktMjgyZi00YTRjLWIxZGUtNTY0Zjk3NWU2ODEwIiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6InBvbGljeSIsIm5iZiI6MTYzMzEwNjkzMywiZXhwIjoxNjQwODg2NDgwLCJpc3MiOiJJcm9ubWFuU29mdHdhcmUiLCJhdWQiOiJQb3dlclNoZWxsVW5pdmVyc2FsIn0.GHjJI3kMpcAY1pvOGLWOdPqC2-IPo0-4lJfHZwStmOk'
        Identity   = @{
            Name = 'Admin'
        }
        Role       = 'Administrator'
        Expiration = (Get-Date).AddMonths(6)
    } | ConvertTo-Json) -Headers @{
    "Content-Type"  = "application/json";
    "Authorization" = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMjVjMzFlZTAtMGM4Mi00NzBiLWJkZGYtOGFmOTgxZGI2ZDdmIiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmYiOjE2MzM2NDY5OTgsImV4cCI6MTYzNjIzODk0MCwiaXNzIjoiSXJvbm1hblNvZnR3YXJlIiwiYXVkIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCJ9.jw2VCvtpOWpgnpIUlO8sTdK9Z5RMoWLmvYn0MDmzkNM"   
}

Erweiterte App-Token-Sicherheit

Wenn die erweiterte App-Token-Sicherheit aktiviert ist, sind Token-Werte nur bei der Erstellung zugänglich. Sie werden gehasht und die Datenbank speichert den Hash-Wert anstelle des Tokens. Sie verwenden das Token genauso wie jedes andere Token.

Das Aktivieren der App-Token-Sicherheit macht alle vorhandenen Token ungültig.

Systemtoken

Systemtoken sind eine Möglichkeit, Token für Nicht-Benutzer-Systeme bereitzustellen. Sie sind nicht direkt an die Identität eines Benutzers gebunden. Sie können einen Namen für das Token sowie Ablauf und Rollen angeben.

Signaturschlüssel

Lokaler Signaturschlüssel

Standardmäßig erstellt PowerShell Universal einen Signaturschlüssel basierend auf der Zeichenfolge Jwt \ SigningKey in appsettings.json. Dieser Wert wird zum Kodieren und Dekodieren des Tokens verwendet. Wenn die Signaturschlüssel nicht übereinstimmen, wird das Token als ungültig betrachtet. Das Ändern des Signaturschlüssels macht alle vorhandenen Signaturschlüssel ungültig.

Remote-Signaturschlüssel

Möglicherweise möchten Sie ein OAuth 2.0-Discovery-Dokument zur Validierung des Signaturschlüssels verwenden. Durch die Verwendung eines solchen Remote-Systems stellen Sie sicher, dass die PowerShell Universal-Konfiguration bei einer Änderung der Signaturschlüssel nicht geändert werden muss. Um einen Remote-Signaturschlüssel zu verwenden, setzen Sie den Wert Jwt \ DiscoveryDocument in appsettings.json auf die URL des OAuth 2.0-Metadatendokuments. Beim Laden von PowerShell Universal werden die Signaturschlüssel aus dem Dokument gelesen und dem JWT-Validierungssystem bereitgestellt.

{
    "Jwt" : {
        "DiscoveryDocument": "https://auth20/metadata.xml"
    }
}

Externe App-Token

Bei der Konfiguration eines Remote-Signaturschlüssels werden die Token vom OAuth 2.0-Anbieter generiert. Daher werden auch die Claim-Informationen von diesem Anbieter generiert. Um Rollen und Berechtigungen innerhalb von PowerShell Universal ordnungsgemäß zuzuweisen, müssen Sie sicherstellen, dass die richtigen Claims innerhalb des Tokens definiert sind. PowerShell Universal wertet die folgenden Claim-Werte innerhalb eines Tokens aus.

• PSUPermission – Definiert die Berechtigungen des Tokens
• Roles – Definiert die Rollen des Tokens.

Um den Zugriff auf Ressourcen innerhalb einer PowerShell Universal-Instanz zu ermöglichen, stellen Sie sicher, dass das Token die richtigen Claims enthält. Beispielsweise würde das folgende Token vollständigen Zugriff auf die PowerShell Universal-Management-APIs erlauben, da es den Claim PSUPermission mit einem Selektor für alle Berechtigungen bereitstellt. Sie können das Beispiel unten verwenden, um zu sehen, wie sich dies in Auth0 umsetzen lässt.

{
  "PSUPermission": "(.*)",
  "iss": "https://myprovider.us.auth0.com/",
  "sub": "wKeaTMprlv7kX46eI9SwwvaGJzWPkbtt@clients",
  "aud": "https://mydomain.com",
  "iat": 1758898719,
  "exp": 1758985119,
  "scope": "(.*) Administrator",
  "gty": "client-credentials",
  "azp": "wKeaTMprlv7kX46eI9SwwvaGJzWPkbtt",
  "permissions": [
    "(.*)",
    "Administrator"
  ]
}

Alternativ können Sie die Claims-Auswertung für JWT-Token aktivieren. Standardmäßig verwendet PowerShell Universal beim Empfang eines Tokens einen statischen Satz von Berechtigungen. Wenn Sie die Claims-Auswertung für JWT-Token aktivieren, verarbeitet das Autorisierungssystem das Token und fügt die Berechtigungen bei der Verwendung des Tokens hinzu und nicht bei dessen Generierung.

Claim-Auswertung für Token

Um die Claim-Auswertung für Token zu aktivieren, können Sie appsettings.json anpassen, um PSU anzuweisen, die Claims-Auswertung während der Ausführung der Token-Validierung durchzuführen.

{
    "Jwt": {
        "EvaluateClaims": "true"
    }
}

Dabei wird roles.ps1 verwendet, um die Claims der bereitgestellten Token zu prüfen und Berechtigungen basierend auf den qualifizierten Rollen zuzuweisen.

Beispiel: Auth0-Zugriffstoken mit Claim-Auswertung

Mit den Standardfunktionen von Auth0 können Sie Token generieren, die dann Rollen basierend auf den Claims des Tokens bereitstellen. Dies erfordert keine speziellen Trigger oder Aktionen innerhalb von Auth0.

Eine Auth0-Anwendung erstellen

Erstellen Sie in Auth0 eine Anwendung für eine reguläre Webanwendung. Klicken Sie dazu auf Applications \ Applications und dann auf Create Application.

Eine Auth0-API erstellen

Erstellen Sie als Nächstes eine Auth0-API, indem Sie auf Applications \ APIs und dann auf Create API klicken. Setzen Sie Name und Namespace auf eindeutige Werte und belassen Sie die übrigen Optionen auf den Standardwerten.

Benutzerdefinierte Berechtigungsbereiche in Ihrer API erstellen

Definieren Sie innerhalb Ihrer API benutzerdefinierte Berechtigungen, z. B. eine mit einem Rollennamen.

Die Anwendung zur Nutzung der API autorisieren

Klicken Sie in den Anwendungseinstellungen auf APIs und aktivieren Sie den Schalter neben der API, um die Anwendung zur Nutzung der API zu autorisieren. Wählen Sie die Berechtigungen aus, die Sie der Anwendung bereitstellen möchten. Diese werden als Berechtigungs-Claims im Token angezeigt.

Ein Zugriffstoken von Auth0 abrufen

Nachdem die Anwendung und die API definiert sind, können Sie nun ein Zugriffstoken in Auth0 anfordern. Die Werte client_id und client_secret finden Sie auf der Seite Application Details. Der Wert audience sollte der Identifier Ihrer API sein.

Invoke-RestMethod 'https://ironmansoftware.us.auth0.com/oauth/token' -Body @{
    client_id = "xyz123"
    client_secret = "xyz123"
    audience = "https://powershelluniversal.com"
    grant_type = "client_credentials"
} -Method POST

PowerShell Universal konfigurieren

Sie müssen PowerShell Universal so konfigurieren, dass Auth0 als JWT-Anbieter verwendet wird. Dazu passen Sie die Datei appsettings.json an. Diese sollte Werte aus Auth0 enthalten. Das DiscoveryDocument ist Teil Ihres Mandanten und hilft, Daten wie die Signaturschlüssel für die JWT-Token zu definieren. Der Issuer ist die URL Ihres Mandanten. Die Audience ist der Identifier Ihrer API.

{
    "Jwt": {
        "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration",
        "Issuer": "https://ironmansoftware.us.auth0.com/",
        "Audience": "https://powershelluniversal.com",
        "EvaluateClaims": "true"
    }
}

Eine Rolle für die Zuordnung zur Auth0-Berechtigung konfigurieren

Erstellen Sie abschließend eine Rolle, die der Auth0-Berechtigung zugeordnet ist. Das folgende Beispiel prüft, ob das API-Token einen Berechtigungs-Claim mit dem Wert Administrator besitzt, wie oben konfiguriert. Ist dies der Fall, wird dem Token die Rolle API Admin zugewiesen, die alle Berechtigungen innerhalb der Management-API von PowerShell Universal umfasst.

New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator"

Verwendung eines App-Tokens mit PowerShell Universal

Nachdem Sie nun ein Auth0-App-Token haben, können Sie es genauso verwenden wie integrierte App-Token.

Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" }

Beispiel: Auth0-Zugriffstoken mit benutzerdefinierten Claims

Sie können Auth0-APIs und -Anwendungen verwenden, um App-Token für PowerShell Universal bereitzustellen.

Eine Auth0-Anwendung erstellen

Erstellen Sie in Auth0 eine Anwendung für eine reguläre Webanwendung. Klicken Sie dazu auf Applications \ Applications und dann auf Create Application.

Eine Auth0-API erstellen

Erstellen Sie als Nächstes eine Auth0-API, indem Sie auf Applications \ APIs und dann auf Create API klicken. Setzen Sie Name und Namespace auf eindeutige Werte und belassen Sie die übrigen Optionen auf den Standardwerten.

Die Anwendung zur Nutzung der API autorisieren

Klicken Sie in den Anwendungseinstellungen auf APIs und aktivieren Sie den Schalter neben der API, um die Anwendung zur Nutzung der API zu autorisieren.

Ein Zugriffstoken von Auth0 abrufen

Nachdem die Anwendung und die API definiert sind, können Sie nun ein Zugriffstoken in Auth0 anfordern. Die Werte client_id und client_secret finden Sie auf der Seite Application Details. Der Wert audience sollte der Identifier Ihrer API sein.

Invoke-RestMethod 'https://ironmansoftware.us.auth0.com/oauth/token' -Body @{
    client_id = "xyz123"
    client_secret = "xyz123"
    audience = "https://powershelluniversal.com"
    grant_type = "client_credentials"
} -Method POST

PowerShell Universal konfigurieren

Sie müssen PowerShell Universal so konfigurieren, dass Auth0 als JWT-Anbieter verwendet wird. Dazu passen Sie die Datei appsettings.json an. Diese sollte Werte aus Auth0 enthalten. Das DiscoveryDocument ist Teil Ihres Mandanten und hilft, Daten wie die Signaturschlüssel für die JWT-Token zu definieren. Der Issuer ist die URL Ihres Mandanten. Die Audience ist der Identifier Ihrer API.

{
    "Jwt": {
        "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration",
        "Issuer": "https://ironmansoftware.us.auth0.com/",
        "Audience": "https://powershelluniversal.com"
    }
}

Verwendung eines App-Tokens mit PowerShell Universal

Nachdem Sie nun ein Auth0-App-Token haben, können Sie es genauso verwenden wie integrierte App-Token.

Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" }

Optional: Einen Auth0-Aktions-Trigger definieren

Beim Gewähren eines neuen Zugriffstokens von Auth0 enthalten diese nicht die Standardrollen oder -berechtigungen wie integrierte App-Token in PowerShell Universal. Sie können dies steuern, indem Sie eine Custom Action definieren und sie dem Trigger credential-exchange zuweisen.

Klicken Sie auf Actions, dann auf Library und Create Action und anschließend auf Create Custom Action. Wählen Sie den Trigger Password Reset / Post Challenge aus und benennen Sie die Aktion.

Definieren Sie die Aktion, indem Sie einen benutzerdefinierten Claim für den Claim-Typ PSUPermission festlegen. Dieses Beispiel gewährt einfach vollständigen Zugriff auf die PowerShell Universal-APIs. Sie können den Ereigniskontext verwenden, um zu definieren, welche Berechtigungen basierend auf der Zugriffstoken-Anfrage empfangen werden.

exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("PSUPermission", "(.*)")
};

Fügen Sie als Nächstes die Aktion zum Workflow-Trigger für credential-exchange hinzu, indem Sie auf Actions, dann auf Triggers und anschließend auf credential-exchange. klicken

Ziehen Sie die Aktion Set Permissions in den Workflow.

Sobald dies abgeschlossen ist, können Sie ein neues Token generieren und auf jede API innerhalb von PowerShell Universal zugreifen.

Invoke-RestMethod http://localhost:5000/api/v1/identity -Headers @{ Authorization = "tokenValue" }

Siehe auch

• Devolutions Academy – Outline and authentication