拡張機能属性を操作するための Azure AD コマンドレット

[アーティクル]
04/25/2024

拡張属性について

Azure AD ディレクトリは、拡張属性を使って手軽に拡張することができます。ディレクトリに存在するさまざまなオブジェクトの属性の値を、新しい属性を使って格納することが可能です。拡張属性を関連付けることができるオブジェクトの種類は次のとおりです。

users
テナントの詳細
devices
applications

拡張プロパティは、開発者のディレクトリ内の Application オブジェクトに登録されます。そのアプリケーションが、開発者ディレクトリ内のユーザーまたは管理者によって承諾されると、対応するプロパティが対象のディレクトリタイプに追加され、開発者のディレクトリ内ですぐに利用できる状態になます。マルチテナントアプリケーションの場合、別の組織のユーザーまたは管理者によってアプリケーションが承諾されるとすぐに、その別の組織のディレクトリに存在する対象のディレクトリタイプで、拡張プロパティが利用可能な状態となります。

拡張プロパティが登録されているアプリケーションの "読み取り専用" アクセス許可を、ある 1 つの組織が承諾した場合、別の組織のディレクトリにおいても、それらのプロパティが利用できる状態になります。加えて拡張プロパティは、それが登録されているアプリケーションだけでなく、組織内の承諾されているアプリケーションであれば、どのアプリケーションからでも利用することができます。その組織に存在する他の承諾済みアプリケーションも、必要なアクセス許可さえあれば、新しい拡張プロパティの値を読み取ったり書き込んだりすることが可能です。

他の組織のディレクトリで承諾が取り消されるか、アプリケーションが削除された場合、対象のディレクトリオブジェクトの拡張プロパティは利用できなくなります。アプリケーションによって拡張プロパティが削除された場合、対象のディレクトリオブジェクトでは、その拡張プロパティが利用できなくなります。マルチテナントアプリケーションで、承諾後に新たな拡張プロパティが追加された場合は、それらのプロパティが直ちに別の組織のディレクトリで利用できるようになります。

注意

拡張機能プロパティの値がオブジェクトで設定され、そのプロパティがそのオブジェクトのディレクトリでアクセス不可能になった場合、引き続き、そのオブジェクトの上限 (100 拡張機能プロパティ値) に対してプロパティがカウントされます。プロパティの値を設定後にカウントから除外する唯一の方法は、明示的に null に設定することです。しかし拡張プロパティが利用できない状態では、それもできません。

拡張プロパティについて詳しくは、こちらの記事をご覧ください。

使用例

以下の例では、ユーザーオブジェクトを使用して拡張プロパティを操作します。まずユーザーを参照しやすいように、対応する ObjectId を特定します。

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

ユーザーのすべてのプロパティの値を取得する

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

ユーザーを取得してすべての拡張プロパティを表示する

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

このコマンドレットは、ユーザーのすべての拡張プロパティとその現在の値を返します。

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

ユーザーの特定の拡張プロパティの値を取得する

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

テナントに定義されているすべての拡張プロパティを取得する

Get-AzureADApplication | Get-AzureADApplicationExtensionProperty

新しい拡張プロパティを作成する

拡張プロパティは、特定のアプリケーションを対象にいつでも作成することができます。単に汎用的なプロパティをディレクトリに追加する場合は、プレースホルダーアプリケーションを作成してください。

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

同時に、そのアプリケーションのサービスプリンシパルもディレクトリに作成する必要があります。そうして初めて新しい拡張プロパティを作成することができます。

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

このアプリケーションを使って新しい拡張プロパティを作成することができます。

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

コマンドレットが正常に完了すると、新しい拡張属性オブジェクトが返されます。

ObjectId                             Name                                                     TargetObjects
--------                             ----                                                     -------------
91ec8ae5-6813-4453-afd7-31680a484892 extension_0380f0f700c040b5aa577c9268940b53_MyNewProperty {User}

注意

新しいプロパティの Name は、プレースホルダーアプリケーション>の "Extension_" + <objectID + "_" + <新しいプロパティ>の名前から生成されます。その名前の実際の値は、作成するアプリケーションごとに異なります。 1 つのプロパティを複数のオブジェクト型に割り当てることができます。この例で使用している TargetObject は 1 つ ("User") だけですが、"User" と "Group" を指定することも可能です。その場合、ユーザーオブジェクトとグループオブジェクトの両方に拡張属性オブジェクトが割り当てられます。

拡張プロパティの値を設定する

先ほどの例の拡張プロパティには値を代入することができます。

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

アプリケーションに対して定義されているすべての拡張属性を取得する

アプリケーションに対して定義されている一連の拡張属性を取得することができます。

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

このコマンドレットを実行すると、指定したアプリケーションの一連の拡張プロパティが返されます。

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

91ec8ae5-6813-4453-afd7-31680a484892 extension_0380f0f700c040b5aa577c9268940b53_MyNewProperty  {User}

拡張プロパティを削除する

不要になった拡張プロパティは削除することができます。

Remove-AzureADApplicationExtensionProperty -ObjectId (Get-AzureADApplication -SearchString "My Properties Bag").ObjectID -ExtensionPropertyId 91ec8ae5-6813-4453-afd7-31680a484892

注意

拡張後に Azure AD から属性を削除することも、PayOps チームに要求を発生させずにを Tenant Schema Extension App 削除することもできません。また、Azure AD ウィザードでディレクトリ拡張機能オプションをオフにしても、属性が削除されたり、アプリが削除されたりすることはありません。