Microsoft Graph PowerShell でライセンス操作

◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください

【4/18開催】VSCode Dev Containersで楽々開発環境構築祭り〜Python/Reactなどなど〜
Visual Studio Codeの拡張機能であるDev Containersを使ってReactとかPythonとかSpring Bootとかの開発環境をラクチンで構築する方法を紹介するイベントです。
https://tech-lab.connpass.com/event/311864/

こんにちは。サイオステクノロジーの木村です。

こちらの記事によると、ライセンス割り当てAPIの廃止に伴い、2022年6月30日以降、MSOnline Powershell のライセンスを操作する以下のコマンドが使えなくなるようです。

Set-MsolUserLicense
New-MsolUser (-LicenseAssignment または -LicenseOptions を指定する場合)

そのため、これらコマンドを使用してスクリプトなどでライセンス操作を行なっている場合、修正する必要があります。

これらコマンドの代わりに今後は、Microsoft Graph PowerShell SDKの Set-MgUserLicense コマンドを使用してライセンス操作をすることが推奨されています。

そこで今回は、Microsoft Graph PowerShell を使用してライセンス操作を行う方法について記載します。

尚、Microsoft Graph PowerShell SDK で「ユーザーの作成」を行う方法について記載した記事もありますので併せてご覧ください。
『Microsoft Graph PowerShell でユーザー作成（MSOnline との比較）』

1 Microsoft Graph PowerShell とは
2 Microsoft Graph PowerShellモジュールのインストール
3 Microsoft Graphへの接続（管理者の資格情報を使用）
4 Microsoft Graphへの接続（サービスプリンシパルを使用）
5 ライセンス情報の取得
6 ライセンス操作
7 Microsoft Graphからの切断
8 その他（ユーザー作成と同時にライセンス付与できる？）

Microsoft Graph PowerShell とは

Microsoft Graph PowerShell は、Microsoft Graph APIのAPIラッパーとして機能し、PowerShellコマンドの実行にてMicrosoft Graph API を呼び出せるようにしたPowerShellモジュールです。
公式ドキュメントはこちら

Microsoft Graph PowerShellモジュールのインストール

PowerShellを管理者で起動し、以下のコマンドを実行してインストールします。


 Install-Module Microsoft.Graph

Microsoft Graphへの接続（管理者の資格情報を使用）

管理者の資格情報をもとにMicrosoft Graphへ接続する手順は以下になります。

1. PowerShellを起動し、以下のコマンドを実行します。
（パラメータ Scopes には、テナントに紐づくライセンス情報を取得するために、Organization.Read.All のアクセス許可を指定します。また、ユーザーのライセンス情報取得・付与などを行うために、User.ReadWrite.All　のアクセス許可を指定します。）


 Connect-MgGraph -Scopes "Organization.Read.All","User.ReadWrite.All"

2. サインイン画面が表示されますので、管理者のユーザー名とパスワードを入力し、「サインイン」をクリックします。

3. 「承諾」をクリックします。

4. 認証情報を正しく入力しサインインすると接続が完了します。「Get-MgSubscribedSku」などのコマンドを実行すると、実行でき、接続されていることが確認できます。

5. ライセンスの操作を行う場合は、以下のコマンドを実行しモジュールのインポートを行います。


 Import-Module -Name Microsoft.Graph.Users

Microsoft Graphへの接続（サービスプリンシパルを使用）

サインイン画面を表示し、管理者の資格情報を入力する方法ですと、画面にアカウント名・パスワードを手入力しなければならず、スクリプトなどで自動で接続を行うことはできません。
以下に記載するサービスプリンシパルを使用する方法では、画面にアカウント名・パスワードを手入力する必要がなく、スクリプトなどで自動で接続することができます。
サービスプリンシパルを使用する方法では、証明書を発行したアプリケーションにアクセス許可を付与し、アプリケーション経由で認証および操作を行います。

アプリケーションの登録

アプリケーションをAzureADに登録します。以下の手順で行います。

1. 管理者でAzureポータル（https://portal.azure.com/）にログインします。

2. メニューより「Azure Active Directory」をクリックします。

3. 「アプリの登録」をクリックし「＋新規登録」をクリックします。

4. アプリケーションの登録ページで、以下を入力し「登録」をクリックします。

名前：任意の名称
サポートされているアカウントの種類：この組織ディレクトリのみに含まれるアカウント
リダイレクトURI（省略可能）：Web、テキストボックスは空欄

5. 表示された [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] の値をメモしておきます。

6. 「API のアクセス許可」をクリックし、「+アクセス許可の追加」をクリックします。

7. 「Microsoft Graph」をクリックします。

8. 「アプリケーションの許可」をクリックし、[Organization.Read.All] と [User.ReadWrite.All] を選択して [アクセス許可の追加] をクリックします。

9. <テナント名>に管理者の同意を与えます」をクリックします。

10. 「はい」をクリックします。

11. 状態が「<テナント名＞に付与されました」と表示されれば、アプリケーションの登録は完了です。

12. アプリケーションに登録する証明書を用意し、GraphPowerShellに接続する環境にインストールします。
自己証明書を使用する場合は、PowerShell にて、以下のコマンドで自己証明書の作成とインストールができます。


 #証明書の作成
 $mycert = New-SelfSignedCertificate -Subject "<証明書のSubject>" `
   -CertStoreLocation "<証明書ストア>" -NotAfter <有効期限> `
   -KeyExportPolicy Exportable -KeySpec Signature

 #エクスポート（CERファイル）
 $mycert | Export-Certificate -FilePath <CERファイル名>

 #作成した証明書の拇印
 $mycert | Select Thumbprint

例


 #証明書の作成
 $mycert = New-SelfSignedCertificate -Subject "TestApp01" `
   -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) `
   -KeyExportPolicy Exportable -KeySpec Signature

 #エクスポート（CERファイル）
 $mycert | Export-Certificate -FilePath ".\mycert1.cer"

 #作成した証明書の拇印
 $mycert | Select Thumbprint

13. 先の手順で登録したアプリケーションのページにて、「証明書とシークレット」をクリックし、「証明書のアップロード」をクリックします。

14. 登録したい証明書を指定し、「追加」をクリックします。

15. アプリケーションに証明書が追加されます。

Microsoft Graphへの接続

PowerShellを起動し、以下のコマンドを実行して接続します。
接続後、ライセンス操作に必要なモジュールをインポートします。


 Connect-MgGraph -Clientid "<登録したアプリのアプリケーション (クライアント) ID>" `
   -TenantId "<アプリを登録したテナントのディレクトリ (テナント) ID>"  `
   -CertificateThumbprint "<証明書の拇印>"

 #必要なモジュールのインポート
 Import-Module -Name Microsoft.Graph.Users

例


 Connect-MgGraph -Clientid "78ff1c4a-xxxx-0000-xxxx-179f8f1a8013" `
   -TenantId "30377ae5-xxxx-0000-xxxx-4569432250b1" `
   -CertificateThumbprint "1606C825A0000EE0Exxxxxx81462AD8D80xxxxxx"

 #必要なモジュールのインポート
 Import-Module -Name Microsoft.Graph.Users

ライセンス情報の取得

ユーザーへのライセンス付与や削除を行う際は、ライセンスの SkuId や ServicePlanId を使用します。（SkuIdやサービスプランの詳細についてはこちらの公開情報をご参照ください。）
以下に、それらライセンス情報の取得方法を記載します。

テナントに紐づくライセンス情報の取得

テナントに紐づくライセンス情報は以下のコマンドで取得できます。

コマンド：Get-MgSubscribedSku

例：ライセンスのSkuIdの確認


 Get-MgSubscribedSku | fl Id, SkuId, SkuPartNumber

例：ライセンスに紐づくServicePlanIdの確認


 Get-MgSubscribedSku -SubscribedSkuId <ServicePlanIdを確認したいライセンスのId> |  `
  %{$_.ServicePlans} | ft ServicePlanId, ServicePlanName

ユーザーに付与されているライセンス情報の取得

ユーザーに付与されているライセンス情報は以下のコマンドで取得できます。

コマンド：Get-MgUser
コマンド：Get-MgUserLicenseDetail

例：Get-MgUser コマンドで、付与されているライセンスのSkuId, 無効にされているサービスプランを確認


 Get-MgUser -UserId <ユーザーのUPN> -Property AssignedLicenses | `
  Select-Object -ExpandProperty AssignedLicenses | ft SkuId, DisabledPlans

例：Get-MgUserLicenseDetail コマンドで、付与されているライセンスのサービスプランなどを確認


 Get-MgUserLicenseDetail -UserId <ユーザーのUPN> | fl

ライセンス操作

ユーザーのライセンスの操作を行うには以下のコマンドを使用します。

コマンド：Set-MgUserLicense

ユーザーにライセンスを付与する

MicrosoftGraphAssignedLicense オブジェクトを作成し、
SkuIdに付与するライセンスの SkuId を、
DisabledPlansにそのSkuIdで無効にするサービスプランの ServicePlanId を指定します。
それを Set-MgUserLicense コマンドの AddLicenses パラメーターに配列として指定すると、ユーザーにライセンスを付与することができます。
DisabledPlansに何も指定しない場合は、全てのサービスプランが有効になります。
複数のライセンスを割り当てる場合は、それぞれの MicrosoftGraphAssignedLicense オブジェクトを作成し、Set-MgUserLicense コマンドの AddLicenses パラメーターに、カンマ区切りで指定します。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "<付与するライセンスの SkuId>";
 $license.DisabledPlans = @("<無効にするサービス プランの ServicePlanId>");
 Set-MgUserLicense -UserId <ユーザーのUPN> -AddLicenses @($license) -RemoveLicenses @();

例1：ライセンスを付与し、全てのサービスプランを有効にする場合
以下の例では、Microsoft E3 ライセンスを付与します。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "05e9a617-0261-4cee-bb44-138d3ef5d965";
 Set-MgUserLicense -UserId test@example.onmicrosoft.com -AddLicenses @($license) -RemoveLicenses @();

例2：ライセンスを付与し、特定のサービスプランを無効にする場合
以下の例では、Microsoft E3 ライセンスを付与し、Sway と　Yammer Enterprise を無効にします。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "05e9a617-0261-4cee-bb44-138d3ef5d965";
 $license.DisabledPlans = @("a23b959c-7ce8-4e57-9140-b90eb88a9e97", "7547a3fe-08ee-4ccb-b430-5077c5041653");
 Set-MgUserLicense -UserId test@example.onmicrosoft.com -AddLicenses @($license) -RemoveLicenses @();

例3：複数のライセンスを付与する場合
以下の例では、Microsoft E3 ライセンスと、 Power BI Free ライセンスを付与します。Microsoft E3 ライセンスは、Swayを無効にします。


 # Microsoft E3 ライセンス
 $license1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license1.SkuId = "05e9a617-0261-4cee-bb44-138d3ef5d965";
 $license1.DisabledPlans = @("a23b959c-7ce8-4e57-9140-b90eb88a9e97");

 # Power BI (free) ライセンス
 $license2 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license2.SkuId = "a403ebcc-fae0-4ca2-8c8c-7a907fd6c235";

 Set-MgUserLicense -UserId test@example.onmicrosoft.com -AddLicenses @($license1, $license2) -RemoveLicenses @();

ユーザーからライセンスを削除する

Set-MgUserLicense コマンドの RemoveLicenses パラメーターに削除したいライセンスの SkuId を配列として指定すると、指定したライセンスをユーザーから削除することができます。


 Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses @() -RemoveLicenses @("<削除するライセンスの SkuId>")

例1：１つのライセンスを削除する場合


 Set-MgUserLicense -UserId test@example.onmicrosoft.com `
  -AddLicenses @() -RemoveLicenses @("05e9a617-0261-4cee-bb44-138d3ef5d965");

例2：複数のライセンスを削除する場合
複数削除する場合は、カンマ区切りで指定します。


 Set-MgUserLicense -UserId test@example.onmicrosoft.com `
  -AddLicenses @() -RemoveLicenses `
  @("05e9a617-0261-4cee-bb44-138d3ef5d965", "a403ebcc-fae0-4ca2-8c8c-7a907fd6c235");

ユーザーのライセンスを変更する

ユーザーのライセンスを変更する（現在付与されているライセンスを削除し、別のライセンスを付与する）には、削除するライセンスをRemoveLicenses に指定し、新しく付与するライセンスを AddLicenses に指定します。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "<新しく割り当てるライセンスの SkuId>";
 Set-MgUserLicense -UserId <ユーザーのUPN> -AddLicenses @($license) -RemoveLicenses @("<現在付与されているライセンスの SkuId >");

例
以下の例では、Microsoft E3 ライセンスを削除し、新しくProject Plan5 ライセンスを割り当てます。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "09015f9f-377f-4538-bbb5-f75ceb09358a";

 Set-MgUserLicense -UserId test@example.onmicrosoft.com -AddLicenses @($license) -RemoveLicenses @("05e9a617-0261-4cee-bb44-138d3ef5d965");

ユーザーに付与されているライセンスのサービスプランを変更する

ユーザーに付与されているライセンスのサービスプランを変更するには、ユーザーにライセンスを付与する時と同様、MicrosoftGraphAssignedLicense オブジェクトを作成し、
SkuIdにライセンスの SkuId を、
DisabledPlansにそのSkuIdで無効にするサービスプランの ServicePlanId を指定します。
それをSet-MgUserLicense コマンドの AddLicenses パラメーターに指定します。
DisabledPlansに指定されたサービスプラン以外は有効になります。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "<サービスプランを変更するライセンスの SkuId>";
 $license.DisabledPlans = @("<無効にするサービス プランの ServicePlanId>");
 Set-MgUserLicense -UserId <ユーザーのUPN> -AddLicenses @($license) -RemoveLicenses @();

例
以下の例では、既に付与されているMicrosoft E3 ライセンスについて、無効にするサービスプランをExchange Online と、Yammer Enterprise に変更します。


 $license = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense;
 $license.SkuId = "05e9a617-0261-4cee-bb44-138d3ef5d965";
 $license.DisabledPlans = @("efb87545-963c-4e0d-99df-69c6916d9eb0","7547a3fe-08ee-4ccb-b430-5077c5041653");
 Set-MgUserLicense -UserId test@example.onmicrosoft.com -AddLicenses @($license) -RemoveLicenses @();

Microsoft Graphからの切断

以下のコマンドを実行すると、接続を切断できます。


 Disconnect-MgGraph

その他（ユーザー作成と同時にライセンス付与できる？）

APIの廃止に伴い使用できなくなるコマンドは、以下の２つです。

Set-MsolUserLicense
New-MsolUser (-LicenseAssignment または -LicenseOptions を指定する場合)

これに対して代わりに推奨されているコマンドは Set-MgUserLicense のみです。
つまり、New-MsolUser を使用時は、ユーザー作成と同時にライセンスの付与ができていましたが、今後はユーザー作成と同時にライセンス付与ができず、ユーザー作成後に Set-MgUserLicense コマンドでライセンスを付与する形になります。
Microsoft Graph PowerShell SDK には、New-MsolUser のようにユーザー作成を行う New-MgUser コマンドがあります。そして、New-MgUser コマンドにはおそらくライセンスを付与するために使うであろうと思われる -AssignedLicenses パラメータがあるのですが、当記事の執筆時点では、このパラメータはread-onlyとなっており、機能が提供されていないようです。「-AssignedLicenses」パラメータの機能が提供されるようになれば、Microsoft Graph PowerShellでもユーザー作成と同時にライセンスが付与されるようになるかもしれません。機能が提供されることを期待します。
New-MgUser コマンドについての詳細はこちらの公式ドキュメントを参照して下さい。