Microsoft Graph の認証と承認の基本方法
Microsoft Graph は、Microsoft Entra IDや Microsoft 365 などの Microsoft クラウド サービスのデータにアクセスするための保護された Web API です。 これは、OAuth アクセス トークンを使用してアプリが Microsoft Graph を呼び出す権限があることを確認するMicrosoft ID プラットフォームによって保護されています。
この記事では、Microsoft ID プラットフォームとアクセス トークンの概要、アプリでアクセス トークンを取得する方法について説明します。 詳細については、「Microsoft ID プラットフォームとは」を参照してください。 アプリとMicrosoft ID プラットフォームを統合してトークンを取得する方法がわかっている場合は、Microsoft Graph に固有の情報とサンプルのMicrosoft ID プラットフォームコード サンプルに関するページを参照してください。
アプリケーションの登録
アプリがMicrosoft ID プラットフォームからアクセス トークンを取得するには、Microsoft Entra 管理センターに登録する必要があります。 登録によりアプリが Microsoft ID プラットフォームと統合され、次のようなトークンを取得する際に使用する情報を確立します。
- アプリケーション ID: Microsoft ID プラットフォームによって割り当てられた一意の識別子。
- リダイレクト URI/URL: アプリがMicrosoft ID プラットフォームから応答を受信する 1 つ以上のエンドポイント。 (ネイティブ アプリとモバイル アプリの場合、URI はMicrosoft ID プラットフォームによって割り当てられます)。
- クライアント シークレット: アプリがMicrosoft ID プラットフォームで認証するために使用するパスワード。 必要に応じて、証明書またはフェデレーション ID 資格情報を使用できます。 このプロパティは、ネイティブ、モバイル、シングル ページ アプリケーションなどのパブリック クライアントには必要ありません。
詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照してください。
アクセス シナリオ
アプリがMicrosoft ID プラットフォームで認証するために使用する方法は、アプリがデータにアクセスする方法によって異なります。 このアクセスは、次の図に示すように、2 つの方法のいずれかで実行できます。
- 委任されたアクセス。サインインしているユーザーに代わって動作するアプリ。
- アプリ専用アクセス。独自の ID で動作するアプリ。
委任されたアクセス (ユーザーに代わってアクセスする)
このアクセス シナリオでは、ユーザーがクライアント アプリケーションにサインインし、クライアント アプリケーションがユーザーの代わりに Microsoft Graph を呼び出します。 クライアントとユーザーの両方が要求を行う権限を持っている必要があります。
委任されたアクセスには、 委任されたアクセス許可 (スコープとも呼ばれます) が必要 です。 スコープは、特定のリソースによって公開されるアクセス許可であり、ユーザーに代わってアプリが実行できる操作を表します。
アプリとユーザーの両方が要求を行う権限を持っている必要があるため、リソースは、クライアント アプリに委任されたアクセス許可を付与し、クライアント アプリが指定されたユーザーの代わりにデータにアクセスできるようにします。 ユーザーの場合、リソースに対して実行できるアクションは、リソースにアクセスするために必要なアクセス許可に依存します。 たとえば、ユーザーがリソースの所有者であるか、ロールベースのアクセス制御システム (RBAC) (RBAC) (MICROSOFT ENTRA RBAC など) を介して特定のロールが割り当てられている場合があります。
注:
エイリアスを持つ /me エンドポイントと API は、サインインしているユーザーでのみ動作するため、委任されたアクセス シナリオで呼び出されます。
アプリ専用アクセス (ユーザーなしのアクセス)
このアクセス シナリオでは、サインインしているユーザーなしで、アプリケーションが独自にデータを操作できます。 アプリのみの アクセスは、自動化やバックアップなどのシナリオで使用され、主にバックグラウンド サービスまたはデーモンとして実行されるアプリによって使用されます。 ユーザーをサインインさせるのが望ましくない場合や、必要なデータを 1 人のユーザーにスコープ指定できない場合に適しています。
アプリは、次のいずれかの方法で、独自の ID で Microsoft Graph を呼び出す特権を取得します。
- アプリにアプリケーションのアクセス許可が割り当てられると、アプリ ロールとも呼ばれます
- アプリに、管理するリソースの所有権が割り当てられている場合
注:
また、アプリは、Microsoft Entra RBAC などのロールベースのアクセス制御システムによって付与されたアクセス許可を通じて特権を取得することもできます。
Microsoft Graph のアクセス許可
Microsoft Graph では、ユーザー、グループ、メールなどの Microsoft Graph リソースに対するアプリのアクセスを制御する詳細なアクセス許可が公開されています。 開発者は、アクセス シナリオと実行する操作に基づいて、アプリに対して要求する Microsoft Graph のアクセス許可を決定します。
Microsoft Graph では、サポートされている アクセス シナリオに対して 2 種類のアクセス許可が公開されています。
- 委任されたアクセス許可: スコープとも呼ばれ、サインインしているユーザーの代わりにアプリケーションが動作できるようにします。
- アプリケーションのアクセス許可: アプリ ロールとも呼ばれ、サインインしているユーザーなしでアプリが独自にデータにアクセスできるようにします。
ユーザーがアプリにサインインする場合、アプリはアクセス トークンに含める必要があるアクセス許可を指定する必要があります。 これらのアクセス許可:
- 管理者がアプリケーションに対して事前認証を行う場合があります。
- ユーザーが直接同意する場合があります。
- 事前認証されていない場合は、同意を付与するために管理者特権が必要になる場合があります。 たとえば、セキュリティへの影響が大きい可能性があるアクセス許可の場合などです。
アクセス許可と同意の詳細については、「アクセス 許可と同意の概要」を参照してください。
注:
ベスト プラクティスとして、データにアクセスして正しく機能するためにアプリに必要な最小限のアクセス許可を要求します。 必要以上の権限でアクセス許可を要求することはセキュリティ対策としては不十分であり、ユーザーが同意を控え、アプリの使用に影響を与える可能性があります。
Microsoft Graph のアクセス許可とその使用方法の詳細については、「 Microsoft Graph のアクセス許可の概要」を参照してください。
アクセス トークン
アプリケーションは、microsoft Graph などの API の呼び出しに使用するアクセス トークンを取得するために、Microsoft ID プラットフォームに対して認証要求を行います。 Microsoft ID プラットフォームが発行するアクセス トークンには、アプリケーションに関する詳細と委任されたアクセス シナリオのユーザーに関する要求が含まれています。 Microsoft Graph など、Microsoft ID プラットフォームによってセキュリティ保護された Web API は、要求を使用して呼び出し元を検証し、呼び出し元が要求している操作を実行するための適切な特権を持っていることを確認します。 トークンのコンテンツは API のみを対象としているため、呼び出し元は、アクセス トークンを不透明として処理する必要があります。 Microsoft Graphを呼び出すときは、トランスポート層セキュリティ (TLS) を使用するセキュリティで保護されたチャネルを介してアクセス トークンを送信することで、アクセス トークンを常に保護します。
次の例は、Microsoft ID プラットフォームのアクセス トークンを示します。
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
アクセス トークンは、Microsoft ID プラットフォームが提供するセキュリティ トークンの一種です。 有効期間は短いですが、既定の有効期間は可変です。
Microsoft Graph を呼び出すために、アプリはアクセス トークンを ベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチすることで 承認 要求を行います。 その例として、サインインしているユーザーのプロファイル情報を返す呼び出しを次に示します (読みやすくするために、アクセス トークンは短くされています)。
GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==
アクセス トークンを取得する
認証ライブラリを使用して、Microsoft ID プラットフォームとのトークン操作を管理することをお勧めします。 認証ライブラリは、検証、Cookie 処理、トークンキャッシュ、セキュリティで保護された接続の維持など、多くのプロトコルの詳細を抽象化するため、開発をアプリの機能に集中できます。 Microsoft は、オープン ソースのクライアント ライブラリとサーバー ミドルウェアを発行します。
Microsoft ID プラットフォームのエンドポイントの場合:
- Microsoft Authentication Library (MSAL) クライアント ライブラリは、.NET、JavaScript、Android、iOS など、さまざまなフレームワークで使用できます。 すべてのプラットフォームが運用環境でサポートされるプレビュー段階にあり、重大な変更が導入された場合、Microsoft はアップグレードのパスを保証します。
- Microsoft のサーバー ミドルウェアは、.NET core と ASP.NET (OWIN OpenID Connect と OAuth) と Node.js (Microsoft ID プラットフォーム Passport.js) で使用できます。
- Microsoft ID プラットフォームは、多くのサードパーティ認証ライブラリとも互換性があります。
Microsoft クライアント ライブラリ、Microsoft サーバー ミドルウェア、および互換性のあるサード パーティ 製ライブラリの完全な一覧については、Microsoft ID プラットフォームドキュメントを参照してください。
認証ライブラリを使用してアクセス トークンを取得する必要はありません。 認証ライブラリを使用せずにMicrosoft ID プラットフォーム エンドポイントを直接使用する方法については、次の記事を参照してください。