Jetons d'application

Jetons d'application pour accéder aux API de PowerShell Universal.

Vous pouvez utiliser les jetons d'application de PowerShell Universal avec les points de terminaison API personnalisés et l'API de gestion. L'API de gestion utilise les rôles standard Administrator, Operator et Reader. Les jetons d'application pour les API personnalisées peuvent utiliser des rôles personnalisés ainsi que les rôles intégrés.

Vous pouvez accorder des jetons d'application via la console d'administration ou directement via l'API de gestion.

Console d'administration

Pour accorder un jeton dans la console d'administration, accédez à Security \ Tokens. Cliquez sur le bouton Create App Token pour accorder un jeton d'application.

Lorsque vous cliquez sur Create App Token, une boîte de dialogue vous permet de spécifier l'identité, le rôle et la date d'expiration du jeton.

Boîte de dialogue de jeton d'application

API de gestion

Vous pouvez également accorder des jetons d'application à des utilisateurs via l'API de gestion. Pour accorder un jeton d'application par programmation à l'aide de l'API, vous pouvez procéder comme suit :

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

Les administrateurs peuvent accorder des jetons d'application à n'importe quel utilisateur en spécifiant l'ID d'identité de cet utilisateur. Pour accorder un jeton d'application à une identité via l'API REST, l'utilisateur doit avoir un rôle défini. Le rôle Operator définit l'utilisateur, et son jeton d'application se verra accorder l'accès selon ce rôle.

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

Rôles

Les rôles des jetons d'application sont assignés directement dans le jeton lui-même. Les rôles indiquent ce que le jeton est autorisé à effectuer. Ils ne sont pas calculés lors de l'utilisation, de sorte que le mappage rôle-revendication ne fonctionnera pas avec les jetons d'application.

Nous suggérons également de limiter le nombre de rôles dans un jeton d'application. Plus il y a de rôles ajoutés au jeton, plus la taille du jeton augmente, ce qui peut réduire les performances ou causer des problèmes avec certains outils qui n'autorisent pas des valeurs de jeton plus longues.

Vous pouvez utiliser des rôles personnalisés avec un ensemble d'autorisations personnalisées pour limiter le nombre de rôles tout en fournissant un accès personnalisé à la plateforme PowerShell Universal. Les autorisations sont évaluées lors de l'utilisation du rôle. Cela signifie que l'attribution d'un rôle personnalisé à un jeton le rend plus flexible qu'un rôle intégré, car les autorisations peuvent être ajoutées ou supprimées d'un rôle sans générer un nouveau jeton.

Migration de jetons d'application

Vous pouvez migrer des jetons d'application entre systèmes à l'aide de l'API de gestion. Ceci est utile lors du développement de scénarios de haute disponibilité.

Voici un exemple du POST requis pour créer un jeton d'application existant dans n'importe quelle instance PSU. Notez que la clé de signature doit être identique entre les instances. Vous avez besoin d'un jeton d'application valide dans le système cible pour créer les jetons migrés.

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"   
}

Sécurité renforcée des jetons d'application

Lorsque la sécurité renforcée des jetons d'application est activée, les valeurs des jetons ne sont accessibles qu'au moment de leur création. Elles sont hachées et la base de données stocke la valeur de hachage plutôt que le jeton. Vous utilisez le jeton de la même manière que tout autre jeton.

L'activation de la sécurité des jetons d'application invalidera tous les jetons existants.

Jetons système

Les jetons système sont un moyen de fournir des jetons à des systèmes non utilisateurs. Ils ne sont pas liés directement à l'identité d'un utilisateur. Vous pouvez fournir un nom pour le jeton ainsi qu'une date d'expiration et des rôles.

Clés de signature

Clé de signature locale

Par défaut, PowerShell Universal crée une clé de signature basée sur la chaîne Jwt \ SigningKey dans appsettings.json. Cette valeur est utilisée pour encoder et décoder le jeton. Si les clés de signature ne correspondent pas, le jeton sera considéré comme invalide. La modification de la clé de signature invalidera toutes les clés de signature existantes.

Clé de signature distante

Vous pouvez utiliser un document de découverte OAuth 2.0 pour fournir la validation de la clé de signature. En utilisant un système distant de ce type, vous pouvez vous assurer que lorsque les clés de signature sont modifiées, la configuration de PowerShell Universal n'aura pas besoin d'être modifiée. Pour utiliser une clé de signature distante, définissez la valeur Jwt \ DiscoveryDocument dans appsettings.json sur l'URL du document de métadonnées OAuth 2.0. Lors du chargement de PowerShell Universal, les clés de signature seront lues à partir du document et fournies au système de validation JWT.

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

Jetons d'application externes

Lors de la configuration d'une clé de signature distante, les jetons sont générés par le fournisseur OAuth 2.0. De ce fait, les informations de revendications sont également générées par ce fournisseur. Afin d'assigner correctement les rôles et les autorisations dans PowerShell Universal, vous devez vous assurer que les revendications appropriées sont définies dans le jeton. PowerShell Universal évaluera les valeurs de revendication suivantes dans un jeton.

• PSUPermission - Définit les autorisations du jeton
• Roles - Définit les rôles du jeton.

Pour permettre l'accès aux ressources d'une instance PowerShell Universal, assurez-vous que le jeton contient les revendications appropriées. Par exemple, le jeton suivant permettrait un accès complet aux API de gestion de PowerShell Universal car il fournit la revendication PSUPermission avec un sélecteur pour toutes les autorisations. Vous pouvez utiliser l'exemple ci-dessous pour voir comment accomplir cela dans Auth0.

{
  "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"
  ]
}

Vous pouvez également activer l'évaluation des revendications pour les jetons JWT. Par défaut, PowerShell Universal utilise un ensemble statique d'autorisations lors de la réception d'un jeton. Si vous activez l'évaluation des revendications pour les jetons JWT, le système d'autorisation traitera le jeton et ajoutera les autorisations lors de l'utilisation du jeton plutôt que lors de sa génération.

Évaluation des revendications pour les jetons

Pour activer l'évaluation des revendications pour les jetons, vous pouvez ajuster appsettings.json afin d'indiquer à PSU d'exécuter l'évaluation des revendications pendant la validation du jeton.

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

Cela utilisera roles.ps1 pour vérifier les revendications des jetons fournis et assigner des autorisations en fonction des rôles qualifiés.

Exemple : jeton d'accès Auth0 avec évaluation des revendications

En utilisant les fonctionnalités standard d'Auth0, vous pouvez générer des jetons qui fournissent ensuite des rôles basés sur les revendications du jeton. Cela ne nécessite aucun déclencheur ou action spécial dans Auth0.

Créer une application Auth0

Dans Auth0, créez une application pour une application web standard. Vous pouvez le faire en cliquant sur Applications \ Applications, puis sur Create Application.

Créer une API Auth0

Ensuite, créez une API Auth0 en cliquant sur Applications \ APIs, puis sur Create API. Définissez le nom et l'espace de noms avec des valeurs uniques et laissez le reste des options par défaut.

Créer des portées d'autorisation personnalisées dans votre API

Dans votre API, définissez des autorisations personnalisées, par exemple une avec un nom de rôle.

Autoriser l'application à utiliser l'API

Dans les paramètres de l'application, cliquez sur APIs et basculez le commutateur à côté de l'API pour autoriser l'application à utiliser l'API. Sélectionnez les autorisations que vous souhaitez accorder à l'application. Celles-ci apparaîtront sous forme de revendications d'autorisation dans le jeton.

Récupérer un jeton d'accès depuis Auth0

Une fois l'application et l'API définies, vous pouvez demander un jeton d'accès dans Auth0. Les valeurs client_id et client_secret se trouvent sur la page des détails de l'application. La valeur audience doit être l'identifiant de votre API.

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

Configurer PowerShell Universal

Vous devez configurer PowerShell Universal pour utiliser Auth0 comme fournisseur JWT. Vous pouvez le faire en ajustant le fichier appsettings.json. Ces valeurs doivent inclure des valeurs provenant d'Auth0. Le DiscoveryDocument fera partie de votre locataire et aide à définir des données telles que les clés de signature pour les jetons JWT. L'Issuer sera l'URL de votre locataire. L'Audience sera l'identifiant de votre 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"
    }
}

Configurer un rôle pour le mapper à l'autorisation Auth0

Enfin, créez un rôle qui correspond à l'autorisation Auth0. L'exemple suivant vérifie que le jeton API contient une revendication de permissions avec la valeur Administrator comme configuré ci-dessus. Dans ce cas, le jeton se voit attribuer le rôle API Admin qui dispose de toutes les autorisations dans l'API de gestion de PowerShell Universal.

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

Utiliser un jeton d'application avec PowerShell Universal

Maintenant que vous disposez d'un jeton d'application Auth0, vous pouvez l'utiliser de la même manière que les jetons d'application intégrés.

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

Exemple : jeton d'accès Auth0 avec revendications personnalisées

Vous pouvez utiliser les API et les applications Auth0 pour fournir des jetons d'application pour PowerShell Universal.

Créer une application Auth0

Dans Auth0, créez une application pour une application web standard. Vous pouvez le faire en cliquant sur Applications \ Applications, puis sur Create Application.

Créer une API Auth0

Ensuite, créez une API Auth0 en cliquant sur Applications \ APIs, puis sur Create API. Définissez le nom et l'espace de noms avec des valeurs uniques et laissez le reste des options par défaut.

Autoriser l'application à utiliser l'API

Dans les paramètres de l'application, cliquez sur APIs et basculez le commutateur à côté de l'API pour autoriser l'application à utiliser l'API.

Récupérer un jeton d'accès depuis Auth0

Une fois l'application et l'API définies, vous pouvez demander un jeton d'accès dans Auth0. Les valeurs client_id et client_secret se trouvent sur la page des détails de l'application. La valeur audience doit être l'identifiant de votre API.

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

Configurer PowerShell Universal

Vous devez configurer PowerShell Universal pour utiliser Auth0 comme fournisseur JWT. Vous pouvez le faire en ajustant le fichier appsettings.json. Ces valeurs doivent inclure des valeurs provenant d'Auth0. Le DiscoveryDocument fera partie de votre locataire et aide à définir des données telles que les clés de signature pour les jetons JWT. L'Issuer sera l'URL de votre locataire. L'Audience sera l'identifiant de votre API.

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

Utiliser un jeton d'application avec PowerShell Universal

Maintenant que vous disposez d'un jeton d'application Auth0, vous pouvez l'utiliser de la même manière que les jetons d'application intégrés.

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

Facultatif : définir un déclencheur d'action Auth0

Lors de l'octroi d'un nouveau jeton d'accès depuis Auth0, celui-ci ne contiendra pas les rôles ou autorisations standard comme les jetons d'application intégrés dans PowerShell Universal. Vous pouvez contrôler cela en définissant une action personnalisée et en l'assignant au déclencheur credential-exchange.

Cliquez sur Actions, puis sur Library et Create Action, puis sur Create Custom Action. Sélectionnez le déclencheur Password Reset / Post Challenge et nommez l'action.

Définissez l'action en configurant une revendication personnalisée pour le type de revendication PSUPermission. Cet exemple fournit simplement un accès complet aux API de PowerShell Universal. Vous pouvez utiliser le contexte d'événement pour définir les autorisations reçues en fonction de la demande de jeton d'accès.

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

Ensuite, ajoutez l'action au déclencheur de flux de travail pour credential-exchange en cliquant sur Actions, puis sur Triggers, puis sur credential-exchange.

Faites glisser l'action Set Permissions dans le flux de travail.

Une fois cette étape terminée, vous pouvez générer un nouveau jeton et accéder à n'importe quelle API dans PowerShell Universal.

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