Referência técnica do Windows PowerShell Connector

Este artigo descreve o Conector do Windows PowerShell. O artigo se aplica aos seguintes produtos:

• Microsoft Identity Manager 2016 (MIM2016)

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

Visão geral do Conector do PowerShell

O Conector do PowerShell permite que você integre o serviço de sincronização com sistemas externos que oferecem APIs baseadas no Windows PowerShell. O conector atua como uma ponte entre as funcionalidades do framework do agente de gerenciamento de conectividade extensível baseado em chamadas 2 (ECMA2) e o Windows PowerShell. Para obter mais informações sobre a estrutura ECMA, consulte a Referência do Agente de Gerenciamento extensível de conectividade 2.2.

Pré-requisitos

Para usar o conector, verifique se você tem os seguintes itens 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 que o conector executa sejam digitalmente assinados, configure a política de execução usando 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 instrução de suporte para esses scripts será fornecida por esse produto. Se você estiver desenvolvendo seus próprios scripts para uso com esse conector, precisará ter familiaridade com a API do Extensible Connectivity Management Agent para desenvolver e manter esses scripts. Se você estiver integrando sistemas de terceiros usando seus próprios scripts em um ambiente de produção, recomendamos que você trabalhe com o fornecedor de terceiros ou um parceiro de implantação para obter ajuda, diretrizes 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 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, no Serviço de Sincronização , selecione Agente de Gerenciamento e Crie. Selecione o Conector do PowerShell (Microsoft ).

Conectividade

Forneça parâmetros de configuração para se conectar 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:

Conectividade

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

Para os scripts 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 Módulo Comum é denominado de acordo com a configuração Nome de Script do Módulo Comum.

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")

Validação de parâmetro
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. Validar parâmetros de servidor, credenciais de conexão e conectividade são usos comuns do script de validação. O script de validação é chamado depois que as seguintes guias e caixas de diálogo são 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 atributo. 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 de Serviços 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 por 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, sobrenome e endereço postal) do tipo.

Parâmetros adicionais
Além das definições de configuração padrão abordadas até agora, você pode definir configurações personalizadas adicionais que sejam específicas à instância do conector. Esses parâmetros podem ser especificados nos níveis de conector, partição ou etapa de execução e acessados no script relevante do Windows PowerShell. As configurações 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 configurações seguras quando necessário.

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

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

Capacidades

A guia Recursos do Designer do Agente de Gerenciamento define o comportamento e a funcionalidade do conector. As seleções feitas nessa guia não podem ser modificadas depois que o conector tiver sido criado. Esta tabela lista as configurações de funcionalidade.

Parâmetros Globais

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

Descoberta de partição
Uma partição é um namespace separado em um esquema compartilhado. Por exemplo, no Active 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. Importação e exportação têm partição como contexto e todas as operações ocorrem nesse contexto. As partições devem representar uma hierarquia no LDAP. O nome diferenciado 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 diferenciado 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 de partição ou uma Lista[T] de objetos de partição para o pipeline.

Descoberta de hierarquia
O script de descoberta de hierarquia só é usado quando o recurso Estilo de Nome Diferenciado é 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 somente uma lista de nós que sejam filhos diretos do nó raiz fornecido para o script.

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

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

Importação

Conectores que dão suporte a operações de importação devem implementar três scripts.

Iniciar Importação
O script de importação inicial é executado no início de uma etapa de execução de importação. Durante essa 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 de importação inicial 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 dados de importação é chamado pelo conector até que o script indique que não há mais dados a serem importados. O conector do Windows PowerShell tem um limite de página de 9.999 objetos. Se o script retornar mais de 9.999 objetos para importação, você deverá dar suporte à paginação. O conector expõe uma propriedade dados personalizada que pode ser usada para armazenar uma marca d’água, de modo que toda vez que o script de importação de dados for chamado, o script retome a importação de objetos onde ela foi interrompida.

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

O script de dados de importação deve gravar um objeto List[CSEntryChange] no pipeline. Essa coleção é composta por 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 Substituir).

Encerrar Importação
No final da execução de importação, o script de Importação Final é 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 ao pipeline, por exemplo: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)

Exportação

Idênticos à arquitetura de importação do conector, os conectores que dão suporte à exportação devem implementar três scripts.

Iniciar Exportação
O script de exportação inicial é executado no início de uma etapa de execução de exportação. Durante essa 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 de exportação inicial 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 for necessário para processar todas as exportações pendentes. Se o espaço do conector tiver mais exportações pendentes do que o tamanho de página do conector, o script de exportação de dados poderá ser chamado várias vezes e, possivelmente, várias vezes para o mesmo objeto.

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

O script de dados de exportação deve retornar um objeto PutExportEntriesResults para o pipeline. Esse 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 de âncora. Por exemplo, para retornar um objeto PutExportEntriesResults para o pipeline: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)

Exportação final
No final 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

Conectores do Windows PowerShell podem ser usados como um 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á gerar uma das seguintes exceções para informar o Serviço de Sincronização sobre o problema:

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

Conectores de exemplo

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

Outras anotações

Configuração adicional para personificação

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

Leia o acesso às seguintes chaves do Registro:

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

Para determinar o SID (Identificador de Segurança) 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 para as seguintes pastas do sistema de arquivos:

• %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}

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

Resolução de problemas

• Para saber mais sobre como habilitar o registro em log para solucionar problemas do conector, confira How to Enable ETW Tracing for Connectors.