> 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 Puede usar los tokens de aplicación de PowerShell Universal tanto con [endpoints de API personalizados](https://github.com/Devolutions/docs/tree/master/translations/es/powershell-universal/config/security/broken-reference/README.md) como con la [API de gestión](/powershell-universal/es/config/management-api.md). La API de gestión utiliza 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 mediante 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 Security \ 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 diálogo le permite especificar la identidad, el rol y el tiempo de expiración del token.

Diálogo de token de aplicación

## 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 mediante programación con la API, puede hacer lo siguiente: ``` 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 ``` 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 mediante 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. ``` 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 ``` ## 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 el 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, lo que reducirá el rendimiento o causará problemas con determinadas herramientas que no admiten valores de token más largos. Puede usar roles personalizados con un conjunto de permisos personalizado para limitar el número de roles pero proporcionar 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 mediante 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. ```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" } ``` ## 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 al crearlos. Se les aplica un hash y la base de datos almacena el valor 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 del sistema Los tokens del 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 su expiración y sus roles. ## Claves de firma ### Clave de firma local Por defecto, PowerShell Universal crea una clave de firma basada en la cadena Jwt \ SigningKey de appsettings.json. Este valor se usa para codificar y decodificar 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 será 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. ```json { "Jwt" : { "DiscoveryDocument": "https://auth20/metadata.xml" } } ``` ## Tokens de aplicación externos Al configurar una clave de firma remota, los tokens los genera entonces el proveedor de OAuth 2.0. Debido a esto, la información de claims también la genera ese proveedor. Para asignar correctamente roles y permisos dentro de PowerShell Universal, deberá asegurarse de que los claims adecuados estén definidos dentro del token. PowerShell Universal evaluará los siguientes valores de claim dentro de un token. * PSUPermission - Define los permisos del token * Roles - Define los roles del token. Para permitir el acceso a los recursos dentro 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 lograrlo en Auth0. ```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" ] } ``` Como alternativa, puede habilitar la evaluación de claims para tokens JWT. Por defecto, PowerShell Universal usa un conjunto estático de permisos al recibir un token. Si habilita la evaluación de claims para 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. ```json { "Jwt": { "EvaluateClaims": "true" } } ``` 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 Usando funciones estándar de Auth0, puede generar tokens que luego pueden proporcionar roles según los claims del token. Esto no requiere ningún trigger ni acción especial dentro de 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 luego en Create Application.
#### Crear una API de Auth0 A continuación, cree una API de Auth0 haciendo clic en Applications \ APIs y luego 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 a la aplicación a usar la API En la configuración de la aplicación, haga clic en APIs y active el conmutador 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, ahora puede solicitar un token de acceso en Auth0. Los valores `client_id` y `client_secret` se encuentran en la página Application Details. El valor `audience` debe ser el identificador de su API. ```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 ``` #### 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. ```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" } } ``` #### Configurar un rol para asignarlo al permiso de Auth0 Por último, cree un rol que se asigne al permiso de Auth0. El siguiente ejemplo comprueba que el token de 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. ```powershell New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator" ``` #### Usar un token de aplicación con PowerShell Universal Ahora que tiene un token de aplicación de Auth0, puede usarlo igual que lo haría con los tokens de aplicación integrados. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` ### 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 luego en Create Application.
#### Crear una API de Auth0 A continuación, cree una API de Auth0 haciendo clic en Applications \ APIs y luego 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 a la aplicación a usar la API En la configuración de la aplicación, haga clic en APIs y active el conmutador 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, ahora puede solicitar un token de acceso en Auth0. Los valores `client_id` y `client_secret` se encuentran en la página Application Details. El valor `audience` debe ser el identificador de su API. ```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 ``` #### 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. ```json { "Jwt": { "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration", "Issuer": "https://ironmansoftware.us.auth0.com/", "Audience": "https://powershelluniversal.com" } } ``` #### Usar un token de aplicación con PowerShell Universal Ahora que tiene un token de aplicación de Auth0, puede usarlo igual que lo haría con los tokens de aplicación integrados. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` #### Opcional: definir un trigger de acción de Auth0 Al conceder un nuevo token de acceso desde Auth0, este no contendrá los roles o permisos estándar como los tokens de aplicación integrados de PowerShell Universal. Puede controlar esto definiendo una acción personalizada y asignándola al trigger `credential-exchange`. Haga clic en Actions y luego en Library y Create Action y después en Create Custom Action. Seleccione el trigger 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 según la solicitud del token de acceso. ```javascript exports.onExecuteCredentialsExchange = async (event, api) => { api.accessToken.setCustomClaim("PSUPermission", "(.*)") }; ``` A continuación, añada la acción al trigger de flujo de trabajo de `credential-exchange` haciendo clic en Actions y luego en Triggers y después 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. ```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/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.