マイクロソフトグラフに接続する際の重要な部分

ここまでで、Microsoft 365 ワークロードと対話するために PowerShell コードを記述するほとんどの人は、”純粋な” PowerShell コマンドレットの代わりに Microsoft Graph API クエリを使用する必要があることを理解しています。グラフクエリは、通常、数千の Microsoft 365 グループなど、大量のデータを取得する場合、より高速で信頼性が高くなります。ここ数年、人々が Microsoft Graph に慣れ親しむにつれて、コマンドレットをグラフ クエリに置き換えるスクリプトの数が増えました。これらのスクリプトはすべて Azure AD アクセス トークンを使用し、グラフ エクスプローラーなど、Microsoft Graph と対話するユーティリティも同様です (図 1)。

この記事の残りの部分では、Azure AD アクセス トークンに含まれる内容について説明します。

アクセストークンの必要性

グラフクエリは実行前に認証が必要であり、Graph API は先進認証を使用します。 Azure AD で登録されたアプリケーションは、PowerShell とグラフの間のギャップを埋めます。アプリには、アプリ名、その識別子、テナント識別子、一部の資格情報 (アプリ シークレットまたは証明書) など、認証時に使用される詳細が保持されます。このアプリは、グラフ API やその他の API を通じてデータにアクセスするためのアクセス許可も保持しています。認証の時期になると、アプリに属するサービス プリンシパルはこの情報を使用して、Azure AD にアクセス トークンを要求します。Azure AD がアクセス トークンを発行すると、要求が Invoke-RestMethod 又は 呼び出し – WebRequest コマンドレットには、アプリが情報にアクセスするアクセス許可を持っていることを証明できるアクセス トークンを含めることができます。

一見すると、Azure AD アクセス トークンは混乱した大量のテキストです。PowerShell がアクセス トークンの内容を報告する方法は次のとおりです。

eyJ0eXAiOiJKV1QiLCJub25jZSI6IlFQaVN1ck1VX3gtT2YzdzA1YV9XZzZzNFBZRFUwU2NneHlOeDE0eVctRWciLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1yNS1BVWliZkJpaTdOZDFqQmViYXhib1hXMCIsImtpZCI6Ik1yNS1BVWliZkJpaTdOZDFqQmViYXhib1hXMCJ9.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9iNjYyMzEzZi0xNGZjLTQzYTItOWE3YS1kMmUyN2Y0ZjM0NzgvIiwiaWF0IjoxNjQ0ODQ1MDc3LCJuYmYiOjE2NDQ4NDUwNzcsImV4cCI6MTY0NDg0ODk3NywiYWlvIjoiRTJaZ1lEaW1McEgwTSt5QTk5NmczbWZUUXlYN0FBPT0iLCJhcHBfZGlzcGxheW5hbWUiOiJHZXRUZWFtc0xpc3QiLCJhcHBpZCI6IjgyYTIzMzFhLTExYjItNDY3MC1iMDYxLTg3YTg2MDgxMjhhNiIsImFwcGlkYWNyIjoiMSIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0L2I2NjIzMTNmLTE0ZmMtNDNhMi05YTdhLWQyZTI3ZjRmMzQ3OC8iLCJpZHR5cCI6ImFwcCIsIm9pZCI6IjM4NTRiYjA4LTNjMmMtNGI1Ny05NWZjLTI0ZTA3OGQzODY4NSIsInJoIjoiMC5BVndBUHpGaXR2d1Vva09hZXRMaWYwODBlQU1BQUFBQUFBQUF3QUFBQUFBQUFBQmNBQUEuIiwicm9sZXMiOlsiVGVhbVNldHRpbmdzLlJlYWRXcml0ZS5BbGwiLCJUZWFtTWVtYmVyLlJlYWQuQWxsIiwiR3JvdXAuUmVhZC5BbGwiLCJEaXJlY3RvcnkuUmVhZC5BbGwiLCJUZWFtLlJlYWRCYXNpYy5BbGwiLCJUZWFtU2V0dGluZ3MuUmVhZC5BbGwiLCJPcmdhbml6YXRpb24uUmVhZC5BbGwiLCJBdWRpdExvZy5SZWFkLkFsbCJdLCJzdWIiOiIzODU0YmIwOC0zYzJjLTRiNTctOTVmYy0yNGUwNzhkMzg2ODUiLCJ0ZW5hbnRfcmVnaW9uX3Njb3BlIjoiRVUiLCJ0aWQiOiJiNjYyMzEzZi0xNGZjLTQzYTItOWE3YS1kMmUyN2Y0ZjM0NzgiLCJ1dGkiOiI3RVkyWnVXV2JFYVF0T3piVVlwOUFBIiwidmVyIjoiMS4wIiwid2lkcyI6WyIwOTk3YTFkMC0wZDFkLTRhY2ItYjQwOC1kNWNhNzMxMjFlOTAiXSwieG1zX3RjZHQiOjEzMDI1NDMzMTB9.N9yvmkCedti2fzT44VfBkN7GvuCInrIgiMgNxdyZeAyxnbdZjEhxHmNdU6HLLHQ3J-GonpPdt28dKwYxgLcrSibGzSPVHddh6MDPYutSwfIxh2oRanxhgFOWVJADfbFoCxsRFDhKJNT39bsauIUiRNzGzbb6dvWuZQ8LrgWjZzjae2qxVxj9jvYgjXEypeYZgLvPOzJiBCuluAMH3TjPuS-CuglFK_edn4CS-ztCwM0hmDFD5BLNZqng5P2KqGTEgjkMKoyIJ8yTGBJpASfdqqEFqWzQwcQ9ese924qNC3hJR_5TWHp2Fl73bpdhwBHRL5UwGTPi9_ysYdndKhXwgA

アクセストークンの解読

Azure AD アクセス トークンは、OAuth 2.0 ベアラ トークン標準 (RFC6750) は、JSON 形式の Web トークンとして構成されています。JSONコンテンツは、 base64Url エンコード と署名した。ただし、トークンを次のようなサイトに貼り付けると、 https://jwt.ms/の場合、サイトはトークンに含まれる要求の一覧を復号化し、上記の Azure AD アクセス トークンについて以下に示すような詳細が表示されます。

{ "typ": "JWT", 
"nonce": "gq3zmJhybfXGDGqt6RO2PX9s0cimmRpSRrTO90sQ4w4", 
"alg": "RS256",
 "x5t": "Mr5-AUibfBii7Nd1jBebaxboXW0", 
"kid": "Mr5-AUibfBii7Nd1jBebaxboXW0" 
}.
{ "aud": "https://graph.microsoft.com", 
"iss": "https://sts.windows.net/a662313f-14fc-43a2-9a7a-d2e27f4f3478/", 
"iat": 1644833772, 
"nbf": 1644833772,
 "exp": 1644837672,
 "aio": "E2ZgYJif1+eocevtzqRIrgDGA2V3AQ==",
 "app_displayname": "ReportDLs", 
"appid": "76c31534-ca1f-4d46-959a-6159fcb2f77a", 
"appidacr": "1",
 "idp": "https://sts.windows.net/a662313f-14fc-43a2-9a7a-d2e27f4f3478/", 
"idtyp": "app",
 "oid": "4449ce36-3d83-46fb-9045-2d1721e8f032",
 "rh": "0.AVwAPzFitvwUokOaetLif080eAMAAAAAAAAAwAAAAAAAAABcAAA.",
 "roles": 
[ "Group.Read.All", "Directory.Read.All", "User.Read.All" ],
 "sub": "4449ce36-3d83-46fb-9045-2d1721e8f032", 
"tenant_region_scope": "EU", 
"tid": "a662313f-14fc-43a2-9a7a-d2e27f4f3478",
 "uti": "BU1RVc7mHkmBq2FMcZdTAA", 
"ver": "1.0", 
"wids": [ "0997a1d0-0d1d-4acb-b408-d5ca73121e90" ],
 "xms_tcdt": 1302543310 
}
.[Signature]

解読されたトークンは、ヘッダー、ペイロード、および署名の 3 つの部分に分かれます。トークンの目的は情報を隠すことではないため、署名は暗号化によって保護されません。代わりに、トークンの発行者によって秘密キーを使用して署名されます。アクセストークンの署名に使用されるアルゴリズムと秘密鍵の詳細は、そのヘッダーにあります。アプリケーションは、 アクセストークンの署名を検証する 必要に応じて、これは通常、PowerShell スクリプトの実行時には行われません。ペイロードは、トークンによって行われた要求の場所であり、確認する最も興味深い場所です。

要求と範囲

アクセス トークン内の要求の一覧には、単純な要求とスコープ (要求のグループ) が含まれます。要求は、トークンに関連する何かに関するアサーションです。この場合、クレームは次のような詳細を教えてくれます。

• テナント (tid)。
• トークンの意図されたコンシューマー (aud): https://graph.microsoft.com.
• アプリ名 (app_displayname)。
• アプリ識別子 (appid)。
• トークン (iss) の発行を担当するセキュリティ トークン サービス (STS) は次のとおりです。 https://sts.windows.net/a662313f-14fc-43a2-9a7a-d2e27f4f3478/.
• トークンの生成時間 (iat)。
• トークンの有効期限が切れる時刻 (exp)。すべての日付は Unix エポック時間なので、1644837672 は 2022 年 2 月 14 日の 11:21:12 GMT を意味します。既定では、Azure AD によって発行されたアクセス トークンは 1 時間続きますが、継続的なアクセス評価 (CAE) をサポートするアプリケーションで使用されるものを除きます。Azure AD は、重要なユーザー イベント (パスワードの変更など) が発生した場合にいつでもアクセスを終了し、ユーザーに再認証を強制することができるため、28 時間のアクセス トークンを発行します。
• 認証に使用される Microsoft ID システム内のオブジェクトの識別子 (oid)。この場合、スクリプトは登録済みの Azure AD アプリを使用するため、値はアプリのサービス プリンシパルになります。これをテストするには、 Get-AzureADServicePrincipal コマンドレット:

Get-AzureADServicePrincipal -ObjectId 4449ce36-3d83-46fb-9045-2d1721e8f032

ObjectId                             AppId                                DisplayName
--------                             -----                                -----------
4449ce36-3d83-46fb-9045-2d1721e8f032 76c31534-ca1f-4d46-959a-6159fcb2f77a ReportDLs

スコープは要求の論理的なグループであり、リソースへのアクセスを制限するメカニズムとして使用できます。ロール要求には、グラフ API アクセス許可の開始のスコープが含まれています。ng と グループ.読み取り.すべて で終わります ユーザー.読み取り.すべて.したがって、このアプリは、Graph API クエリを実行するときにスコープに記載されているアクセス許可を使用するという組織からの同意を得ていることがわかります。アクセス許可の一覧は、PowerShell スクリプト (この場合は配布リスト メンバーシップのレポートを生成するスクリプト) がグラフに照会してすべてのグループの一覧を検索し、各グループのメンバーシップを読み取るのに十分です。

苦い経験から、私はグラフの権限を間違えるのがどれほど簡単か知っています。確認する 1 つの方法は、グラフ エクスプローラーにサインインし、クエリ (ここでは例を示します) を実行して、エクスプローラーがクエリの実行に使用するアクセス許可を確認することです。ただし、アクセス トークンをダンプして、アクセス トークンのアクセス許可のセットが期待どおりと一致することを確認することもできます。アプリのアクセス許可を要求し、その要求に対して管理者の同意を得られなかった可能性があります。つまり、Azure AD によってアプリに発行されたアクセス トークンには、要求されたアクセス許可が含まれていません。

アクセストークンの使用

適切なアクセストークンがあることに満足したら、それをGraphクエリで使用できます。テナント内の配布グループの一覧を取得する方法を次に示します。アクセストークン$Headersは、 Invoke-RestMethod コマンドレット。

$Headers = @{Authorization = "Bearer $token"}

$Uri = "https://graph.microsoft.com/beta/groups?`$filter=Mailenabled eq true and not groupTypes/any(c:c+eq+'Unified')&`$count=true"
[array]$DLs = (Invoke-RestMethod -Uri $Uri -Headers $Headers -Method Get -ContentType "application/json")
$DLs = $DLs.Value

そして、すべてが計画どおりに進んだら、処理する配布リストのセットが必要です。そうでない場合は、アクセストークンに問題があるはずなので、正方形に戻って取得プロセスを再開します。

---

Office 365 が実際に継続的にどのように機能するかについては、 Office 365 for IT プロフェッショナル 電子ブック。毎月の更新により、Office 365 エコシステム全体で重要な点についてサブスクライバーに通知されます。