Provisionando usuários em aplicativos usando o PowerShell

A documentação a seguir fornece informações de configuração e tutorial demonstrando como o conector PowerShell genérico e o host ECMA (Extensible Connectivity) Connector podem ser usados para integrar o Microsoft Entra ID com sistemas externos que oferecem APIs baseadas no Windows PowerShell.

Para obter informações adicionais, consulte Referência técnica do Windows PowerShell Connector

Pré-requisitos para provisionamento via PowerShell

As seções a seguir detalham os pré-requisitos para este tutorial.

Baixe os arquivos de instalação do PowerShell

Baixe os arquivos de instalação do PowerShell em nosso repositório GitHub. Os arquivos de instalação consistem no arquivo de configuração, no arquivo de entrada, no arquivo de esquema e nos scripts usados.

Pré-requisitos no local

O conector fornece uma ponte entre os recursos do ECMA Connector Host e do Windows PowerShell. Antes de usar o conector, verifique se você tem o seguinte no servidor que hospeda o conector

• Um Windows Server 2016 ou uma versão posterior.
• Pelo menos 3 GB de RAM, para hospedar um agente de provisionamento.
• .NET Framework 4.7.2
• Windows PowerShell 2.0, 3.0 ou 4.0
• Conectividade entre o servidor de hospedagem, o conector e o sistema de destino com o qual os scripts do PowerShell interagem.
• A política de execução no servidor 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 requer 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.

Requisitos da nuvem

• Um locatário do Microsoft Entra com o Microsoft Entra ID P1 ou Premium P2 (ou EMS E3 ou E5). O uso desse recurso requer licenças do Microsoft Entra ID P1. Para encontrar a licença certa para os requisitos, consulte Comparar as funcionalidades geralmente disponíveis do Microsoft Entra ID.
• A função Administrador de Identidade Híbrida para configurar o agente de provisionamento e as funções de Administrador de Aplicativo ou Administrador de Aplicativo em Nuvem para configurar o provisionamento no portal do Azure.
• Os usuários do Microsoft Entra, para serem provisionados, já devem estar preenchidos com quaisquer atributos exigidos pelo esquema.

Baixar, instalar e configurar o Pacote do Agente de Provisionamento do Microsoft Entra Connect

Se você já baixou o agente de provisionamento e o configurou para outro aplicativo local, continue lendo na próxima seção.

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Identidade Híbrida.
2. Navegue até Gerenciamento híbrido de identidade>, Microsoft>Entra Connect>Cloud sync>Agents.

1. Selecione Baixar agente local, revise os termos de serviço e selecione Aceitar termos e download.

   Nota

   Use diferentes agentes de provisionamento para provisionamento de aplicativos locais e sincronização na nuvem do Microsoft Entra Connect / provisionamento orientado por RH. Os três cenários não devem ser gerenciados no mesmo agente.

2. Abra o instalador do agente de provisionamento, concorde com os termos de serviço e selecione Instalar.

3. Quando o assistente de configuração do agente de provisionamento do Microsoft Entra for aberto, continue na guia Selecionar extensão e selecione Provisionamento de aplicativo local quando for solicitada a extensão que você deseja habilitar.

4. O agente de provisionamento usa o navegador da Web do sistema operacional para exibir uma janela pop-up para você se autenticar na ID do Microsoft Entra e, potencialmente, também no provedor de identidade da sua organização. Se você estiver usando o Internet Explorer como navegador no Windows Server, talvez seja necessário adicionar sites da Microsoft à lista de sites confiáveis do navegador para permitir que o JavaScript seja executado corretamente.

5. Forneça credenciais para um administrador do Microsoft Entra quando você for solicitado a autorizar. O usuário deve ter pelo menos a função de Administrador de Identidade Híbrida .

6. Selecione Confirmar para confirmar a configuração. Quando a instalação for bem-sucedida, você poderá selecionar Sair e também fechar o instalador do Pacote do Agente de Provisionamento.

Configurar o aplicativo ECMA local

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.
2. Navegue até Aplicativos de identidade>>Aplicativos corporativos.
3. Selecione Nova aplicação.
4. Pesquise o aplicativo ECMA local, dê um nome ao aplicativo e selecione Criar para adicioná-lo ao seu locatário.
5. Navegue até a página Provisionamento do seu aplicativo.
6. Selecione Introdução.
7. Na página Provisionamento, altere o modo para Automático.
8. Na seção Conectividade Local, selecione o agente que você acabou de implantar e selecione Atribuir Agente(s).
9. Mantenha esta janela do navegador aberta enquanto conclui a próxima etapa de configuração usando o assistente de configuração.

Coloque o arquivo InputFile.txt e Schema.xml em locais

Antes de criar o conector do PowerShell para este tutorial, você precisa copiar o arquivo InputFile.txt e Schema.xml para os locais corretos. Esses arquivos são os que você precisava baixar na seção Baixar os arquivos de instalação do PowerShell.

Configurar o certificado Microsoft Entra ECMA Connector Host

1. No Windows Server onde o agente de provisionamento está instalado, clique com o botão direito do mouse no Assistente de Configuração do Microsoft ECMA2Host no menu Iniciar e execute como administrador. A execução como administrador do Windows é necessária para que o assistente crie os logs de eventos do Windows necessários.
2. Depois que a Configuração do Host do Conector ECMA for iniciada, se for a primeira vez que você executar o assistente, ele solicitará que você crie um certificado. Deixe a porta padrão 8585 e selecione Gerar certificado para gerar um certificado. O certificado gerado automaticamente será autoassinado como parte da raiz confiável. O certificado SAN corresponde ao nome do host.
3. Selecione Guardar.

Criar o conector do PowerShell

Ecrã Geral

1. Inicie o Assistente de Configuração do Microsoft ECMA2Host no menu Iniciar.

2. Na parte superior, selecione Importar e selecione o arquivo configuration.xml da etapa 1.

3. O novo conector deve ser criado e aparecer em vermelho. Clique em Editar.

4. Gere um token secreto usado para autenticar o ID do Microsoft Entra no conector. Deve ter um mínimo de 12 caracteres e ser único para cada aplicação. Se você ainda não tiver um gerador de segredos, poderá usar um comando do PowerShell, como o seguinte, para gerar um exemplo de cadeia de caracteres aleatória.

   -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})
   

5. Na página Propriedades, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

   Property	valor
   Nome	O nome escolhido para o conector, que deve ser exclusivo em todos os conectores em seu ambiente. Por exemplo, PowerShell.
   Temporizador de sincronização automática (minutos)	120
   Token secreto	Introduza o seu token secreto aqui. Deve ter no mínimo 12 caracteres.
   Extensão DLL	Para o conector do PowerShell, selecione Microsoft.IAM.Connector.PowerShell.dll.

Conectividade

A guia conectividade permite que você forneça parâmetros de configuração para se conectar a um sistema remoto. Configure a guia conectividade com as informações fornecidas na tabela.

• Na página Conectividade, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

Capacidades

A guia recursos 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. Configure a guia de recursos com as informações fornecidas na tabela.

• Na página Recursos, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

Parâmetros de Globais

A guia Parâmetros Globais 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. Configure a guia de parâmetros globais com as informações fornecidas na tabela.

• Na página Parâmetros Globais, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

Partições, Executar Perfis, Exportar, FullImport

Mantenha os padrões e clique em Avançar.

Tipos de objeto

Configure a guia Tipos de objeto com as informações fornecidas na tabela.

• Na página Tipos de objeto, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

Selecionar Atributos

Certifique-se de que os seguintes atributos estão selecionados:

• Na página Selecionar Atributos, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

• AzureObjectID

• IsActive

• DisplayName

• EmployeeId

• Título

• Nome de utilizador

• E-mail

Desprovisionamento

Na página Desprovisionamento, você pode especificar se deseja que o Microsoft Entra ID remova os usuários do diretório quando eles saírem do escopo do aplicativo. Em caso afirmativo, em Desativar fluxo, selecione Excluir e, em Excluir fluxo, selecione Excluir. Se Definir valor de atributo for escolhido, os atributos selecionados na página anterior não estarão disponíveis para seleção na página Desprovisionamento.

• Na página Desprovisionamento, todas as informações devem ser preenchidas. A tabela é fornecida como referência. Clique em Next.

Verifique se o serviço ECMA2Host está em execução e pode ler do arquivo via PowerShell

Siga estas etapas para confirmar se o host do conector foi iniciado e identificou todos os usuários existentes do sistema de destino.

1. No servidor que executa o Microsoft Entra ECMA Connector Host, selecione Iniciar.
2. Selecione Executar , se necessário, e digite services.msc na caixa.
3. Na lista Serviços, verifique se o Microsoft ECMA2Host está presente e em execução. Se não estiver em execução, selecione Iniciar.
4. No servidor que executa o Microsoft Entra ECMA Connector Host, inicie o PowerShell.
5. Mude para a pasta onde o host ECMA foi instalado, como C:\Program Files\Microsoft ECMA2Host.
6. Mude para o subdiretório Troubleshooting.
7. Execute o script TestECMA2HostConnection.ps1 no diretório conforme mostrado e forneça como argumentos o nome do conector e o ObjectTypePath valor cache. Se o host do conector não estiver escutando na porta TCP 8585, talvez você também precise fornecer o -Port argumento. Quando solicitado, digite o token secreto configurado para esse conector.

   PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> $cout = .\TestECMA2HostConnection.ps1 -ConnectorName PowerShell -ObjectTypePath cache; $cout.length -gt 9
   Supply values for the following parameters:
   SecretToken: ************
   

8. Se o script exibir uma mensagem de erro ou aviso, verifique se o serviço está em execução e se o nome do conector e o token secreto correspondem aos valores configurados no assistente de configuração.
9. Se o script exibir a saída False, o conector não viu nenhuma entrada no sistema de destino de origem para usuários existentes. Se esta for uma nova instalação do sistema de destino, esse comportamento é esperado e você pode continuar na próxima seção.
10. No entanto, se o sistema de destino já contiver um ou mais usuários, mas o script exibido False, esse status indica que o conector não pôde ler do sistema de destino. Se você tentar provisionar, o Microsoft Entra ID pode não corresponder corretamente os usuários nesse diretório de origem com os usuários no Microsoft Entra ID. Aguarde alguns minutos para que o host do conector termine de ler objetos do sistema de destino existente e, em seguida, execute novamente o script. Se a saída continuar a ser False, verifique a configuração do seu conector e as permissões no sistema de destino estão permitindo que o conector leia os usuários existentes.

Testar a conexão do ID do Microsoft Entra com o host do conector

1. Retorne à janela do navegador da Web onde você estava configurando o provisionamento do aplicativo no portal.

   Nota

   Se a janela tiver expirado, você precisará selecionar novamente o agente.

   1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.
   2. Navegue até Aplicativos de identidade>>Aplicativos corporativos.
   3. Selecione o aplicativo ECMA local.
   4. Selecione Provisionamento.
   5. Se Introdução for exibido, altere o modo para Automático, na seção Conectividade Local , selecione o agente que você acabou de implantar e selecione Atribuir Agente(s) e aguarde 10 minutos. Caso contrário, vá para Editar provisionamento.

2. Na secção Credenciais de administrador, introduza o seguinte URL. Substitua a connectorName parte pelo nome do conector no host ECMA, como PowerShell. Se você forneceu um certificado de sua autoridade de certificação para o host ECMA, substitua localhost pelo nome do host do servidor onde o host ECMA está instalado.

   Property	valor
   URL do locatário	https://localhost:8585/ecma2host_connectorName/scim

3. Insira o valor de Token secreto que você definiu quando criou o conector.

   Nota

   Se você acabou de atribuir o agente para o aplicativo, aguarde 10 minutos para que o registro seja concluído. O teste de conectividade não funcionará até que o registro seja concluído. Forçar a conclusão do registro do agente reiniciando o agente de provisionamento no servidor pode acelerar o processo de registro. Vá para o servidor, procure serviços na barra de pesquisa do Windows, identifique o serviço Microsoft Entra Connect Provisioning Agent , clique com o botão direito do mouse no serviço e reinicie.

4. Selecione Testar conexão e aguarde um minuto.

5. Depois que o teste de conexão for bem-sucedido e indicar que as credenciais fornecidas estão autorizadas a habilitar o provisionamento, selecione Salvar.

Configurar a conexão do aplicativo

Retorne à janela do navegador da Web onde você estava configurando o provisionamento do aplicativo.

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.

2. Navegue até Aplicativos de identidade>>Aplicativos corporativos.

3. Selecione o aplicativo ECMA local.

4. Selecione Provisionamento.

5. Se Introdução for exibido, altere o modo para Automático, na seção Conectividade Local, selecione o agente implantado e selecione Atribuir Agente(s). Caso contrário, vá para Editar provisionamento.

6. Na secção Credenciais de administrador, introduza o seguinte URL. Substitua a {connectorName} parte pelo nome do conector no host do conector ECMA, como CSV. O nome do conector diferencia maiúsculas de minúsculas e deve ser o mesmo caso que foi configurado no assistente. Você também pode substituir localhost pelo nome do host da máquina.

   Property	valor
   URL do locatário	https://localhost:8585/ecma2host_CSV/scim

7. Insira o valor de Token secreto que você definiu quando criou o conector.

   Nota

   Se você acabou de atribuir o agente para o aplicativo, aguarde 10 minutos para que o registro seja concluído. O teste de conectividade não funcionará até que o registro seja concluído. Forçar a conclusão do registro do agente reiniciando o agente de provisionamento no servidor pode acelerar o processo de registro. Vá para o servidor, procure serviços na barra de pesquisa do Windows, identifique o Serviço do Agente de Provisionamento do Microsoft Entra Connect, clique com o botão direito do mouse no serviço e reinicie.

8. Selecione Testar conexão e aguarde um minuto.

9. Depois que o teste de conexão for bem-sucedido e indicar que as credenciais fornecidas estão autorizadas a habilitar o provisionamento, selecione Salvar.

Configurar mapeamentos de atributos

Agora você precisa mapear atributos entre a representação do usuário no Microsoft Entra ID e a representação de um usuário no InputFile.txt local.

Você usará o portal do Azure para configurar o mapeamento entre os atributos do usuário do Microsoft Entra e os atributos que você selecionou anteriormente no assistente de configuração do Host ECMA.

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.

2. Navegue até Aplicativos de identidade>>Aplicativos corporativos.

3. Selecione o aplicativo ECMA local.

4. Selecione Provisionamento.

5. Selecione Editar provisionamento e aguarde 10 segundos.

6. Expanda Mapeamentos e selecione Provisionar usuários do Microsoft Entra. Se esta for a primeira vez que você configurou os mapeamentos de atributos para este aplicativo, haverá apenas um mapeamento presente, para um espaço reservado.

7. Para confirmar que o esquema está disponível no Microsoft Entra ID, marque a caixa de seleção Mostrar opções avançadas e selecione Editar lista de atributos para ScimOnPremises. Certifique-se de que todos os atributos selecionados no assistente de configuração estejam listados. Caso contrário, aguarde alguns minutos até que o esquema seja atualizado e, em seguida, recarregue a página. Depois de ver os atributos listados, cancele esta página para retornar à lista de mapeamentos.

8. Agora, clique no mapeamento userPrincipalName PLACEHOLDER. Esse mapeamento é adicionado por padrão quando você configura o provisionamento local pela primeira vez. Altere o valor para corresponder ao seguinte:

   Tipo de mapeamento	Atributo Source	Atributo de destino
   Direct	userPrincipalName	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName

9. Agora selecione Adicionar Novo Mapeamento e repita a próxima etapa para cada mapeamento.

10. Especifique os atributos de origem e destino para cada um dos mapeamentos na tabela a seguir.

    Tipo de mapeamento	Atributo Source	Atributo de destino
    Direct	objectId	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:AzureObjectID
    Direct	userPrincipalName	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName
    Direct	displayName	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:DisplayName
    Direct	Identificação do empregado	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:EmployeeId
    Direct	jobTitle	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Title
    Direct	correio	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Email
    Expression	Switch([IsSoftDeleted],, "False", "True", "True", "False")	urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:IsActive

    

11. Depois que todos os mapeamentos tiverem sido adicionados, selecione Salvar.

Atribuir utilizadores a uma aplicação

Agora que você tem o Microsoft Entra ECMA Connector Host conversando com o Microsoft Entra ID e o mapeamento de atributos configurado, você pode passar para configurar quem está no escopo para provisionamento.

Se houver usuários existentes no InputFile.txt, você deverá criar atribuições de função de aplicativo para esses usuários existentes. Para saber mais sobre como criar atribuições de função de aplicativo em massa, consulte Governando os usuários existentes de um aplicativo no Microsoft Entra ID.

Caso contrário, se não houver usuários atuais do aplicativo, selecione um usuário de teste do Microsoft Entra que será provisionado para o aplicativo.

1. Verifique se o usuário selecionado tem todas as propriedades, mapeadas para os atributos necessários do esquema.
2. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.
3. Navegue até Aplicativos de identidade>>Aplicativos corporativos.
4. Selecione o aplicativo ECMA local.
5. À esquerda, em Gerir, selecione Utilizadores e grupos.
6. Selecione Adicionar usuário/grupo.
7. Em Usuários, selecione Nenhum selecionado.
8. Selecione os usuários à direita e selecione o botão Selecionar .
9. Agora selecione Atribuir.

Provisionamento de teste

Agora que seus atributos estão mapeados e os usuários são atribuídos, você pode testar o provisionamento sob demanda com um de seus usuários.

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.
2. Navegue até Aplicativos de identidade>>Aplicativos corporativos.
3. Selecione o aplicativo ECMA local.
4. Selecione Provisionamento.
5. Selecione Provisão sob demanda.
6. Procure um dos seus usuários de teste e selecione Provisionar.
7. Após alguns segundos, aparece a mensagem Usuário criado com êxito no sistema de destino, com uma lista dos atributos do usuário.

Comece a provisionar usuários

1. Depois que o provisionamento sob demanda for bem-sucedido, volte para a página de configuração de provisionamento. Verifique se o escopo está definido apenas para usuários e grupos atribuídos, ative o provisionamento e selecione Salvar.
2. Aguarde alguns minutos para que o provisionamento seja iniciado. Pode demorar até 40 minutos. Após a conclusão do trabalho de provisionamento, conforme descrito na próxima seção, se você tiver concluído o teste, poderá alterar o status do provisionamento para Desativado e selecionar Salvar. Essa ação impede que o serviço de provisionamento seja executado no futuro.

Próximos passos

• Provisionamento de aplicativos
• ECMA Connector Host conector SQL genérico
• Conector ECMA Conector LDAP do host