Microsoft Graph の認証と承認の基本方法Authentication and authorization basics for Microsoft Graph

Microsoft Graph を呼び出すには、アプリが Microsoft ID プラットフォームからアクセス トークンを取得する必要があります。To call Microsoft Graph, your app must acquire an access token from the Microsoft identity platform. アクセス トークンには、アプリとアプリに付与されているアクセス許可に関する情報が含まれています。このアクセス許可は、Microsoft Graph を通じて利用できるリソースと API に対応するものです。The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph. アクセス トークンを取得するには、アプリを Microsoft ID プラットフォームで登録し、そのアプリが必要とする Microsoft Graph リソースへのアクセスをユーザーまたは管理者が承認する必要があります。To get an access token, your app must be registered with the Microsoft identity platform and be authorized by either a user or an administrator for access to the Microsoft Graph resources it needs.

このトピックでは、アクセス トークンと Microsoft ID プラットフォームの概要、アプリでアクセス トークンを取得する方法について説明します。This topic provides an overview of access tokens, the Microsoft identity platform, and how your app can get access tokens. トークンを取得するためのアプリと Microsoft ID プラットフォームとの統合について既に詳しく理解している場合は、[次の手順] のセクションまでスキップして、Microsoft Graph に固有の情報とサンプルを参照してください。If you are already familiar with integrating an app with the Microsoft identity platform to get tokens, see the Next Steps section for information and samples specific to Microsoft Graph.

アクセス トークンAccess tokens

Microsoft ID プラットフォームから発行されるアクセス トークンは、Base 64 でエンコードされた JSON Web トークン (JWT) です。Access tokens issued by the Microsoft identity platform are base 64 encoded JSON Web Tokens (JWT). これに含まれている情報 (要求) は、呼び出し元の検証と、呼び出し元が要求している操作を実行するための適切なアクセス許可が付与されていることの確認のために、Microsoft ID プラットフォームによって保護されている Web API (Microsoft Graph など) が使用します。They contain information (claims) that web APIs secured by the Microsoft identity platform, like Microsoft Graph, use to validate the caller and to ensure that the caller has the proper permissions to perform the operation they're requesting. Microsoft Graph の呼び出し時には、アクセス トークンを不透明なものとして扱うことができます。When calling Microsoft Graph, you can treat access tokens as opaque. アクセス トークンは、常にトランスポート層セキュリティ (HTTPS) などのセキュリティで保護されたチャネルを通じて送信する必要があります。You should always transmit access tokens over a secure channel, such as transport layer security (HTTPS).

Microsoft ID プラットフォームのアクセス トークンの例を次のとおりです。The following is an example of a Microsoft identity platform access token:

EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/oeJX6U8nnL9nJ5pHLVuPWD0aNnTPTJD8Y4oQTp5zLhDIIfaJCaGcQperULVF7K6yX8MhHxIBwek418rKIp11om0SWBXOYSGOM0rNNN59qNiKwLNK+MPUf7ObcRBN5I5vg8jB7IMoz66jrNmT2uiWCyI8MmYDZgAACPoaZ9REyqke+AE1/x1ZX0w7OamUexKF8YGZiw+cDpT/BP1GsONnwI4a8M7HsBtDgZPRd6/Hfqlq3HE2xLuhYX8bAc1MUr0gP9KuH6HDQNlIV4KaRZWxyRo1wmKHOF5G5wTHrtxg8tnXylMc1PKOtaXIU4JJZ1l4x/7FwhPmg9M86PBPWr5zwUj2CVXC7wWlL/6M89Mlh8yXESMO3AIuAmEMKjqauPrgi9hAdI2oqnLZWCRL9gcHBida1y0DTXQhcwMv1ORrk65VFHtVgYAegrxu3NDoJiDyVaPZxDwTYRGjPII3va8GALAMVy5xou2ikzRvJjW7Gm3XoaqJCTCExN4m5i/Dqc81Gr4uT7OaeypYTUjnwCh7aMhsOTDJehefzjXhlkn//2eik+NivKx/BTJBEdT6MR97Wh/ns/VcK7QTmbjwbU2cwLngT7Ylq+uzhx54R9JMaSLhnw+/nIrcVkG77Hi3neShKeZmnl5DC9PuwIbtNvVge3Q+V0ws2zsL3z7ndz4tTMYFdvR/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==

Microsoft Graph を呼び出す場合は、アクセス トークンをベアラー トークンとして HTTP 要求の Authorization ヘッダーに添付します。To call Microsoft Graph, you attach the access token as a Bearer token to the Authorization header in an HTTP request. その例として、サインインしているユーザーのプロファイル情報を返す呼び出しを次に示します (読みやすくするために、アクセス トークンは短くされています)。For example, the following call that returns the profile information of the signed-in user (the access token has been shortened for readability):

HTTP/1.1
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==
Host: graph.microsoft.com`
GET https://graph.microsoft.com/v1.0/me/

Microsoft ID プラットフォームにアプリを登録するRegister your app with the Microsoft identity platform

アプリが Microsoft ID プラットフォームからトークンを取得する前に、Azure ポータルに登録する必要があります。Before your app can get a token from the Microsoft identity platform, it must be registered in the Azure portal. 登録によりアプリが Microsoft ID プラットフォームと統合され、次のようなトークンを取得する際に使用する情報を確立します。Registration integrates your app with the Microsoft identity platform and establishes the information that it uses to get tokens, including:

  • アプリケーション ID: Microsoft ID プラットフォームによって割り当てられた一意の識別子。Application ID: A unique identifier assigned by the Microsoft identity platform.
  • リダイレクト URI または URL: アプリが Microsoft ID プラットフォームから応答を受信する 1 つまたは複数のエンドポイントRedirect URI/URL: One or more endpoints at which your app will receive responses from the Microsoft identity platform. (ネイティブ アプリとモバイル アプリにおいては、Microsoft ID プラットフォームが割り当てた URI です)。(For native and mobile apps, this is a URI assigned by the Microsoft identity platform.)
  • アプリケーション シークレット: アプリが Microsoft ID プラットフォームでの認証に使用するパスワードまたは公開鍵や秘密鍵のペアApplication Secret: A password or a public/private key pair that your app uses to authenticate with the Microsoft identity platform. (ネイティブ アプリまたはモバイル アプリの場合は不要です)。(Not needed for native or mobile apps.)

登録時には構成済みのプロパティが要求で使用されます。The properties configured during registration are used in the request. たとえば、次に示すトークン要求の場合、client_idアプリケーション IDredirect_uri はアプリの登録済リダイレクト URI の 1 つ、client_secretアプリケーション シークレットです。For example, in the following token request: client_id is the Application ID, redirect_uri is one of your app's registered Redirect URIs, and client_secret is the Application Secret.

// Line breaks for legibility only

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Microsoft Graph のアクセス許可Microsoft Graph permissions

Microsoft Graph はユーザー、グループ、メールなどのリソースに対するアプリのアクセス権を制御する詳細なアクセス許可を公開します。Microsoft Graph exposes granular permissions that control the access that apps have to resources, like users, groups, and mail. 開発者は Microsoft Graph に要求するアクセス許可を決定します。As a developer, you decide which permissions to request for Microsoft Graph. アプリにサインインした場合、そのアクセス許可に同意するか否かは、ユーザーか、場合によっては管理者が決定します。When a user signs in to your app they, or, in some cases, an administrator, are given a chance to consent to these permissions. ユーザーが同意すると、アプリは必要なリソースと API にアクセスできるようになります。If the user consents, your app is given access to the resources and APIs that it has requested. サインイン ユーザーを必要としないアプリの場合、アクセス許可は、アプリのインストール時に管理者が事前に同意できます。For apps that don't take a signed-in user, permissions can be pre-consented to by an administrator when the app is installed.

Microsoft Graph には次の 2 つの種類のアクセス許可があります。Microsoft Graph has two types of permissions:

  • 委任されたアクセス許可は、サインインしているユーザーが存在するアプリで使用します。Delegated permissions are used by apps that have a signed-in user present. これに該当するアプリの場合は、ユーザーまたは管理者がアプリの要求するアクセス許可に同意します。アプリには、Microsoft Graph の呼び出し時に、サインインしているユーザーとして動作できます。For these apps either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making calls to Microsoft Graph. 一部の委任されたアクセス許可は非管理ユーザーの同意によって付与できますが、高度な特権が付与されるアクセス許可には管理者の同意が必要になります。Some delegated permissions can be consented by non-administrative users, but some higher-privileged permissions require administrator consent.

  • アプリケーションのアクセス許可は、サインインしているユーザーが存在しないアプリで使用します。たとえば、バックグラウンド サービスやデーモンとして実行されるアプリです。Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. アプリケーションのアクセス許可には、管理者のみ同意できます。Application permissions can only be consented by an administrator.

_有効なアクセス許可_は、アプリが Microsoft Graph に要求を出すときに付与されるアクセス許可です。アプリに付与される委任されたアクセス許可とアプリケーションのアクセス許可の相違点について理解することに加えて、Microsoft Graph の呼び出し時の有効なアクセス許可についても理解することが重要です。Effective permissions are the permissions that your app will have when making requests to Microsoft Graph. It is important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to Microsoft Graph.

  • 委任されたアクセス許可の場合、アプリの有効なアクセス許可は、アプリに付与されている委任されたアクセス許可 (同意によって付与) と現在サインインしているユーザーの特権が重なる範囲に収まります。For delegated permissions, the effective permissions of your app will be the intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. サインインしているユーザーよりも多くの特権がアプリに付与されることはありません。Your app can never have more privileges than the signed-in user. 組織では、サインインしているユーザーの特権は、ポリシーで決まることもあれば、1 つ以上の管理者ロールのメンバーシップで決まることもあります。Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. 管理者ロールに関する詳細については、「Azure Active Directory での管理者ロールの割り当て」を参照してください。For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

    たとえば、委任されたアクセス許可として User.ReadWrite.All がアプリに付与されているとします。For example, assume your app has been granted the User.ReadWrite.All delegated permission. 通常、このアクセス許可は、組織内の全ユーザーのプロフィールを読み取り、更新するアクセス許可をアプリに付与します。This permission nominally grants your app permission to read and update the profile of every user in an organization. サインインしているユーザーが全体管理者の場合、アプリは、組織内のすべてのユーザーのプロファイルを更新できるようになります。If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. ただし、サインインしているユーザーが管理者ロールに含まれていない場合、アプリは、そのサインインしているユーザーのプロファイルのみを更新できるようになります。However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. 組織にいる他のユーザーのプロフィールは更新できません。アプリが代理するアクセス許可を持つユーザーに、そういった権限が付与されていないためです。It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.

  • アプリケーションのアクセス許可の場合、アプリの有効なアクセス許可は、そのアクセス許可が暗示する完全なレベルの権限になります。For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. たとえば、アプリケーションのアクセス許可として User.ReadWrite.All が付与されているアプリは、組織内の全ユーザーのプロフィールを更新できます。For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

既定では、次のデータ セットに対するアプリケーション アクセス許可が与えられているアプリは、組織内のすべてのメールボックスにアクセスできます。Note By default, apps that have been granted application permissions to the following data sets can access all the mailboxes in the organization:

管理者はアプリケーション アクセス ポリシーを構成して、アプリのアクセスを_特定_のメールボックスに制限することができます。Administrators can configure application access policy to limit app access to specific mailboxes.

Microsoft Graph に委任されたアクセス許可とアプリケーションのアクセス許可の詳細なリスト、管理者の同意が必要なアクセス許可については、「アクセス許可のリファレンス」を参照してください。For a complete list of delegated and application permissions for Microsoft Graph, as well as which permissions require administrator consent, see the Permissions reference.

アクセス トークンの取得Getting an access token

多くの開発者と同じように、認証ライブラリを使用し、Microsoft ID プラットフォームとのトークンの連携を管理することになります。Like most developers, you will probably use authentication libraries to manage your token interactions with the Microsoft identity platform. 認証ライブラリは、開発者からプロトコルの詳細の多く (検証、Cookie の処理、トークンのキャッシュ、安全な接続の維持など) を取り去り、アプリの開発に集中できるようにします。Authentication libraries abstract many protocol details, like validation, cookie handling, token caching, and maintaining secure connections, away from the developer and let you focus your development on your app. Microsoft はオープン ソース クライアント ライブラリとサーバー ミドルウェアを公開します。Microsoft publishes open source client libraries and server middleware.

Microsoft ID プラットフォームのエンドポイントの場合:For the Microsoft identity platform endpoint:

  • Microsoft Authentication Library (MSAL) クライアント ライブラリは、.NET、JavaScript、Android、および Objective-c で利用できます。すべてのプラットフォームが実稼働対応のプレビューであり、大きな変更が導入されていますが、Microsoft によりアップグレードの経路が保証されています。Microsoft Authentication Library (MSAL) client libraries are available for .NET, JavaScript, Android, and Objective-c. All platforms are in production-supported preview, and, in the event breaking changes are introduced, Microsoft guarantees a path to upgrade.
  • Microsoft のサーバー ミドルウェアは .NET コア、ASP.NET (OWIN OpenID Connect および OAuth)、Node.js (Microsoft ID プラットフォーム Passport.js) で利用できます。Server middleware from Microsoft is available for .NET core and ASP.NET (OWIN OpenID Connect and OAuth) and for Node.js (Microsoft the Microsoft identity platform Passport.js).
  • Microsoft ID プラットフォームには、多数のサード パーティ製認証ライブラリとの互換性があります。The Microsoft identity platform is compatible with many third-party authentication libraries.

Microsoft クライアント ライブラリ、Microsoft サーバー ミドルウェア、および互換性のあるサード パーティ製ライブラリの完全なリストについては、「Microsoft ID プラットフォームの認証ライブラリ」を参照してください。For a complete list of Microsoft client libraries, Microsoft server middleware, and compatible third-party libraries, see Microsoft identity platform authentication libraries.

認証ライブラリを使用してアクセス トークンを取得する必要はありません。You do not need to use an authentication library to get an access token. 認証ライブラリを使わずに Microsoft ID プラットフォームのエンドポイントを直接使用する方法については、「Microsoft ID プラットフォーム認証」を参照してください。To learn about directly using the Microsoft identity platform endpoints without the help of an authentication library, see Microsoft identity platform authentication

次の手順Next steps

コードの作成準備が整ったら、次に示すリソースを使用できるようになります。これらのリソースは、Microsoft ID プラットフォームによる認証と承認をアプリに実装する際に役立ちます。If you're ready to jump into code, you can use the following resources to help you implement authentication and authorization with the Microsoft identity platform in your app.

Microsoft Graph のトレーニングとサンプルMicrosoft Graph training and samples

すぐに使い始められるように、さまざまなプラットフォームで API を認証し使用する方法を示した、一連のトレーニング モジュールとその他のリソースを作成しました。To help you get started quickly, we've created a series of training modules and other resources that show you how to authenticate and use the API on a variety of platforms.

  • [概要] ページで、お好みのプラットフォーム向けのライブラリ、サンプル、トレーニング コンテンツなどのリソースを見つけてください。Use the Get started page to find the libraries, samples, training content, and other resources for your favorite platform.
  • お使いのプラットフォーム向けに構成済みのサンプルをすぐに実行するには、「Microsoft Graph のクイック スタート」を参照してください。To get running quickly with a pre-configured sample for your platform, see the Microsoft Graph Quick Start.
  • GitHub では Microsoft Graph サンプルを公開しています。See our Microsoft Graph samples on GitHub.

Microsoft ID プラットフォーム サンプルとドキュメントMicrosoft identity platform samples and documentation

Microsoft ID プラットフォームのドキュメントには、特に Microsoft ID プラットフォームでの認証と承認に焦点を合わせた記事とサンプルが含まれています。The Microsoft identity platform documentation contains articles and samples that specifically focus on authentication and authorization with the Microsoft identity platform.

関連項目See also