Microsoft Graph とアプリ専用認証を使用して PowerShell スクリプトを構築する

このチュートリアルでは、Microsoft Graph API を使用してアプリ専用認証を使用してデータにアクセスする PowerShell スクリプトを構築する方法について説明します。アプリのみの認証は、組織内のすべてのユーザーのデータにアクセスする必要があるバックグラウンドサービスまたはアプリケーションに適しています。

注:

Microsoft Graph を使用してユーザーの代わりにデータにアクセスする方法については、このユーザー (委任された) 認証チュートリアルを参照してください。

このチュートリアルの内容:

List users

ヒント

このチュートリアルに従う代わりに、 GitHub リポジトリをダウンロードまたは複製し、README の指示に従ってアプリケーションを登録し、プロジェクトを構成できます。

前提条件

このチュートリアルを開始する前に、開発用コンピューターに PowerShell がインストールされている必要があります。 PowerShell 5.1 が最小要件ですが、PowerShell 7 をお勧めします。

また、グローバル管理者ロールを持つ Microsoft の職場または学校アカウントも必要です。 Microsoft 365 テナントをお持ちでない場合は、 Microsoft 365 開発者プログラムを通じてテナントの資格を得る可能性があります。詳細については、 FAQ を参照してください。または、 1 か月間の無料試用版にサインアップするか、Microsoft 365 プランを購入することもできます。

注:

このチュートリアルは、PowerShell 7.2.2 および Microsoft Graph PowerShell SDK バージョン 1.9.5 で記述されています。このガイドの手順は、他のバージョンで動作する可能性がありますが、テストされていません。

ポータルでアプリを登録する

残り 15 分

この演習では、Microsoft Entra に新しいアプリケーションを登録して、アプリのみの認証を有効にします。

自己署名証明書を作成する

Microsoft Graph PowerShell SDK には、アプリ専用認証用の証明書が必要です。開発目的では、自己署名証明書で十分です。ローカルコンピューターに秘密キーがインストールされている証明書と、にエクスポートされた公開キーが必要です。CER、。PEM、または。CRT ファイル。

Windows
Linux/MacOS

Windows では、 pki PowerShell モジュールを使用して証明書を生成できます。

$cert = New-SelfSignedCertificate -Subject "CN=PowerShell App-Only" -CertStoreLocation `
  "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 `
  -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "./PowerShellAppOnly.cer"

Linux または MacOS では、 OpenSSL を使用して秘密キーと公開キーを生成し、PowerShell を使用して PowerShell で読み取り可能な証明書ストアに秘密キーをインストールできます。

次のコマンドを使用して、新しい X509 証明書を生成します。

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -keyout powershell.pem -out powershell.crt -subj "/CN=PowerShell App-Only"

OpenSSL では、PEM パスフレーズの入力を求められます。覚えているパスフレーズを入力します。

次のコマンドを使用して PFX ファイルを作成します。

openssl pkcs12 -export -out powershell.pfx -inkey powershell.pem -in powershell.crt

OpenSSL では、 powershell.pem のパスフレーズの入力を求められます。前の手順で使用したパスフレーズを入力します。
OpenSSL では、エクスポートパスワードの入力を求められます。覚えているパスワードを入力します。

PowerShell を開き、次のコマンドを実行し、<export-password>を前の手順で使用したエクスポートパスワードに置き換えます。

using namespace System.Security.Cryptography.X509Certificates
$store = [X509Store]::new('My', 'CurrentUser', 'ReadWrite')
$store.Add([X509Certificate2]::new('./powershell.pfx', '<export-password>', [X509KeyStorageFlags]::PersistKeyS
et))
$store.Dispose()

アプリケーションをアプリ専用認証に登録する

このセクションでは、クライアント資格情報フローを使用してアプリのみの認証をサポートするアプリケーションを登録します。

ブラウザーを開き、 Microsoft Entra 管理センターに移動し、グローバル管理者アカウントを使用してログインします。
左側のナビゲーションで [Microsoft Entra ID] を 選択し、[ ID] を展開し、[ アプリケーション] を展開して、[ アプリの登録] を選択します。
[新規登録] を選択します。アプリケーションの名前 (例: Graph App-Only Auth Tutorial) を入力します。
[ サポートされているアカウントの種類 ] を [この組織のディレクトリ内のアカウントのみ] に設定します。
[リダイレクト URI]を空のままにします。
[登録] を選択します。アプリケーションの [概要 ] ページで、 アプリケーション (クライアント) ID と ディレクトリ (テナント) ID の値をコピーして保存します。次の手順でこれらの値が必要になります。
[管理] で、[API のアクセス許可] を選択します。
行で省略記号 (...) を選択し、[アクセス許可の削除] を選択して、[構成されたアクセス許可] の下にある既定の User.Readアクセス許可を削除します。
[ アクセス許可の追加] を選択し、[ Microsoft Graph] を選択します。
[アプリケーションのアクセス許可] を選択します。
[ User.Read.All] を選択し、[ アクセス許可の追加] を選択します。
[ 管理者の同意を付与する] を選択し、[ はい ] を選択して、選択したアクセス許可に対して管理者の同意を提供します。
[管理] で [証明書とシークレット] を選択し、[証明書] を選択します。
[ 証明書のアップロード] を選択します。前の手順で作成した PowerShellAppOnly.cer または powershell.crt ファイルをアップロードし、[ 追加] を選択します。

注:

ユーザー認証に登録する手順とは異なり、このセクションではアプリの登録に対する Microsoft Graph のアクセス許可を構成したことに注意してください。これは、アプリのみの認証でクライアント資格情報フローが使用されるため、アプリの登録でアクセス許可を構成する必要があるためです。詳細については、「.default スコープ」を参照してください。

アプリ専用認証を追加する

残り 10 分

このセクションでは、Microsoft Graph PowerShell SDK でアプリのみの認証を使用します。

アプリ専用認証で接続する

次のコマンドを使用して、既存の Microsoft Graph 接続を切断します。
```
Disconnect-MgGraph
```
PowerShell を開き、次のコマンドを使用して $clientID セッション変数を設定し、 <our-client-id> をアプリ登録のクライアント ID に置き換えます。
```
$clientId = <your-client-id>
```
$tenantId セッション変数を設定し、<our-tenant-id>を組織のテナント ID に置き換えます。
```
$tenantId = <your-tenant-id>
```
$certificate セッション変数を、前の手順で作成した証明書のサブジェクトに設定します。
```
$certificate = "CN=PowerShell App-Only"
```
前の手順の証明書を使用して認証するには、 Connect-MgGraph コマンドを使用します。
```
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateName $certificate
```

Get-MgContextを使用して、アプリのみの認証で認証されていることを確認します。 AuthType がAppOnlyされていることを確認します。

PS > Get-MgContext

ClientId              : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
TenantId              : 601faea3-be45-4960-898f-92b379b17cd9
CertificateThumbprint :
Scopes                : {User.Read.All}
AuthType              : AppOnly
AuthProviderType      : ClientCredentialProvider
CertificateName       : CN=PowerShell App-Only
Account               :
AppName               : PowerShell Graph Tutorial
ContextScope          : Process
Certificate           :
PSHostVersion         : 2022.4.1
ClientTimeout         : 00:05:00

ユーザーを一覧表示する

残り 8 分

このセクションでは、アプリのみの認証を使用して、Azure Active Directory 内のすべてのユーザーを一覧表示します。

認証された PowerShell セッションで、次のコマンドを実行してユーザーを一覧表示します。
```
Get-MgUser -Select "displayName,id,mail" -Top 25 -OrderBy "displayName"
```

出力を確認します。

Id                                   DisplayName              Mail                  UserPrincipalName UserType
--                                   -----------              ----                  ----------------- --------
05fb57bf-2653-4396-846d-2f210a91d9cf Adele Vance              AdeleV@contoso.com
a36fe267-a437-4d24-b39e-7344774d606c Alex Wilber              AlexW@contoso.com
54cebbaa-2c56-47ec-b878-c8ff309746b0 Allan Deyoung            AllanD@contoso.com
9cb2ad7c-8e69-46a6-a947-a02c255048de Automate Bot
9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Bianca Pisani
a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Brian Johnson (TAILSPIN) BrianJ@contoso.com
9e2d4937-44ee-4af4-bd56-77a12cc3ecc4 Cameron White
8990227d-31dc-4120-a38e-f652576974f4 Christie Cline           ChristieC@contoso.com
...

コードの説明

ユーザーの一覧表示に使用するコマンドを検討してください。

-Selectを使用して特定のプロパティを要求します
-Topを使用して、返されるユーザーの数を制限します
-OrderByを使用して応答を並べ替える

省略可能: 独自のコードを追加する

残り 5 分

このセクションでは、独自の Microsoft Graph PowerShell SDK コマンドを使用します。これは、Microsoft Graph ドキュメントまたは Graph エクスプローラーのコードスニペット、または作成したコードです。このセクションは省略可能です。

API を選択する

試したい API を Microsoft Graph で見つけます。たとえば、 List グループ API などです。 API ドキュメントの例のいずれかを使用するか、Graph Explorer で API 要求をカスタマイズし、生成されたスニペットを使用するか、 Find-MgGraphCommand コマンドを使用して対応するコマンドを見つけることができます。

たとえば、グループを一覧表示する API エンドポイントは GET /groups。これを使用して、対応する PowerShell コマンドを見つけることができます。

PS > Find-MgGraphCommand -Uri "/groups" -Method "GET"

   APIVersion: v1.0

Command     Module Method URI     OutputType           Permissions
-------     ------ ------ ---     ----------           -----------
Get-MgGroup Groups GET    /groups IMicrosoftGraphGroup {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, G…

   APIVersion: beta

Command     Module Method URI     OutputType            Permissions
-------     ------ ------ ---     ----------            -----------
Get-MgGroup Groups GET    /groups IMicrosoftGraphGroup1 {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, …

出力は、 Get-MgGroup コマンドが対応するコマンドであることを示します。

アクセス許可を構成する

選択した API のリファレンスドキュメントの [アクセス許可] セクションを確認して、サポートされている認証方法を確認します。たとえば、一部の API ではアプリ専用がサポートされていません。

アプリ専用認証を使用して API を呼び出すには (API でサポートされている場合)、Azure AD 管理センターに必要なアクセス許可スコープを追加します。必ず、アプリのみのアクセス許可を使用して切断して再接続してください。

ヒント

Connect-MgGraph コマンドで -ForceRefresh パラメーターを使用すると、新しく構成されたアクセス許可が確実に適用されます。

コマンドを実行する

必要なアクセス許可に接続したら、選択したコマンドを実行します。

おめでとうございます。

100% 完了しました

PowerShell Microsoft Graph アプリ専用チュートリアルを完了しました。 Microsoft Graph を呼び出す作業アプリが作成されたので、新しい機能を試して追加できます。

Microsoft Graph PowerShell SDK でユーザー (委任された) 認証を使用する方法について説明します。
Microsoft Graph でアクセスできるすべてのデータについては、 Microsoft Graph の概要に関するページを参照してください。

次の方法で共有