Microsoft Graph PowerShell SDK を使用した Microsoft 365 のライセンス管理の方法

Microsoft Graph PowerShell SDK を使用した Microsoft 365 のライセンス管理の方法を紹介します。なお紹介する内容は以下の環境で動作確認をしています。

  • Microsoft Graph PowerShell SDK 1.6.1
  • Windows PowerShell 5.1
  • PowerShell 7.1.4

Microsoft Graph PowerShell SDK について

Microsoft Graph PowerShell SDK はオープン ソースで開発されている PowerShell Module で、Microsoft Graph を PowerShell から実行しやすくしたものです。プロジェクトは GitHub で管理されており、PowerShell Module は MIT ライセンスで配布されています。

microsoftgraph/msgraph-sdk-powershell: Powershell SDK for Microsoft Graph
https://github.com/microsoftgraph/msgraph-sdk-powershell

Microsoft Graph PowerShell SDK のインストール

以下のページに記載の手順で Microsoft Graph PowerShell SDK をインストールします。

Install the Microsoft Graph PowerShell SDK
https://docs.microsoft.com/en-us/graph/powershell/installation

たくさんの PowerShell Module がインストールされるためそれなりに時間がかかります。

認証

管理者の資格情報を使用する方法と、アプリケーションのアクセス許可を使用する方法があります。管理者自身が操作してライセンスの管理を行う場合は管理者の資格情報を使用する方法でよいでしょう。バッチ処理など、無人化や自動化を行う場合はアプリケーションのアクセス許可を使用します。

管理者の資格情報を使用する場合

以下のコマンドを実行して、サインインと、ライセンスの管理に必要なアクセス許可への同意を行います。テナントに紐づくライセンスの情報を確認するために Organization.Read.All のアクセス許可が必要です。またライセンスの付与などのために User.ReadWrite.All のアクセス許可が必要です。

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

認証画面がポップアップしますので、管理者アカウントでサインします。アクセス許可の同意を求められたら [承諾] をクリックします。[組織の代理として同意する] はオフのままで問題ありません。

アプリケーションのアクセス許可を使用する場合

基本的な内容は以下の技術情報に記載されています。

Use app-only authentication with the Microsoft Graph PowerShell SDK
https://docs.microsoft.com/en-us/graph/powershell/app-only?tabs=azure-portal

Azure AD へのアプリケーションの登録がまずは必要です。以下に手順を紹介します。

  1. Azure Portal にサインインします。
  2. [Azure Active Directory] – [アプリの登録] – [新規登録] をクリックします。
  3. [名前] に任意のアプリの名前を入力します。(例 : App01)
  4. [サポートされているアカウントの種類] から [この組織ディレクトリのみに含まれるアカウント] を選択します。
  5. [リダイレクト URI] で [Web] を選択し、テキスト ボックスは空欄のままにします。
  6. [登録] をクリックします。
  7. 表示された [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] の値を控えておきます。
  8. [管理] – [API のアクセス許可] – [アクセス許可の追加] をクリックします。
  9. [Microsoft Graph] – [アプリケーションの許可] をクリックし、[Organization.Read.All] と [User.ReadWrite.All] を選択して [アクセス許可の追加] をクリックします。
  10. [構成されたアクセス許可] の中の [種類] が [委任済み] である [User.Read] の右側の [・・・] をクリックし、[アクセス許可の削除] をクリックします。確認が表示されるので [はい、削除します] をクリックします。
  11. [<テナント名> に管理者の同意を与えます] をクリックします。確認が表示されるので [はい] をクリックします。

次に証明書を発行します。

  1. Windows PowerShell を起動します。
  2. 以下のようにコマンドを実行します。証明書が発行され、cer ファイルと pfx ファイルが出力され、コンソール上に証明書の Thumbprint が表示されます。
$mycert = New-SelfSignedCertificate -Subject "<アプリの名前>" -CertStoreLocation "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
$mycert | Export-Certificate -FilePath <エクスポート先のファイル名>
$mycert | Export-PfxCertificate -FilePath <エクスポート先のファイル名> -Password $(ConvertTo-SecureString -String "<エクスポートした PFX ファイルを保護する任意のパスワード>" -Force -AsPlainText)
$mycert | Select Thumbprint

実行例)

$mycert = New-SelfSignedCertificate -Subject "App01" -CertStoreLocation "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
$mycert | Export-Certificate -FilePath c:\temp\mycert.cer
$mycert | Export-PfxCertificate -FilePath c:\temp\mycert.pfx -Password $(ConvertTo-SecureString -String "1234" -Force -AsPlainText)
$mycert | Select Thumbprint
  1. Azure Portal で先ほど登録したアプリのページに戻ります。
  2. [管理] – [証明書とシークレット] をクリックします。
  3. [証明書のアップロード] をクリックします。
  4. 先ほど出力された CERファイルを選択して [追加] をクリックします。

以上で準備は完了です。

証明書の拇印を指定して証明書ストアから読み込んで接続するには以下のようにコマンドを実行します。

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

実行例)

Connect-MgGraph -ClientId "b502ac25-c0b0-4436-bd12-fdb79ece2341" -TenantId "7d046331-5ea5-4306-87ae-8d51f3dcc71e" -CertificateThumbprint "C1BF2E11A13E4F898627AFAA7FF848A63AD2D68E"

X509Certificate2 オブジェクトを指定して接続するには以下のようにコマンドを実行します。この例では証明書ストアから証明書を読み込んでいます。

Connect-MgGraph -ClientId "<登録したアプリのアプリケーション (クライアント) ID>" -TenantId "<アプリを登録したテナントのディレクトリ (テナント) ID>" -Certificate:(Get-ChildItem -Path Cert:\CurrentUser\My\<証明書の拇印>)

実行例)

Connect-MgGraph -ClientId "b502ac25-c0b0-4436-bd12-fdb79ece2341" -TenantId "7d046331-5ea5-4306-87ae-8d51f3dcc71e" -Certificate:(Get-ChildItem -Path Cert:\CurrentUser\My\C1BF2E11A13E4F898627AFAA7FF848A63AD2D68E)

証明書の名前を指定して証明書ストアから読み込んで接続するには以下のようにコマンドを実行します。

Connect-MgGraph -ClientId "<登録したアプリのアプリケーション (クライアント) ID>" -TenantId "<アプリを登録したテナントのディレクトリ (テナント) ID>" -CertificateName "CN=<証明書のサブジェクト名>"

実行例)

Connect-MgGraph -ClientId "b502ac25-c0b0-4436-bd12-fdb79ece2341" -TenantId "7d046331-5ea5-4306-87ae-8d51f3dcc71e" -CertificateName "CN=App01"

ライセンス情報の確認

テナントに紐づくライセンスの情報を確認します。以下のコマンドを実行します。

Get-MgSubscribedSku | ft Id, SkuId, SkuPartNumber

ライセンスの付与の際には SkuId の値を使用します。そのため、どの SkuId がこれから管理したいライセンスなのかを判別する必要があります。SkuPartNumber の値から推測できるものもありますが、詳細は以下の技術情報に記載されていますのでそちらをご参照ください。例えば Microsoft 365 E5 の SkuPartNumber は SPE_E5 で SkuId は 06ebc4ee-1bb5-47dd-8120-11324bc54e06 です。

Product names and service plan identifiers for licensing
https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/licensing-service-plan-reference

さらにライセンスの中の一部のサービス プランを無効にしたいというシナリオの場合、サービス プランの情報も確認しておく必要があります。その場合は以下のようにコマンドを実行します。

Get-MgSubscribedSku -SubscribedSkuId "<Get-MgSubscribedSku コマンドで確認した、サービス プランを確認したいライセンスの Id>" | Select-Object -ExpandProperty ServicePlans | ft ServicePlanId, ServicePlanName

実行例)

Get-MgSubscribedSku -SubscribedSkuId "7d046331-5ea5-4306-87ae-8d51f3dcc71e_06ebc4ee-1bb5-47dd-8120-11324bc54e06" | Select-Object -ExpandProperty ServicePlans | ft ServicePlanId, ServicePlanName

サービス プランの情報も上記の技術情報に記載されています。例えば Exchange Online Plan 2 の ServicePlanName は EXCHANGE_S_ENTERPRISE で ServicePlanId は efb87545-963c-4e0d-99df-69c6916d9eb0 です。

ユーザーの UsageLocation の設定

ライセンスを割り当てるユーザーは、事前に UsageLocation が設定されている必要があります。設定されていない場合にはライセンス割り当てに失敗します。そのため、はじめてライセンス割り当てを行うユーザーの場合は、事前に以下のようなコマンドで UsageLocation を設定します。この例ではユーザーの UsageLocation を ”JP” に設定します。

Update-MgUser -UserId <対象ユーザーの UPN> -UsageLocation "<ユーザーの場所>"

実行例)

Update-MgUser -UserId TestGraphUser01@contoso.onmicrosoft.com -UsageLocation "JP"

なお現在の UsageLocation の値は以下のコマンドで確認できます。

Get-MgUser -UserId <対象ユーザーの UPN> -Property UsageLocation | fl UsageLocation

実行例)

Get-MgUser -UserId TestGraphUser01@contoso.onmicrosoft.com -Property UsageLocation | fl UsageLocation

シナリオ 1 : ユーザーにライセンスを割り当てる

ユーザーにライセンスを割り当てます。まだライセンスが何も割り当てられていない場合であっても、既に割り当てられており追加する場合でも、どちらも手順は同じです。

すべてのサービス プランを有効にして特定のライセンスを割り当てる

割り当てるライセンスの SkuId を指定した MicrosoftGraphAssignedLicense オブジェクトを作成し、Set-MgUserLicense コマンドの AddLicenses パラメーターに配列として指定します。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<割り当てるライセンスの SkuId>"}
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses @($License1) -RemoveLicenses @()

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @($License1) -RemoveLicenses @()

すべてのサービス プランを有効にして複数のライセンスを割り当てる

複数のライセンスを割り当てる場合はそれぞれの MicrosoftGraphAssignedLicense オブジェクトを作成し、Set-MgUserLicense コマンドの AddLicenses パラメーターにカンマ区切りで指定します。以下の例では 2 つのライセンスを割り当てます。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<割り当てるライセンスの SkuId (1 つ目)>"}
$License2 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<割り当てるライセンスの SkuId (2 つ目)>"}
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses @($License1, $License2) -RemoveLicenses @()

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"}
$License2 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "84a661c4-e949-4bd2-a560-ed7766fcaf2b"}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @($License1, $License2) -RemoveLicenses @()

特定のサービス プランを無効にして特定のライセンスを割り当てる

ライセンス割り当て時に無効にするサービス プランがある場合は DisablePlans に ServicePlanId を配列として指定します。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<割り当てるライセンスの SkuId>"; DisabledPlans = @("<無効にするサービス プランの ServicePlanId>")}
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses @($License1) -RemoveLicenses @()

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"; DisabledPlans = @("b21a6b06-1988-436e-a07b-51ec6d9f52ad")}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @($License1) -RemoveLicenses @()

複数のサービス プランを無効にして特定のライセンスを割り当てる

無効にするサービス プランが複数ある場合は DisablePlans に ServicePlanId をカンマ区切りで指定します。以下の例では 2 つのサービス プランを無効にしてライセンスを割り当てます。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<割り当てるライセンスの SkuId>"; DisabledPlans = @("<無効にするサービス プランの ServicePlanId (1 つ目)>", "<無効にするサービス プランの ServicePlanId (2 つ目)>")}
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses @($License1) -RemoveLicenses @()

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"; DisabledPlans = @("b21a6b06-1988-436e-a07b-51ec6d9f52ad", "0898bdbb-73b0-471a-81e5-20f1fe4dd66e")}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @($License1) -RemoveLicenses @()

シナリオ 2 : ユーザーからライセンスを削除する

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

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

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

実行例)

Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @() -RemoveLicenses @("06ebc4ee-1bb5-47dd-8120-11324bc54e06")

特定のユーザーに対して、複数ライセンスを削除する

ユーザーから複数のライセンスを削除するには、Set-MgUserLicense コマンドの RemoveLicenses パラメーターの配列に、削除したいライセンスの SkuId をカンマ区切りで指定します。以下の例ではユーザーから 2 つのライセンスを削除します。

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

実行例)

Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @() -RemoveLicenses @("06ebc4ee-1bb5-47dd-8120-11324bc54e06", "84a661c4-e949-4bd2-a560-ed7766fcaf2b")

シナリオ 3. 割り当て済みライセンスの無効にするサービス プランを変更する

ライセンスを割り当てる場合と同じ方法で、DisabledPlans の内容を変更してコマンドを実行することにより、無効にするサービス プランを変更することができます。上書きになるので、元々無効だったサービス プランを引き続き無効にしたいのであれば DisabledPlans に改めて指定する必要があります。

割り当て済みライセンスの無効にするサービス プランを変更する

以下の例では、割り当て済みのライセンスに関して指定した 2 つのサービス プランだけを無効にします。指定していないサービス プランは有効になります。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<無効にするサービス プランを変更する割り当て済みライセンスの SkuId>"; DisabledPlans = @("<無効にするサービス プランの ServicePlanId (1 つ目)>", "<無効にするサービス プランの ServicePlanId (1 つ目)>")}
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses $License1 -RemoveLicenses @()

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"; DisabledPlans = @("b21a6b06-1988-436e-a07b-51ec6d9f52ad", "0898bdbb-73b0-471a-81e5-20f1fe4dd66e")}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses $License1 -RemoveLicenses @()

割り当て済みライセンスの無効にしているサービス プランをすべて有効にする

割り当て済みライセンスの無効にしているサービス プランをすべて有効にするには、DisabledPlans に何も指定をせずにコマンドを実行します。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<すべてのサービス プランを有効にする割り当て済みライセンスの SkuId>"; DisabledPlans = @()}
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses $License1 -RemoveLicenses @()

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"; DisabledPlans = @()}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses $License1 -RemoveLicenses @()

すでに一部のサービス プランを無効にしているライセンスに対して、追加で特定のサービス プランを無効にする

すでに一部のサービス プランを無効にしているライセンスに対して、追加で特定のサービス プランを無効にする場合、現在の DisablePlans の内容を取得した上で追加を行います。

$License1 = Get-MgUser -UserId <対象ユーザーの UPN> -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses | ?{$_.SkuId -eq "<対象の割り当て済みライセンスの SkuId>"}
$License1.DisabledPlans += "<追加で無効にするサービス プランの ServicePlanId>"
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses $License1 -RemoveLicenses @()

実行例)

$License1 = Get-MgUser -UserId TestGraphUser01@contoso.onmicrosoft.com -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses | ?{$_.SkuId -eq "06ebc4ee-1bb5-47dd-8120-11324bc54e06"}
$License1.DisabledPlans += "b21a6b06-1988-436e-a07b-51ec6d9f52ad"
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses $License1 -RemoveLicenses @()

すでに 1 つ以上のサービス プランを無効にしているライセンスに対して、特定のサービス プランのみを無効から有効に変える

すでに 1 つ以上のサービス プランを無効にしているライセンスに対して、特定のサービス プランのみを無効から有効に変える現在の DisablePlans の内容を取得した上で有効にするサービス プランを取り除きます。

$License1 = Get-MgUser -UserId <対象ユーザーの UPN> -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses | ?{$_.SkuId -eq "<対象の割り当て済みライセンスの SkuId>"}
$License1.DisabledPlans = @($License1.DisabledPlans | ?{$_ -ne "<向こうから有効に変えるサービス プランの ServicePlanId>"})
Set-MgUserLicense -UserId <対象ユーザーの UPN> -AddLicenses $License1 -RemoveLicenses @()

実行例)

$License1 = Get-MgUser -UserId TestGraphUser01@contoso.onmicrosoft.com -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses | ?{$_.SkuId -eq "06ebc4ee-1bb5-47dd-8120-11324bc54e06"}
$License1.DisabledPlans = @($License1.DisabledPlans | ?{$_ -ne "b21a6b06-1988-436e-a07b-51ec6d9f52ad"})
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses $License1 -RemoveLicenses @()

シナリオ 4 : ライセンスを変更する

現在割り当て済みのライセンスを削除して別のライセンスを割り当てるには、現在割り当て済みのライセンスは RemoveLicenses に指定し、新しく割り当てるライセンスを AddLicenses に指定します。

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "<新しく割り当てるライセンスの SkuId>"}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @($License1) -RemoveLicenses @("<現在割り当て済みのライセンス>")

実行例)

$License1 = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignedLicense -Property @{SkuId = "06ebc4ee-1bb5-47dd-8120-11324bc54e06"}
Set-MgUserLicense -UserId TestGraphUser01@contoso.onmicrosoft.com -AddLicenses @($License1) -RemoveLicenses @("6fd2c87f-b296-42f0-b197-1e91e994b900")

参考: ユーザーに割り当て済みのライセンスを確認する

ユーザーに割り当てられているライセンスを確認するには、上記でも使用した Get-MgUser コマンドを使用する方法と、Get-MgUserLicenseDetail コマンドを使用する方法があります。

Get-MgUser コマンドを使用してユーザーに割り当てられているライセンスを確認する

Met-MgUser コマンドを使用することで、Set-MgUserLicense コマンドでも使用する MicrosoftGraphAssignedLicense の内容を確認することができます。

Get-MgUser -UserId <対象ユーザーの UPN> -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses

実行例)

Get-MgUser -UserId TestGraphUser01@contoso.onmicrosoft.com -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses

Get-MgUserLicenseDetail コマンドを使用してユーザーに割り当てられているライセンスを確認する

Get-MgUserLicenseDetail コマンドを使用することで、ユーザーに割り当てたライセンスやサービス プランのプロビジョニング状況を確認することができます。以下のように実行するとユーザーに割り当てたライセンスの情報を確認できます。

Get-MgUserLicenseDetail -UserId <対象ユーザーの UPN>

実行例)

Get-MgUserLicenseDetail -UserId TestGraphUser01@contoso.onmicrosoft.com

サービス プランの情報を確認するには以下のようにコマンドを実行します。

Get-MgUserLicenseDetail -UserId <対象ユーザーの UPN> | Select-Object -ExpandProperty ServicePlans

実行例)

Get-MgUserLicenseDetail -UserId TestGraphUser01@contoso.onmicrosoft.com | Select-Object -ExpandProperty ServicePlans

切断

以下のコマンドを実行して、Microsoft Graph PowerShell SDK から切断します。

Disconnect-MgGraph