Sincronizando atributos de extensão para o Microsoft Entra Application Provisioning

Artigo
04/10/2024

O Microsoft Entra ID deve conter todos os dados (atributos) necessários para criar um perfil de usuário ao provisionar contas de usuário do Microsoft Entra ID para um aplicativo SaaS ou aplicativo local. Ao personalizar mapeamentos de atributos para provisionamento de usuário, você pode achar que o atributo que deseja mapear não aparece na lista de atributos de origem no ID do Microsoft Entra. Este artigo mostra como adicionar o atributo ausente.

Determinar onde as extensões precisam ser adicionadas

A adição de atributos ausentes necessários para um aplicativo começará no Ative Directory local ou na ID do Microsoft Entra, dependendo de onde as contas de usuário residem e como elas são trazidas para a ID do Microsoft Entra.

Primeiro, identifique quais usuários em seu locatário do Microsoft Entra precisam de acesso ao aplicativo e, portanto, estarão no escopo de serem provisionados no aplicativo.

Em seguida, determine qual é a origem do atributo e a topologia de como esses usuários são trazidos para o Microsoft Entra ID.

Fonte do atributo	Topologia	Passos necessários
Sistema de RH	Os trabalhadores do sistema de RH são provisionados como usuários no Microsoft Entra ID.	Crie um atributo de extensão no Microsoft Entra ID. Atualize o mapeamento de entrada HR para preencher o atributo extension em usuários do Microsoft Entra ID a partir do sistema HR.
Sistema de RH	Os trabalhadores do sistema de RH são provisionados como usuários no Windows Server AD. A sincronização na nuvem do Microsoft Entra Connect sincroniza-os com o Microsoft Entra ID.	Estenda o esquema do AD, se necessário. Crie um atributo de extensão no Microsoft Entra ID usando a sincronização na nuvem. Atualize o mapeamento de entrada HR para preencher o atributo extension no usuário do AD a partir do sistema HR.
Sistema de RH	Os trabalhadores do sistema de RH são provisionados como usuários no Windows Server AD. O Microsoft Entra Connect sincroniza-os com o Microsoft Entra ID.	Estenda o esquema do AD, se necessário. Crie um atributo de extensão no Microsoft Entra ID usando o Microsoft Entra Connect. Atualize o mapeamento de entrada HR para preencher o atributo extension no usuário do AD a partir do sistema HR.

Se os usuários da sua organização já estiverem no Ative Directory local ou se você os estiver criando no Ative Directory, você deverá sincronizar os usuários do Ative Directory com o Microsoft Entra ID. Você pode sincronizar usuários e atributos usando o Microsoft Entra Connect ou a sincronização na nuvem do Microsoft Entra Connect.

Verifique com os administradores de domínio do Ative Directory locais se os atributos necessários fazem parte da classe de objeto do esquema User AD DS e, se não forem, estenda o esquema dos Serviços de Domínio Ative Directory nos domínios em que esses usuários têm contas.
Configure a sincronização na nuvem do Microsoft Entra Connect ou do Microsoft Entra Connect para sincronizar os usuários com seu atributo de extensão do Ative Directory para o Microsoft Entra ID. Ambas as soluções sincronizam automaticamente determinados atributos com o Microsoft Entra ID, mas não todos os atributos. Além disso, alguns atributos (como sAMAccountName) que são sincronizados por padrão podem não ser expostos usando a API do Graph. Nesses casos, você pode usar o recurso de extensão de diretório do Microsoft Entra Connect para sincronizar o atributo com o ID do Microsoft Entra ou usar a sincronização na nuvem do Microsoft Entra Connect. Dessa forma, o atributo fica visível para a API do Graph e o serviço de provisionamento do Microsoft Entra.
Se os usuários no Ative Directory local ainda não tiverem os atributos necessários, você precisará atualizar os usuários no Ative Directory. Essa atualização pode ser feita lendo as propriedades do Workday, do SAP SuccessFactors ou, se você estiver usando um sistema de RH diferente, usando a API de RH de entrada.
Aguarde até que a sincronização na nuvem do Microsoft Entra Connect ou do Microsoft Entra Connect sincronize as atualizações feitas no esquema do Ative Directory e os usuários do Ative Directory na ID do Microsoft Entra.

Como alternativa, se nenhum dos usuários que precisam de acesso ao aplicativo tiver origem no Ative Directory local, você precisará criar extensões de esquema usando o PowerShell ou o Microsoft Graph no Microsoft Entra ID antes de configurar o provisionamento para seu aplicativo.

As seções a seguir descrevem como criar atributos de extensão para um locatário com usuários somente na nuvem e para um locatário com usuários do Ative Directory.

Criar um atributo de extensão em um locatário com usuários somente na nuvem

Você pode usar o Microsoft Graph e o PowerShell para estender o esquema de usuário para usuários no Microsoft Entra ID. Isso é necessário se você tiver usuários que precisam desse atributo e nenhum deles for originado ou sincronizado do Ative Directory local. (Se você tiver o Ative Directory, continue lendo abaixo na seção sobre como usar o recurso de extensão de diretório do Microsoft Entra Connect para sincronizar o atributo com o Microsoft Entra ID.)

Depois que as extensões de esquema são criadas, esses atributos de extensão são descobertos automaticamente quando você visita a página de provisionamento no centro de administração do Microsoft Entra, na maioria dos casos.

Quando você tiver mais de 1.000 entidades de serviço, poderá encontrar extensões ausentes na lista de atributos de origem. Se um atributo que você criou não aparecer automaticamente, verifique se o atributo foi criado e adicione-o manualmente ao seu esquema. Para verificar se foi criado, use o Microsoft Graph e o Graph Explorer. Para adicioná-lo manualmente ao seu esquema, consulte Editando a lista de atributos suportados.

Criar um atributo de extensão para usuários somente na nuvem usando o Microsoft Graph

Você pode estender o esquema de usuários do Microsoft Entra usando o Microsoft Graph.

Primeiro, liste os aplicativos em seu locatário para obter a ID do aplicativo em que você está trabalhando. Para saber mais, consulte Listar extensionProperties.

GET https://graph.microsoft.com/v1.0/applications

Em seguida, crie o atributo extension. Substitua a propriedade ID abaixo pela ID recuperada na etapa anterior. Você precisa usar o atributo "ID" e não o "appId". Para saber mais, consulte [Create extensionProperty]/graph/api/application-post-extensionproperty).

POST https://graph.microsoft.com/v1.0/applications/{id}/extensionProperties
Content-type: application/json

{
    "name": "extensionName",
    "dataType": "string",
    "targetObjects": [
      "User"
    ]
}

A solicitação anterior criou um atributo de extensão com o formato extension_appID_extensionName. Agora você pode atualizar um usuário com esse atributo de extensão. Para saber mais, consulte Atualizar usuário.

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
  "extension_inputAppId_extensionName": "extensionValue"
}

Finalmente, verifique o atributo para o usuário. Para saber mais, consulte Obter um usuário. O Graph v1.0 não retorna por padrão nenhum dos atributos de extensão de diretório de um usuário, a menos que os atributos sejam especificados na solicitação como uma das propriedades a serem retornadas.

GET https://graph.microsoft.com/v1.0/users/{id}?$select=displayName,extension_inputAppId_extensionName

Criar um atributo de extensão para usuários somente na nuvem usando o PowerShell

Você pode criar uma extensão personalizada usando o PowerShell.

Nota

Os módulos Azure AD e MSOnline PowerShell foram preteridos a partir de 30 de março de 2024. Para saber mais, leia a atualização de descontinuação. Após essa data, o suporte para esses módulos é limitado à assistência de migração para o SDK do Microsoft Graph PowerShell e correções de segurança. Os módulos preteridos continuarão a funcionar até 30 de março de 2025.

Recomendamos migrar para o Microsoft Graph PowerShell para interagir com o Microsoft Entra ID (anteriormente Azure AD). Para perguntas comuns sobre migração, consulte as Perguntas frequentes sobre migração. Nota: As versões 1.0.x do MSOnline podem sofrer interrupções após 30 de junho de 2024.

#Connect to your Azure AD tenant
Connect-AzureAD

#Create an application (you can instead use an existing application if you would like)
$App = New-AzureADApplication -DisplayName “test app name” -IdentifierUris https://testapp

#Create a service principal
New-AzureADServicePrincipal -AppId $App.AppId

#Create an extension property
New-AzureADApplicationExtensionProperty -ObjectId $App.ObjectId -Name “TestAttributeName” -DataType “String” -TargetObjects “User”

Opcionalmente, você pode testar se pode definir a propriedade extension em um usuário somente na nuvem.

#List users in your tenant to determine the objectid for your user
Get-AzureADUser

#Set a value for the extension property on the user. Replace the objectid with the ID of the user and the extension name with the value from the previous step
Set-AzureADUserExtension -objectid 0ccf8df6-62f1-4175-9e55-73da9e742690 -ExtensionName “extension_6552753978624005a48638a778921fan3_TestAttributeName”

#Verify that the attribute was added correctly.
Get-AzureADUser -ObjectId 0ccf8df6-62f1-4175-9e55-73da9e742690 | Select -ExpandProperty ExtensionProperty

Criar um atributo de extensão usando a sincronização na nuvem

Se você tiver usuários no Ative Directory e estiver usando a sincronização na nuvem do Microsoft Entra Connect, a sincronização na nuvem descobrirá automaticamente suas extensões no Ative Directory local quando você adicionar um novo mapeamento. Se você estiver usando a sincronização do Microsoft Entra Connect, continue lendo na próxima seção criar um atributo de extensão usando o Microsoft Entra Connect.

Use as etapas abaixo para descobrir automaticamente esses atributos e configurar um mapeamento correspondente para o Microsoft Entra ID.

Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Identidade Híbrida.
Navegue até Gerenciamento híbrido de>identidade>Microsoft Entra Connect>Cloud sync.
Selecione a configuração que deseja adicionar o atributo de extensão e o mapeamento.
Em Gerenciar atributos , selecione clique para editar mapeamentos.
Selecione Adicionar mapeamento de atributos. Os atributos são descobertos automaticamente.
Os novos atributos estão disponíveis na lista suspensa em atributo source.
Preencha o tipo de mapeamento desejado e selecione Aplicar.

Para obter mais informações, consulte Mapeamento de atributos personalizados na sincronização de nuvem do Microsoft Entra Connect.

Criar um atributo de extensão usando o Microsoft Entra Connect

Se os usuários que acessam os aplicativos forem originários do Ative Directory local, você deverá sincronizar os atributos com os usuários do Ative Directory para o Microsoft Entra ID. Se você usar o Microsoft Entra Connect, precisará executar as seguintes tarefas antes de configurar o provisionamento para seu aplicativo.

Verifique com os administradores de domínio do Ative Directory locais se os atributos necessários fazem parte da classe de objeto do esquema User AD DS e, se não forem, estenda o esquema dos Serviços de Domínio Ative Directory nos domínios em que esses usuários têm contas.
Abra o assistente do Microsoft Entra Connect, escolha Tarefas e, em seguida, escolha Personalizar opções de sincronização.
Inicie sessão como Administrador Global.
Na página Recursos opcionais, selecione Sincronização de atributos de extensão de diretório.
Selecione o(s) atributo(s) que deseja estender para o Microsoft Entra ID.

Nota

A pesquisa em Atributos disponíveis diferencia maiúsculas de minúsculas .
Conclua o assistente do Microsoft Entra Connect e permita a execução de um ciclo de sincronização completo. Quando o ciclo é concluído, o esquema é estendido e os novos valores são sincronizados entre o AD local e a ID do Microsoft Entra.

Nota

A capacidade de provisionar atributos de referência do AD local, como managedby ou DN/DistinguishedName, não é suportada atualmente. Você pode solicitar esse recurso no User Voice.

Preencher e usar o novo atributo

No centro de administração do Microsoft Entra, enquanto você edita mapeamentos de atributos de usuário para logon único ou provisionamento da ID do Microsoft Entra para um aplicativo, a lista de atributos de origem agora conterá o atributo adicionado no formato <attributename> (extension_<appID>_<attributename>), onde appID é o identificador de um aplicativo de espaço reservado em seu locatário. Selecione o atributo e mapeie-o para o aplicativo de destino para provisionamento.

Assistente do Microsoft Entra Connect Página de seleção de extensões de diretório

Em seguida, você precisará preencher os usuários atribuídos ao aplicativo com o atributo necessário, antes de habilitar o provisionamento para o aplicativo. Se o atributo não for originário do Ative Directory, há cinco maneiras de preencher os usuários em massa:

Se as propriedades tiverem origem em um sistema de RH e você estiver provisionando os trabalhadores desse sistema de RH como usuários no Ative Directory, configure um mapeamento de Workday, SAP SuccessFactors ou, se estiver usando um sistema de RH diferente, usando a API de RH de entrada para o atributo Ative Directory. Em seguida, aguarde a sincronização na nuvem do Microsoft Entra Connect ou do Microsoft Entra Connect para sincronizar as atualizações feitas no esquema do Ative Directory e os usuários do Ative Directory no Microsoft Entra ID.
Se as propriedades tiverem origem em um sistema de RH e você não estiver usando o Ative Directory, poderá configurar um mapeamento do Workday, SAP SuccessFactors ou outros por meio da API de entrada para o atributo de usuário do Microsoft Entra.
Se as propriedades forem originadas em outro sistema local, você poderá configurar o MIM Connector for Microsoft Graph para criar ou atualizar usuários do Microsoft Entra.
Se as propriedades forem originadas dos próprios usuários, você poderá solicitar que os usuários forneçam os valores do atributo quando solicitarem acesso ao aplicativo, incluindo os requisitos de atributo no catálogo de gerenciamento de direitos.
Para todas as outras situações, um aplicativo personalizado pode atualizar os usuários por meio da API do Microsoft Graph .

Próximos passos

Definir quem está no escopo do provisionamento