Módulo

Conexión a PowerShell Universal

El módulo de PowerShell Universal necesita algunos datos para conectarse al servidor. En primer lugar, necesita conocer la URL o el nombre del equipo y, en segundo lugar, necesita credenciales para acceder a los recursos de forma remota.

Puede utilizar el cmdlet Connect-PSUServer para configurar una conexión con el servidor. Al llamar a este cmdlet se establece la información de conexión para todo el proceso. Si está ejecutando un proceso multiusuario, debe tener en cuenta las implicaciones del uso de este comando.

Connect-PSUServer -ComputerName http://localhost:5000 -AppToken xyz123

Al ejecutar scripts en el entorno Integrated o dentro de aplicaciones o API en PowerShell Universal, considere utilizar directamente los valores de nombre de equipo y credenciales para los cmdlets, con el fin de evitar compartirlos en todo el proceso.

Get-PSUJob -ComputerName http://localhost:5000 -AppToken xyz123

Autenticación

Token de aplicación

Puede utilizar el parámetro -AppToken para autenticarse contra la API con el token especificado. Trate el token de aplicación como una contraseña, ya que concede acceso según los roles asignados a él.

Credenciales predeterminadas

También puede utilizar credenciales predeterminadas, o credenciales de Windows. Este mecanismo solo se admite si el servidor de destino tiene habilitada la autenticación de Windows. Los roles y permisos se concederán al conectarse al servidor.

Credenciales

Si tiene habilitada la autenticación por formulario, puede utilizar la autenticación básica especificando un objeto PSCredential en el parámetro -Credential de Connect-PSUServer.

Ámbito

Connect-PSUServer admite un parámetro de ámbito para definir cómo persistir la información de conexión. De forma predeterminada, el ámbito es Process. El ámbito de proceso almacena la información de conexión en un ámbito estático de .NET. Todos los cmdlets ejecutados en el proceso actual utilizarán esta información de conexión.

Si está utilizando Connect-PSUServer en un entorno con múltiples runspaces, como el entorno Integrated o dentro de aplicaciones en PowerShell Universal, es posible que solo desee almacenar la información de conexión para el runspace actual. Utilice el valor de parámetro -Scope Runspace para ajustar cómo se almacena la información de conexión.

Desconexión

Puede desconectarse del servidor de PowerShell Universal utilizando el cmdlet Disconnect-PSUServer. Si ha utilizado el ámbito Runspace, borrará las variables necesarias y, si ha utilizado el ámbito Process, borrará las propiedades estáticas necesarias.

Conexiones internas

Al utilizar el módulo Universal dentro de PowerShell Universal, no es necesario especificar credenciales ni el nombre del equipo en instalaciones básicas. La autorización coincidirá con el usuario actual y la URL de la API se inferirá del servidor actual.

Autorización

Al utilizar el modelo de seguridad Strict, la autorización se basa en el llamante. Por ejemplo, si un usuario llama a un endpoint de API y ese endpoint llama a Invoke-PSUScript, la llamada se realiza en nombre del llamante del endpoint. Los permisos del llamante se aplican en la ejecución del script.

Al utilizar otros modelos de seguridad, los cmdlets se llaman en nombre del usuario System y la autorización no se aplica en función del llamante del recurso.

Modelo de seguridad de autorización

Puede cambiar el modelo de autorización para permitir que cualquier llamada realizada desde dentro de PowerShell Universal funcione sin un token de aplicación. Aunque algunos puedan considerar que esto es menos seguro, depende del uso que su organización haga de la plataforma. Este valor se puede establecer en appsettings.json o en la variable de entorno API__SecurityModel.

Se requiere un contexto de usuario para la autenticación. Esto significa que, al utilizar el módulo en contextos sin usuario, como las programaciones, deberá proporcionar un token de aplicación.

En ámbitos que tienen un contexto de usuario, como una aplicación, las llamadas a los cmdlets se realizan con los privilegios de ese usuario. Por ejemplo, si un usuario que accede a una aplicación no tiene acceso para llamar a Get-PSUScript, el cmdlet no podrá utilizarse sin un token de aplicación con esos privilegios.

{
    "Api": {
       "SecurityModel": "Strict"
    }
}

El modo Permissive sigue utilizando las API externas de PowerShell Universal y comunica el contexto de usuario, si está disponible, al llamar a las API de PowerShell Universal. El modo Permissive permite el uso del modificador -Integrated para omitir la autorización y utilizar la conexión TCP de canal inverso en lugar de la API externa de PowerShell Universal.

{
    "Api": {
       "SecurityModel": "Permissive"
    }
}

También puede utilizar el modelo de seguridad Integrated para evitar por completo la necesidad de configurar tokens de aplicación, URL o certificados. El modelo de seguridad Integrated no comunica el contexto de usuario, ni siquiera cuando el usuario está autenticado. También utiliza la conexión TCP de canal inverso en lugar de la API externa de PowerShell Universal.

{
    "Api": {
       "SecurityModel": "Integrated"
    }
}

Confiar en el certificado HTTPS

En algunos entornos, puede ser necesario permitir que PowerShell Universal confíe en el certificado del servidor web para que la comunicación se realice correctamente. En cada llamada, puede utilizar el parámetro -TrustCertificate para permitir este comportamiento. Además, puede establecer el valor a nivel de servidor para permitir las comunicaciones internas.

{
    "Api": {
       "TrustCertificate": true
    }
}

Modo Integrated

El modo Integrated utiliza la conexión de canal inverso interna de PowerShell Universal para comunicarse con los servicios a través del módulo Universal. Al utilizar el modo Integrated, la autorización solo se realiza cuando la API está en el modo de seguridad Strict.

Puede invocar cmdlets utilizando el modo Integrated mediante el parámetro de modificador -Integrated.

El modelo de seguridad del servidor también se puede establecer en Integrated. Esto obliga a que todas las llamadas a cmdlets utilicen el modo Integrated y ya no requiere el uso del parámetro -Integrated.

Programaciones

Las programaciones no tienen un usuario actual. Deberá especificar un token de aplicación o una credencial predeterminada al utilizar cmdlets dentro de scripts programados. Aunque esto supone un paso adicional, garantiza que solo se apliquen los permisos necesarios al script de la programación.

Las programaciones no tienen un contexto de usuario, por lo que deberá especificar uno para que se ejecuten correctamente al utilizar estos cmdlets.

Proxies inversos (IIS)

PowerShell Universal utiliza todos los datos disponibles para determinar la URL adecuada a la que llamar al usar la API. Esto puede resultar problemático al utilizar un proxy inverso, como IIS. La URL que ve PowerShell Universal es diferente de la URL real y accesible. Esto puede causar problemas cuando los cmdlets intentan acceder a la API.

Para solucionar este problema, puede especificar la URL adecuada en cada llamada a un cmdlet o personalizar la URL de la API en la configuración de la aplicación.

Especificar la URL

Para especificar la URL, simplemente indíquela en el parámetro -ComputerName.

Get-PSUJob -ComputerName 'https://external.company.com/psu'

Configuración de la aplicación

También puede establecer el valor de la URL de la API en la configuración de la aplicación para proporcionar el mismo valor en toda la plataforma. Establezca el valor en una variable de entorno o en el fichero appsettings.json.

{
  "API": {
    "URL": "https://external.company.com/psu"
  }
}

Consideraciones técnicas

El módulo Universal utiliza gRPC para todas las comunicaciones con el servidor de PowerShell Universal. Según la configuración del servidor, la comunicación gRPC será ligeramente diferente.

HTTPS

Al utilizar HTTPS, se empleará el canal de comunicación gRPC estándar. Esta es la configuración más rápida porque no requiere serialización especial ni adaptaciones para protocolos de nivel inferior. gRPC requiere HTTP/2.

Si se utiliza HTTPS, el sistema debe confiar en el certificado. Si el certificado es autofirmado, puede utilizar el parámetro -TrustCertificate en los cmdlets para evitar la comprobación del certificado.

HTTP y autenticación de Windows

Al utilizar HTTP o la autenticación de Windows, HTTP/2 no se admite y gRPC no puede ejecutarse de forma nativa porque no se admiten las cabeceras finales. Para adaptarse a esto, el módulo Universal utilizará una tecnología llamada gRPC-Web para traducir las llamadas gRPC a HTTP y JSON, con el fin de llamar a métodos REST de HTTP en lugar de a los métodos gRPC estándar.

Esta configuración es ligeramente más lenta, pero no debería notarse en la mayoría de los entornos.

Modo Integrated

El modo Integrated no utiliza la API externa y se comunica a través del canal inverso gRPC de PowerShell Universal. No es necesario configurar URL de API, certificados ni credenciales.