Referência técnica do Conector do Windows PowerShell

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

  • Microsoft Identity Manager 2016 (MIM2016)
  • Gestor de Identidade 2010 R2 (FIM2010R2)
    • Deve utilizar o hotfix 4.1.3671.0 ou mais tarde KB3092178.

Para MIM2016 e FIM2010R2, o Conector está disponível como download do Microsoft Download Center.

Visão geral do Conector PowerShell

O Conector PowerShell permite-lhe integrar o serviço de sincronização com sistemas externos que oferecem APIs Windows PowerShell baseados. O conector fornece uma ponte entre as capacidades do quadro extensível de gestão de conectividade extensível 2 (ECMA2) e Windows PowerShell. Para obter mais informações sobre o quadro da ECMA, consulte a Referência do Agente de Gestão extensível da Conectividade 2.2.

Pré-requisitos

Antes de utilizar o Conector, certifique-se de que tem o seguinte no servidor de sincronização:

  • Microsoft .NET 4.5.2 Framework ou mais tarde
  • Windows PowerShell 2.0, 3.0 ou 4.0

A política de execução do servidor de Serviço de Sincronização tem de ser configurada para permitir que o conector seja executado Windows PowerShell scripts. A menos que os scripts que o conector executa sejam assinados digitalmente, configuure a política de execução executando este comando:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

A implantação deste conector requer um ou mais scripts PowerShell. Alguns produtos da Microsoft podem fornecer scripts para uso com este conector, e a declaração de suporte para esses scripts seria fornecida por esse produto. Se estiver a desenvolver os seus próprios scripts para uso com este conector, terá de ter familiaridade com a API do Agente de Gestão de Conectividade Extensível para desenvolver e manter esses scripts. Se estiver a integrar-se em sistemas de terceiros utilizando os seus próprios scripts num ambiente de produção, recomendamos que trabalhe com o fornecedor de terceiros ou com um parceiro de implantação para ajuda, orientação e suporte para esta integração.

Criar um novo Conector

Para criar um conector Windows PowerShell no serviço de sincronização, deve fornecer uma série de scripts Windows PowerShell que executem os passos solicitados pelo serviço de sincronização. Dependendo da fonte de dados a que se conecta e da funcionalidade que necessita, os scripts que deve implementar variam. Esta secção descreve cada um dos scripts que podem ser implementados e quando são necessários.

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

Para criar um conector PowerShell, no Serviço de Sincronização selecione o Agente de Gestão e crie. Selecione o Conector PowerShell (Microsoft).

Criar Conector

Conectividade

Parâmetros de configuração de fornecimento para a ligação a um sistema remoto. Estes valores são armazenados de forma segura pelo Serviço de Sincronização e disponibilizados aos scripts Windows PowerShell quando o conector é executado.

MIM Sync configuração de conectividade Conectividade

Pode configurar os seguintes parâmetros de conectividade:

Conetividade

Parâmetro Valor Predefinido Objetivo
Servidor O nome do servidor a que o conector deve ligar-se.
Domínio Domínio da credencial para armazenar para utilização quando o conector estiver em funcionação.
Utilizador Nome de utilizador da credencial para armazenar para utilização quando o conector é executado.
Palavra-passe Palavra-passe da credencial para armazenar para utilização quando o conector estiver em funcionação.
Personificar conta de conector Falso Quando verdadeiro, o serviço de sincronização executa os scripts Windows PowerShell no contexto das credenciais fornecidas. Quando possível, recomenda-se que o parâmetro $Credentials seja passado a cada script em vez de personificação. Para obter mais informações sobre permissões adicionais necessárias para utilizar esta opção, consulte Configuração Adicional para personificação.
Carregue o perfil do utilizador ao fazer-se passar Falso Instrui Windows para carregar o perfil do utilizador das credenciais do conector durante a personificação. Se o utilizador personificado tiver um perfil de roaming, o conector não carrega o perfil de roaming. Para obter mais informações sobre permissões adicionais necessárias para utilizar este parâmetro, consulte Configuração Adicional para personificação.
Tipo de logon ao personificar Nenhuma Tipo de logon durante a personificação. Para mais informações, consulte a documentação do DwLogonType.
Apenas scripts assinados Falso Se for verdade, o conector Windows PowerShell valida que cada script tem uma assinatura digital válida. Se for falsa, certifique-se de que a política de execução Windows PowerShell do serviço de sincronização do serviço de sincronização é assinada remotamente ou sem restrições.

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

Para scripts de Sincronização de Importação, Exportação e Palavra-Passe, o módulo comum é extraído para a pasta MAData do conector. Para os scripts de deteção de Schema, Validação, Hierarquia e Partição, o módulo comum é extraído para a pasta %TEMP%. Em ambos os casos, o script do Módulo Comum extraído é nomeado de acordo com a definição de nome do script do módulo comum.

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

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

Validação de parâmetros
O Script de Validação é um script Windows PowerShell opcional que pode ser usado para garantir que os parâmetros de configuração do conector fornecidos pelo administrador são válidos. Validar servidor, credenciais de ligação e parâmetros de conectividade são usos comuns do script de validação. O script de validação é chamado após modificação dos seguintes separadores e diálogos:

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

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

Name Tipo de Dados Descrição
ConfigParameterPage ConfigParameterPage O separador de configuração ou diálogo que desencadeou o pedido de validação.
ConfigParameters KeyedCollection [string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.

O script de validação deve devolver um único objeto ParameterValidationResult ao pipeline.

Schema Discovery
O guião do Schema Discovery é obrigatório. Este script devolve os tipos de objetos, atributos e atribui restrições que o Serviço de Sincronização utiliza ao configurar regras de fluxo de atributos. O script Schema Discovery é executado durante a criação do conector e povoa o esquema do conector. Também é utilizado pela ação Refresh Schema no Gestor de Serviços de Sincronização.

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

Name Tipo de Dados Descrição
ConfigParameters KeyedCollection [string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.

O script deve devolver um único objeto De Schema ao oleoduto. O objeto Schema é composto por objetos SchemaType que representam tipos de objetos (por exemplo: utilizadores e grupos). O objeto SchemaType contém uma coleção de objetos SchemaAttribute que representam os atributos (por exemplo: nome dado, apelido e endereço postal) do tipo.

Parâmetros adicionais
Além das definições de configuração padrão, pode definir definições de configuração personalizadas adicionais específicas à instância do Conector. Estes parâmetros podem ser especificados nos níveis de conector, partição ou passo de execução e acedidos a partir do roteiro Windows PowerShell relevante. As definições de configuração personalizada podem ser armazenadas na base de dados do Serviço de Sincronização em formato de texto simples ou podem ser encriptadas. O Serviço de Sincronização encripta e desencripta automaticamente as definições de configuração seguras quando necessário.

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

Para aceder às definições de configuração personalizadas a partir de um script, deve sufixar o nome com um sublinhado (_ ) e o âmbito do parâmetro (Global, Partition ou RunStep). Por exemplo, para aceder ao parâmetro Global FileName, utilize este corte de código: $ConfigurationParameters["FileName_Global"].Value

Capacidades

O separador de capacidades do Designer de Agente de Gestão define o comportamento e a funcionalidade do conector. As seleções efetuadas neste separador não podem ser modificadas quando o conector tiver sido criado. Esta tabela lista as definições de capacidade.

separador de configuração do conector MIM Sync

Funcionalidade Description
Estilo de nome distinto Indica se o conector suporta nomes distintos e, em caso afirmativo, que estilo.
Tipo de exportação Determina o tipo de objetos que são apresentados ao script Exportação.
  • AttributeReplace – inclui o conjunto completo de valores para um atributo multi-valor quando o atributo muda.
  • AttributeUpdate – inclui apenas os deltas a um atributo multi-valor quando o atributo muda.
  • MultivaluedReferenceAttributeUpdate - inclui um conjunto completo de valores para atributos multi-valorizados não-referência e apenas deltas para atributos de referência multi-valorizados.
  • ObjectReplace – inclui todos os atributos para um objeto quando qualquer atributo muda
  • Normalização de Dados Instrui o Serviço de Sincronização para normalizar os atributos de âncora antes de serem fornecidos aos scripts.
    Confirmação de Objetos Configura o comportamento de importação pendente no Serviço de Sincronização.
  • Normal – comportamento padrão que espera que todas as alterações exportadas sejam confirmadas através da importação
  • NoDeleteConfirmation – quando um objeto é eliminado, não há nenhuma importação pendente gerada.
  • NoAddAndDeleteConfirmation – quando um objeto é criado ou eliminado, não há nenhuma importação pendente gerada.
  • Use o DN como Âncora Se o Estilo de Nome Distinto estiver definido para LDAP, o atributo de âncora para o espaço do conector é também o nome distinto.
    Operações Simultâneas de Vários Conectores Quando verificados, vários conectores Windows PowerShell podem funcionar simultaneamente.
    Partições Quando verificado, o conector suporta múltiplas divisórias e descoberta de partição.
    Hierarquia Quando verificado, o conector suporta uma estrutura hierárquica de estilo LDAP.
    Permitir a importação Quando verificado, o conector importa dados através de scripts de importação.
    Permitir a Importação Delta Quando verificado, o conector pode solicitar deltas a partir dos scripts de importação.
    Permitir a exportação Quando verificado, o conector exporta dados através de scripts de exportação.
    Ativar a exportação completa Quando verificados, os scripts de exportação suportam a exportação de todo o espaço do conector. Para utilizar esta opção, o Enable Export também deve ser verificado.
    Sem valores de referência no primeiro passe de exportação Quando verificados, os atributos de referência são exportados num segundo passe de exportação.
    Ativar o renomeo de objetos Quando verificados, nomes distintos podem ser modificados.
    Delete-Add Como Substituir Quando verificadas, as operações de exclusão-add são exportadas como uma única substituição.
    Ativar operações de senha Quando verificados, os scripts de sincronização de palavras-passe são suportados.
    Ativar a senha de exportação no primeiro passe Quando verificadas, as palavras-passe definidas durante o provisionamento são exportadas quando o objeto é criado.

    Parâmetros de Globais

    O separador Parâmetros Globais no Designer de Agente de Gestão permite-lhe configurar as Windows PowerShell scripts que são executados pelo conector. Também pode configurar valores globais para configurações de configuração personalizadas definidas no separador Conectividade.

    Descoberta da Partição
    Uma divisória é um espaço de nome separado dentro de um esquema compartilhado. Por exemplo, no Ative Directory cada domínio é uma divisória dentro de uma floresta. Uma divisória é o agrupamento lógico para as operações de importação e exportação. As importações e exportações têm a partição como contexto e todas as operações acontecem neste contexto. As divisórias devem representar uma hierarquia na LDAP. O nome distinto de uma divisória é utilizado na importação para verificar se todos os objetos devolvidos estão no âmbito de uma partição. O nome distinguido da partição também é utilizado durante o fornecimento do metaverso ao espaço do conector para determinar a partição a que um objeto deve ser associado durante a exportação.

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

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.

    O script deve devolver ao oleoduto um único objeto de partição ou uma Lista[T] de objetos de partição.

    Descoberta da Hierarquia
    O script de descoberta da hierarquia só é usado quando a capacidade de Estilo de Nome Distinto é LDAP. O script é utilizado para permitir que navegue e selecione um conjunto de contentores que são considerados dentro ou fora do alcance para operações de importação e exportação. O script deve apenas fornecer uma lista de nós que são crianças diretas do nó raiz fornecido ao script.

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

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    ParentNode HierárquicaNode O nó de raiz da hierarquia sob a qual o guião deve devolver as crianças diretas.

    O guião deve devolver ao oleoduto um único objeto Hierárquica de Uma Criança ou uma Lista[T] de objetos hierárquis de crianças HierárquicaNode.

    Importar

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

    Começar a importar
    O roteiro de importação inicial é executado no início de um passo de importação. Durante este passo, pode estabelecer uma ligação ao sistema de origem e fazer etapas preparatórias antes de importar dados do sistema conectado.

    O roteiro de importação iniciante recebe os seguintes parâmetros do conector:

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    OpenImportConnectionRunStep OpenImportConnectionRunStep Informa o script sobre o tipo de corrida de importação (delta ou cheio), partição, hierarquia, marca de água e tamanho de página esperado.
    Tipos Esquema Esquema para o espaço do conector que é importado.

    O script deve devolver um único objeto OpenImportConnectionResults ao oleoduto, por exemplo:

    Importar Dados
    O script de dados de importação é chamado pelo conector até que o script indique que não há mais dados para importar. O conector Windows PowerShell tem um tamanho de página de 9.999 objetos. Se o seu script devolver mais de 9.999 objetos para importação, deve suportar a chamada. O conector expõe uma propriedade de dados personalizada que pode usar para armazenar uma marca de água para que cada vez que o script de dados de importação seja chamado, o seu script recomeça a importar objetos onde este foi deixado.

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

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    GetImportEntriesRunStep ImportRunStep Detém a marca de água (CustomData) que pode ser usada durante as importações de página e delta.
    OpenImportConnectionRunStep OpenImportConnectionRunStep Informa o script sobre o tipo de corrida de importação (delta ou cheio), partição, hierarquia, marca de água e tamanho de página esperado.
    Tipos Esquema Esquema para o espaço do conector que é importado.

    O roteiro de dados de importação deve escrever uma lista[CSEntryChange]objeto para o pipeline. Esta coleção é composta por atributos CSEntryChange que representam cada objeto sendo importado. Durante uma corrida de Importação Completa, esta coleção deve ter um conjunto completo de objetos CSEntryChange que têm 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 importar, ou uma representação completa dos objetos que mudaram (modo de substituição).

    Fim da Importação
    No final da corrida de importação, o roteiro de Fim de Importação é executado. Este script deve executar quaisquer tarefas de limpeza necessárias (por exemplo, fechar ligações aos sistemas e responder a falhas).

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

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    OpenImportConnectionRunStep OpenImportConnectionRunStep Informa o script sobre o tipo de corrida de importação (delta ou cheio), partição, hierarquia, marca de água e tamanho de página esperado.
    CloseImportConnectionRunStep CloseImportConnectionRunStep Informa o guião sobre a razão pela qual a importação foi encerrada.

    O script deve devolver um único objeto CloseImportConnectionResults ao oleoduto, por exemplo:

    Exportar

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

    Começar a exportar
    O roteiro de exportação inicial é executado no início de um passo de exportação. Durante este passo, pode estabelecer uma ligação ao sistema de origem e realizar quaisquer etapas preparatórias antes de exportar dados para o sistema conectado.

    O roteiro de exportação iniciante recebe os seguintes parâmetros do conector:

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    OpenExportConnectionRunStep OpenExportConnectionRunStep Informa o script sobre o tipo de corrida de exportação (delta ou cheio), partição, hierarquia e tamanho de página esperado.
    Tipos Esquema Esquema para o espaço do conector que é exportado.

    O script não deve devolver nenhuma saída ao oleoduto.

    Dados de Exportação
    O Serviço de Sincronização chama o script de Dados de Exportação 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 da página do conector, o script de dados de exportação pode ser chamado várias vezes e possivelmente várias vezes para o mesmo objeto.

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

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    Entradas CS IListCSEntryChange Lista de todos os objetos do espaço do conector com exportações pendentes a serem processados durante este passe.
    OpenExportConnectionRunStep OpenExportConnectionRunStep Informa o script sobre o tipo de corrida de exportação (delta ou cheio), partição, hierarquia e tamanho de página esperado.
    Tipos Esquema Esquema para o espaço do conector que é exportado.

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

    Exportação final
    No final da corrida à exportação, o guião "Fim exportação" será executado. Este script deve executar quaisquer tarefas de limpeza necessárias (por exemplo, fechar ligações aos sistemas e responder a falhas).

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

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    OpenExportConnectionRunStep OpenExportConnectionRunStep Informa o script sobre o tipo de corrida de exportação (delta ou cheio), partição, hierarquia e tamanho de página esperado.
    CloseExportConnectionRunStep CloseExportConnectionRunStep Informa o guião sobre a razão pela qual a exportação foi encerrada.

    O script não deve devolver nenhuma saída ao oleoduto.

    Sincronização de Palavras-passe

    Windows PowerShell conectores podem ser usados como alvo para alterações/resets de palavra-passe.

    O script da palavra-passe recebe os seguintes parâmetros do conector:

    Name Tipo de Dados Descrição
    ConfigParameters KeyedCollection[string, ConfigParameter] Tabela de parâmetros de configuração para o Conector.
    Credencial PSCredential Contém quaisquer credenciais inseridas pelo administrador no separador Conectividade.
    Partição Partição Partição do diretório em que o CSEntry está.
    CSEntry CSEntry Entrada de espaço do conector para o objeto que é recebido uma alteração de senha ou reset.
    Tipo de Operação String Indica se a operação é um reset(SetPassword)ou uma alteração(ChangePassword).
    Opções password Opções password Bandeiras que especificam o comportamento de reposição da palavra-passe pretendida. Este parâmetro só está disponível se o OperationType for o SetPassword.
    Palavra-velho String Preenchido com a senha antiga do objeto para alterações de senha. Este parâmetro só está disponível se o OperationType for ChangePassword.
    Palavra nova String Preenchido com a nova senha do objeto que o script deve definir.

    Não se espera que o script da palavra-passe devolva quaisquer resultados ao pipeline Windows PowerShell. Se ocorrer um erro no script da palavra-passe, o script deve lançar uma das seguintes exceções para informar o Serviço de Sincronização sobre o problema:

    Conectores de amostra

    Para obter uma visão geral completa dos conectores de amostra disponíveis, consulte Windows PowerShell Coleção de Conector de Amostrado Conector .

    Outras notas

    Configuração adicional para personificação

    Conceder ao utilizador que se personi por se passar as seguintes permissões no servidor do Serviço de Sincronização:

    Leia o acesso às seguintes chaves de registo:

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

    Para determinar o Identificador de Segurança (SID) da conta de serviço de sincronização, execute os seguintes comandos PowerShell:

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

    Leia o acesso às seguintes pastas do sistema de ficheiros:

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

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

    Resolução de problemas

    • Para obter informações sobre como permitir a sessão de registo para resolver problemas no conector, consulte o Rastreio ETW para Conectores.