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

[アーティクル]
09/08/2023

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

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

前提条件

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

Microsoft ID プラットフォームの認証と承認の概念について説明します。詳細については、「認証と承認の基本」を参照してください。
Microsoft Entra ID でアプリを登録します。詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照してください。

認証および承認の手順

アプリがクライアント資格情報フローを使用して Microsoft Graph への承認とアクセスを取得するには、次の 5 つの手順に従う必要があります。

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

ヒント

Postman で手順 2 から 5 を試してください。トークンと ID を置き換えることを忘れないでください。

1. アプリを登録する

アプリでMicrosoft ID プラットフォームエンドポイントを使用したり、Microsoft Graph を呼び出したりする前に、適切に登録する必要があります。 Microsoft Entra管理センターにアプリを登録する手順に従います。

アプリの登録から、次の値を保存します。

アプリ登録ポータルによって割り当てられたアプリケーション ID (Microsoft Entra 管理センターのオブジェクト ID と呼ばれます)。
クライアントシークレット (アプリケーションパスワード)、証明書、またはフェデレーション ID 資格情報。
Microsoft Entra ID からトークン応答を受信するアプリのリダイレクト URI。
アプリが管理者の同意を要求する機能を実装している場合に管理者の同意応答を受け取るサービスのリダイレクト URI。

2.Microsoft Graph のアクセス許可を構成する

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

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

Azure アプリ登録ポータルでアプリのアプリケーションのアクセス許可を構成するには、次の手順に従います。

アプリケーションの [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 に設定します。

試す: ブラウザーに次の要求を貼り付けることで、自分で試すことができます。 Microsoft Entra テナントのグローバル管理者としてサインインすると、アプリの [管理者の同意] ダイアログボックスが表示されます。

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

4. アクセストークンを要求する

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

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

トークン要求

アクセストークンを取得するために /token 、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=qWgdYAmab0YSkuL1qKv5bPX
&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=qWgdYAmab0YSkuL1qKv5bPX' \
--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`のみです。

5.アクセストークンを使用して、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 では、Microsoft ID プラットフォームでサポートされている認証ライブラリの使用方法を示すさまざまなコードサンプルを構築および管理しています。これらのコードサンプルにアクセスするには、「次の手順」を参照してください。

次の手順

この記事は、Microsoft ID プラットフォームによる Microsoft Graph の認証と承認に関する次の一連の記事の一部です。

次に、Microsoft によってビルドおよび保守されているコードサンプルから選択して、サポートされている認証ライブラリを使用するカスタムアプリを実行し、独自の ID で Microsoft Graph を呼び出します。

Microsoft Graph チュートリアル >

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

前提条件

認証および承認の手順

1. アプリを登録する

2.Microsoft Graph のアクセス許可を構成する

要求

応答

4. アクセストークンを要求する

トークン要求

トークンの応答

5.アクセストークンを使用して、Microsoft Graph を呼び出す

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

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

次の手順

その他のリソース

その他のリソース

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

前提条件

認証および承認の手順

1. アプリを登録する

2.Microsoft Graph のアクセス許可を構成する

3. 管理者の同意を要求する

要求

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

応答

4. アクセス トークンを要求する

トークン要求

トークンの応答

5.アクセス トークンを使用して、Microsoft Graph を呼び出す

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

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

次の手順

その他のリソース

その他のリソース

4. アクセストークンを要求する

5.アクセストークンを使用して、Microsoft Graph を呼び出す