Configuración de la aplicación

La configuración de la aplicación se encuentra en el fichero appsettings.json dentro del directorio de instalación. Este fichero define varios ajustes que puede aplicar a PowerShell Universal. Aunque puede editar este fichero directamente, se recomienda utilizar uno de los métodos siguientes para conservar la configuración, ya que el fichero appsettings.json del directorio de instalación se sobrescribirá en las actualizaciones.

Cuando se instala desde el MSI, el directorio de instalación de PowerShell Universal es ${env:ProgramFiles(x86)}\Universal.

AppSettings.json en ProgramData

Puede crear un fichero appsettings.json dentro de la carpeta $Env:ProgramData\PowerShellUniversal. Puede utilizar un subconjunto de los ajustes del fichero appsettings.json. Por ejemplo, si quisiera sobrescribir los ajustes de JWT, podría tener un fichero appsettings.json como este.

{
  "Jwt": {  
    "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
    "Issuer": "IronmanSoftware",
    "Audience": "PowerShellUniversal"
  }
}

Variables de entorno

También puede establecer variables de entorno para sus ajustes. Las variables de entorno deben tener un guion bajo entre cada subconjunto del fichero appsettings.json. Por ejemplo, si quiere cambiar la clave de firma de JWT mediante una variable de entorno, establecería la variable $Env:Jwt__SigningKey. Si quisiera establecer la URL de la API externa, establecería $Env:Api__Url.

Ejemplos

Uso de una variable de entorno para el secreto de OpenID Connect.

$Env:Authentication__OIDC__ClientSecret = "mySecret"

Uso de una variable de entorno para la clave de firma de JWT.

$Env:Jwt__SigningKey = "mySigningKey"

Línea de comandos

Puede especificar la ubicación del fichero appsettings.json mediante el argumento de línea de comandos --appsettings de Universal.Server.exe .

.\Universal.Server.exe --appsettings C:\appsettings.json

Descripciones de los ajustes

Kestrel / Endpoints

Valor predeterminado

"Kestrel": {
  "Endpoints": {
    "HTTP": {
      "Url": "http://*:5000"
    }
  },
  "RedirectToHttps": "false"
},

La sección de endpoints de Kestrel le permite configurar el servidor web. Esta configuración no se utiliza al alojar en IIS. En esta sección puede configurar opciones como HTTPS y el puerto en el que escuchará PowerShell Universal.

Kestrel es la implementación de servidor web para ASP.NET Core que utiliza PowerShell Universal. Para obtener más información sobre las opciones de configuración de Kestrel, visite esta página de documentación de Microsoft.

Clave	Descripción
RedirectToHttps	Cuando es true, el servidor web redirigirá las solicitudes HTTP a HTTPS
BasePath	Necesario al configurar PowerShell Universal como un sitio anidado dentro de IIS. Debe contener la ruta anidada de IIS. Por ejemplo, /psu
Hsts \ MaxAgeDays	Establece la antigüedad máxima en días para HTTP Strict Transport Security.
CookiePolicy	Cuando se establece en SameSiteNone, se aplicará el valor SameSite=None a las cookies en PSU. Esto es útil cuando se aloja PSU en iframes.
Headers	Un objeto en el que las claves son las cabeceras que se establecerán en cada solicitud y el valor es el valor de la cabecera.

Azure Application Insights

Valor predeterminado

"ApplicationInsights": {
  "ConnectionString": ""
},

Clave	Descripción
ConnectionString	Establece la cadena de conexión para Application Insights.

Registro

Valor predeterminado

{
    "SystemLogPath": "%PROGRAMDATA%/PowerShellUniversal/Logs/System/log.txt",
    "SystemLogLevel": "Information"
}

Establece la ruta y el nivel del registro del sistema. Esto se sobrescribirá con el nivel de registro de settings.ps1 una vez que se cargue. Este ajuste es útil para depurar problemas durante el arranque del sistema.

Clave	Descripción
SystemLogPath	Ruta al fichero de registro.
SystemLogLevel	El nivel del registro del sistema. Puede establecer valores como Debug, Information, Warning y Error.

AllowedHosts

Valor predeterminado

    "AllowedHosts": "*",

Los hosts que pueden conectarse al servidor web. De forma predeterminada, cualquier host.

CorsHosts

Valor predeterminado

    "CorsHosts": "",

Configura los hosts que pueden realizar solicitudes de intercambio de recursos entre orígenes (CORS) al servidor. Para permitir varios hosts, separe cada host con un punto y coma.

"CorsHosts" : "https://www.google.com;https://login.microsoftonline.com"

Data

Valor predeterminado

"Data": {
  "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
  "ConnectionString": "%ProgramData%\\UniversalAutomation\\database.db",
  "GitRemote": "",
  "GitUserName": "",
  "GitPassword": "", 
  "GitBranch": "",
  "ConfigurationScript": "",
  "ExternalGitClient": false,
  "Mode": "automatic",
  "SlowQueryLimit": 500,
  "Persistence": {}
},

Clave	Descripción
RepositoryPath	Ruta a la ubicación de almacenamiento de los ficheros de configuración utilizados por Universal.
ConnectionString	Ruta a la base de datos utilizada por Universal.
GitRemote	Remoto de Git utilizado para sincronizar con Universal.
GitBranch	Rama de Git que se debe extraer al sincronizar con Universal.
GitUserName	Nombre de usuario de Git utilizado para sincronizar con GitRemote. Cuando se utiliza un PAT, este puede ser cualquier valor.
GitPassword	La contraseña de usuario de Git o el token de acceso personal utilizado para sincronizar con GitRemote.
GitSyncTimeout	El número de segundos antes de que se agote el tiempo de espera de un comando del cliente Git externo. El valor predeterminado es 60 segundos.
ConfigurationScript	Ubicación de un script de configuración personalizado que se debe cargar. Puede devolver objetos como scripts, dashboards y endpoints desde este script.
ExternalGitClient	Cuando se establece en true, se utilizará el cliente Git del sistema operativo en lugar del cliente de biblioteca integrado
Mode	Establece el modo de Git. Puede ser manual o automático. El valor predeterminado es manual.
SlowQueryLimit	El número de milisegundos que debe ejecutarse una consulta SQL antes de que se escriba un mensaje de registro. El valor predeterminado es 200 ms. Solo está disponible para MS SQL.
Persistence	Configura la persistencia de recursos en base de datos.
InvisibilityTimeoutMinutes	El número de minutos antes de que se agote el tiempo de espera de un trabajo en Hangfire. El valor predeterminado es 5. Solo se aplica a PostgreSQL.

API

Valor predeterminado

"Api": {
  "Url": "",
  "HideManagementDoc": false
},

Clave	Descripción
Url	Establece la URL externa utilizada internamente por Universal. Esto es necesario cuando se ejecuta Universal desde dentro de un proxy inverso como IIS. Cuando se utilizan cmdlets como Get-UAScript desde dentro de un trabajo en ejecución, el servidor Universal necesita determinar dónde está el servidor web. Cuando se ejecuta dentro de un proxy, no puede determinarlo por sí mismo. Le convendrá configurarlo para que apunte al nombre y al puerto del sitio web de IIS en esta configuración.
HideManagementDoc	Si es true, oculta la documentación OpenAPI de la API de administración de PowerShell Universal.

`Api.Url` lo utiliza internamente PowerShell Universal cuando los cmdlets necesitan volver a llamar al servidor PSU desde trabajos, endpoints u otros contextos de ejecución internos. En entornos con proxy inverso o con balanceo de carga, asegúrese de que este valor apunte a una URL estable y directamente accesible del host de PSU. Utilizar un alias DNS u otro endpoint indirecto puede provocar fallos intermitentes de los cmdlets si ese alias se resuelve a través de un proxy o una ruta de backend inestables. Si es necesario, especifique `-ComputerName` explícitamente en la llamada al cmdlet.

Autenticación

Valor predeterminado

"Authentication" : {
    "Windows": {
      "Enabled": "false"
    },
    "WSFed": {
      "Enabled": "false",
      "MetadataAddress": "",
      "Wtrealm": "",
      "CallbackPath": "/auth/signin-wsfed",
      "Wreply": "",
      "UseTokenLifetime": true,
      "CorrelationCookieSameSite": ""
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true,
      "Scope": "openid profile groups",
      "GetUserInfo": false
    },
    "ClientCertificate": {
      "Enabled": "false"
    },
    "SessionTimeout": "25"
  },

Windows

Clave	Descripción
Enabled	Habilita o deshabilita la autenticación de Windows.

OIDC

Ajustes de autenticación de OpenID Connect.

Clave	Descripción
Enabled	Si OIDC está habilitado.
CallbackPath	La ruta a la que el proveedor de OIDC realizará la llamada de retorno.
ClientID	El ID de cliente de OIDC configurado.
ClientSecret	El secreto de cliente de OIDC configurado.
Resource	Recursos concedidos con este token de OIDC.
Authority	La autoridad que se debe invocar al autenticar. Esta es la URL de su proveedor de OIDC.
ResponseType	El tipo de respuesta devuelta por el proveedor. El valor más habitual aquí es code
SaveTokens	Si se debe guardar el token para que esté disponible para endpoints como los dashboards.
CorrelationCookieSameSite	Ajustes same de la cookie de correlación.
UseTokenLifetime	Si se establece en true, la duración de la cookie se establecerá en la duración del token. Esto anula el valor de tiempo de espera de la sesión.
GetUserInfo	Devuelve información adicional del usuario para su uso en los ficheros roles.ps1. Puede acceder a la información adicional mediante la variable $UserInfo.

WSFed

Configuración de autenticación WS-Federation.

Clave	Descripción
Enabled	Si WS-Fed está habilitado.
MetadataAddress	La dirección de metadatos para recuperar información sobre la instancia de WS-Fed.
Wrealm
Wreply
CallbackPath	La ruta a la que el proveedor OIDC realizará la llamada de retorno.
UseTokenLifetime	Si se establece en true, la duración de la cookie se establecerá en la duración del token. Esto anula el valor de tiempo de espera de la sesión.
CorrelationCookieSameSite	Configuración same de la cookie de correlación.

Umbral de tiempo de espera de sesión (minutos)

Clave	Descripción
SessionTimeout	Número de minutos antes de que caduque una sesión iniciada (el valor predeterminado es 25)

JWT

Ajustes de configuración de JSON Web Token

Valor predeterminado

"Jwt": {  
  "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
  "Issuer": "IronmanSoftware",
  "Audience": "PowerShellUniversal"
},

Clave	Descripción
SigningKey	La clave de firma para los tokens JWT.
Issuer	El emisor que se incluirá en el token.
Audience	La audiencia que se incluirá en el token.

Secrets

Opciones para configurar las bóvedas de secretos predeterminadas.

Valor predeterminado

"Secrets": {
  "SecretStore": {
    "Password": "PSUSecretStore"
  },
  "Database": {
    "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf",
    "Password": "",
    "KeySize": 128
  },
  "SecretManagement": {
    "OutOfProcess": false
  }
}

Clave	Descripción
SecretStore \ Password	La contraseña de la bóveda PSUSecretStore. Utiliza el módulo Microsoft SecretStore.
Database \ EncryptionKey	La clave de cifrado AES 128 utilizada para cifrar los secretos almacenados en la base de datos.
Database \ Password	Una contraseña utilizada para generar una clave de cifrado. EncryptionKey se ignorará si se especifica una contraseña.
Database \ KeySize	El número de bytes de la clave. Debe ser múltiplo de 128 y su valor predeterminado es 128.
SecretManagement \ OutOfProcess	Indica si las operaciones de gestión de secretos deben ejecutarse fuera de proceso. El valor predeterminado es false.

Generar una clave de cifrado

Las claves de cifrado son de 128 bits y requieren la longitud adecuada. Se codifican como una cadena base64 y se convierten en bytes durante el inicio.

Puede utilizar el siguiente código para generar una clave secreta con la longitud adecuada.

$random = [System.Security.Cryptography.RandomNumberGenerator]::Create();
$buffer = New-Object byte[] 16;
$random.GetBytes($buffer);
[Convert]::ToBase64String($buffer)

UniversalAutomation

Configuración para funciones específicas de automatización.

Valor predeterminado

"UniversalAutomation": {
    "Queues": [],
    "JobHandshakeTimeout": 30,
    "JobDebugging": false,
    "ContinueJobOnServerStop": false,
    "HangfireWorkerCount" : 100
  }

Clave	Descripción
Queues	Colas personalizadas de las que forma parte esta instancia de PSU.
JobHandshakeTimeout	El número de segundos que se esperará antes de que falle un trabajo tras iniciar el proceso de PowerShell que lo ejecuta, si el proceso no se comunica de vuelta con el servidor.
JobDebugging	Si se generan ficheros en el directorio temporal al iniciar un trabajo. Esto resulta útil para la depuración si los trabajos caducan antes de iniciarse.
ContinueJobOnServerStop	Si se debe continuar ejecutando un trabajo después de detener el servicio. No se podrá informar del progreso del trabajo, pero el script continuará ejecutándose.
HangfireWorkerCount	El número de subprocesos de trabajo de Hangfire que se iniciarán en el servidor. Esta configuración es específica del nodo. El valor predeterminado es 100. Es el número total de trabajos que pueden ejecutarse en un nodo concreto a la vez.

HideAdminConsole

{
    "HideAdminConsole": false
}

Impide que el servicio sirva la consola de administración. Esto impedirá que cualquier usuario, incluidos los administradores, utilice la consola de administración.

NodeName

{
    "NodeName": ""
}

La opción de nombre de nodo se utiliza para cambiar el nombre de la instancia de PowerShell Universal. De forma predeterminada, es el nombre del ordenador local. Al utilizar PowerShell Universal en un contenedor, esto puede resultar problemático porque el nombre puede cambiar cada vez que se reinicia el contenedor.

Para establecer un nombre de nodo estático, cambie este parámetro.

Recursos estáticos

Puede definir recursos estáticos mediante la configuración de la aplicación. Esto incluye las variables de entorno y appsettings.json. Para definir un recurso, utilice el nodo Resources dentro de appsettings.json o el prefijo Resources con una variable de entorno.

Por ejemplo, para definir un rol estático en appsettings.json, utilice lo siguiente.

{
    "Resources": {
        "Roles": [
            {
                "Name": "Static Role",
                "ClaimType": "group",
                "ClaimValue": "xyz123"
            }
        }
    }
}

Puede definir el mismo rol mediante variables de entorno.

$ENV:Resources__Roles__0__Name = "Static Role"
$ENV:Resources__Roles__0__ClaimType = "group"
$ENV:Resources__Roles__0__ClaimValue = "xyz123"

Ejemplo: Docker Compose

Puede utilizar variables de entorno en un fichero YML de Docker Compose para definir recursos que estarán disponibles en PowerShell Universal tras su inicio. El siguiente ejemplo crea etiquetas y un rol, establece un título de administrador personalizado, añade una licencia y establece el entorno predeterminado.

services:    
    psu:         
      image: ironmansoftware/universal:latest
      environment:
          - Resources__Tags__0__Name=Production  
          - Resources__Tags__1__Name=Development
          - Resources__Roles__0__Name=PSUAdmin
          - Resources__Roles__0__ClaimType=groups
          - Resources__Roles__0__ClaimValue=1234567890abcdef1234567890abcdef
          - Resources__Roles__0__Permissions_0=*
          - Resources__Settings__DefaultEnvironment=PowerShell 7
          - Resources__Branding__AdminConsoleTitle=PSU Admin Console
          - Authentication__OIDC__Enabled=true
          - Authentication__OIDC__ClientId=123-123-123-123-123
          - Authentication__OIDC__ClientSecret=secret
          - Authentication__OIDC__Authority=https://login.microsoftonline.com/123-123-123-123
          - PSULICENSE=<License></License>
      ports:
        - "5000:5000"

Configuración del entorno de ejecución de .NET

El entorno de ejecución de .NET también admite ajustes que se aplican a PowerShell Universal. Es posible que desee ajustar esta configuración según sus necesidades.

Puede encontrar toda la información sobre la configuración del entorno de ejecución de .NET en Microsoft Docs.

Exceso de ficheros temporales

En entornos Linux, es posible que el entorno de ejecución cree muchos ficheros temporales para habilitar las funciones de depuración. Deshabilitar la configuración de diagnóstico del entorno de ejecución evitará que esto ocurra. No podrá utilizar las herramientas de depuración de .NET con esta opción deshabilitada.

$Env:DOTNET_EnableDiagnostics = $false

Véase también

• Devolutions Academy – Creación de un endpoint básico