> 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/es/seguridad/app-tokens.md). # Tokens de aplicación Conceda, gestione y migre tokens de aplicación de PowerShell Universal para el acceso a la API, con información sobre roles, claves de firma y seguridad mejorada de tokens. Puede usar los tokens de aplicación de PowerShell Universal tanto con [endpoints de API personalizados](/powershell-universal/es/api/endpoints.md) como con la [API de gestión](/powershell-universal/es/config/management-api.md). La API de gestión usa los roles estándar Administrator, Operator y Reader. Los tokens de aplicación de API personalizada pueden utilizar roles personalizados además de los integrados. Puede conceder tokens de aplicación usando la consola de administración o puede usar la API de gestión directamente. ## Consola de administración Para conceder un token en la consola de administración, vaya a Secure > Application Tokens. Haga clic en el botón Create App Token para conceder un token de aplicación. Al hacer clic en Create App Token, un cuadro de diálogo le permite especificar la identidad, el rol y el tiempo de expiración del token. ## API de gestión También puede conceder tokens de aplicación a los usuarios desde la API de gestión. Para conceder un token de aplicación de forma programática mediante la API, puede hacer lo siguiente: {% 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 %} Los administradores pueden conceder tokens de aplicación a cualquier usuario especificando el ID de identidad del usuario. Para conceder un token de aplicación a una identidad a través de la API REST, el usuario necesita un rol definido. El rol Operator define al usuario y su token de aplicación recibirá acceso según ese rol. {% 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 %} ## Roles Los roles de los tokens de aplicación se asignan directamente en el propio token. Los roles indican lo que el token es capaz de realizar. No se calculan durante su uso, por lo que la asignación de roles a claims no funcionará con los tokens de aplicación. También sugerimos limitar el número de roles dentro de un token de aplicación. Cuantos más roles se añadan al token, mayor será el tamaño del token y se reducirá el rendimiento o se provocarán problemas con determinadas herramientas que no admiten valores de token más largos. Puede usar roles personalizados con un conjunto personalizado de permisos para limitar el número de roles, pero proporcionando un acceso personalizado a la plataforma PowerShell Universal. Los permisos se evalúan cuando se usa el rol. Esto significa que asignar un rol personalizado a un token lo hace más flexible que un rol integrado, ya que los permisos se pueden añadir o quitar de un rol sin generar un nuevo token. ## Migración de tokens de aplicación Puede migrar tokens de aplicación entre sistemas usando la API de gestión. Esto resulta útil al desarrollar para escenarios de alta disponibilidad. A continuación se muestra un ejemplo del POST necesario para crear un token de aplicación existente en cualquier instancia de PSU. Tenga en cuenta que la clave de firma debe ser la misma entre las instancias. Necesita un token de aplicación válido en el sistema de destino para crear los tokens migrados. {% 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 %} ## Seguridad mejorada de tokens de aplicación Cuando la seguridad mejorada de tokens de aplicación está habilitada, los valores de los tokens solo son accesibles en el momento de su creación. Se les aplica un hash y la base de datos almacena el valor del hash en lugar del token. El token se usa igual que cualquier otro token. {% hint style="warning" %} Habilitar la seguridad de tokens de aplicación invalidará todos los tokens existentes. {% endhint %} ## Tokens de sistema Los tokens de sistema son una forma de proporcionar tokens a sistemas que no son usuarios. No están vinculados directamente a la identidad de un usuario. Puede proporcionar un nombre para el token, así como la expiración y los roles. ## Claves de firma ### Clave de firma local De forma predeterminada, PowerShell Universal crea una clave de firma basada en la cadena Jwt \ SigningKey de appsettings.json. Este valor se usa para codificar y descodificar el token. Si las claves de firma no coinciden, el token se considerará no válido. Cambiar la clave de firma invalidará todas las claves de firma existentes. ### Clave de firma remota Puede que desee usar un documento de descubrimiento de OAuth 2.0 para proporcionar la validación de la clave de firma. Al usar un sistema remoto como este, puede asegurarse de que, cuando se cambien las claves de firma, no sea necesario cambiar la configuración de PowerShell Universal. Para usar una clave de firma remota, establezca el valor Jwt \ DiscoveryDocument de appsettings.json en la URL del documento de metadatos de OAuth 2.0. Cuando PowerShell Universal se cargue, leerá las claves de firma del documento y las proporcionará al sistema de validación de JWT. {% code collapsedlinecount="10" %} ```json { "Jwt" : { "DiscoveryDocument": "https://auth20/metadata.xml" } } ``` {% endcode %} ## Tokens de aplicación externos Al configurar una clave de firma remota, los tokens se generan entonces mediante el proveedor de OAuth 2.0. Debido a esto, la información de claims también la genera ese proveedor. Para asignar correctamente los roles y permisos en PowerShell Universal, deberá asegurarse de que los claims adecuados estén definidos en el token. PowerShell Universal evaluará los siguientes valores de claim en un token. * PSUPermission - Define los permisos del token * Roles - Define los roles del token. Para permitir el acceso a los recursos de una instancia de PowerShell Universal, asegúrese de que el token contenga los claims adecuados. Por ejemplo, el siguiente token permitiría todo el acceso a las APIs de gestión de PowerShell Universal porque proporciona el claim `PSUPermission` con un selector para todos los permisos. Puede usar el [ejemplo siguiente](#example-auth0-access-token-with-custom-claims) para ver cómo lograr esto en 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 %} Como alternativa, puede habilitar la evaluación de claims para los tokens JWT. De forma predeterminada, PowerShell Universal usa un conjunto estático de permisos al recibir un token. Si habilita la evaluación de claims para los tokens JWT, el sistema de autorización procesará el token y añadirá los permisos cuando se use el token en lugar de cuando se genere. ### Evaluación de claims para tokens Para habilitar la evaluación de claims para tokens, puede ajustar appsettings.json para indicar a PSU que ejecute la evaluación de claims durante la ejecución de la validación del token. {% code collapsedlinecount="10" %} ```json { "Jwt": { "EvaluateClaims": "true" } } ``` {% endcode %} Esto usará `roles.ps1` para comprobar los claims de los tokens que se proporcionan y asignar permisos según los roles cualificados. ### Ejemplo: token de acceso de Auth0 con evaluación de claims Mediante las funciones estándar de Auth0, puede generar tokens que luego pueden proporcionar roles según los claims del token. Esto no requiere ningún desencadenador ni acción especial en Auth0. #### Crear una aplicación de Auth0 En Auth0, cree una aplicación para una aplicación web normal. Puede hacerlo haciendo clic en Applications \ Applications y después en Create Application. #### Crear una API de Auth0 A continuación, cree una API de Auth0 haciendo clic en Applications \ APIs y después en Create API. Establezca el nombre y el espacio de nombres en valores únicos y deje el resto de las opciones con sus valores predeterminados. #### Crear ámbitos de permisos personalizados en su API Dentro de su API, defina permisos personalizados, como uno con un nombre de rol. #### Autorizar la aplicación para usar la API En la configuración de la aplicación, haga clic en APIs y active el interruptor junto a la API para autorizar a la aplicación a usar la API. Seleccione los permisos que desea proporcionar a la aplicación. Estos aparecerán como claims de permisos en el token. #### Obtener un token de acceso de Auth0 Con la aplicación y la API definidas, ya puede solicitar un token de acceso en Auth0. Los valores `client_id` y `client_secret` se pueden encontrar en la página de detalles de la aplicación. El valor `audience` debe ser el identificador de su 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 %} #### Configurar PowerShell Universal Deberá configurar PowerShell Universal para usar Auth0 como proveedor de JWT. Puede hacerlo ajustando el fichero appsettings.json. Este debe incluir valores de Auth0. El `DiscoveryDocument` formará parte de su tenant y ayuda a definir datos como las claves de firma de los tokens JWT. El `Issuer` será la URL de su tenant. El `Audience` será el identificador de su 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 %} #### Configurar un rol que se asigne al permiso de Auth0 Por último, cree un rol que se asigne al permiso de Auth0. El siguiente ejemplo comprueba que el token de la API tenga un claim de permisos con el valor `Administrator`, como configuramos anteriormente. Si es así, al token se le asigna el rol API Admin, que tiene todos los permisos dentro de la API de gestión de PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator" ``` {% endcode %} #### Uso de un token de aplicación con PowerShell Universal Ahora que tiene un token de aplicación de Auth0, puede usarlo igual que usaría los tokens de aplicación integrados. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} ### Ejemplo: token de acceso de Auth0 con claims personalizados Puede usar las APIs y aplicaciones de Auth0 para proporcionar tokens de aplicación para PowerShell Universal. #### Crear una aplicación de Auth0 En Auth0, cree una aplicación para una aplicación web normal. Puede hacerlo haciendo clic en Applications \ Applications y después en Create Application. #### Crear una API de Auth0 A continuación, cree una API de Auth0 haciendo clic en Applications \ APIs y después en Create API. Establezca el nombre y el espacio de nombres en valores únicos y deje el resto de las opciones con sus valores predeterminados. #### Autorizar la aplicación para usar la API En la configuración de la aplicación, haga clic en APIs y active el interruptor junto a la API para autorizar a la aplicación a usar la API. #### Obtener un token de acceso de Auth0 Con la aplicación y la API definidas, ya puede solicitar un token de acceso en Auth0. Los valores `client_id` y `client_secret` se pueden encontrar en la página de detalles de la aplicación. El valor `audience` debe ser el identificador de su 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 %} #### Configurar PowerShell Universal Deberá configurar PowerShell Universal para usar Auth0 como proveedor de JWT. Puede hacerlo ajustando el fichero appsettings.json. Este debe incluir valores de Auth0. El `DiscoveryDocument` formará parte de su tenant y ayuda a definir datos como las claves de firma de los tokens JWT. El `Issuer` será la URL de su tenant. El `Audience` será el identificador de su 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 %} #### Uso de un token de aplicación con PowerShell Universal Ahora que tiene un token de aplicación de Auth0, puede usarlo igual que usaría los tokens de aplicación integrados. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} #### Opcional: definir un desencadenador de acción de Auth0 Al conceder un nuevo token de acceso desde Auth0, estos no contendrán los roles o permisos estándar como los tokens de aplicación integrados de PowerShell Universal. Puede controlarlo definiendo una acción personalizada y asignándola al desencadenador `credential-exchange`. Haga clic en Actions y después en Library y Create Action y a continuación en Create Custom Action. Seleccione el desencadenador Password Reset / Post Challenge y asigne un nombre a la acción. Defina la acción estableciendo un claim personalizado para el tipo de claim `PSUPermission`. Este ejemplo simplemente proporciona todo el acceso a las APIs de PowerShell Universal. Puede usar el contexto del evento para definir qué permisos se reciben en función de la solicitud del token de acceso. {% code collapsedlinecount="10" %} ```javascript exports.onExecuteCredentialsExchange = async (event, api) => { api.accessToken.setCustomClaim("PSUPermission", "(.*)") }; ``` {% endcode %} A continuación, añada la acción al desencadenador del flujo de trabajo de `credential-exchange` haciendo clic en Actions y después en Triggers y a continuación en `credential-exchange.` Arrastre la acción Set Permissions al flujo de trabajo. Una vez completado esto, puede generar un nuevo token y acceder a cualquier API dentro de PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} ### Véase también * [Devolutions Academy – Esquema y autenticación](https://academy.devolutions.net/student/activity/3542770-part-1-outline-and-authentication) * [Devolutions Academy – Autenticación](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/es/seguridad/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.