ユーザーなしでアクセスを取得

[アーティクル]
08/28/2024

Microsoft Graph を呼び出すには、アプリがMicrosoft ID プラットフォームからアクセストークンを取得する必要があります。このアクセストークンには、サインインしているユーザーの代わりに Microsoft Graph にアクセスするアプリが承認されているか、独自の ID でアクセスできるかに関する情報が含まれます。この記事では、アプリが独自の ID (アプリ専用アクセスとも呼ばれます) を使用して Microsoft Graph にアクセスする方法に関するガイダンスを提供します。

この記事では、 OAuth 2.0 クライアント資格情報付与フローと呼ばれる一般的なフローを使用して、アプリが独自の ID で Microsoft Graph を呼び出すために必要な生の HTTP 要求について詳しく説明します。または、未加工の HTTP 要求を書き込むのを避け、アクセストークンを取得して Microsoft Graph を呼び出すのに役立つ Microsoft ビルドまたはサポートされている認証ライブラリを使用することもできます。詳細については、「 Microsoft 認証ライブラリ (MSAL) を使用する」を参照してください。

この記事では、クライアント資格情報フローの使用に関する次の手順を実行します。

アプリに対する Microsoft Graph アプリケーションのアクセス許可を構成します。
管理者の同意を要求します。
アクセストークンを要求します。
アクセストークンを使用して Microsoft Graph を呼び出します。

前提条件

この記事の手順に進む前に、次の手順を実行してください。

Microsoft ID プラットフォームの認証と承認の概念について説明します。詳細については、「認証と承認の基本」を参照してください。
アプリをMicrosoft Entra IDに登録します。詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照してください。アプリの登録から次の値を保存します。
- アプリケーション ID (Microsoft Entra 管理センターのオブジェクト ID と呼ばれます)。
- クライアントシークレット (アプリケーションパスワード)、証明書、またはフェデレーション ID 資格情報。
- Microsoft Entra IDからトークン応答を受け取るためのアプリのリダイレクト URI。
- アプリが管理者の同意を要求する機能を実装している場合に管理者の同意応答を受け取るサービスのリダイレクト URI。

手順 1: Microsoft Graph のアクセス許可を構成する

Microsoft Graph は、独自の ID で Microsoft Graph を呼び出すアプリのアプリケーションアクセス許可を公開します。これらのアクセス許可には常に管理者の同意が必要です。

アプリを登録するときにアプリに必要なアプリケーションのアクセス許可を事前に構成します。管理者は、organizationにアプリをインストールするときにMicrosoft Entra 管理センターを使用するか、アプリでサインアップエクスペリエンスを提供して、管理者が構成したアクセス許可に同意できるように、これらのアクセス許可に同意できます。管理者の同意Microsoft Entra ID記録すると、アプリはもう一度同意を要求しなくてもトークンを要求できます。

Microsoft Entra 管理センターのアプリ登録エクスペリエンスでアプリのアプリケーションのアクセス許可を構成するには、次の手順に従います。

アプリケーションの [API アクセス許可 ] ページで、[ アクセス許可の追加] を選択します。
[Microsoft Graph] を選択>[アプリケーションのアクセス許可] を選択します。
[ アクセス許可の選択 ] ダイアログで、アプリに構成するアクセス許可を選択します。

次のスクリーンショットは、Microsoft Graph のアプリケーションのアクセス許可に対する [アクセス許可の選択] ダイアログボックスを示しています。

Microsoft Graph のアプリケーションのアクセス許可に対する [アクセス許可の選択] ウィンドウ。

重要

アプリに必要な最小限の権限セットを常に構成します。詳細については、「 Microsoft Graph のアクセス許可を使用するためのベストプラクティス」を参照してください。

管理者は、Microsoft Entra 管理センターでアプリに必要なアクセス許可を付与できます。ただし、Microsoft Entra 管理センターにアクセスできない場合は、Microsoft ID プラットフォーム /adminconsent エンドポイントを使用して管理者にサインアップエクスペリエンスを提供できます。

重要

構成済みのアクセス許可を変更する場合は、管理者の同意プロセスも繰り返す必要があります。アプリ登録ポータルで行われた変更は、特権ロール管理者などの承認された管理者がアプリに再同意するまで反映されません。

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions  HTTP/1.1

curl --location --request GET 'https://login.microsoftonline.com/{tenant}/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&redirect_id=https%3A%2F%2Flocalhost%2Fmyapp%2Fpermissions&state=12345'

パラメーター	条件	説明
tenant	必須	アクセス許可を要求するテナント。値は GUID またはフレンドリ名形式にすることができます。ユーザーが属しているテナントがわからない場合に、任意のテナントでサインインできるようにする場合は、 `common`を使用します。
client_id	必須	Azure アプリ登録ポータルがアプリに割り当てたアプリケーション ID。
redirect_uri	必須	アプリで処理する応答を送信するリダイレクト URI。ポータルに登録したリダイレクト URI のいずれかと一致する必要があります。 URL でエンコードする必要があり、追加のパスセグメントを含めることができます。
state	推奨	トークン応答にも返される要求に含まれる値。任意のコンテンツの文字列を指定できます。状態は、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードするために使用されます。

/adminconsent エンドポイントへの要求では、Microsoft Entra IDは、承認された管理者のみがサインインして要求を完了できることを強制します。管理者は、アプリ登録ポータルでアプリに対して要求したすべてのアプリケーションアクセス許可を承認するように求められます。

次のスクリーンショットは、管理者に提示Microsoft Entra ID同意ダイアログの例です。

管理者の同意ダイアログは、同意するアクセス許可と、アクセス許可が許可するアクションを示します。

応答

管理者がアプリケーションのアクセス許可を承認した場合、成功応答は次のようになります。

// Line breaks are for legibility only.

https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#

パラメーター	説明
tenant	アプリケーションに要求されたアクセス許可を GUID 形式で付与したテナント。
state	トークン応答にも返される要求に含まれる値。任意のコンテンツの文字列を指定できます。状態は、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードするために使用されます。
admin_consent	True に設定します。

手順 3: アクセストークンを要求する

OAuth 2.0 クライアント資格情報の付与フローでは、アプリの登録時に保存したアプリケーション ID とクライアントシークレットの値を使用して、Microsoft ID プラットフォーム/tokenのエンドポイントからアクセストークンを直接要求します。

トークン要求で scope パラメーターの値としてhttps://graph.microsoft.com/.defaultを渡すことで、構成済みのアクセス許可を指定します。

トークン要求

アクセストークンを取得するために、 ID プラットフォームエンドポイントに POST 要求を送信します。この要求では、クライアントはクライアントシークレットを使用します。

HTTP
cURL

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYA....L1qKv5bPX
&grant_type=client_credentials

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=535fb089-9ff3-47b6-9bfb-4f1264799865' \
--data-urlencode 'scope=https://graph.microsoft.com/.default' \
--data-urlencode 'client_secret=qWgdYA....L1qKv5bPX' \
--data-urlencode 'grant_type=client_credentials'

パラメーター	条件	説明
tenant	必須	アクセス許可を要求するテナント。値は GUID またはフレンドリ名形式にすることができます。
client_id	必須	アプリの登録時に Azure アプリ登録ポータルが割り当てたアプリケーション ID。
スコープ	必須	この要求でスコープパラメーターに渡される値は、必要なリソースの識別子 (アプリ ID URI) で、 `.default` サフィックスが付加されている必要があります。たとえば、Microsoft Graph リソースアプリ ID URI は `https://graph.microsoft.com/` です。したがって、Microsoft Graphの場合、スコープの値は `https://graph.microsoft.com/.default` になります。この値は、管理者が同意したすべてのアプリレベルのアクセス許可をアクセストークンに含めるように Microsoft ID プラットフォームのエンドポイントに通知します。
client_secret	必須	アプリ登録ポータルでアプリ用に生成したクライアントシークレット。 URL でエンコードされていることを確認します。
grant_type	必須	`client_credentials` である必要があります。

トークンの応答

成功応答は、次のようになります。

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in":3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

パラメーター	説明
access_token	要求されたアクセストークン。アプリでは、Microsoft Graph の呼び出しでこのトークンを使用できます。
expires_in	アクセストークンの有効期間 (秒単位)。
ext_expires_in	アクセストークンの有効期間の延長を示し、トークン発行サービスが応答しない場合の回復性をサポートするために使用されます。
token_type	トークンの種類の値を示します。 Microsoft Entra IDがサポートする型は`Bearer`のみです。

手順 4: アクセストークンを使用して Microsoft Graph を呼び出す

アクセストークンを取得した後、アプリはそれを使用して、アクセストークンを ベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチすることで Microsoft Graph を呼び出します。次の要求は、テナント内のすべてのユーザーを取得します。この API を呼び出すには、アプリに User.Read.All アクセス許可が必要です。

HTTP
cURL

GET https://graph.microsoft.com/v1.0/users  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

curl --location --request GET 'https://graph.microsoft.com/v1.0/users' \
--header 'Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw' \
--data ''

成功した応答は次のようになります (一部の応答ヘッダーが削除されました)。

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@Contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@Contoso.com",
            "id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
        },
        {
            "businessPhones": [
                "+1 425 555 0109"
            ],
            "displayName": "Adele Vance",
            "givenName": "Adele",
            "jobTitle": "Retail Manager",
            "mail": "AdeleV@Contoso.com",
            "mobilePhone": null,
            "officeLocation": "18/2111",
            "preferredLanguage": null,
            "surname": "Vance",
            "userPrincipalName": "AdeleV@Contoso.com",
            "id": "59bb3898-0621-4414-ac61-74f9d7201355"
        }
    ]
}

サポートされているアプリのシナリオとリソース

独自の ID で Microsoft Graph を呼び出すアプリは、次の 2 つのカテゴリのいずれかに分類されます。

サインインしたユーザーが存在しないサーバーで実行されるバックグラウンドサービス (デーモン)。
サインインしているユーザーが存在するが、独自の ID で Microsoft Graph を呼び出すアプリ。たとえば、ユーザーが持つよりも高い昇格された特権を必要とする機能を使用する場合です。

この記事では、アプリが資格情報としてクライアントシークレットを使用しました。必要に応じて、証明書またはフェデレーション ID 資格情報を構成できます。

独自の ID で Microsoft Graph を呼び出し、クライアント資格情報フローを使用するアプリの詳細については、「認証フローとアプリケーションシナリオ: デーモンの名前で Web API を呼び出すデーモンアプリ」を参照してください。

Microsoft 認証ライブラリ (MSAL) を使用する

この記事では、クライアント資格情報フローを実行するために生の HTTP 要求を手動で作成して発行する場合にのみ必要な低レベルのプロトコルの詳細について説明しました。運用アプリでは、Microsoft 認証ライブラリ (MSAL) などの Microsoft ビルドまたはサポートされている認証ライブラリを使用して、セキュリティトークンを取得し、Microsoft Graph などの保護された Web API を呼び出します。

MSAL およびその他のサポートされている認証ライブラリは、検証、Cookie 処理、トークンキャッシュ、セキュリティで保護された接続などの詳細を処理することで、プロセスを簡略化します。を使用すると、アプリケーションの機能に集中できます。

Microsoft ID プラットフォームコードサンプルにアクセスして、MSAL を使用してアクセストークンを取得し、Microsoft Graph を呼び出す方法を確認します。

Microsoft Graph チュートリアルを調べて、アプリのみのシナリオでデータにアクセスする基本的なアプリケーションを作成します。

次の方法で共有

ユーザーなしでアクセスを取得

前提条件

手順 1: Microsoft Graph のアクセス許可を構成する

要求

応答

手順 3: アクセストークンを要求する

トークン要求

トークンの応答

手順 4: アクセストークンを使用して Microsoft Graph を呼び出す

サポートされているアプリのシナリオとリソース

Microsoft 認証ライブラリ (MSAL) を使用する

フィードバック

その他のリソース

次の方法で共有

ユーザーなしでアクセスを取得

前提条件

手順 1: Microsoft Graph のアクセス許可を構成する

手順 2: 管理者の同意を要求する

要求

管理者の同意エクスペリエンス

応答

手順 3: アクセス トークンを要求する

トークン要求

トークンの応答

手順 4: アクセス トークンを使用して Microsoft Graph を呼び出す

サポートされているアプリのシナリオとリソース

Microsoft 認証ライブラリ (MSAL) を使用する

関連コンテンツ

フィードバック

その他のリソース

手順 3: アクセストークンを要求する

手順 4: アクセストークンを使用して Microsoft Graph を呼び出す