Office アドインで OAuth 認証フレームワークを使用するUse the OAuth authorization framework in an Office Add-in

OAuth は、Office 365、Facebook、Google、SalesForce、LinkedIn などのオンライン サービス プロバイダーがユーザー認証を実行するのに使用する認証のオープン標準です。OAuth 認証フレームワークは、Azure と Office 365 で使用される既定の認証プロトコルです。OAuth 認証フレームワークは、エンタープライズ (企業) とコンシューマー シナリオの両方で使用されます。OAuth is the open standard for authorization that online service providers such as Office 365, Facebook, Google, SalesForce, LinkedIn and others use to perform user authentication. The OAuth authorization framework is the default authorization protocol used in Azure and Office 365. The OAuth authorization framework is used in both enterprise (corporate) and consumer scenarios.

オンライン サービス プロバイダーは、REST 経由で公開されているパブリックの Api を提供することができます。Online service providers may provide public APIs exposed via REST. 開発者は、オンライン サービス プロバイダーにデータを読み書きする、Office アドインでこれらのパブリック Api を使用できます。Developers can use these public APIs in their Office Add-ins to read or write data to the online service provider. アドインでのオンライン サービス プロバイダーからのデータを統合すること、その価値を幅広く導入してユーザーに潜在顧客が増加します。Integrating data from online service providers in an add-in increases its value, which leads to greater user adoption. アドインでこれらの Api を使用するときにユーザーを OAuth 認証フレームワークを使用して認証する必要があります。When using these APIs in your add-in, users will be required to authenticate using the OAuth authorization framework.

このトピックでは、アドインで認証フローを実装して、ユーザー認証を実行する方法について説明します。このトピックに含まれているコード セグメントは、Office-Add-in-NodeJS-ServerAuth のコード サンプルから採用されています。This topic describes how to implement an authentication flow in your add-in to perform user authentication. Code segments included in this topic are taken from the Office-Add-in-NodeJS-ServerAuth code sample.

注意

セキュリティ上の理由から、ブラウザーは IFrame のサインイン ページを表示できません。お客様が使用している Office のバージョンによって、特に Web ベースのバージョンによっては、アドインは IFrame で表示されます。これは、認証フローを管理する方法におけるいくつかの考慮事項を提起します。For security reasons, browsers are not allowed to display sign-in pages in an IFrame. Depending on the version of Office that your customers use, most notably web-based versions, your add-in is displayed in an IFrame. This imposes some considerations on how to manage the authentication flow.

次のダイアグラムは、必要なコンポーネントと、アドインで認証を実装するときに発生するイベントのフローを示します。The following diagram shows the required components and the flow of events that occur when implementing authentication in your add-in.

Office アドインでの OAuth 認証の実行

ダイアグラムは、次の必要なコンポーネントを使用する方法を示しています。The diagram shows how the following required components are used:

  • Office は作業ウィンドウ アドインをユーザーのコンピューター上で実行します。アドインは、認証フローを開始するためのポップアップ ウィンドウを開きます。使用するプラットホームによりますが、アドインは IFRAME で実行される可能性があるため、アドインが認証フローを直接開始することはできません。セキュリティ上の理由から、OAuth サインイン ページは IFRAME に表示できません。Office runs a task pane add-in on the user's computer. Your add-in opens a pop-up window to start the authentication flow. Add-ins cannot start authentication flows directly because add-ins, depending on the platform used, may run in an IFRAME. For security reasons, OAuth sign-in pages can't be displayed in an IFRAME.

  • Web サーバーはアドインのコードをホストします。このコード サンプルでは、ユーザーのアクセス トークンを格納するために Web サーバーで実行されているデータベース サーバーを使用します。アクセス トークンの保持が必要です。そうすれば、ポップアップ ウィンドウを使用して認証が完了した後、メインのアドインのページが同じトークンを使用してオンライン サービスからのデータにアクセスできます。アドインまたはポップアップから渡される情報に依存できないため、サーバー側のオプションを使用してトークンを保存することが必要です。A web server hosts your add-in's code. This code sample uses a database server running on the web server to store the user's access token. Persisting the access token is necessary so that after authentication completes using the pop-up window, the main add-in's pages can use the same tokens to access data from the online service. Saving the tokens by using server-side options is necessary because you can't rely on information passed from the add-in or the pop-up.

  • OAuth 2.0 プロバイダーはユーザー認証を行います。The OAuth 2.0 provider performs user authentication.

重要

アクセス トークンは作業ウィンドウに返すことはできませんが、サーバー上で使用することができます。このコード サンプルでは、アクセス トークンはデータベースに 2 分間保存されます。2 分後、トークンは、データベースから削除され、ユーザーは再認証するよう求められます。独自の実装でこの期間を変更する前に、2 分よりも長い期間データベースにアクセス トークンを格納する場合のセキュリティ上のリスクを考慮してください。Access tokens can't be returned to the task pane, but they can be used on the server. In this code sample, the access tokens are stored in the database for 2 minutes. After 2 minutes, tokens are purged from the database and users are prompted to re-authenticate. Before changing this time period in your own implementation, consider the security risks associated with storing access tokens in a database for a time period that is longer than 2 minutes.

手順 1 - ソケットを開始してポップアップ ウィンドウを開くStep 1 - Start socket and open a pop-up window

このコード サンプルを実行すると、Office で作業ウィンドウ アドインが表示されます。ユーザーがログインするのに OAuth プロバイダーを選択すると、アドインはまずソケットを作成します。このサンプルでは、アドインで優れたユーザー エクスペリエンスを提供するためにソケットを使用します。アドインは、ユーザーに認証の成否を伝達するためにソケットを使用します。ソケットを使用すれば、アドインのメイン ページは認証状態で簡単に更新され、ユーザーの操作またはポーリングを必要としません。routes/connect.js から取られた次のコード セグメントでは、ソケットを開始する方法を示します。ソケットには、アドインのセッション ID である decodedNodeCookie を使用して名前を付けます。このコード サンプルは、socket.io を使用してソケットを作成します。When you run this code sample, a task pane add-in displays in Office. When the user chooses an OAuth provider to log into, the add-in first creates a socket. This sample uses a socket to provide a good user experience in the add-in. The add-in uses the socket to communicate the success or failure of the authentication to the user. By using a socket, the add-in's main page is easily updated with the authentication status, and doesn't require user interaction or polling. The following code segment, taken from routes/connect.js, shows how to start the socket. The socket is named using decodedNodeCookie, which is the add-in's session ID. This code sample creates the socket by using socket.io.

io.on('connection', function (socket) {
  console.log('Socket connection established');
  var jsonCookie =
    cookie.parse(socket
      .handshake
      .headers
      .cookie);
  var decodedNodeCookie =
    cookieParser
      .signedCookie(jsonCookie.nodecookie, '<Insert a random string>');
  console.log('Decoded cookie: ' + decodedNodeCookie);
  // The session ID becomes the room name for this session.
  socket.join(decodedNodeCookie);
  io.to(decodedNodeCookie).emit('init', 'Private socket session established');
});

次に、アドインはソケットに接続します。次のコードが /public/javascripts/client.js にあります。Next, the add-in connects to the socket. The following code can be found in /public/javascripts/client.js.

var socket = io.connect('https://localhost:3001', { secure: true });

次に、アドインは、window.open を使用してユーザーのコンピューター上でポップアップ ウィンドウを開きます。window.open を実行する場合、リダイレクト URI とアドインのセッション ID が URL で渡されるようにします。アドインのセッション ID は、アドインの UI に認証状態情報を送信するときに、使用するソケットを指定するために使用されます。次のコード セグメントが、views/index.jade にあります。Next, the add-in opens a pop-up window on the user's computer using window.open. When running window.open, ensure the redirect URI and session ID of the add-in is passed in the URL. The session ID of the add-in is used to identify the socket to use when sending authentication status information to the add-in's UI. The following code segment can be found in views/index.jade.

onclick="window.open('/connect/azure/#{sessionID}', 'AuthPopup', 'width=500,height=500,centerscreen=1,menubar=0,toolbar=0,location=0,personalbar=0,status=0,titlebar=0,dialog=1')")

手順 2 と 3 - 認証フローを開始して、サインイン ページを表示する&Steps 2 & 3 - Start the authentication flow and show the sign-in page

アドインは認証フローを開始する必要があります。次のコード セグメントでは、Passport OAuth ライブラリを使用します。認証フローを開始するときは、OAuth プロバイダーの認証 URL と、アドインのセッション ID を渡すことを確認します。アドインのセッション ID は、State パラメーターで渡す必要があります。ポップアップ ウィンドウに、ユーザーがサインインするための OAuth プロバイダーのサインイン ページが表示されます。The add-in must start the authentication flow. The code segment below uses the Passport OAuth library. When starting the authentication flow, ensure that you pass the authorization URL of the OAuth provider, and the session ID of the add-in. The session ID of the add-in must be passed in the state parameter. The pop-up window now displays the OAuth provider's sign-in page so that users can sign in.

router.get('/azure/:sessionID', function(req, res, next) { 
   passport.authenticate( 
     'azure',  
     { state: req.params.sessionID }, 

手順 4、5、6 - ユーザーがサインインして、Web サーバーでトークンを受信する&Steps 4, 5 & 6 - User signs in and web server receives tokens

正常にサインインした後で、アクセス トークン、リフレッシュ トークン、State パラメーターがアドインに返されます。State パラメーターには、セッション ID が含まれます。これは、手順 7 でソケットへ認証状態情報を送信するために使用されます。app.js から取られた次のコード セグメントは、データベースにアクセス トークンを格納します。After a successful sign-in, an access token, refresh token, and state parameter are returned to the add-in. The state parameter contains the session ID, which is used to send authentication status information to the socket in step 7. The following code segment, taken from app.js, stores the access token in the database.

  dbHelperInstance.insertDoc(userData, null, 
         function (err, body) { 
           if (!err) { 
             console.log("Inserted session entry [" + userData.sessid + "] id: " + body.id); 
           } 
           done(err, userData); 
         }); 

手順 7 - アドインの UI で認証情報を表示するStep 7 - Show authentication information in the add-in's UI

connect.js から取られた次のコード セグメントは、認証状態情報を使用してアドインの UI を更新します。手順 1 で作成されたソケットを使用して、アドインの UI が更新されます。The following code segment, taken from connect.js, updates the add-in's UI with the authentication status information. The add-in's UI is updated by using the socket that was created in step 1.


       io.to(user.sessid).emit('auth_success', providers); 
       next(); 

関連項目See also