ユーザーなしでアクセスを取得Get access without a user

一部のアプリでは、ユーザーの代わりに独自の ID を使用して Microsoft Graph を呼び出します。多くの場合、これらは、サインインしたユーザーが存在しないサーバー上で実行される、バックグラウンド サービスかデーモンです。この種のアプリの例として、夜間に起動して実行される電子メール アーカイブ サービスがあります。場合によっては、サインインしているユーザーが存在するアプリでも、独自の ID で Microsoft Graph を呼び出す必要があります。たとえば、サインインしたユーザーが所有している組織内の特権よりも高い特権を必要とする機能をアプリが使用する必要がある場合があります。Some apps call Microsoft Graph with their own identity and not on behalf of a user. In many cases, these are background services or daemons that run on a server without the presence of a signed-in user. An example of such an app might be an email archival service that wakes up and runs overnight. In some cases, apps that have a signed-in user present may also need to call Microsoft Graph under their own identity. For example, an app may need to use functionality that requires more elevated privileges in an organization than those carried by the signed-in user.

独自の ID で Microsoft Graph を呼び出すアプリは、OAuth 2.0 クライアント資格情報の付与フローを使用して、Azure AD からアクセス トークンを取得します。このトピックでは、サービスを構成し、OAuth クライアント資格情報の付与フローを使用して、アクセス トークンを取得する基本的な手順について説明します。Apps that call Microsoft Graph with their own identity use the OAuth 2.0 client credentials grant flow to get access tokens from Azure AD. In this topic, we will walk through the basic steps to configure a service and use the OAuth client credentials grant flow to get an access token.

認証および承認の手順Authentication and authorization steps

サービスを構成し、サービスが独自の ID で Microsoft Graph を呼び出すために使用できる Microsoft ID プラットフォームのエンドポイントからトークンを取得するために必要となる、基本的な手順は次のとおりです。The basic steps required to configure a service and get a token from the Azure AD v2.0 endpoint that your service can use to call Microsoft Graph under its own identity are:

  1. アプリを登録する。Register your app.
  2. アプリで Microsoft Graph のアクセス許可を構成する。Configure permissions for Microsoft Graph on your app.
  3. 管理者の同意を取得する。Get administrator consent.
  4. アクセス トークンを取得する。Get an access token.
  5. アクセス トークンを使用して、Microsoft Graph を呼び出す。Use the access token to call Microsoft Graph.

1.アプリを登録する1. Register your app

Microsoft ID プラットフォームのエンドポイントで認証するには、まずアプリを Azure アプリ登録ポータル で登録する必要があります。アプリを登録するには、Microsoft アカウントのほか、職場または学校のアカウントを使用できます。To authenticate with the Azure v2.0 endpoint, you must first register your app at the Microsoft App Registration Portal. You can use either a Microsoft account or a work or school account to register your app.

独自の ID で Microsoft Graph を呼び出すサービスの場合は、Web プラットフォーム用のアプリを登録して、次の値をコピーする必要があります。For a service that will call Microsoft Graph under its own identity, you need to register your app for the Web platform and copy the following values:

  • Azure アプリ登録ポータルが割り当てたアプリケーション ID。The Application ID assigned by the app registration portal.
  • クライアント (アプリケーション) シークレット。パスワードか、公開鍵や秘密鍵のペア (証明書) のいずれか。An Application Secret, either a password or a public/private key pair (certificate).
  • トークンの応答を受け取るためのサービスのリダイレクト URL。A Redirect URL for your service to receive token responses from Azure AD.
  • アプリに管理者の同意を要求する機能が実装されている場合は、サービスが管理者の同意の応答を受信するためのリダイレクト URL。A Redirect URL for your service to receive admin consent responses if your app implements functionality to request administrator consent.

Azure アプリ登録ポータルを使用してアプリを構成する手順については、「アプリを登録する」を参照してください。For steps on how to configure an app using the Microsoft App Registration Portal, see Register your app.

OAuth 2.0 クライアント資格情報の付与フローでは、Azure AD が割り当てたアプリケーション ID と、ポータルを使用して作成したアプリケーション シークレットを使用して、アプリが Microsoft ID プラットフォーム/tokenのエンドポイントで直接認証されます。With the OAuth 2.0 client credentials grant flow, your app authenticates directly at the Azure AD v2.0 /token endpoint using the Application ID assigned by Azure AD and the Application Secret that you create using the portal.

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

独自の ID で Microsoft Graph を呼び出すアプリの場合、Microsoft Graph はアプリケーションのアクセス許可を公開します。(Microsoft Graph は、ユーザーに代わって Microsoft Graph を呼び出すアプリの委任されたアクセス許可も公開します。)アプリに必要なアプリケーションのアクセス許可は、アプリを登録する時点で事前に構成します。アプリケーションのアクセス許可には常に管理者の同意が必要です。管理者は、組織にアプリがインストールされるときに Azure ポータルを使用してこれらのアクセス許可に同意するか、構成済みのアクセス許可に管理者が同意することによりアプリでサインアップ エクスペリエンスを提供することができます。管理者の同意が Azure AD によって記録されると、アプリは再度同意を要求する必要なしにトークンを要求できます。Microsoft Graph で使用できるアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。For apps that call Microsoft Graph under their own identity, Microsoft Graph exposes application permissions. (Microsoft Graph also exposes delegated permissions for apps that call Microsoft Graph on behalf of a user.) You pre-configure the application permissions your app needs when you register your app. Application permissions always require administrator consent. An administrator can either consent to these permissions using the Azure portal when your app is installed in their organization, or you can provide a sign-up experience in your app through which administrators can consent to the permissions you configured. Once administrator consent is recorded by Azure AD, your app can request tokens without having to request consent again. For more detailed information about the permissions available with Microsoft Graph, see the Permissions reference

Azure アプリ登録ポータルでアプリのアプリケーション アクセス許可を構成するには、アプリケーションの [API アクセス許可] ページで [アクセス許可を追加]、[Microsoft Graph] の順に選択し、[アプリケーションのアクセス許可] でアプリに必要なアクセス許可を選択します。To configure application permissions for your app in the Azure app registration portal: under an application's API permissions page, choose Add a permission, select Microsoft Graph, and then choose the permissions your app requires under Application permissions.

次のスクリーンショットは、Microsoft Graph のアプリケーションのアクセス許可に対する [アクセス許可の選択] ダイアログを示しています。The following screenshot shows the Select Permissions dialog for Microsoft Graph application permissions.

Microsoft Graph のアプリケーションのアクセス許可に対する [アクセス許可の選択] ダイアログ。

:アプリで必要になるアクセス許可の、最低限の権限セットを構成することをお勧めします。これにより、アクセス許可の長大なリストに同意を求めるものよりも快適なエクスペリエンスを管理者に提供できます。Note: We recommend configuring the least privileged set of permissions required by your app. This provides a much more comfortable experience for administrators than having to consent to a long list of permissions.

管理者に任せて Azure ポータルでアプリケーションに必要なアクセス許可を付与することができます。ただし、多くの場合、Microsoft ID プラットフォーム/adminconsentのエンドポイントを使用して管理者にサインアップ エクスペリエンスを提供するほうが優れた選択肢になります。You can rely on an administrator to grant the permissions your app needs at the Azure portal; however, often, a better option is to provide a sign-up experience for administrators by using the Azure AD v2.0 /adminconsent endpoint.

重要:構成済みのアクセス許可に変更を加える場合は常に、管理者の同意プロセスも繰り返す必要があります。Important: Any time you make a change to the configured permissions, you must also repeat the Admin Consent process. アプリ登録ポータルで行われた変更は、テナント管理者が同意を再適用するまで反映されません。Changes made in the app registration portal will not be reflected until consent has been reapplied by the tenant's administrator.

要求Request

// 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
パラメーターParameter 条件Condition 説明Description
tenanttenant 必須Required アクセス許可の要求元のディレクトリ テナント。これは、GUID またはフレンドリ名の形式で指定できます。ユーザーが所属しているテナントがわからないときに、そのユーザーを任意のテナントでサインインさせる場合は、common を使用します。The directory tenant that you want to request permission from. This can be in GUID or friendly name format. If you don't know which tenant the user belongs to and you want to let them sign in with any tenant, use common.
client_idclient_id 必須Required Azure アプリ登録ポータルがアプリに割り当てたアプリケーション ID。The Application ID that the registration portal (apps.dev.microsoft.com) assigned your app.
redirect_uriredirect_uri 必須Required アプリが処理するために応答を送信するリダイレクト URI。URL でエンコードされている必要があることを除き、ポータルに登録したリダイレクト URI のいずれかに完全に一致する必要があります。また追加のパス セグメントを含めることができます。The redirect URI where you want the response to be sent for your app to handle. It must exactly match one of the redirect URIs that you registered in the portal, except that it must be URL encoded, and it can have additional path segments.
statestate 推奨Recommended トークン応答でも返される、要求に含まれている値。任意のコンテンツの文字列にすることができます。state は、使用していたページまたはビューなど、認証要求が発生する前の、アプリでのユーザーの状態に関する情報をエンコードするために使用されます。A value that is included in the request that also is returned in the token response. It can be a string of any content that you want. The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

/adminconsent エンドポイントへの要求では、Azure AD はテナント管理者のみがサインインして要求を完了できるように強制します。管理者は、アプリ登録ポータルでユーザーがアプリに対して要求したすべてのアプリケーションのアクセス許可を承認するよう求められます。With requests to the /adminconsent endpoint, Azure AD enforces that only a tenant administrator can sign in to complete the request. The administrator will be asked to approve all the application permissions that you have requested for your app in the app registration portal.

Azure AD が管理者に提示する同意ダイアログの例を次に示します。The following is an example of the consent dialog that Azure AD presents to the administrator:

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

応答Response

管理者がアプリケーションのアクセス許可を承認した場合、成功応答は次のようになります。If the administrator approves the permissions for your application, the successful response looks like this:

// Line breaks are for legibility only.

GET https://localhost/myapp/permissions
?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=12345
&admin_consent=True
パラメーターParameter 説明Description
tenanttenant 要求されたアクセス許可をアプリケーションに付与したディレクトリ テナント (GUID 形式)。The directory tenant that granted your application the permissions that it requested, in GUID format.
statestate トークン応答でも返される、要求に含まれている値。任意のコンテンツの文字列にすることができます。state は、使用していたページまたはビューなど、認証要求が発生する前の、アプリでのユーザーの状態に関する情報をエンコードするために使用されます。A value that is included in the request that also is returned in the token response. It can be a string of any content that you want. The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consentadmin_consent true に設定します。Set to true.

お試しください:次の要求をブラウザーに貼り付けて、これを試してみることができます。Azure AD テナントのグローバル管理者としてサインインすると、アプリの管理者の同意ダイアログ ボックスが表示されます。(これは、前述の同意ダイアログ ボックスのスクリーンショットのアプリとは別のアプリになります。)Try: You can try this for yourself by pasting the following request in a browser. If you sign in as a Global administrator for an Azure AD tenant, you will be presented with the administrator consent dialog box for the app. (This will be a different app than that in the consent dialog box screenshot shown earlier.)

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

4. アクセス トークンを取得する4. Get an access token

OAuth 2.0 クライアント資格情報の付与フローでは、アプリの登録時に保存したアプリケーション ID とアプリケーション シークレットの値を使用して、Microsoft ID プラットフォーム/tokenのエンドポイントからアクセス トークンを直接要求します。In the OAuth 2.0 client credentials grant flow, you use the Application ID and Application Secret values that you saved when you registered your app to request an access token directly from the Azure AD v2.0 /token endpoint.

トークン要求の scope パラメーターの値として https://graph.microsoft.com/.default を渡すことにより、事前構成済みのアクセス許可を指定します。詳細については、次のトークン要求の scope パラメーターの説明を参照してください。You specify the pre-configured permissions by passing https://graph.microsoft.com/.default as the value for the scope parameter in the token request. See the scope parameter description in the token request below for details.

トークン要求Token request

POST 要求を /token ID プラットフォームに送信して、アクセス トークンを取得します。You send a POST request to the /token v2.0 endpoint to acquire an access token:

// 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
パラメーターParameter 条件Condition 説明Description
tenanttenant 必須Required アクセス許可の要求元のディレクトリ テナント。これは、GUID またはフレンドリ名の形式で指定できます。The directory tenant that you want to request permission from. This can be in GUID or friendly name format.
client_idclient_id 必須Required アプリの登録時に Azure アプリ登録ポータルが割り当てたアプリケーション ID。The Application ID that the Azure app registration portal assigned when you registered your app.
スコープscope 必須Required この要求で scope パラメーターに渡される値は、必要なリソースのリソース識別子 (アプリケーション ID の URI) になっている必要があります (.default サフィックス付き)。The value passed for the scope parameter in this request should be the resource identifier (Application ID URI) of the resource you want. Microsoft Graph の場合、値は https://graph.microsoft.com/.default です。For Microsoft Graph, the name is https://graph.microsoft.com/.default. この値は、アプリに構成した全アプリケーションのアクセス許可のうち、使用するリソースに関連付けられているアクセス許可のトークンを発行するように Microsoft ID プラットフォームに通知します。This value informs the token endpoint that of all the direct application permissions you have configured for your app, it should issue a token for the ones associated with the resource you want to use.
client_secretclient_secret 必須Required アプリケーション登録ポータルでアプリ用に生成したアプリケーション シークレット。The Application Secret that you generated for your app in the app registration portal.
grant_typegrant_type 必須Required client_credentials である必要があります。Must be client_credentials.

トークンの応答Token response

成功応答は、次のようになります。A successful response looks like this:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
パラメーターParameter 説明Description
access_tokenaccess_token 要求されたアクセス トークン。アプリはこのトークンを Microsoft Graph の呼び出しで使用できます。The requested access token. Your app can use this token in calls to Microsoft Graph.
token_typetoken_type トークンの種類の値を示します。Azure AD がサポートしている種類は bearer のみです。Indicates the token type value. The only type that Azure AD supports is bearer.
expires_inexpires_in アクセス トークンの有効期間 (秒単位)。How long the access token is valid (in seconds).

5.アクセス トークンを使用して、Microsoft Graph を呼び出す5. Use the access token to call Microsoft Graph

アクセス トークンの取得後は、そのトークンを使用して (トークンを要求の Authorization ヘッダーに含める)、Microsoft Graph を呼び出すことができます。次の要求は、特定のユーザーのプロファイルを取得します。この API を呼び出すには、アプリに User.Read.All アクセス許可が必要です。After you have an access token, you can use it to call Microsoft Graph by including it in the Authorization header of a request. The following request gets the profile of a specific user. Your app must have the User.Read.All permission to call this API.

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

正常な応答は次のようになります (一部の応答ヘッダーは削除されています)。A successful response will look similar to this (some response headers have been removed):

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"
}

サポートされているアプリのシナリオとリソースSupported app scenarios and resources

独自の ID で Microsoft Graph を呼び出すアプリは、次に示す 2 つのカテゴリのいずれかに分類されます。Apps that call Microsoft Graph under their own identity fall into one of two categories:

  • サインインしたユーザーが存在しないサーバーで実行されるバックグラウンド サービス (デーモン)。Background services (daemons) that run on a server without a signed-in user.
  • サインインしたユーザーは存在するが、独自の ID でも Microsoft Graph を呼び出すアプリ (たとえば、ユーザーの特権よりも高い特権を必要とする機能を使用するため)。Apps that have a signed-in user but also call Microsoft Graph with their own identity; for example, to use functionality that requires more elevated privileges than those of the user.

独自の ID で Microsoft Graph を呼び出すアプリは、OAuth 2.0 クライアントの認証情報の付与を使用して Azure AD で認証し、トークンを取得します。Apps that call Microsoft Graph with their own identity use the OAuth 2.0 client credentials grant to authenticate with Azure AD and get a token. For the v2.0 endpoint, you can explore this scenario further with the following resources: Microsoft ID プラットフォームのエンドポイントの場合は、次のリソースを使用して、このシナリオについてさらに詳しく調べることができます。For the Azure AD endpoint, you can explore this scenario further with the following resources:

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

Microsoft では引き続き Azure AD エンドポイントをサポートします。Microsoft continues to support the Azure AD endpoint. Microsoft ID プラットフォームのエンドポイントと Azure AD のエンドポイントの使用には、いくつかの違いがあります。There are several differences between using the Azure AD endpoint and the Azure AD v2.0 endpoint. For example: Azure AD エンドポイントを使用する場合:When using the Azure AD endpoint:

  • アプリがマルチ テナント アプリの場合は、Microsoft Azure portal でマルチ テナントとなるよう明示的に設定する必要があります。If your app is a multi-tenant app, you must explicitly configure it to be multi-tenant at the Azure portal.
  • 管理者の同意エンドポイント (/adminconsent) はありません。There is no admin consent endpoint (/adminconsent). その代わりに、認証要求に prompt=admin_consent パラメーターを追加することで、アプリは実行時に管理者の同意を要求できます。Instead, your app can request administrator consent during runtime by adding the prompt=admin_consent parameter to an authorization request. 詳細については、「Azure Active Directory とアプリケーションの統合」の「実行時の Azure AD 同意フレームワークのトリガー」を参照してください。There is no admin consent endpoint (), instead, your app can request administrator consent during runtime by adding the parameter to an authorization request. For more information, see Triggering the Azure AD consent framework at runtime in Integrating applications with Azure Active Directory.
  • 承認とトークン要求のパラメーターは異なります。たとえば、Azure AD エンドポイント要求には、scope パラメーターはありません。その代わりに、resource パラメーターを使用して、承認 (管理者の同意用) またはトークンが要求されているリソース (resource=https://graph.microsoft.com) の URI を指定します。The parameters in authorization and token requests are different. For example, there is no scope parameter in Azure AD endpoint requests; instead, the resource parameter is used to specify the URI of the resource (resource=https://graph.microsoft.com) that authorization (for administrator consent) or a token is being requested for.

Azure AD エンドポイントの場合は、次のリソースを使用して、このシナリオについてさらに詳しく調べることができます。For the Azure AD endpoint, you can explore this scenario further with the following resources:

  • クライアント資格情報の付与フローの概要、サンプル、詳細な処理へのクイック リンクについては、「開発者のための Azure Active Directory」の作業の開始セクションサービス間を参照してください。For quick links to an overview, samples, and a detailed treatment of the client credentials grant flow, see Service-to-Service in the Getting Started section in Azure Active Directory for Developers.
  • Azure AD エンドポイントの場合は、Azure Active Directory 認証ライブラリ (ADAL) を使用して Azure AD からトークンを取得できます。ADAL は、.NET、iOS、Android、JavaScript、Java、および Node.js を含む、いくつかのプラットフォームで利用できます。Azure AD エンドポイント向けの ADAL と、その他の Microsoft 認証ライブラリの詳細については、「Azure Active Directory 認証ライブラリ」を参照してください。For the Azure AD endpoint, you can use the Azure Active Directory Authentication Library (ADAL) to get tokens from Azure AD. ADAL is available for several platforms including .NET, iOS, Android, JavaScript, Java, and Node.js. For more information about ADAL and other Microsoft authentication libraries for the Azure AD endpoint, see Azure Active Directory Authentication Libraries.