> 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/fr/securite/app-tokens.md). # Jetons d'appli Accorder, gérer et migrer les jetons d'application PowerShell Universal pour l'accès à l'API, en couvrant les rôles, les clés de signature et la sécurité renforcée des jetons. Vous pouvez utiliser les jetons d'application PowerShell Universal à la fois avec les [terminaux d'API personnalisés](/powershell-universal/fr/api/endpoints.md) et l'[API de gestion](/powershell-universal/fr/config/management-api.md). 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 : {% code collapsedlinecount="10" %} ``` 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 ``` {% endcode %} Les 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. {% code collapsedlinecount="10" %} ``` 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 ``` {% endcode %} ## 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. {% code collapsedlinecount="10" %} ```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" } ``` {% endcode %} ## 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. {% hint style="warning" %} L'activation de la sécurité des jetons d'application invalidera tous les jetons existants. {% endhint %} ## 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. {% code collapsedlinecount="10" %} ```json { "Jwt" : { "DiscoveryDocument": "https://auth20/metadata.xml" } } ``` {% endcode %} ## 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](#example-auth0-access-token-with-custom-claims) pour voir comment accomplir cela dans Auth0. {% code collapsedlinecount="10" %} ```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" ] } ``` {% endcode %} 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. {% code collapsedlinecount="10" %} ```json { "Jwt": { "EvaluateClaims": "true" } } ``` {% endcode %} 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. {% code collapsedlinecount="10" %} ```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 ``` {% endcode %} #### 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. {% code collapsedlinecount="10" %} ```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" } } ``` {% endcode %} #### 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. {% code collapsedlinecount="10" %} ```powershell New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator" ``` {% endcode %} #### 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. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} ### 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. {% code collapsedlinecount="10" %} ```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 ``` {% endcode %} #### 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. {% code collapsedlinecount="10" %} ```json { "Jwt": { "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration", "Issuer": "https://ironmansoftware.us.auth0.com/", "Audience": "https://powershelluniversal.com" } } ``` {% endcode %} #### 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. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} #### 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. {% code collapsedlinecount="10" %} ```javascript exports.onExecuteCredentialsExchange = async (event, api) => { api.accessToken.setCustomClaim("PSUPermission", "(.*)") }; ``` {% endcode %} 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. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} ### Voir aussi * [Devolutions Academy – Plan et authentification](https://academy.devolutions.net/student/activity/3542770-part-1-outline-and-authentication) * [Devolutions Academy – Authentification](https://academy.devolutions.net/student/path/3465905/activity/5612255) --- # 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/fr/securite/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.