Referência técnica do Windows PowerShell Connector

Este artigo descreve o Windows PowerShell Connector. O artigo aplica-se aos seguintes produtos:

• Microsoft Identity Manager 2016 (MIM2016)

Por MIM2016, o Conector está disponível para download no Centro de Download da Microsoft.

Visão geral do conector do PowerShell

O PowerShell Connector permite integrar o serviço de sincronização com sistemas externos que oferecem APIs baseadas no Windows PowerShell. O conector estabelece uma ligação entre as capacidades da estrutura de agente de gestão de conectividade extensível baseada em chamadas (ECMA2) e o Windows PowerShell. Para obter mais informações sobre a estrutura ECMA, consulte Extensible Connectivity 2.2 Management Agent Reference.

Pré-requisitos

Antes de usar o conector, verifique se você tem o seguinte no servidor de sincronização:

• Microsoft .NET 4.6.2 Framework ou posterior
• Windows PowerShell 2.0, 3.0 ou 4.0

A política de execução no servidor do Serviço de Sincronização deve ser configurada para permitir que o conector execute scripts do Windows PowerShell. A menos que os scripts executados pelo conector sejam assinados digitalmente, configure a política de execução executando este comando:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

A implantação desse conector exigirá um ou mais scripts do PowerShell. Alguns produtos da Microsoft podem fornecer scripts para uso com esse conector, e a declaração de suporte para esses scripts seria fornecida por esse produto. Se você estiver desenvolvendo seus próprios scripts para uso com esse conector, precisará ter familiaridade com a API do Agente de Gerenciamento de Conectividade Extensível para desenvolver e manter esses scripts. Se você estiver integrando com sistemas de terceiros usando seus próprios scripts em um ambiente de produção, recomendamos que você trabalhe com o fornecedor terceirizado ou um parceiro de implantação para obter ajuda, orientação e suporte para essa integração.

Criar um novo conector

Para criar um conector do Windows PowerShell no serviço de sincronização, você deve fornecer uma série de scripts do Windows PowerShell que executam as etapas solicitadas pelo serviço de sincronização. Dependendo da fonte de dados à qual você se conecta e da funcionalidade necessária, os scripts que você deve implementar variam. Esta seção descreve cada um dos scripts que podem ser implementados e quando eles são necessários.

O conector do Windows PowerShell foi projetado para armazenar cada um dos scripts dentro do banco de dados do Serviço de Sincronização. Embora seja possível executar scripts armazenados no sistema de arquivos, é mais fácil inserir o corpo de cada script diretamente na configuração do conector.

Para Criar um conector do PowerShell, em Serviço de Sincronização , selecione Agente de Gerenciamento e Criar. Selecione o conector do PowerShell (Microsoft ).

Conectividade

Forneça parâmetros de configuração para conexão a um sistema remoto. Esses valores são armazenados com segurança pelo Serviço de Sincronização e disponibilizados para seus scripts do Windows PowerShell quando o conector é executado.

Você pode configurar os seguintes parâmetros de conectividade:

Conetividade

Módulo comum
O conector permite armazenar um módulo compartilhado do Windows PowerShell na configuração. Quando o conector executa um script, o módulo do Windows PowerShell é extraído para o sistema de arquivos para que possa ser importado por cada script.

Para scripts de Importação, Exportação e Sincronização de Senha, o módulo comum é extraído para a pasta MAData do conector. Para scripts de descoberta de esquema, validação, hierarquia e partição, o módulo comum é extraído para a pasta %TEMP%. Em ambos os casos, o script Common Module extraído é nomeado de acordo com a configuração Common Module Script Name.

Para carregar um módulo chamado FIMPowerShellConnectorModule.psm1 da pasta MAData, use a seguinte instrução: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")

Para carregar um módulo chamado FIMPowerShellConnectorModule.psm1 da pasta %TEMP%, use a seguinte instrução: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")

Parameter Validation
O Script de Validação é um script opcional do Windows PowerShell que pode ser usado para garantir que os parâmetros de configuração do conector fornecidos pelo administrador sejam válidos. A validação de servidor, credenciais de conexão e parâmetros de conectividade são usos comuns do script de validação. O script de validação é chamado depois de as seguintes abas e caixas de diálogo serem modificadas:

• Conectividade
• Parâmetros globais
• Configuração de partição

O script de validação recebe os seguintes parâmetros do conector:

O script de validação deve retornar um único objeto ParameterValidationResult para o pipeline.

Descoberta de esquema
O script de descoberta de esquema é obrigatório. Esse script retorna os tipos de objeto, atributos e restrições de atributo que o Serviço de Sincronização usa ao configurar regras de fluxo de atributos. O script de Descoberta de Esquema é executado durante a criação do conector e preenche o esquema do conector. Ele também é usado pela ação Atualizar esquema no Gerenciador do Serviço de Sincronização.

O script de descoberta de esquema recebe os seguintes parâmetros do conector:

O script deve retornar um único objeto Schema para o pipeline. O objeto Schema é composto de objetos SchemaType que representam tipos de objeto (por exemplo: usuários e grupos). O objeto SchemaType contém uma coleção de objetos SchemaAttribute que representam os atributos (por exemplo: nome próprio, sobrenome e endereço postal) do tipo.

Parâmetros adicionais
Além das definições de configuração padrão, você pode definir definições de configuração personalizadas adicionais que são específicas para a instância do conector. Esses parâmetros podem ser especificados nos níveis de conector, partição ou etapa de execução e acessados a partir do script relevante do Windows PowerShell. As definições de configuração personalizadas podem ser armazenadas no banco de dados do Serviço de Sincronização em formato de texto sem formatação ou podem ser criptografadas. O Serviço de Sincronização criptografa e descriptografa automaticamente as definições de configuração seguras quando necessário.

Para especificar definições de configuração personalizadas, separe o nome de cada parâmetro com uma vírgula ( , ).

Para acessar definições de configuração personalizadas a partir de um script, você deve sufixar o nome com um sublinhado ( _ ) e o escopo do parâmetro (Global, Partition ou RunStep). Por exemplo, para acessar o parâmetro Global FileName, use este trecho de código: $ConfigurationParameters["FileName_Global"].Value

Capacidades

A guia recursos do Management Agent Designer define o comportamento e a funcionalidade do conector. As seleções feitas nesta guia não podem ser modificadas quando o conector tiver sido criado. Esta tabela lista as configurações de capacidade.

Parâmetros globais

A guia Parâmetros Globais no Management Agent Designer permite configurar os scripts do Windows PowerShell executados pelo conector. Você também pode configurar valores globais para definições de configuração personalizadas definidas na guia Conectividade.

Descoberta de partições
Uma partição é um namespace separado dentro de um esquema compartilhado. Por exemplo, no Ative Directory, cada domínio é uma partição dentro de uma floresta. Uma partição é o agrupamento lógico para operações de importação e exportação. Importar e Exportar têm a partição como contexto e todas as operações acontecem nesse contexto. As partições devem representar uma hierarquia no LDAP. O nome distinto de uma partição é usado na importação para verificar se todos os objetos retornados estão dentro do escopo de uma partição. O nome distinto da partição também é usado durante o provisionamento do metaverso para o espaço do conector para determinar a partição à qual um objeto deve ser associado durante a exportação.

O script de descoberta de partição recebe os seguintes parâmetros do conector:

O script deve retornar um único objeto Partition ou uma List[T] de objetos do tipo Partition para o pipeline.

Descoberta de hierarquia
O script de descoberta de hierarquia só é usado quando o recurso Estilo de Nome Distinto é LDAP. O script é usado para permitir que você navegue e selecione um conjunto de contêineres que é considerado dentro ou fora do escopo para operações de importação e exportação. O script deve fornecer apenas uma lista de nós que são filhos diretos do nó raiz fornecido ao script.

O script de descoberta de hierarquia recebe os seguintes parâmetros do conector:

O script deve retornar um único objeto HierarchyNode filho ou uma "List[T]" de objetos HierarchyNode filhos para o pipeline.

Importação

Os conectores que suportam operações de importação devem implementar três scripts.

Iniciar importação
O script begin import é executado no início de uma etapa de execução de importação. Durante esta etapa, você pode estabelecer uma conexão com o sistema de origem e executar etapas preparatórias antes de importar dados do sistema conectado.

O script start import recebe os seguintes parâmetros do conector:

O script deve retornar um único objeto OpenImportConnectionResults para o pipeline, por exemplo: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)

Importar dados
O script de importação de dados é chamado pelo conector até que o script indique que não há mais dados para importar. O conector do Windows PowerShell tem um tamanho de página de 9.999 objetos. Se o script retornar mais de 9.999 objetos para importação, você deverá oferecer suporte à paginação. O conector expõe uma propriedade de dados personalizada que você pode usar para armazenar uma marca d'água para que, cada vez que o script de importação de dados for chamado, o script retome a importação de objetos de onde parou.

O script de importação de dados recebe os seguintes parâmetros do conector:

O script de dados de importação deve gravar um objeto List[CSEntryChange] no pipeline. Esta coleção é composta de atributos CSEntryChange que representam cada objeto que está sendo importado. Durante uma execução de Importação Completa, essa coleção deve ter um conjunto completo de objetos CSEntryChange que tenham todos os atributos para cada objeto. Durante uma importação delta, o objeto CSEntryChange deve conter os deltas de nível de atributo para cada objeto a ser importado ou uma representação completa dos objetos que foram alterados (modo de substituição).

Fim da importação
Na conclusão da execução de importação, o script End Import é executado. Esse script deve executar todas as tarefas de limpeza necessárias (por exemplo, fechar conexões com sistemas e responder a falhas).

O script de importação final recebe os seguintes parâmetros do conector:

O script deve retornar um único objeto CloseImportConnectionResults para o pipeline, por exemplo: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)

Exportação

Idêntica à arquitetura de importação do conector, os conectores que suportam a exportação devem implementar três scripts.

Iniciar exportação
O script begin export é executado no início de uma etapa de execução de exportação. Durante esta etapa, você pode estabelecer uma conexão com o sistema de origem e realizar quaisquer etapas preparatórias antes de exportar dados para o sistema conectado.

O script begin export recebe os seguintes parâmetros do conector:

O script não deve retornar nenhuma saída para o pipeline.

Exportar dados
O Serviço de Sincronização chama o script Exportar Dados quantas vezes forem necessárias para processar todas as exportações pendentes. Se o espaço do conector tiver mais exportações pendentes do que o tamanho da página do conector, o script de dados de exportação poderá ser chamado várias vezes e, possivelmente, várias vezes para o mesmo objeto.

O script de exportação de dados recebe os seguintes parâmetros do conector:

O script de dados de exportação deve retornar um objeto PutExportEntriesResults para o pipeline. Este objeto não precisa incluir informações de resultado para cada conector exportado, a menos que ocorra um erro ou uma alteração no atributo anchor. Por exemplo, para retornar um objeto PutExportEntriesResults ao pipeline: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)

Fim da exportação
Na conclusão da execução da exportação, o script End Export será executado. Esse script deve executar todas as tarefas de limpeza necessárias (por exemplo, fechar conexões com sistemas e responder a falhas).

O script de exportação final recebe os seguintes parâmetros do conector:

O script não deve retornar nenhuma saída para o pipeline.

Sincronização de senha

Os conectores do Windows PowerShell podem ser usados como destino para alterações/redefinições de senha.

O script de senha recebe os seguintes parâmetros do conector:

Não se espera que o script de senha retorne nenhum resultado para o pipeline do Windows PowerShell. Se ocorrer um erro no script de senha, o script deverá lançar uma das seguintes exceções para informar o Serviço de Sincronização sobre o problema:

• PasswordPolicyViolationException – Lançado se a senha não atender à política de senha no sistema conectado.
• PasswordIllFormedException – Lançado se a senha não for aceitável para o sistema conectado.
• PasswordExtension – Gerado para todos os outros erros no script de senha.

Conectores de amostra

Para obter uma visão geral completa dos conectores de exemplo disponíveis, consulte Coleção de conectores de exemplo do conector do Windows PowerShell.

Outras notas

Configuração adicional para representação

Conceda ao usuário representado as seguintes permissões no servidor do Serviço de Sincronização:

Acesso de leitura às seguintes chaves do Registro:

• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Ambiente

Para determinar o identificador de segurança (SID) da conta de serviço do Serviço de Sincronização, execute os seguintes comandos do PowerShell:

$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value

Acesso de leitura às seguintes pastas do sistema de arquivos:

• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Serviço de Sincronização\Extensões
• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\ExtensionsCache
• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\{ConnectorName}

Substitua o nome do conector do Windows PowerShell pelo espaço reservado {ConnectorName}.

Solução de problemas

• Para obter informações sobre como ativar o registo para solucionar problemas do conector, consulte Como ativar o rastreamento ETW para conectores.