Partilhar via

Azure AD cmdlets para trabalhar com atributos de extensão

  • Artigo

Sobre os atributos de extensão

Os atributos de extensão oferecem um meio cómodo para expandir o seu diretório do Azure AD com novos atributos que pode utilizar para armazenar valores de atributo de objetos no seu diretório. Pode anexar um atributo de extensão aos seguintes tipos de objeto:

  • utilizadores
  • detalhes de inquilino
  • dispositivos
  • aplicações

As propriedades de extensão são registadas num objeto de Aplicação no diretório do programador. Depois de um utilizador ou administrador autorizar a aplicação no diretório do programador, a propriedade é adicionada ao tipo de diretório de destino e fica imediatamente acessível no diretório do programador. No caso de uma aplicação multi-inquilino, quando um utilizador ou administrador noutra organização autoriza a aplicação, as propriedades de extensão ficam imediatamente acessíveis no tipo de diretório de destino no diretório da outra organização.

Se uma organização autorizar permissões "só de leitura" para uma aplicação com extensões registadas, as propriedades continuam a ficar acessíveis no diretório da outra organização. Além disso, qualquer aplicação autorizada pode aceder às propriedades de extensão numa organização, e não apenas a aplicação na qual estão registadas. Outras aplicações autorizadas nessa organização podem ler ou escrever valores para a nova propriedade de extensão, caso tenham permissões suficientes.

Se a aplicação for eliminada ou o consentimento for removido no diretório da outra organização, a propriedade de extensão fica inacessível no objeto de diretório de destino. Se a extensão for eliminada pela aplicação, fica também inacessível no objeto de diretório de destino. Se uma aplicação multi-inquilino adicionar mais propriedades de extensão depois de a autorização ser concedida, estas propriedades ficam imediatamente acessíveis no diretório da outra organização.

Nota

Se o valor de uma propriedade de extensão estiver definido num objeto e essa propriedade ficar inacessível no diretório desse objeto, a propriedade ainda conta para o limite de 100 valores de propriedade de extensão desse objeto. A única forma de deixar de considerar o valor da propriedade depois de ser definido é defini-lo explicitamente como nulo. Não é possível fazê-lo se a propriedade de extensão não estiver acessível.

Pode ler mais sobre as propriedades de extensão neste artigo.

Exemplos

Nestes exemplos, vamos utilizar um objeto de utilizador e trabalhar com as propriedades de extensão. Em primeiro lugar, vamos localizar o ObjectId do utilizador, para que possamos mencioná-lo mais tarde:

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

Obter todos os valores de propriedade de um utilizador

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

Obter um utilizador e mostrar todas as propriedades de extensão

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

Este cmdlet devolve todas as propriedades de extensão de um utilizador com os respetivos 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

Obter o valor de uma propriedade de extensão específica para um utilizador

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

Obter todas as propriedades de extensão que estão definidas no seu inquilino

Get-AzureADApplication | Get-AzureADApplicationExtensionProperty

Criar uma nova propriedade de extensão

As propriedades de extensão são sempre criadas para uma aplicação específica. Se pretender apenas adicionar propriedades genéricas ao seu diretório, pode criar uma aplicação de marcador de posição:

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

Tenha em atenção que também é necessário criar um principal de serviço para esta aplicação no seu diretório, para que possa criar uma nova propriedade de extensão:

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

Agora, podemos utilizar esta aplicação para criar uma nova propriedade de extensão:

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

Quando o cmdlet for concluído com êxito, devolve o novo objeto de atributo de extensão:

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

Nota

O Nome da nova propriedade é gerado a partir do formato "Extension_" + <objectID da sua aplicação de marcador de posição> + "_" + <o nome da nova propriedade>. O valor exato do nome irá, por isso, ser diferente para diferentes aplicações que criar. Pode atribuir uma propriedade a mais do que um tipo de objeto. No nosso exemplo, utilizámos apenas um TargetObject, "User", mas podia também ter especificado "User","Group", e assim atribuiria o objeto aos objetos utilizador e grupo.

Definir valores para propriedades de extensão

Com a propriedade de extensão que criámos no exemplo anterior, podemos agora atribuir um valor à mesma:

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

Obter todos os atributos de extensão que estão definidos para a sua aplicação

Pode obter a lista de atributos de extensão que foram definidos para a sua aplicação:

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

Este cmdlet devolve a lista de propriedades de extensão na aplicação:

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

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

Eliminar propriedades de extensão

Se já não precisar de uma propriedade de extensão, pode eliminá-la:

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

Nota

Não pode remover o atributo de Azure AD uma vez expandido nem eliminar o Tenant Schema Extension App sem criar um pedido para a Equipa do PayOps. Além disso, desativar a opção de extensões de diretório do Azure AD assistente não remove os atributos nem permite-lhe eliminar a aplicação.