Compartilhar via

Azure AD cmdlets para trabalhar com atributos de extensão

  • Artigo

Sobre os atributos de extensão

Os atributos de extensão oferecem uma maneira conveniente de estender seu diretório do Azure AD com novos atributos que você pode usar para armazenar os valores do atributo para os objetos em seu diretório. Você pode anexar um atributo de extensão aos seguintes tipos de objeto:

  • users
  • detalhes do locatário
  • dispositivos
  • de dimensionamento da Web

As propriedades de extensão são registradas em um objeto de Aplicativo no diretório do desenvolvedor. Depois do aplicativo ter sido consentido por um usuário ou um administrador no diretório do desenvolvedor, a propriedade é adicionada ao tipo de diretório de destino e torna-se imediatamente acessível no diretório do desenvolvedor. Para um aplicativo multilocatário, quando o aplicativo recebe o consentimento de um usuário ou um administrador em outra organização, as propriedades de extensão tornam-se imediatamente acessíveis no tipo de diretório de destino no diretório da outra organização.

Se uma organização consentir com as permissões de "somente leitura" para um aplicativo com extensões registradas, as propriedades ainda ficarão acessíveis no diretório da outra organização. Além disso, as propriedades de extensão são acessíveis por qualquer aplicativo consentido em uma organização, não apenas para o aplicativo no qual estão registradas. Outros aplicativos consentidos nessa organização poderão ler ou gravar os valores para a nova propriedade de extensão se tiverem permissões suficientes.

Se o aplicativo for removido ou o consentimento for removido no diretório da outra organização, a propriedade de extensão ficará inacessível no objeto de diretório de destino. Se a extensão for excluída pelo aplicativo, também ficará inacessível no objeto de diretório de destino. Se um aplicativo multilocatário adicionar propriedades de extensão extras após o consentimento ser concedido, essas propriedades ficarão imediatamente acessíveis no diretório da outra organização.

Observação

Se o valor de uma propriedade de extensão for definido em um objeto e essa propriedade se tornar inacessível no diretório desse objeto, a propriedade ainda será contabilizado em relação ao limite desse objeto de 100 valores de propriedade de extensão. A única maneira de não levar em consideração o valor da propriedade depois dele ter sido definido é defini-lo para nulo explicitamente. Não será possível fazer isso se a propriedade de extensão estiver inacessível.

Você pode ler mais sobre as propriedades de extensão neste artigo.

Exemplos

Nestes exemplos, usaremos um objeto do usuário e trabalharemos com as propriedades de extensão. Primeiro, encontraremos a ObjectId do usuário para que possamos consultá-la facilmente depois:

$UserId = (Get-AzureADUser -Searchstring <UPN of the user we're working with>).ObjectId

Obter todos os valores de propriedade de um usuário

(Get-AzureADUser -ObjectId $UserId).ToJson()

Obter um usuário e mostrar todas as propriedades de extensão

Get-AzureADUser -ObjectId $UserId | Select -ExpandProperty ExtensionProperty

Esse cmdlet retorna todas as propriedades de extensão de um usuário com seus valores atuais:

Key                                                                   Value
---                                                                   -----
odata.metadata                                                        https://graph.windows.net/85b5ff1e-0402-400c-9e3c-0f9e965325d1/$metad...
odata.type                                                            Microsoft.DirectoryServices.User
thumbnailPhoto@odata.mediaContentType                                 image/Jpeg
extension_e5e29b8a85d941eab8d12162bd004528_extensionAttribute13       Test

Recuperar o valor de uma propriedade de extensão específica para um usuário

(Get-AzureADUserExtension -ObjectId $UserId).get_item("extension_e5e29b8a85d941eab8d12162bd004528_wWWHomePage")

Recuperar todas as propriedades de extensão definidas em seu locatário

Get-AzureADApplication | Get-AzureADApplicationExtensionProperty

Criar uma nova propriedade de extensão

As propriedades de extensão são sempre criadas para um aplicativo específico. Se você quiser adicionar propriedades genéricas ao diretório, poderá criar um aplicativo de espaço reservado:

$MyApp = (New-AzureADApplication -DisplayName "My Properties Bag" -IdentifierUris "https://dummy").ObjectId

Observe que você precisa criar uma entidade de serviço para esse aplicativo em seu diretório também para que possa criar uma nova propriedade de extensão:

New-AzureADServicePrincipal -AppId (Get-AzureADApplication -SearchString "My Properties Bag").AppId

Agora, podemos usar esse aplicativo para criar uma nova propriedade de extensão:

New-AzureADApplicationExtensionProperty -ObjectId $MyApp -Name "MyNewProperty" -DataType "String" -TargetObjects "User"

Quando o cmdlet concluir com êxito, ele retornará o novo objeto do atributo de extensão:

ObjectId                             Name                                                     TargetObjects
--------                             ----                                                     -------------
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb extension_0380f0f700c040b5aa577c9268940b53_MyNewProperty {User}

Observação

O Nome da nova propriedade é gerado a partir do formato "Extension_" + <objectID do aplicativo> de espaço reservado + "_" + <o nome da nova propriedade>. Portanto, o valor exato do nome será diferente para os diferentes aplicativos criados. Você pode atribuir uma propriedade a mais de um tipo de objeto. Em nosso exemplo, apenas usamos um TargetObject, "Usuário", mas você também poderia ter especificado "Usuário", "Grupo". Isso atribuiria o objeto aos objetos usuário e grupo.

Definindo valores para as propriedades de extensão

Com a propriedade de extensão utilizada no exemplo anterior, agora podemos atribuir um valor a ela:

Set-AzureADUserExtension -ObjectId $UserId -ExtensionName "extension_0380f0f700c040b5aa577c9268940b53_MyNewProperty" -ExtensionValue "MyNewValue"

Recuperando todos os atributos de extensão definidos para seu aplicativo

É possível recuperar todos os atributos de extensão definidos para seu aplicativo:

Get-AzureADApplicationExtensionProperty -ObjectId (Get-AzureADApplication -SearchString "My Properties Bag").ObjectId

Este cmdlet retorna a lista de propriedades de extensão em seu aplicativo:

ObjectId                             Name                                                      TargetObjects
--------                             ----                                                      -------------

aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb extension_0380f0f700c040b5aa577c9268940b53_MyNewProperty  {User}

Excluindo as propriedades de extensão

Se você não precisar mais de uma propriedade de extensão, poderá excluí-la:

Remove-AzureADApplicationExtensionProperty -ObjectId (Get-AzureADApplication -SearchString "My Properties Bag").ObjectID -ExtensionPropertyId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb

Observação

Você não pode remover o atributo de Azure AD uma vez estendido nem excluir o Tenant Schema Extension App sem gerar uma solicitação para a equipe do PayOps. Além disso, desativar a opção de extensões de diretório do assistente de Azure AD não removerá os atributos nem permitirá que você se livre do aplicativo.