Office アドインで外部サービスを承認するAuthorize external services in your Office Add-in

大手のオンライン サービス (Office 365、Google、Facebook、LinkedIn、SalesForce、GitHub など) では、開発者は、ユーザーが自分のアカウントに別のアプリケーションからアクセスできるようにすることが可能です。これにより、開発者は、これらのサービスを Office アドインに含めることができるようになります。Popular online services, including Office 365, Google, Facebook, LinkedIn, SalesForce, and GitHub, let developers give users access to their accounts in other applications. This gives you the ability to include these services in your Office Add-in.

Web アプリケーションからオンライン サービスへのアクセスを可能にするための業界標準のフレームワークは OAuth 2.0 です。ほとんどの場合、このフレームワークをアドインで使用するために、その動作のしくみを詳しく知る必要はありません。開発者は、この詳細を簡略化している多数のライブラリを使用できます。The industry standard framework for enabling web application access to an online service is OAuth 2.0. In most situations, you don't need to know the details of how the framework works to use it in your add-in. Many libraries are available that simplify the details for you.

OAuth の基本的な考え方は、ユーザーやグループと同様に、アプリケーションは専用の ID とアクセス許可のセットによって、それ自体がセキュリティ プリンシパルになり得るということです。通常のシナリオでは、ユーザーがオンライン サービスを必要とする Office アドインのアクションを実行すると、アドインは、ユーザーのアカウントへ特定のセットのアクセス許可を付与するよう求める要求をサービスに送信します。サービスは、該当するアクセス許可をアドインに付与するように求めるプロンプトをユーザーに表示します。アクセス許可が付与されると、サービスは小さなエンコードされたアクセス トークンをアドインに送信します。アドインは、サービスの API へのすべての要求にトークンを含めることで、サービスを使用できるようになります。ただし、そのアドインが実行できるアクションは、ユーザーが付与したアクセス許可の範囲内に限定されます。また、トークンは特定の時間が経過すると期限切れになります。A fundamental idea of OAuth is that an application can be a security principal unto itself, just like a user or a group, with its own identity and set of permissions. In the most typical scenarios, when the user takes an action in the Office add-in that requires the online service, the add-in sends the service a request for a specific set of permissions to the user's account. The service then prompts the user to grant the add-in those permissions. After the permissions are granted, the service sends the add-in a small encoded access token. The add-in can use the service by including the token in all its requests to the service's APIs. But the add-in can act only within the permissions that the user granted it. The token also expires after a specified time.

さまざまなシナリオに向けて、フローまたは許可の種類と呼ばれる、いくつかの OAuth パターンが設計されています。Several OAuth patterns, called flows or grant types, are designed for different scenarios. 最も一般的な実装パターンは次の 2 つです。The following two patterns are the most commonly implemented:

  • 暗黙的フロー: アドインとオンライン サービスとの通信は、クライアント側の JavaScript で実装されます。Implicit flow: Communication between the add-in and the online service is implemented with client-side JavaScript.
  • 認証コード フロー: アドインの Web アプリケーションとオンライン サービスとの通信は、サーバー間で行われます。そのため、これはサーバー側のコードで実装されます。Authorization Code flow: Communication is server-to-server between your add-in's web application and the online service. So, it is implemented with server-side code.

OAuth フローの目的は、アプリケーションの ID と承認の安全を確保することです。認証コード フローでは、クライアント シークレットが提供されます。これは、秘密にしておく必要があります。単一ページ アプリケーション (SPA) には、シークレットを保護する方法がありません。そのため、SPA には暗黙的フローを使用するようにお勧めします。The purpose of an OAuth flow is to secure the identity and authorization of the application. In the Authorization Code flow, you're provided a client secret that needs to be kept hidden. A Single Page Application (SPA) has no way to protect the secret, so we recommend that you use the Implicit flow in SPAs.

暗黙的フローと認証コード フローのメリットとデメリットについて理解しておく必要があります。You should be familiar with the pros and cons of the Implicit flow and the Authorization Code flow. これら 2 つのフローの詳細については、「認証コード フロー」と「暗黙的フロー」を参照してください。For more infomation about these two flows, see Authorization Code and Implicit.

注意

仲介者サービスを使用するというオプションもあります。このサービスは、自動的に承認を行い、アドインにアクセス トークンを渡します。You also have the option of using a middleman service to perform authorization and pass the access token to your add-in. このシナリオの詳細については、後述の「仲介者サービス」セクションを参照してください。For details about this scenario, see the Middleman services section later in this article.

Microsoft Graph への承認Authorization to Microsoft Graph

Microsoft Graph を使用して Office 365 や OneDrive などの外部サービスにアクセスできる場合、「Office アドインのシングル サインオンを有効化する」とその関連記事に記載されているシングル サインオン システムを使用することにより、ユーザーには最適な、そして開発者には最も簡単な開発経験が得られます。If the external service is accessible through Microsoft Graph, such as Office 365 or OneDrive, then you can provide the best experience for your users, and the easiest development experience for yourself, by using the single sign-on system described at Enable single sign-on for Office Add-ins and its related articles. この記事に記載されている手法は、Microsoft Graph を使用してアクセスできない外部サービスに最適です。The techniques described in this article are best used for external services that are not accessible with Microsoft Graph. ただし、Microsoft Graph にアクセスするためにそれらの手法を使用することもできます。そのため、シングル サインオンの利点よりも、それらを好まれるかもしれません。However, they can be used to access Microsoft Graph, and you might prefer them to the advantages of single sign-on. たとえば、シングル サインオン システムにはサーバー側のコードが必要であるため、真の単一ページのアプリでは使用できません。For example, the single sign-on system requires server-side code, so it cannot be used with a true single page app. また、シングル サインオン システムは一部のプラットフォームではまだサポートされていません。Also, the single sign-on system is not yet supported on all platforms.

Office アドインに暗黙的フローを使用するUsing the Implicit flow in Office Add-ins

オンライン サービスが暗黙的フローをサポートしているかどうかを判断する最良の方法は、サービスのドキュメントを調べることです。The best way to find out if an online service supports the Implicit flow is to consult the service's documentation. サービスが暗黙的フローをサポートしている場合、Office-js-helpers Javascript ライブラリを使って細かい作業を行うことができます。For services that support the Implicit flow, you can use the Office-js-helpers JavaScript library to do all the detailed work for you:

暗黙的フローをサポートするその他のライブラリの詳細については、後述の「ライブラリ」セクションを参照してください。For information about other libraries that support the Implicit flow, see the Libraries section later in this article.

Office アドインに認証コード フローを使用するUsing the Authorization Code flow in Office Add-ins

各種の言語とフレームワークで認証コード フローを実装するために利用できるライブラリは多数あります。これらのライブラリの詳細については、後述の「ライブラリ」セクションを参照してください。Many libraries are available for implementing the Authorization Code flow in various languages and frameworks. For more information about some of these libraries, see the Libraries section later in this article.

次のサンプルでは、認証コード フローを実装するアドインの例を示します。The following samples provide examples of add-ins that implement the Authorization Code flow:

Relay 関数と Proxy 関数Relay/Proxy functions

サーバーなしの Web アプリケーションでも、サービスでホストされる簡単な関数 (Azure FunctionsAmazon Lambda など) でクライアント IDクライアント シークレットの値を使用すると、認証コード フローを使用できます。この関数は、特定のコードをアクセス トークンに交換して、それを中継してクライアントに戻します。このアプローチのセキュリティは、関数へのアクセスが、どの程度適切に保護されているかによって異なります。You can use the Authorization Code flow even with a serverless web application by storing the client ID and client secret values in a simple function that is hosted in a service such as Azure Functions or Amazon Lambda. The function exchanges a given code for an access token and relays it back to the client. The security of this approach depends on how well access to the function is guarded.

この技法を使用する場合は、アドインでオンライン サービス (Google や Facebook など) のログイン画面を示す UI やポップアップを表示します。ユーザーがオンライン サービスにサインインして、自分のリソースへのアクセス許可をアドインに付与すると、アドインはオンライン関数に送信できるコードを受信します。後述の「仲介者サービス」セクションで説明しているサービスでも同様のフローを使用します。To use this technique, your add-in displays a UI/popup to show the login screen for the online service (Google, Facebook, and so on). When the user signs in and grants the add-in permission to her resources in the online service, the add-in receives a code which can be then sent to the online function. The services described in the Middleman services section later in this article use a similar flow.

ライブラリLibraries

各種の言語とプラットフォームで暗黙的フローと認証コード フローを実装するために利用できるライブラリが多数あります。Libraries are available for many languages and platforms, for both the Implicit flow and the Authorization Code flow. ライブラリには汎用のものや、特定のオンライン サービス向けのものがあります。Some libraries are general purpose, while others are for specific online services.

認証プロバイダーとして Azure Active Directory を使用する Office 365 などのサービス:Azure Active Directory 認証ライブラリMicrosoft 認証ライブラリのプレビュー版も利用できます。Office 365 and other services that use Azure Active Directory as the authorization provider: Azure Active Directory Authentication Libraries. A preview is also available for the Microsoft Authentication Library.

Google:GitHub.com/Google で "auth" または目的の言語の名前を検索します。最も関連のあるリポジトリには、google-auth-library-[name of language] という名前が付いています。Google: Search GitHub.com/Google for "auth" or the name of your language. Most of the relevant repos are named google-auth-library-[name of language].

Facebook:Facebook for Developers で "library" または "sdk" を検索します。Facebook: Search Facebook for Developers for "library" or "sdk".

汎用の OAuth 2.0:数十の言語に対応したライブラリへのリンクが、「OAuth Code」のページに掲載されています。このページは、IETF OAuth 作業部会によって維持されています。これらのライブラリの一部は、OAuth 準拠のサービスを実装するためのものです。アドイン開発者にとって重要なライブラリは、このページに記載されたクライアントと呼ばれるライブラリです。これは、目的の Web サーバーが OAuth 準拠のサービスのクライアントになるためです。General OAuth 2.0: A page of links to libraries for over a dozen languages is maintained by the IETF OAuth Working Group at: OAuth Code. Note that some of these libraries are for implementing an OAuth compliant service. The libraries of interest to you as a an add-in developer are called client libraries on this page because your web server is a client of the OAuth compliant service.

仲介者サービスMiddleman services

アドインでは、OAuth.io や Auth0 などの仲介者サービスを使用して、承認を行うことができます。このサービスは、大手オンライン サービスに対応したアクセス トークンを提供するものか、アドインでソーシャル ログインできるようにするプロセスを簡単にするもの (またはその両方) です。短いコードを使用することで、仲介者サービスに接続するクライアント側スクリプトやサーバー側コードをアドインで使用できるようになり、仲介者サービスがオンライン サービスに必要なトークンをアドインに送信します。すべての承認の実装コードは、仲介者サービスに含まれています。Your add-in can use a middleman service such as OAuth.io or Auth0 to perform authorization. A middleman service may either provide access tokens for popular online services or simplify the process of enabling social login for your add-in, or both. With very little code, your add-in can use either client-side script or server-side code to connect to the middleman service and it will send your add-in any required tokens for the online service. All of the authorization implementation code is in the middleman service.

承認に仲介者サービスを使用しているアドインの例を次に示します。For examples of add-ins that use a middleman service for authorization, see the following samples:

  • Office-Add-in-Auth0 では、Auth0 を使用して Facebook、Google、Microsoft のアカウントへのソーシャル ログインを可能にしています。Office-Add-in-Auth0 uses Auth0 to enable social login with Facebook, Google, and Microsoft Accounts.

  • Office-Add-in-OAuth.io では、OAuth.io を使用して、Facebook と Google からのアクセス トークンを取得します。Office-Add-in-OAuth.io uses OAuth.io to get access tokens from Facebook and Google.

CORS とはWhat is CORS?

CORS は Cross Origin Resource Sharing の略です。アドイン内で CORS を使用する方法の詳細については、「Office アドインにおける同一生成元ポリシーの制限への対処」を参照してください。CORS stands for Cross Origin Resource Sharing. For information about how to use CORS inside add-ins, see Addressing same-origin policy limitations in Office Add-ins.