> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/sicherheit/app-tokens.md). # App-Tokens Sie können PowerShell Universal App-Token sowohl mit [benutzerdefinierten API-Endpunkten](https://github.com/Devolutions/docs/tree/master/translations/de/powershell-universal/config/security/broken-reference/README.md) als auch mit der [Management-API](/powershell-universal/de/config/management-api.md) verwenden. Die Management-API verwendet die Standardrollen Administrator, Operator und Reader. Die App-Token für benutzerdefinierte APIs können sowohl benutzerdefinierte als auch integrierte Rollen nutzen. Sie können App-Token über die Admin-Konsole erteilen oder die Management-API direkt verwenden. ## Admin-Konsole Um ein Token in der Admin-Konsole zu erteilen, navigieren Sie zu Security \ Tokens. Klicken Sie auf die Schaltfläche Create App Token, um ein App-Token zu erteilen.
Wenn Sie auf Create App Token klicken, können Sie in einem Dialog 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 erteilen. Um ein App-Token programmatisch über die API zu erteilen, 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 erteilen, indem sie die Identitäts-ID des Benutzers angeben. Um einer Identität über die REST-API ein App-Token zu erteilen, benötigt der Benutzer eine definierte Rolle. Die Operator-Rolle definiert den Benutzer, und dessen 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=adam@ironmansoftware.onmicrosoft.com; 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 Tools verursachen kann, die längere Token-Werte nicht zulassen. Sie können benutzerdefinierte Rollen mit einem benutzerdefinierten Satz von Berechtigungen verwenden, um die Anzahl der Rollen zu begrenzen, aber dennoch benutzerdefinierten Zugriff auf die PowerShell Universal-Plattform zu gewähren. 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 einer Rolle hinzugefügt oder daraus entfernt werden können, ohne ein neues Token zu erzeugen. ## Migrieren von App-Token Sie können App-Token über die Management-API zwischen Systemen migrieren. Dies ist bei der Entwicklung für Hochverfügbarkeitsszenarien hilfreich. Nachfolgend finden Sie ein Beispiel für den POST, der erforderlich ist, um ein bestehendes App-Token in einer beliebigen PSU-Instanz zu erstellen. Beachten Sie, dass der Signierschlüssel zwischen den Instanzen identisch sein muss. Sie benötigen ein gültiges App-Token im Zielsystem, um die migrierten Token zu erstellen. ```powershell 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. {% hint style="warning" %} Das Aktivieren der App-Token-Sicherheit macht alle bestehenden Token ungültig. {% endhint %} ## Systemtoken Systemtoken sind eine Möglichkeit, Token für Nicht-Benutzersysteme 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. ## Signierschlüssel ### Lokaler Signierschlüssel Standardmäßig erstellt PowerShell Universal einen Signierschlüssel basierend auf der Zeichenfolge Jwt \ SigningKey in appsettings.json. Dieser Wert wird zum Codieren und Decodieren des Tokens verwendet. Wenn die Signierschlüssel nicht übereinstimmen, wird das Token als ungültig betrachtet. Eine Änderung des Signierschlüssels macht alle bestehenden Signierschlüssel ungültig. ### Remote-Signierschlüssel Möglicherweise möchten Sie ein OAuth 2.0-Discovery-Dokument verwenden, um die Validierung von Signierschlüsseln bereitzustellen. Durch die Verwendung eines solchen Remote-Systems können Sie sicherstellen, dass bei einer Änderung der Signierschlüssel die PowerShell Universal-Konfiguration nicht geändert werden muss. Um einen Remote-Signierschlüssel zu verwenden, setzen Sie den Wert Jwt \ DiscoveryDocument in appsettings.json auf die URL des OAuth 2.0-Metadatendokuments. Beim Laden liest PowerShell Universal die Signierschlüssel aus dem Dokument und stellt sie dem JWT-Validierungssystem bereit. ```json { "Jwt" : { "DiscoveryDocument": "https://auth20/metadata.xml" } } ``` ## Externe App-Token Bei der Konfiguration eines Remote-Signierschlüssels werden Token dann vom OAuth 2.0-Anbieter generiert. Aus diesem Grund 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 allen Zugriff auf die PowerShell Universal-Management-APIs erlauben, da es den `PSUPermission`-Claim mit einem Selektor für alle Berechtigungen bereitstellt. Sie können das [Beispiel unten](#example-auth0-access-token-with-custom-claims) verwenden, um zu sehen, wie dies in Auth0 umgesetzt wird. ```json { "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 einen statischen Satz von Berechtigungen, wenn ein Token empfangen wird. 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. ```json { "Jwt": { "EvaluateClaims": "true" } } ``` Dadurch 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 Standardfunktionen von Auth0 können Sie Token generieren, die dann Rollen basierend auf den Claims des Tokens bereitstellen. Dies erfordert keine besonderen Trigger oder Actions innerhalb von Auth0. #### Erstellen einer Auth0-Anwendung Erstellen Sie in Auth0 eine Anwendung für eine reguläre Webanwendung. Sie können dies tun, indem Sie auf Applications \ Applications und dann auf Create Application klicken.
#### Erstellen einer Auth0-API Erstellen Sie als Nächstes eine Auth0-API, indem Sie auf Applications \ APIs und dann auf Create API klicken. Legen Sie Name und Namespace auf eindeutige Werte fest und lassen Sie die übrigen Optionen auf den Standardwerten.
#### Erstellen benutzerdefinierter Berechtigungs-Scopes in Ihrer API Definieren Sie innerhalb Ihrer API benutzerdefinierte Berechtigungen, zum Beispiel eine mit einem Rollennamen.
#### Autorisieren der Anwendung zur Verwendung der API Klicken Sie in den Anwendungseinstellungen auf APIs und aktivieren Sie den Schalter neben der API, um die Anwendung zur Verwendung der API zu autorisieren. Wählen Sie die Berechtigungen aus, die Sie der Anwendung bereitstellen möchten. Diese erscheinen als Berechtigungs-Claims im Token.
#### Abrufen eines Zugriffstokens von Auth0 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. ```powershell 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 ``` #### Konfigurieren von PowerShell Universal Sie müssen PowerShell Universal so konfigurieren, dass Auth0 als JWT-Anbieter verwendet wird. Sie können dies tun, indem Sie die Datei appsettings.json anpassen. Diese sollte Werte von Auth0 enthalten. Das `DiscoveryDocument` ist Teil Ihres Tenants und hilft, Daten wie die Signierschlüssel für die JWT-Token zu definieren. Der `Issuer` ist die URL Ihres Tenants. Die `Audience` ist der Identifier Ihrer API. ```json { "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" } } ``` #### Konfigurieren einer Rolle zur Zuordnung zur Auth0-Berechtigung Erstellen Sie schließlich eine Rolle, die der Auth0-Berechtigung zugeordnet wird. Das folgende Beispiel prüft, ob das API-Token einen Permissions-Claim mit dem Wert `Administrator` besitzt, wie wir es oben konfiguriert haben. Wenn ja, wird dem Token die Rolle API Admin zugewiesen, die alle Berechtigungen innerhalb der Management-API von PowerShell Universal umfasst. ```powershell New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator" ``` #### Verwenden eines App-Tokens mit PowerShell Universal Da Sie nun ein Auth0-App-Token haben, können Sie es genauso verwenden wie integrierte App-Token. ```powershell 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. #### Erstellen einer Auth0-Anwendung Erstellen Sie in Auth0 eine Anwendung für eine reguläre Webanwendung. Sie können dies tun, indem Sie auf Applications \ Applications und dann auf Create Application klicken.
#### Erstellen einer Auth0-API Erstellen Sie als Nächstes eine Auth0-API, indem Sie auf Applications \ APIs und dann auf Create API klicken. Legen Sie Name und Namespace auf eindeutige Werte fest und lassen Sie die übrigen Optionen auf den Standardwerten.
#### Autorisieren der Anwendung zur Verwendung der API Klicken Sie in den Anwendungseinstellungen auf APIs und aktivieren Sie den Schalter neben der API, um die Anwendung zur Verwendung der API zu autorisieren. #### Abrufen eines Zugriffstokens von Auth0 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. ```powershell 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 ``` #### Konfigurieren von PowerShell Universal Sie müssen PowerShell Universal so konfigurieren, dass Auth0 als JWT-Anbieter verwendet wird. Sie können dies tun, indem Sie die Datei appsettings.json anpassen. Diese sollte Werte von Auth0 enthalten. Das `DiscoveryDocument` ist Teil Ihres Tenants und hilft, Daten wie die Signierschlüssel für die JWT-Token zu definieren. Der `Issuer` ist die URL Ihres Tenants. Die `Audience` ist der Identifier Ihrer API. ```json { "Jwt": { "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration", "Issuer": "https://ironmansoftware.us.auth0.com/", "Audience": "https://powershelluniversal.com" } } ``` #### Verwenden eines App-Tokens mit PowerShell Universal Da Sie nun ein Auth0-App-Token haben, können Sie es genauso verwenden wie integrierte App-Token. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` #### Optional: Definieren eines Auth0-Action-Triggers Wenn ein neues Zugriffstoken von Auth0 erteilt wird, enthält es 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 Action.
Definieren Sie die Action, indem Sie einen benutzerdefinierten Claim für den Claim-Typ `PSUPermission` festlegen. Dieses Beispiel stellt einfach allen Zugriff auf die PowerShell Universal-APIs bereit. Sie können den Ereigniskontext verwenden, um zu definieren, welche Berechtigungen basierend auf der Zugriffstoken-Anforderung empfangen werden. ```javascript exports.onExecuteCredentialsExchange = async (event, api) => { api.accessToken.setCustomClaim("PSUPermission", "(.*)") }; ``` Fügen Sie als Nächstes die Action dem Workflow-Trigger für `credential-exchange` hinzu, indem Sie auf Actions, dann auf Triggers und anschließend auf `credential-exchange.` klicken
Ziehen Sie die Action 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. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity -Headers @{ Authorization = "tokenValue" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/de/sicherheit/app-tokens.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.