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)
Por MIM2016, o Conector está disponível como transferência a partir do Centro de Transferências da Microsoft.
Descrição geral do Conector do PowerShell
O Conector do PowerShell permite-lhe integrar o serviço de sincronização com sistemas externos que oferecem APIs baseadas em Windows PowerShell. O conector fornece uma ponte entre as capacidades da arquitetura do agente de gestão de conectividade extensível 2 (ECMA2) baseado em chamadas e Windows PowerShell. Para obter mais informações sobre a arquitetura ECMA, veja Extensible Connectivity 2.2 Management Agent Reference (Referência do Agente de Gestão de Conectividade Extensível 2.2).
Pré-requisitos
Antes de utilizar o Conector, certifique-se de que 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 tem de ser configurada para permitir que o conector execute Windows PowerShell scripts. A menos que os scripts que o conector executa estejam assinados digitalmente, configure a política de execução ao executar este comando:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
A implementação deste conector requer um ou mais scripts do PowerShell. Alguns produtos Microsoft podem fornecer scripts para utilização 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 utilização com este conector, terá de estar familiarizado com a API do Agente de Gestão de Conectividade Extensível para desenvolver e manter esses scripts. Se estiver a integrar com sistemas de terceiros através dos seus próprios scripts num ambiente de produção, recomendamos que trabalhe com o fornecedor de terceiros ou com um parceiro de implementação para obter 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, tem de fornecer uma série de scripts Windows PowerShell que executam os passos pedidos pelo serviço de sincronização. Consoante a origem de dados à qual se liga e a funcionalidade necessária, os scripts que tem de 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 armazenados no sistema de ficheiros, é 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 Gestão e Criar. Selecione o Conector do PowerShell (Microsoft).
Conectividade
Forneça parâmetros de configuração para ligar a um sistema remoto. Estes valores são armazenados em segurança pelo Serviço de Sincronização e disponibilizados aos scripts Windows PowerShell quando o conector é executado.
Pode configurar os seguintes parâmetros de Conectividade:
Conetividade
| Parâmetro | Valor Predefinido | Objetivo |
|---|---|---|
| Servidor | <Em branco> | Nome do servidor ao qual o conector se deve ligar. |
| Domínio | <Em branco> | Domínio da credencial a armazenar para utilização quando o conector é executado. |
| Utilizador | <Em branco> | Nome de utilizador da credencial a armazenar para utilização quando o conector é executado. |
| Palavra-passe | <Em branco> | Palavra-passe da credencial a armazenar para utilização quando o conector é executado. |
| Representar Conta do Conector | Falso | Quando verdadeiro, o serviço de sincronização executa os scripts de Windows PowerShell no contexto das credenciais fornecidas. Sempre que possível, recomenda-se que o parâmetro $Credentials seja transmitido para cada script em vez de ser representado. Para obter mais informações sobre as permissões adicionais necessárias para utilizar esta opção, veja Configuração Adicional para Representação. |
| Carregar Perfil de Utilizador ao Representar | Falso | Instrui o Windows a carregar o perfil de utilizador das credenciais do conector durante a representação. Se o utilizador representado 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, veja Configuração Adicional para Representação. |
| Tipo de Início de Sessão ao Representar | Nenhuma | Tipo de início de sessão durante a representação. Para obter mais informações, veja a documentação dwLogonType . |
| Apenas Scripts Assinados | Falso | Se for verdadeiro, o conector Windows PowerShell valida que cada script tem uma assinatura digital válida. Se for falso, certifique-se de que a política de execução Windows PowerShell do servidor do Serviço de Sincronização é RemoteSigned ou Unrestricted. |
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 Importação, Exportação e Sincronização de Palavras-passe, o módulo comum é extraído para a pasta MAData do conector. Para scripts de deteção de Esquema, 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 Nome do Script do Módulo Comum.
Para carregar um módulo denominado FIMPowerShellConnectorModule.psm1 a partir da pasta MAData, utilize a seguinte instrução: Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")
Para carregar um módulo denominado FIMPowerShellConnectorModule.psm1 a partir da pasta %TEMP%, utilize a seguinte instrução: Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")
Validação de Parâmetros
O Script de Validação é um script de Windows PowerShell opcional que pode ser utilizado para garantir que os parâmetros de configuração do conector fornecidos pelo administrador são válidos. Validar o servidor, as credenciais de ligação e os parâmetros de conectividade são utilizações comuns do script de validação. O script de validação é chamado depois de os seguintes separadores e caixas de diálogo serem modificados:
- Conectividade
- Parâmetros de Globais
- Configuração da Partição
O script de validação recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameterPage | ConfigParameterPage | O separador ou caixa de diálogo de configuração que acionou o pedido de validação. |
| ConfigParameters | KeyedCollection [cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
O script de validação deve devolver um único objeto ParameterValidationResult ao pipeline.
Deteção de Esquemas
O script de Deteção de Esquemas é obrigatório. Este script devolve os tipos de objetos, atributos e restrições de atributos que o Serviço de Sincronização utiliza ao configurar regras de fluxo de atributos. O script de Deteção de Esquemas é executado durante a criação do conector e preenche o esquema do conector. Também é utilizada pela ação Atualizar Esquema no Service Manager de Sincronização.
O script de deteção de esquemas recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection [cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
O script tem de devolver um único objeto de Esquema ao pipeline. O objeto Esquema é 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, 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 da 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 script de Windows PowerShell relevante. As definições de configuração personalizadas 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 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, tem de sufixar o nome com um caráter de sublinhado ( _ ) e o âmbito do parâmetro (Global, Partição ou RunStep). Por exemplo, para aceder ao parâmetro Global FileName, utilize este fragmento de código: $ConfigurationParameters["FileName_Global"].Value
Capacidades
O separador capacidades do Agente de Gestão Designer 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.
| 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 Exportar. |
| Normalização de Dados | Instrui o Serviço de Sincronização a normalizar os atributos de âncora antes de serem fornecidos aos scripts. |
| Confirmação do Objeto | Configura o comportamento de importação pendente no Serviço de Sincronização. |
| Utilizar o DN como Âncora | Se o Estilo de Nome Distinto estiver definido como 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 verificado, vários conectores de Windows PowerShell podem ser executados em simultâneo. |
| Partições | Quando selecionado, o conector suporta várias partições e deteção de partições. |
| Hierarquia | Quando selecionado, o conector suporta uma estrutura hierárquica de estilo LDAP. |
| Ativar Importação | Quando selecionado, o conector importa dados através de scripts de importação. |
| Ativar Importação Delta | Quando selecionado, o conector pode pedir deltas aos scripts de importação. |
| Ativar Exportação | Quando selecionado, o conector exporta dados através de scripts de exportação. |
| Ativar Exportação Completa | Quando selecionados, os scripts de exportação suportam a exportação de todo o espaço do conector. Para utilizar esta opção, a opção Ativar Exportação também tem de ser verificada. |
| 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 Nome do Objeto | Quando selecionado, os nomes distintos podem ser modificados. |
| Delete-Add Como Substituir | Quando selecionadas, as operações delete-add são exportadas como uma única substituição. |
| Ativar Operações de Palavra-passe | Quando selecionado, os scripts de sincronização de palavras-passe são suportados. |
| Ativar a Exportação de Palavra-passe no First Pass | Quando selecionadas, as palavras-passe definidas durante o aprovisionamento são exportadas quando o objeto é criado. |
Parâmetros de Globais
O separador Parâmetros Globais no Designer do Agente de Gestão permite-lhe configurar os scripts de Windows PowerShell que são executados pelo conector. Também pode configurar valores globais para definições de configuração personalizadas definidas no separador Conectividade.
Deteção de Partições
Uma partição é um espaço de nomes separado num esquema partilhado. Por exemplo, no Active Directory, cada domínio é uma partição numa floresta. Uma partição é o agrupamento lógico para operações de importação e exportação. A importação e a exportação têm partição como contexto e todas as operações acontecem neste contexto. As partições devem representar uma hierarquia no LDAP. O nome distinto de uma partição é utilizado na importação para verificar se todos os objetos devolvidos estão no âmbito de uma partição. O nome distinto da partição também é utilizado durante o aprovisionamento 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 deteção de partições recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
O script tem de devolver um único objeto partição ou uma Lista[T] de objetos de Partição para o pipeline.
Deteção de Hierarquia
O script de deteção de hierarquia só é utilizado quando a capacidade Estilo de Nome Distinto é LDAP. O script é utilizado para permitir que navegue e selecione um conjunto de contentores que é considerado dentro ou fora do âmbito para operações de importação e exportação. O script deve fornecer apenas uma lista de nós que são subordinados diretos do nó raiz fornecido para o script.
O script de deteção de hierarquias recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| ParentNode | HierarchyNode | O nó raiz da hierarquia sob a qual o script deve devolver subordinados diretos. |
O script tem de devolver um único objeto HierarchyNode subordinado ou uma Lista[T] de objetos hierarchyNode subordinados para o pipeline.
Importar
Os conectores que suportam operações de importação têm de implementar três scripts.
Iniciar Importação
O script de importação inicial é executado no início de um passo de execução de importação. Durante este passo, pode estabelecer uma ligação ao sistema de origem e realizar passos preparatórios antes de importar dados do sistema ligado.
O script de importação de início recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informa o script sobre o tipo de execução de importação (delta ou completa), partição, hierarquia, marca d'água e tamanho de página esperado. |
| Tipos | Esquema | Esquema para o espaço do conector que é importado. |
O script tem de devolver um único objeto OpenImportConnectionResults ao 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 existem mais dados para importar. O conector Windows PowerShell tem um tamanho de página de 9999 objetos. Se o script devolver mais de 9999 objetos para importação, tem de suportar a paginação. O conector expõe uma propriedade de dados personalizada que pode utilizar para armazenar uma marca d'água para que, sempre que o script de importação de dados for chamado, o script retome a importação de objetos onde ficou.
O script de dados de importação recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| GetImportEntriesRunStep | ImportRunStep | Contém a marca d'água (CustomData) que pode ser utilizada durante importações paginadas e importações delta. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informa o script sobre o tipo de execução de importação (delta ou completa), partição, hierarquia, marca d'água e tamanho de página esperado. |
| Tipos | Esquema | Esquema para o espaço do conector que é importado. |
O script de dados de importação tem de escrever um objeto List[CSEntryChange] no pipeline. Esta coleção é composta por atributos CSEntryChange que representam cada objeto que está a ser importado. Durante uma execução 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 foram alterados (Modo de substituição).
Terminar Importação
No final da execução da importação, o script End Import é executado. Este script deve executar todas as tarefas de limpeza necessárias (por exemplo, fechar ligações a 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[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| OpenImportConnectionRunStep | OpenImportConnectionRunStep | Informa o script sobre o tipo de execução de importação (delta ou completa), partição, hierarquia, marca d'água e tamanho de página esperado. |
| CloseImportConnectionRunStep | CloseImportConnectionRunStep | Informa o script sobre o motivo pelo qual a importação foi terminada. |
O script tem de devolver um único objeto CloseImportConnectionResults ao pipeline, por exemplo: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Exportar
Idêntico à arquitetura de importação do conector, os conectores que suportam Exportar têm de implementar três scripts.
Iniciar Exportação
O script de exportação de início é executado no início de um passo de execução de exportação. Durante este passo, pode estabelecer uma ligação ao sistema de origem e realizar quaisquer passos preparatórios antes de exportar dados para o sistema ligado.
O script de exportação de início recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informa o script sobre o tipo de execução de exportação (delta ou completa), partição, hierarquia e tamanho de página esperado. |
| Tipos | Esquema | Esquema para o espaço de conector que é exportado. |
O script não deve devolver qualquer saída ao 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 da página do conector, o script de exportação de dados poderá ser chamado várias vezes e possivelmente múltiplas vezes para o mesmo objeto.
O script de exportação de dados recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| CSEntries | IListCSEntryChange | Lista de todos os objetos de espaço do conector com exportações pendentes a processar durante esta passagem. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informa o script sobre o tipo de execução de exportação (delta ou completa), partição, hierarquia e tamanho de página esperado. |
| Tipos | Esquema | Esquema para o espaço de conector que é exportado. |
O script de dados de exportação tem de devolver um objeto PutExportEntriesResults ao pipeline. Este objeto não precisa de incluir informações de resultados para cada conector exportado, a menos que ocorra um erro ou uma alteração ao atributo de âncora. Por exemplo, para devolver um objeto PutExportEntriesResults ao pipeline: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
Terminar Exportação
No final da execução da exportação, o script End Export (Exportação Final) a ser executado. Este script deve efetuar todas as tarefas de limpeza necessárias (por exemplo, fechar ligações a 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[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| OpenExportConnectionRunStep | OpenExportConnectionRunStep | Informa o script sobre o tipo de execução de exportação (delta ou completa), partição, hierarquia e tamanho de página esperado. |
| CloseExportConnectionRunStep | CloseExportConnectionRunStep | Informa o script sobre o motivo pelo qual a exportação foi terminada. |
O script não deve devolver qualquer saída ao pipeline.
Sincronização de Palavras-passe
Windows PowerShell conectores podem ser utilizados como destino para alterações/reposições de palavras-passe.
O script de palavra-passe recebe os seguintes parâmetros do conector:
| Name | Tipo de Dados | Descrição |
|---|---|---|
| ConfigParameters | KeyedCollection[cadeia, ConfigParameter] | Tabela de parâmetros de configuração para o Conector. |
| Credencial | PSCredential | Contém as credenciais introduzidas pelo administrador no separador Conectividade. |
| Partição | Partição | Partição de diretório na qual o CSEntry se encontra. |
| CSEntry | CSEntry | Entrada de espaço do conector para o objeto que recebe uma alteração ou reposição de palavra-passe. |
| Tipo de Operação | String | Indica se a operação é uma reposição (SetPassword) ou uma alteração (ChangePassword). |
| PasswordOptions | PasswordOptions | Sinalizadores que especificam o comportamento de reposição de palavra-passe pretendido. Este parâmetro só está disponível se OperationType for SetPassword. |
| Palavra-passe Antiga | String | Preenchido com a palavra-passe antiga do objeto para alterações de palavra-passe. Este parâmetro só está disponível se OperationType for ChangePassword. |
| Nova Palavra-passe | String | Preenchido com a nova palavra-passe do objeto que o script deve definir. |
Não é esperado que o script de palavra-passe devolva resultados ao pipeline de Windows PowerShell. Se ocorrer um erro no script de palavra-passe, o script deverá gerar uma das seguintes exceções para informar o Serviço de Sincronização sobre o problema:
- PasswordPolicyViolationException – emitida se a palavra-passe não cumprir a política de palavras-passe no sistema ligado.
- PasswordIllFormedException – emitida se a palavra-passe não for aceitável para o sistema ligado.
- PasswordExtension – emitida para todos os outros erros no script de palavra-passe.
Conectores de Exemplo
Para obter uma descrição geral completa dos conectores de exemplo disponíveis, veja Windows PowerShell Coleção de Conectores de Exemplo do Conector.
Outras notas
Configuração Adicional para Representação
Conceda ao utilizador que é representado pelas seguintes permissões no servidor do Serviço de Sincronização:
Acesso de leitura à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 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 ficheiros:
- %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 pelo marcador de posição {ConnectorName}.
Resolução de problemas
- Para obter informações sobre como ativar o registo para resolver problemas do conector, veja Como Ativar o Rastreio etw para conectores.