Referencia técnica del conector de Windows PowerShell
En este artículo se describe el conector de Windows PowerShell. El artículo se aplica a los siguientes productos:
- Microsoft Identity Manager 2016 (MIM2016)
Para MIM2016, el conector está disponible como descarga desde el Centro de descarga de Microsoft.
Información general sobre el conector de PowerShell
El conector de PowerShell le permite integrar el servicio de sincronización con los sistemas externos que ofrecen API basadas en Windows PowerShell. El conector proporciona un puente entre las funcionalidades del marco del agente de administración de conectividad extensible 2 (ECMA2) basado en llamadas y Windows PowerShell. Para obtener más información sobre el marco ECMA, consulte Extensible Connectivity 2.2 Management Agent Reference.
Requisitos previos
Antes de usar el conector, asegúrese de que tiene lo siguiente en el servidor de sincronización:
- Microsoft .NET 4.6.2 Framework o posterior
- Windows PowerShell 2.0, 3.0 o 4.0
La directiva de ejecución en el servidor del servicio de sincronización debe configurarse para permitir que el conector ejecute scripts de Windows PowerShell. A menos que los scripts que ejecutan el conector estén firmados digitalmente, configure la directiva de ejecución mediante la ejecución de este comando:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
La implementación de este conector requerirá uno o varios scripts de PowerShell. Algunos productos de Microsoft pueden proporcionar secuencias de comandos para su uso con este conector, y la declaración de soporte para esas secuencias de comandos sería proporcionada por ese producto. Si va a desarrollar sus propios scripts para su uso con este conector, deberá estar familiarizado con la API del agente de administración de conectividad extensible para desarrollar y mantener esos scripts. Si va a realizar la integración con sistemas de terceros mediante sus propias secuencias de comandos en un entorno de producción, le recomendamos que trabaje con el proveedor de terceros o con un socio de implementación para obtener ayuda, orientación y soporte para esta integración.
Creación de un nuevo conector
Para crear un conector de Windows PowerShell en el servicio de sincronización, debe proporcionar una serie de scripts de Windows PowerShell que ejecuten los pasos solicitados por el servicio de sincronización. Dependiendo del origen de datos al que se conecte y de la funcionalidad que precise, varían los scripts que debe implementar. En esta sección se describen los scripts que se pueden implementar, así como cuándo son necesarios.
El conector de Windows PowerShell está diseñado para almacenar cada uno de los scripts dentro de la base de datos del servicio de sincronización. Aunque es posible ejecutar scripts que se almacenan en el sistema de archivos, es más fácil insertar el cuerpo de cada script directamente en la configuración del conector.
Para crear un conector de PowerShell, en Servicio de sincronización, seleccione Agente de administración y Crear. Seleccione el conector PowerShell (Microsoft) .
Conectividad
Proporcione los parámetros de configuración para conectarse a un sistema remoto. Estos valores se guardan con seguridad el servicio de sincronización y estarán disponibles de los scripts de Windows PowerShell cuando se ejecuta el conector.
Puede configurar los siguientes parámetros de conectividad:
Conectividad
| Parámetro | Valor predeterminado | Propósito |
|---|---|---|
| Server | <En blanco> | Nombre del servidor al que debe conectarse el conector. |
| Dominio | <En blanco> | Dominio de la credencial para almacenar para su uso cuando se ejecuta el conector. |
| Usuario | <En blanco> | Nombre de usuario de la credencial para almacenar para su uso cuando se ejecuta el conector. |
| Contraseña | <En blanco> | Contraseña de la credencial para almacenar para su uso cuando se ejecuta el conector. |
| Suplantación de la cuenta del conector | False | Cuando es true, el servicio de sincronización ejecuta los scripts de Windows PowerShell en el contexto de las credenciales suministradas. Cuando sea posible, se recomienda que se use el parámetro $Credentials pasado a cada script en lugar de la suplantación. Para más información sobre los permisos adicionales necesarios para usar este parámetro, consulte Configuración adicional para la suplantación. |
| Carga del perfil de usuario al suplantar | False | Indica a Windows que cargue el perfil de usuario de las credenciales del conector durante la suplantación. Si el usuario suplantado tiene un perfil móvil, el conector no carga el perfil móvil. Para más información sobre los permisos adicionales necesarios para usar este parámetro, consulte Configuración adicional para la suplantación. |
| Tipo de inicio de sesión al suplantar | None | Tipo de inicio de sesión durante la suplantación Para obtener más información, consulte la documentación de dwLogonType. |
| Solo scripts firmados | False | Si es true, el conector de Windows PowerShell valida que cada script tenga una firma digital válida. Si es false, asegúrese de que la directiva de ejecución de Windows PowerShell del servidor de servicio de sincronización es RemoteSigned o Unrestricted. |
Módulo común
: el conector le permite almacenar un módulo compartido de Windows PowerShell en la configuración. Cuando el conector ejecuta un script, el módulo de Windows PowerShell se extrae en el sistema de archivos, por lo que puede importarlo cada script.
Para los scripts de importación, exportación y sincronización de contraseña, el módulo común se extrae en la carpeta MAData del conector. Para los scripts de esquema, validación, jerarquía y detección de partición, el módulo común se extrae en la carpeta %TEMP%. En ambos casos, el script del módulo común extraído se denomina según la configuración de nombre de script del módulo común.
Para cargar un módulo denominado FIMPowerShellConnectorModule.psm1 desde la carpeta MAData, use la siguiente instrucción: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")
Para cargar un módulo denominado FIMPowerShellConnectorModule.psm1 desde la carpeta %TEMP%, use la siguiente instrucción: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")
Validación de parámetros
El script de validación es un script de Windows PowerShell opcional que puede usarse para comprobar la validez de los parámetros de configuración del conector proporcionados por el administrador. La validación del servidor y de las credenciales de conexión, así como los parámetros de conectividad, son los usos comunes del script de validación. El script de validación se llama después de que se hayan modificado las pestañas y cuadros de diálogo siguientes:
- Conectividad
- Parámetros globales
- Configuración de la partición
El script de validación recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameterPage | ConfigParameterPage | La pestaña o cuadro de diálogo de configuración que desencadenó la solicitud de validación. |
| ConfigParameters | KeyedCollection [string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
El script de validación debe devolver un solo objeto ParameterValidationResult a la canalización.
Detección de esquemas
El script Detección de esquema es obligatorio. Este script devuelve los tipos de objeto, atributos y las restricciones de atributos que utiliza el servicio de sincronización al configurar las reglas de flujo de atributos. El script Detección de esquema se ejecuta durante la creación del conector y rellena el esquema del conector. También lo utiliza la acción Refresh Schema de Synchronization Service Manager.
El script de detección del esquema recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection [string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
El script debe devolver un único objeto Schema a la canalización. El objeto Schema consta de objetos SchemaType que representan los tipos de objeto (por ejemplo, usuarios o grupos). El objeto SchemaType contiene una colección de objetos SchemaAttribute que representan los atributos (por ejemplo, nombre, apellido y dirección postal) del tipo.
Parámetros adicionales
Además de la configuración estándar descrita hasta ahora, puede definir opciones de configuración personalizadas adicionales que son específicos de la instancia del conector. Estos parámetros se pueden especificar en los niveles del conector, partición o paso de ejecución y se puede acceder a ellos desde el script de Windows PowerShell competente. Las opciones de configuración personalizadas pueden almacenarse en la base de datos del servicio de sincronización como texto sin formato o pueden cifrarse. El servicio de sincronización automáticamente cifra y descifra proteger las opciones de configuración seguras cuando sea necesario.
Para especificar opciones de configuración personalizadas, separe el nombre de cada parámetro por una coma (,).
Para acceder a las opciones de configuración personalizadas desde un script, debe sufijar el nombre con un carácter de subrayado ( _ ) y el ámbito del parámetro (Global, Partition o RunStep). Por ejemplo, para acceder el parámetro Global FileName, use este fragmento de código: $ConfigurationParameters["FileName_Global"].Value
Funcionalidades
La pestaña Funcionalidades del Diseñador de agente de administración define el comportamiento y la funcionalidad del conector. Las selecciones realizadas en esta pestaña no pueden modificarse cuando se crea el conector. En esta tabla se muestra la configuración de la funcionalidad.
| Capacidad | Descripción |
|---|---|
| Estilo de nombre distintivo | Indica si el conector admite nombres distintivos y si es así, de qué estilo. |
| Tipo de exportación | Determina los tipos de objetos presentes en el script de exportación. |
| Normalización de datos | Indica al servicio de sincronización que normalice los atributos de anclaje antes de que se proporcionen a los scripts. |
| Confirmación de objeto | Configura el comportamiento de importación pendiente en el servicio de sincronización. |
| Usar el nombre distintivo como delimitador | Si se establece el estilo de nombre distintivo en LDAP, el atributo de anclaje del espacio del conector también es el nombre distintivo. |
| Operaciones simultáneas de varios conectores | Cuando está activada, se pueden ejecutar simultáneamente varios conectores de Windows PowerShell. |
| Particiones | Cuando está activada, el conector admite varias particiones y la detección de particiones. |
| Hierarchy | Cuando está activada, el conector admite una estructura jerárquica de estilo LDAP. |
| Habilitar importación | Cuando está activada, el conector importa datos a través de scripts de importación. |
| Habilitar importación diferencial | Cuando está activada, el conector puede solicitar los valores diferenciales de los scripts de importación. |
| Habilitar exportación | Cuando está activada, el conector exporta datos a través de scripts de exportación. |
| Habilitar exportación completa | Cuando está activada, los scripts de exportación admiten la exportación del espacio del conector completo. Para usar esta opción, también debe estar activada la opción Habilitar exportación. |
| No hay valores de referencia en el primer paso de exportación | Cuando está activada, se exportan los atributos de referencia en un segundo paso de exportación. |
| Habilitar cambio de nombre de objeto | Cuando está activada, se pueden modificar los nombres distintivos. |
| Eliminar-agregar al reemplazar | Cuando se activa, las operaciones de eliminar-agregar se exportan como un único reemplazo. |
| Habilitar operaciones de contraseña | Cuando está activada, se admiten los scripts de sincronización de contraseña. |
| Habilitar contraseña de exportación en el primer paso | Cuando está activada, se exportan las contraseñas establecidas durante el aprovisionamiento cuando se crea el objeto. |
Parámetros globales
La pestaña Global parámetros (Parámetros globales) en el Diseñador del agente de administración permite configurar los scripts de Windows PowerShell que ejecuta el conector. También puede configurar valores globales para los valores de configuración personalizados definidos en la pestaña Conectividad.
Detección de particiones
Una partición es un espacio de nombres independiente dentro de un esquema compartido. Por ejemplo, en Active Directory, cada dominio es una partición dentro de un bosque. Una partición es la agrupación lógica de las operaciones de importación y exportación. La importación y exportación tienen particiones como contexto y todas las operaciones tienen lugar en este contexto. Se supone que las particiones representan una jerarquía en LDAP. El nombre distintivo de una partición se usa en la importación para comprobar que todos los objetos devueltos están dentro del ámbito de una partición. El nombre distintivo de la partición también se usa durante el aprovisionamiento del metaverso al espacio de conector para determinar con qué partición de un objeto debe asociarse durante la exportación.
El script de detección de partición recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
El script debe devolver o bien un único objeto Partition o un elemento List[T] de objetos Partition en la canalización.
Detección de jerarquía
El script de detección de jerarquía solo se usa cuando la funcionalidad del estilo de nombre distintivo es LDAP. El script se usa para permitirle buscar y seleccionar un conjunto de contenedores que se consideran dentro o fuera del ámbito para operaciones de importación y exportación. El script solo debe proporcionar una lista de nodos que son elementos secundarios directos del nodo raíz proporcionado en el script.
El script de detección de jerarquía recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| ParentNode | HierarchyNode | El nodo raíz de la jerarquía bajo el cual el script debe devolver los elementos secundarios directos. |
El script debe devolver un único objeto HierarchyNode secundario o un elemento List[T] de objetos HierarchyNode secundarios a la canalización.
Importar
Los conectores que admiten operaciones de importación deben implementar tres scripts.
Begin Import
El script de inicio de importación se ejecuta al principio de un paso de ejecución de importación. Durante este paso, puede establecer una conexión al sistema de origen y realizar los pasos preparatorios necesarios antes de importar datos desde el sistema conectado.
El script de inicio de importación recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informa al script del tipo de ejecución de importación (diferencial o completo), partición, jerarquía, marca de agua y tamaño de página esperado. |
| Tipos | Esquema | El esquema del espacio del conector que se importa. |
El script debe devolver un único objeto OpenImportConnectionResults a la canalización, por ejemplo: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)
Import Data
El conector llama al script de importación de datos hasta que el script indica que no hay ningún dato más para importar. El conector de Windows PowerShell tiene un tamaño de página de 9 999 objetos. Si el script devuelve más de 9999 objetos para importar, debe admitir la paginación. El conector expone una propiedad de datos personalizados que se puede usar para almacenar una marca de agua, de tal forma que cada vez que se llame al script, este reanuda la importación de objetos donde se quedó.
El script de importación de datos recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| GetImportEntriesRunStep | ImportRunStep | Almacena la marca de agua (CustomData) que se puede usar durante las importaciones paginadas y las importaciones diferenciales. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informa al script del tipo de ejecución de importación (diferencial o completo), partición, jerarquía, marca de agua y tamaño de página esperado. |
| Tipos | Esquema | El esquema del espacio del conector que se importa. |
El script de importación debe escribir un objeto List[CSEntryChange] en la canalización. Esta colección se compone de atributos de CSEntryChange que representan cada objeto que se va a importar. Durante una ejecución de importación completa, esta colección debe tener un conjunto completo de objetos CSEntryChange que tengan todos los atributos para cada objeto. Durante una importación diferencial, el objeto CSEntryChange debe contener los valores diferenciales de nivel de atributo para cada objeto que se va a importar o una representación completa de los objetos que han cambiado (modo de reemplazo).
End Import
Al acabar la ejecución de importación, se ejecutará el script de finalización de importación. Este script debe realizar las tareas de limpieza necesarias (por ejemplo, cerrar las conexiones a los sistemas y responder a errores).
El script de finalización de importación recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informa al script del tipo de ejecución de importación (diferencial o completo), partición, jerarquía, marca de agua y tamaño de página esperado. |
| CloseImportConnectionRunStep | CloseImportConnectionRunStep | Informa al script del motivo de la finalización de la importación. |
El script debe devolver un único objeto CloseImportConnectionResults a la canalización, por ejemplo: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Exportación
De manera idéntica a la arquitectura de importación del conector, los conectores que admiten la exportación deben implementar tres scripts.
Begin Export
El script de inicio de exportación se ejecuta al principio de un paso de ejecución de exportación. Durante este paso, puede establecer una conexión al sistema de origen y llevar a cabo los pasos preparatorios necesarios antes de exportar datos desde el sistema conectado.
El script de inicio de exportación recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informa al script del tipo de ejecución de exportación (diferencial o completo), partición, jerarquía y tamaño de página esperado. |
| Tipos | Esquema | El esquema del espacio del conector que se exporta. |
El script no debe devolver ningún resultado a la canalización.
Export Data
El servicio de sincronización llamará al script de exportación de datos tantas veces como sea necesario para procesar todas las exportaciones pendientes. Si el espacio del conector tiene más exportaciones pendientes que el tamaño de la página del conector, el script de exportación de datos puede llamarse varias veces y posiblemente varias veces para el mismo objeto.
El script de exportación de datos recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| CSEntries | IListCSEntryChange | Lista de todos los objetos del espacio del conector con las exportaciones pendientes para su procesamiento durante este paso. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informa al script del tipo de ejecución de exportación (diferencial o completo), partición, jerarquía y tamaño de página esperado. |
| Tipos | Esquema | El esquema del espacio del conector que se exporta. |
El script de exportación de datos debe devolver un objeto PutExportEntriesResults a la canalización. Este objeto no necesita incluir la información de resultados para cada conector exportado a menos que se produzca un error o un cambio en el atributo delimitador. Por ejemplo, para devolver un objeto PutExportEntriesResults a la canalización: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
End Export
Al acabar la ejecución de la importación, se ejecutará el script de finalización de exportación. Este script debe realizar las tareas de limpieza necesarias (por ejemplo, cerrar las conexiones a los sistemas y responder a errores).
El script de finalización de exportación recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informa al script del tipo de ejecución de exportación (diferencial o completo), partición, jerarquía y tamaño de página esperado. |
| CloseExportConnectionRunStep | CloseExportConnectionRunStep | Informa al script del motivo de la finalización de la exportación. |
El script no debe devolver ningún resultado a la canalización.
Sincronización de contraseñas
Se pueden usar los conectores de Windows PowerShell como destino para los cambios o restablecimientos de contraseña.
El script de contraseña recibe los parámetros siguientes del conector:
| Nombre | Tipo de datos | Descripción |
|---|---|---|
| ConfigParameters | KeyedCollection[string, ConfigParameter] | Tabla de parámetros de configuración para el conector. |
| Credencial | PSCredential | Contiene las credenciales especificadas por el administrador en la pestaña Conectividad. |
| Partition | Partición | Partición del directorio en el que se encuentra CSEntry. |
| CSEntry | CSEntry | Entrada del espacio de conector para el objeto que recibe un cambio o restablecimiento de contraseña. |
| OperationType | String | Indica si la operación es un restablecimiento (SetPassword) o un cambio (ChangePassword). |
| PasswordOptions | PasswordOptions | Marcas que especifican el comportamiento de restablecimiento de contraseña pretendido. Este parámetro solo está disponible si OperationType es SetPassword. |
| OldPassword | String | Se rellena con la contraseña anterior del objeto para cambios de contraseña. Este parámetro solo está disponible si OperationType es ChangePassword. |
| NewPassword | String | Se rellena con la nueva contraseña del objeto que debe establecer el script. |
El script de contraseña no devuelve ningún resultado a la canalización de Windows PowerShell. Si se produce un error en el script de contraseña, este producirá una de las excepciones siguientes para informar al servicio de sincronización acerca del problema:
- PasswordPolicyViolationException: se inicia si la contraseña no cumple la directiva de contraseñas del sistema conectado.
- PasswordIllFormedException: se inicia si no se acepta la contraseña en el sistema conectado.
- PasswordExtension: se inicia para todos los demás errores del script de contraseña.
Conectores de ejemplo
Para una introducción general de los conectores de ejemplo disponibles, consulte Windows PowerShell Connector Sample Connector Collection.
Otras notas
Configuración adicional para la suplantación
Conceda al usuario suplantado los permisos siguientes en el servidor del servicio de sincronización:
Acceso de lectura a las claves del Registro siguientes:
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
- HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Entorno
Para determinar el identificador de seguridad (SID) de la cuenta de servicio del servicio de sincronización, ejecute los siguientes comandos de PowerShell:
$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value
Acceso de lectura a las carpetas del sistema de archivo siguientes:
- %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions
- %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\ExtensionsCache
- %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\{ConnectorName}
Sustituya el nombre del conector de Windows PowerShell por el marcador de posición {nombreDeConector}.
Solución de problemas
- Para más información acerca de cómo habilitar el registro para solucionar problemas del conector, consulte How to Enable ETW Tracing for FIM 2010 R2 Connectors.