Jetons d'appli
Vous pouvez utiliser les jetons d'application PowerShell Universal à la fois avec les terminaux d'API personnalisés et l'API de gestion. L'API de gestion utilise les rôles standards Administrator, Operator et Reader. Les jetons d'application de l'API personnalisée peuvent utiliser des rôles personnalisés ainsi que les rôles intégrés.
Vous pouvez accorder des jetons d'application à l'aide de la console d'administration ou vous pouvez utiliser directement l'API de gestion.
Console d'administration
Pour accorder un jeton dans la console d'administration, naviguez vers Secure > Application 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 le délai d'expiration du jeton.
API de gestion
Vous pouvez aussi accorder des jetons d'application aux utilisateurs à partir de l'API de gestion. Pour accorder un jeton d'application par programmation à l'aide de l'API, vous pouvez faire ce qui 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:00Les administrateurs peuvent accorder des jetons d'application à n'importe quel utilisateur en spécifiant l'ID d'identité de l'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 un accès basé sur ce rôle.
Rôles
Les rôles des jetons d'application sont attribués directement dans le jeton lui-même. Les rôles indiquent ce que le jeton est en mesure d'effectuer. Ils ne sont pas calculés lors de l'utilisation, donc le mappage de rôle à revendication ne fonctionnera pas avec les jetons d'application.
Nous suggérons aussi 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 réduit la performance ou cause des problèmes avec certains outils qui n'acceptent pas les valeurs de jeton plus longues.
Vous pouvez utiliser des rôles personnalisés avec un ensemble de permissions personnalisé pour limiter le nombre de rôles tout en fournissant un accès personnalisé à la plateforme PowerShell Universal. Les permissions sont évaluées lorsque le rôle est utilisé. Cela signifie qu'attribuer un rôle personnalisé à un jeton le rend plus flexible qu'un rôle intégré, puisque les permissions peuvent être ajoutées ou retirées d'un rôle sans générer un nouveau jeton.
Migration des jetons d'application
Vous pouvez migrer des jetons d'application entre systèmes à l'aide de l'API de gestion. Cela est utile lors du développement pour des 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 la même entre les instances. Vous avez besoin d'un jeton d'application valide dans le système cible pour créer les jetons migrés.
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 façon que n'importe quel 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 une façon 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 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. Changer la clé de signature invalidera toutes les clés de signature existantes.
Clé de signature distante
Vous pourriez vouloir utiliser un document de découverte OAuth 2.0 pour fournir la validation de la clé de signature. En utilisant un système distant comme celui-ci, 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 à l'URL du document de métadonnées OAuth 2.0. Lorsque PowerShell Universal se charge, il lira les clés de signature dans le document et les fournira au système de validation JWT.
Jetons d'application externes
Lors de la configuration d'une clé de signature distante, les jetons sont alors générés par le fournisseur OAuth 2.0. Pour cette raison, l'information des revendications est aussi générée par ce fournisseur. Afin d'attribuer correctement les rôles et les permissions dans PowerShell Universal, vous devrez 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 permissions du jeton
Roles - Définit les rôles du jeton.
Afin de permettre l'accès aux ressources dans une instance PowerShell Universal, assurez-vous que le jeton contient les revendications appropriées. Par exemple, le jeton suivant permettrait tous les accès aux API de gestion de PowerShell Universal parce qu'il fournit la revendication PSUPermission avec un sélecteur pour toutes les permissions. Vous pouvez utiliser l'exemple ci-dessous pour voir comment accomplir cela dans Auth0.
Vous pouvez aussi activer l'évaluation des revendications pour les jetons JWT. Par défaut, PowerShell Universal utilise un ensemble statique de permissions 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 permissions lorsque le jeton est utilisé plutôt que lorsqu'il est généré.
É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 durant l'exécution de la validation du jeton.
Cela utilisera roles.ps1 pour vérifier les revendications des jetons fournis et attribuer les permissions en fonction des rôles qualifiés.
Exemple : Jeton d'accès Auth0 avec évaluation des revendications
En utilisant les fonctionnalités standards d'Auth0, vous pouvez générer des jetons qui peuvent ensuite fournir des rôles basés sur les revendications du jeton. Cela ne nécessite aucun déclencheur ni aucune action spéciale 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 Create Application.
Créer une API Auth0
Ensuite, créez une API Auth0 en cliquant sur Applications \ APIs, puis Create API. Définissez le nom et l'espace de noms à des valeurs uniques et laissez le reste des options par défaut.
Créer des portées de permissions personnalisées dans votre API
Dans votre API, définissez des permissions personnalisées, comme 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 l'interrupteur à côté de l'API pour autoriser l'application à utiliser l'API. Sélectionnez les permissions que vous souhaitez fournir à l'application. Celles-ci apparaîtront comme des revendications de permission dans le jeton.
Récupérer un jeton d'accès depuis Auth0
Une fois l'application et l'API définies, vous pouvez maintenant demander un jeton d'accès dans Auth0. Les valeurs client_id et client_secret se trouvent sur la page Application Details. La valeur audience doit être l'identificateur de votre API.
Configurer PowerShell Universal
Vous devrez configurer PowerShell Universal pour utiliser Auth0 comme fournisseur JWT. Vous pouvez le faire en ajustant le fichier appsettings.json. Celui-ci devrait inclure des valeurs provenant d'Auth0. Le DiscoveryDocument fera partie de votre locataire et aide à définir des données comme les clés de signature pour les jetons JWT. L'Issuer sera l'URL de votre locataire. L'Audience sera l'identificateur de votre API.
Configurer un rôle pour le mapper à la permission Auth0
Enfin, créez un rôle qui correspond à la permission Auth0. L'exemple suivant vérifie que le jeton d'API possède une revendication de permissions avec la valeur Administrator comme nous l'avons configuré ci-dessus. Si c'est le cas, le jeton se voit attribuer le rôle API Admin, qui possède toutes les permissions dans l'API de gestion de PowerShell Universal.
Utiliser un jeton d'application avec PowerShell Universal
Maintenant que vous avez un jeton d'application Auth0, vous pouvez l'utiliser comme vous le feriez avec les jetons d'application intégrés.
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 Create Application.
Créer une API Auth0
Ensuite, créez une API Auth0 en cliquant sur Applications \ APIs, puis Create API. Définissez le nom et l'espace de noms à 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 l'interrupteur à 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 maintenant demander un jeton d'accès dans Auth0. Les valeurs client_id et client_secret se trouvent sur la page Application Details. La valeur audience doit être l'identificateur de votre API.
Configurer PowerShell Universal
Vous devrez configurer PowerShell Universal pour utiliser Auth0 comme fournisseur JWT. Vous pouvez le faire en ajustant le fichier appsettings.json. Celui-ci devrait inclure des valeurs provenant d'Auth0. Le DiscoveryDocument fera partie de votre locataire et aide à définir des données comme les clés de signature pour les jetons JWT. L'Issuer sera l'URL de votre locataire. L'Audience sera l'identificateur de votre API.
Utiliser un jeton d'application avec PowerShell Universal
Maintenant que vous avez un jeton d'application Auth0, vous pouvez l'utiliser comme vous le feriez avec les jetons d'application intégrés.
Optionnel : Définir un déclencheur d'action Auth0
Lors de l'octroi d'un nouveau jeton d'accès depuis Auth0, ceux-ci ne contiendront pas les rôles ou les permissions standards 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'attribuant au déclencheur credential-exchange.
Cliquez sur Actions, puis Library et Create Action, puis 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 tous les accès aux API de PowerShell Universal. Vous pouvez utiliser le contexte de l'événement pour définir quelles permissions sont reçues en fonction de la demande de jeton d'accès.
Ensuite, ajoutez l'action au déclencheur de flux de travail pour credential-exchange en cliquant sur Actions, puis Triggers, puis credential-exchange.
Faites glisser l'action Set Permissions dans le flux de travail.
Une fois cela terminé, vous pouvez générer un nouveau jeton et accéder à n'importe quelle API dans PowerShell Universal.
Voir aussi
Mis à jour
Ce contenu vous a-t-il été utile ?