Sincronizando atributos de extensão para o provisionamento de aplicativos do Microsoft Entra

O Microsoft Entra ID deve conter todos os dados (atributos) necessários para criar um perfil do usuário ao provisionar contas de usuário do Microsoft Entra ID para um aplicativo SaaS ou em aplicativos locais. Ao personalizar mapeamentos de atributos para provisionamento de usuário, você pode descobrir que o atributo que deseja mapear não aparece na lista de Atributos de origemno Microsoft Entra ID. 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 Active Directory local ou no Microsoft Entra ID, dependendo de onde residem as contas de usuário e como elas são trazidas para o Microsoft Entra ID.

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

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

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

1. Verifique com os administradores de domínio do Active Directory local se os atributos necessários fazem parte do esquema do AD DS User classe de objeto e, se não fizerem, estenda o esquema do Active Directory Domain Services nos domínios em que esses usuários têm contas.
2. Configure Microsoft Entra Connect ou sincronização na nuvem do Microsoft Entra Connect para sincronizar os usuários com o respectivo atributo de extensão do Active Directory para o Microsoft Entra ID. Essas duas 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 por meio da 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 Microsoft Entra ID ou usar a sincronização em nuvem do Microsoft Entra Connect. Dessa forma, o atributo fica visível para a API do Graph e para o serviço de provisionamento do Microsoft Entra.
3. Se os usuários no Active Directory local ainda não tiverem os atributos necessários, será necessário atualizar os usuários no Active 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.
4. Aguarde a sincronização do Microsoft Entra Connect ou a sincronização na nuvem do Microsoft Entra Connect para sincronizar essas atualizações feitas no esquema do Active Directory e nos usuários do Active Directory para o Microsoft Entra ID.

Como alternativa, se nenhum dos usuários que precisam acessar o aplicativo tiver origem no Active Directory local, será necessário criar extensões de esquema usando o PowerShell ou o Microsoft Graph no Microsoft Entra ID, antes de configurar o provisionamento para o 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 Active 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 do usuário para usuários no Microsoft Entra ID. Isso é necessário se você tiver usuários que precisam desse atributo e nenhum deles se origina ou é sincronizado a partir do Active Directory local. (Se você tiver o Active Directory, continue a leitura 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, os atributos de extensão são descobertos automaticamente na próxima vez que você visitar 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, talvez encontre 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 ele foi criado, use o Microsoft Graph e o Explorador do Graph. Para adicioná-lo manualmente ao seu esquema, confira Editar a lista de atributos com suporte.

Criar um atributo de extensão para somente usuários da 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 na qual você está trabalhando. Para saber mais, confira List extensionProperties.

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

Em seguida, crie o atributo de extensão. Substitua a propriedade ID abaixo pela ID recuperada na etapa anterior. Você precisará usar o atributo "ID" e não "appId". Para saber mais, confira [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, confira Atualizar usuário.

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

{
  "extension_inputAppId_extensionName": "extensionValue"
}

Por fim, verifique o atributo do usuário. Para saber mais, confira Obter um usuário. Observe que 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 apenas na nuvem usando o PowerShell

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

#Connect to your Entra tenant
Connect-Entra -Scopes 'Application.ReadWrite.All'

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

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

#Create an extension property
New-EntraApplicationExtensionProperty -ApplicationId $App.ObjectId -Name "TestAttributeName" -DataType "String" -TargetObjects "User"

Opcionalmente, você pode testar se pode definir a propriedade de extensão em um usuário somente na nuvem.

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

#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-EntraUserExtension -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb -ExtensionName "extension_6552753978624005a48638a778921fan3_TestAttributeName"

#Verify that the attribute was added correctly.
Get-EntraUser -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb | Select -ExpandProperty ExtensionProperty

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

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

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

1. Entre no centro de administração do Microsoft Entra como, no mínimo, um Administrador de identidade híbrida.
2. Navegue até Entra ID>Entra Connect>Sincronização na nuvem.
3. Selecione a configuração a que deseja adicionar o atributo de extensão e o mapeamento.
4. Em Gerenciar atributos, selecione Clique para editar mapeamentos.
5. Selecione Adicionar o mapeamento de atributo. Os atributos são descobertos automaticamente.
6. Os novos atributos estão disponíveis na lista suspensa em atributo de origem.
7. Preencha o tipo de mapeamento desejado e clique em Aplicar.

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

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

Se os usuários que acessam os aplicativos tiverem origem no Active Directory local, será necessário sincronizar os atributos com os usuários do Active 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.

1. Verifique com os administradores de domínio do Active Directory local se os atributos necessários fazem parte do esquema do AD DS User classe de objeto e, se não fizerem, estenda o esquema do Active Directory Domain Services nos domínios em que esses usuários têm contas.

2. Abra o assistente do Microsoft Entra Connect, escolha Tarefas e, em seguida, escolha Personalizar opções de sincronização.

3. Entre como Administrador de identidade híbrida.

4. Na página Recursos Opcionais, selecione Sincronização do atributo Extensão de diretório.

5. Selecione os atributos que você deseja estender para o Microsoft Entra ID.

   Observação

   A pesquisa em Atributos Disponíveis diferencia maiúsculas de minúsculas.

6. Conclua o assistente do Microsoft Entra Connect e permita que um ciclo completo de sincronização seja executado. Quando o ciclo for concluído, o esquema será estendido e os novos valores serão sincronizados entre o AD local e o Microsoft Entra ID.

Preencher e usar o novo atributo

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

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 se originar no Active Directory, há cinco maneiras de preencher os usuários em lote:

• Se as propriedades forem originadas em um sistema de RH e você estiver provisionando os trabalhadores desse sistema de RH como usuários no Active Directory, configure um mapeamento do Workday, SAP SuccessFactors ou se estiver usando um sistema de RH diferente, usando a API de RH de entrada para o atributo Active Directory. Em seguida, aguarde a sincronização do Microsoft Entra Connect ou do sincronização na nuvem do Microsoft Entra Connect para sincronizar essas atualizações feitas no esquema do Active Directory e nos usuários do Active Directory para o Microsoft Entra ID.
• Se as propriedades forem originadas em um sistema de RH e você não estiver usando o Active Directory, você 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 tiverem origem em outro sistema local, você pode configurar o Conector MIM para Microsoft Graph para criar ou atualizar os usuários do Microsoft Entra.
• Se as propriedades tiverem origem dos próprios usuários, você pode pedir para os usuários fornecerem 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óximas etapas

• Defina quem está no escopo de provisionamento