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

[アーティクル]
08/31/2022

一部のアプリでは、ユーザーの代わりに独自の ID を使用して Microsoft Graph を呼び出します。多くの場合、これらのアプリは、サインインしたユーザーが存在しないサーバー上で実行される、バックグラウンドサービスかデーモンです。この種のアプリの例として、夜間に起動して実行される電子メールアーカイブサービスがあります。場合によっては、サインインしているユーザーが存在するアプリでも、独自の ID で Microsoft Graph を呼び出す必要があります。たとえば、サインインしたユーザーが所有しているよりも高い組織内の特権を必要とする機能をアプリが使用する必要がある場合があります。

独自の ID で Microsoft Graph を呼び出すアプリは、OAuth 2.0 クライアント資格情報の付与フローを使用して、Azure AD からアクセストークンを取得します。この記事では、サービスを構成し、OAuth クライアント資格情報の付与フローを使用して、アクセストークンを取得する基本的な手順について説明します。

認証および承認の手順

これらの基本的な手順に従って、サービスを構成し、Microsoft ID プラットフォームのエンドポイントからトークンを取得します。サービスは、独自の ID で Microsoft Graph を呼び出すためにトークンを使用できます。

アプリを登録する。
アプリで Microsoft Graph のアクセス許可を構成する。
管理者の同意を取得する。
アクセストークンを取得する。
アクセストークンを使用して、Microsoft Graph を呼び出す。

1.アプリを登録する

Microsoft ID プラットフォームのエンドポイントで認証するには、まずアプリを Azure アプリ登録ポータルで登録する必要があります。アプリを登録するには、Microsoft アカウントのほか、職場または学校のアカウントを使用できます。

独自の ID で Microsoft Graph を呼び出すサービスの場合は、Web プラットフォーム用のアプリを登録して、次の値をコピーする必要があります。

Azure アプリ登録ポータルが割り当てたアプリケーション ID。
クライアント (アプリケーション) シークレット。パスワードか、公開鍵や秘密鍵のペア (証明書) のいずれか。
トークンの応答を受け取るためのサービスのリダイレクト URL。
アプリに管理者の同意を要求する機能が実装されている場合は、サービスが管理者の同意の応答を受信するためのリダイレクト URL。

Azure アプリ登録ポータルを使用してアプリを構成する手順については、「アプリを登録する」を参照してください。

OAuth 2.0 クライアント資格情報の付与フローでは、Azure AD が割り当てたアプリケーション ID と、ポータルを使用して作成したクライアントシークレットを使用して、アプリが Microsoft ID プラットフォーム/tokenのエンドポイントで直接認証されます。

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

Microsoft Graph は、独自の ID で Microsoft Graph を呼び出すアプリの アプリケーションのアクセス許可 を公開します (Microsoft Graph は、ユーザーに代わって Microsoft Graph を呼び出すアプリの委任されたアクセス許可も公開できます)。

アプリに必要なアプリケーションのアクセス許可は、アプリを登録する時点で事前に構成します。アプリケーションのアクセス許可には常に管理者の同意が必要です。管理者は、組織にアプリがインストールされるときに Azure ポータルを使用してこれらのアクセス許可に同意するか、構成済みのアクセス許可に管理者が同意することによりアプリでサインアップエクスペリエンスを提供することができます。管理者の同意が Azure AD によって記録されると、アプリは再度同意を要求する必要なしにトークンを要求できます。Microsoft Graph で使用できるアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

Azure アプリ登録ポータルでアプリのアプリケーションアクセス許可を構成するには、アプリケーションの [API アクセス許可] ページで [アクセス許可を追加]、[Microsoft Graph] の順に選択し、[アプリケーションのアクセス許可] でアプリに必要なアクセス許可を選択します。

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

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

重要

セキュリティを強化するため、アプリで必要になるアクセス許可の、最低限の権限セットを構成します。詳細については、「最低限の特権の原則によってセキュリティを強化する」を参照してください。

管理者に任せて Azure ポータルでアプリケーションに必要なアクセス許可を付与することができます。ただし、多くの場合、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

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

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

次のスクリーンショットは、Azure AD が管理者に提示する同意ダイアログの例を示します。

管理者の同意ダイアログ。

応答

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

// Line breaks are for legibility only.

GET https://localhost/myapp/permissions
?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=12345
&admin_consent=True

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

お試しください: 次の要求をブラウザーに貼り付けて、これを試してみることができます。Azure AD テナントのグローバル管理者としてサインインすると、アプリの管理者の同意ダイアログボックスが表示されます。(これは、前述の同意ダイアログボックスのスクリーンショットのアプリとは別のアプリになります。)

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 を渡すことにより、事前構成済みのアクセス許可を指定します。詳細については、次のトークン要求の scope パラメーターの説明を参照してください。

トークン要求

POST 要求を /token ID プラットフォームに送信して、アクセストークンを取得します。

// 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

パラメーター	条件	説明
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	トークンの種類の値を示します。Azure AD がサポートしている種類は `Bearer` のみです。

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

アクセストークンの取得後は、そのトークンを使用して (トークンを要求の Authorization ヘッダーに含める)、Microsoft Graph を呼び出すことができます。次の要求は、特定のユーザーのプロファイルを取得します。この API を呼び出すには、アプリに User.Read.All アクセス許可が必要です。

GET https://graph.microsoft.com/v1.0/users/12345678-73a6-4952-a53a-e9916737ff7f
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

正常な応答は次のようになります (一部の応答ヘッダーは削除されています)。

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
Duration: 309.0273
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id":"12345678-73a6-4952-a53a-e9916737ff7f",
    "businessPhones":[
        "+1 555555555"
    ],
    "displayName":"Chris Green",
    "givenName":"Chris",
    "jobTitle":"Software Engineer",
    "mail":null,
    "mobilePhone":"+1 5555555555",
    "officeLocation":"Seattle Office",
    "preferredLanguage":null,
    "surname":"Green",
    "userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}

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

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

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

独自の ID で Microsoft Graph を呼び出すアプリは、OAuth 2.0 クライアント資格情報の付与を使用して Azure AD で認証し、トークンを取得します。Microsoft ID プラットフォームエンドポイントの場合は、次のリソースを使用して、このシナリオについてさらに詳しく調べることができます。

エラーへの対応を含む、クライアント資格情報の付与フローの完全な処理については、「Azure Active Directory v2.0 と OAuth 2.0 クライアント資格情報フロー」を参照してください。
サービスから Microsoft Graph を呼び出すサンプルについては、GitHub の「v2.0 デーモンのサンプル」を参照してください。
推奨される Microsoft ライブラリとサードパーティ製認証ライブラリの詳細については、「Microsoft ID プラットフォームの認証ライブラリ」を参照してください。

エンドポイントに関する考慮事項

Microsoft では引き続き Azure AD エンドポイントをサポートします。 Microsoft ID プラットフォームのエンドポイントと Azure AD のエンドポイントの使用には、いくつかの違いがあります。 Azure AD エンドポイントを使用する場合:

アプリがマルチテナントアプリの場合は、Microsoft Azure portal でマルチテナントとなるよう明示的に設定する必要があります。
管理者の同意エンドポイント () はありません。その代わりに、同意要求に prompt=admin_consent パラメーターを追加することで、アプリは実行時に管理者の同意を要求できます。詳細については、「Azure Active Directory とアプリケーションの統合」の「実行時の Azure AD 同意フレームワークのトリガー」を参照してください。
承認とトークン要求のパラメーターは異なります。たとえば、Azure AD エンドポイント要求には、scope パラメーターはありません。その代わりに、resource パラメーターを使用して、承認 (管理者の同意用) またはトークンが要求されているリソース (resource=https://graph.microsoft.com) の URI を指定します。

次のリソースを使用して、このシナリオについてさらに詳しく調べることができます。

さまざまな種類のアプリで Microsoft ID プラットフォームを使用する方法については、「Microsoft ID プラットフォームのドキュメント」の「はじめに」リンクを参照してください。
Microsoft ID プラットフォームのエンドポイントで使用可能な Microsoft Authentication Library (MSAL) およびサーバーミドルウェアの詳細については、「Microsoft Authentication Library」を参照してください。

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

認証および承認の手順

1.アプリを登録する

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

要求

応答

4. アクセストークンを取得する

トークン要求

トークンの応答

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

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

エンドポイントに関する考慮事項

関連項目

フィードバック

その他のリソース

その他のリソース

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

認証および承認の手順

1.アプリを登録する

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

3.管理者の同意を取得する

要求

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

応答

4. アクセス トークンを取得する

トークン要求

トークンの応答

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

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

エンドポイントに関する考慮事項

関連項目

フィードバック

その他のリソース

その他のリソース

4. アクセストークンを取得する

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