Office アドインにおける認証と承認の概要

Office アドインでは、既定で匿名アクセスが許可されますが、ユーザーに対して、アドインを使用するために Microsoft アカウント、Microsoft 365 Education または職場アカウント、その他の一般的なアカウントでサインインすることを要求できます。 これによりユーザーの確認がアドインで可能になることから、このタスクはユーザー認証と呼ばれています。

アドインは、Microsoft Graph データ (Microsoft 365 プロファイル、OneDrive ファイル、SharePoint データなど) や、Google、Facebook、LinkedIn、SalesForce、GitHub などの他の外部ソースのデータにアクセスするユーザーの同意を得ることもできます。 このタスクは、ユーザーではなく、承認されている アドイン であるため、アドイン (またはアプリ) 承認と呼ばれます。

認証と承認のための主要なリソース

このドキュメントでは、認証と承認を正常に実装するために Office アドインを作成および構成する方法について説明します。 ただし、言及されている多くの概念とセキュリティ テクノロジは、このドキュメントの範囲外です。 たとえば、OAuth フロー、トークン キャッシュ、ID 管理などの一般的なセキュリティの概念については、ここでは説明しません。 このドキュメントでは、Microsoft Azure やMicrosoft ID プラットフォームに固有のドキュメントも含まれません。 これらの領域の詳細情報が必要な場合は、次のリソースを参照することをお勧めします。

• Microsoft ID プラットフォーム
• Microsoft ID プラットフォームのサポートとヘルプ オプション
• Microsoft ID プラットフォームにおける OAuth 2.0 と OpenID Connect プロトコル

SSO のシナリオ

シングル サインオン (SSO) を使用すると、Office に 1 回サインインするだけで済むため、ユーザーにとって便利です。 アドインに個別にサインインする必要はありません。 SSO はすべてのバージョンの Office でサポートされているわけではありません。そのため、Microsoft ID プラットフォームを使用して別のサインイン 方法を実装する必要があります。 サポートされている Office バージョンの詳細については、「Identity API 要件セット」を参照してください。

SSO を使用してユーザーの ID を取得する

多くの場合、アドインではユーザーの ID のみが必要です。 たとえば、アドインをカスタマイズして、ユーザーの名前を作業ウィンドウに表示するだけという場合があります。 または、データベース内のデータにユーザーを関連付けるために一意の ID が必要な場合があります。 これは、Office からユーザーのアクセス トークンを取得するだけで実現できます。

SSO を使用してユーザーの ID を取得するには、getAccessToken メソッドを呼び出します。 このメソッドは、preferred_username、name、sub、oid などの、現在サインインしているユーザーに固有のいくつかの要求を含む ID トークンでもあるアクセス トークンを返します。 これらのプロパティの詳細については、「Microsoft ID プラットフォームの ID トークン」を参照してください。 getAccessToken によって返されるトークンの例については、「アクセス トークンの例」を参照してください。

ユーザーがサインインしていない場合、Office はダイアログ ボックスを開き、Microsoft ID プラットフォームを使用してユーザーにサインインを要求します。 その後、メソッドによってアクセス トークンが返されるか、ユーザーをサインインできない場合はエラーがスローされます。

ユーザーのデータを格納する必要があるシナリオでは、トークンから値を取得してユーザーを一意に識別する方法の詳細について、「Microsoft ID プラットフォームの ID トークン」を参照してください。 この値を使用して、管理しているユーザー テーブルまたはユーザー データベース内のユーザーを参照します。 ユーザー設定やユーザーのアカウントの状態などのユーザー関連情報を格納するには、データベースを使用します。 SSO を使用しているため、ユーザーはアドインに個別にサインインしないため、ユーザーのパスワードを保存する必要はありません。

SSO を使用したユーザー認証の実装を開始する前に、「 Office アドインのシングル サインオンを有効にする」の記事をよく理解しておいてください。

SSO を使用して Web API にアクセスする

アドインに、承認されたユーザーを必要とするサーバー側 API がある場合は、getAccessToken メソッドを呼び出してアクセス トークンを取得します。 アクセス トークンは、( Microsoft Azure アプリの登録を通じて構成された) 独自の Web サーバーへのアクセスを提供します。 Web サーバーで API を呼び出すときは、アクセス トークンを渡してユーザーを承認します。

次のコードは、アドインの Web サーバー API に対して HTTPS GET 要求を作成してデータを取得する方法を示しています。 このコードは、作業ウィンドウなどで、クライアント側で実行されます。 最初に getAccessToken を呼び出してアクセス トークンを取得します。 次に、サーバー API の正しい承認ヘッダーと URL を使用して AJAX 呼び出しを作成します。

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

次のコードは、前のコード例の REST 呼び出しの /api/data ハンドラーの例を示しています。 このコードは、Web サーバーで実行されている ASP.NET コードです。 属性では [Authorize] 、有効なアクセス トークンがクライアントから渡される必要があります。または、クライアントにエラーが返されます。

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

SSO を使用して Microsoft Graph にアクセスする

一部のシナリオでは、ユーザーの ID が必要なだけでなく、ユーザーの代わりに Microsoft Graph リソースにアクセスする必要もあります。 たとえば、ユーザーの代わりにメールを送信したり、Teams でチャットを作成したりする必要がある場合があります。 これらのアクションなどについては、Microsoft Graph を使用して実行できます。 次の手順に従う必要があります。

1. getAccessToken を呼び出して、SSO を使用して現在のユーザーのアクセス トークンを取得します。 ユーザーがサインインしていない場合、Office はダイアログ ボックスを開き、Microsoft ID プラットフォームを使用してユーザーにサインインします。 ユーザーがサインインする、またはユーザーが既にサインインしている場合、メソッドによりアクセス トークンが返されます。
2. アクセス トークンをサーバー側のコードに渡します。
3. サーバー側で OAuth 2.0 On-Behalf-Of フローを使用して、アクセス トークンを、Microsoft Graph を呼び出すために必要な委任されたユーザーの ID とアクセス許可を含む新しいアクセス トークンに交換します。

アドインで Microsoft Graph にアクセスするための SSO の実装を開始する前に、次の記事をよく理解しておいてください。

• Office アドインのシングル サインオンを有効化する
• SSO を使用した Microsoft Graph への承認

また、SSO を使用して Microsoft Graph にアクセスするための Office アドインの構築について説明する次の記事の少なくとも 1 つを読む必要があります。 その手順を実行しない場合でも、SSO と On-Behalf-Of フローの実装方法に関する重要な情報が含まれています。

• 「シングル サインオンを使用する ASP.NET Office アドインを作成する」では、Office アドイン ASP.NET SSO のサンプルについて説明します。
• 「シングル サインオンを使用する Node.js Office アドインを作成する」では、Office アドイン NodeJS SSO のサンプルについて説明します。

SSO 以外のシナリオ

一部のシナリオでは、SSO を使用したくない場合があります。 たとえば、Microsoft ID プラットフォームとは異なる ID プロバイダーを使用して認証する必要がある場合があります。 また、SSO はすべてのシナリオでサポートされているわけではありません。 たとえば、以前のバージョンの Office では SSO がサポートされていません。 この場合は、アドインの代替認証システムにフォールバックする必要があります。

Microsoft ID プラットフォームを使用して認証する

アドインは、認証プロバイダーとして Microsoft ID プラットフォームを使用してユーザーをサインインすることができます。 ユーザーにサインインしたら、Microsoft ID プラットフォームを使用して、Microsoft Graph または Microsoft が管理する他のサービスへのアドインを承認できます。 Office を介した SSO が利用できない場合は、この方法を代替サインイン方法として使用します。 また、SSO が使用可能な場合でも、ユーザーにアドインに個別にサインインさせるシナリオもあります。たとえば、現在 Office にサインインしている ID とは異なる ID を使用してアドインにサインインするオプションが必要な場合です。

Microsoft ID プラットフォームでは、サインイン ページを iframe で開くことができないことに注意してください。 Office アドインがOffice on the webで実行されている場合、作業ウィンドウは iframe です。 これは、Office ダイアログ API で開かれるダイアログ ボックスを使用して、サインイン ページを開く必要があることを意味します。 このことは、認証ヘルパー ライブラリの使用方法に影響します。 詳細については、「Office ダイアログ API を使用して認証および承認する」を参照してください。

Microsoft ID プラットフォームを使用した認証の実装の詳細については、「Microsoft ID プラットフォーム (v2.0) の概要」を参照してください。 ドキュメントには、多くのチュートリアルとガイドのほか、関連するサンプルとライブラリへのリンクが含まれています。 「Office ダイアログ API を使用して認証および承認する」の説明にあるように、Office ダイアログ ボックスで実行するサンプル内のコードを調整する必要がある場合があります。

SSO を使用しないで Microsoft Graph にアクセスする

Microsoft ID プラットフォームから Microsoft Graph へのアクセス トークンを取得することで、アドインの Microsoft Graph データに対する承認を取得できます。 これを行うには、Office 経由の SSO に依存しません (または、SSO が失敗したか、サポートされていない場合)。 詳細については、「SSO を使用せずに Microsoft Graph にアクセスする」を参照してください。詳細情報とサンプルへのリンクが含まれています。

Microsoft 以外のデータ ソースへのアクセス

大手のオンライン サービス (Google、Facebook、LinkedIn、SalesForce、GitHub など) では、開発者は、ユーザーが自分のアカウントに別のアプリケーションからアクセスできるようにすることが可能です。 これにより、開発者はこれらのサービスを Office アドインに含めることができます。 アドインでこれを実行する方法の概要については、「Authorize external services in your Office Add-in (Office アドインで外部サービスを承認する)」を参照してください。

関連項目

• Microsoft ID プラットフォームのドキュメント
• Microsoft ID プラットフォームのアクセス トークン
• Microsoft ID プラットフォームにおける OAuth 2.0 と OpenID Connect プロトコル
• Microsoft ID プラットフォームと OAuth 2.0 On-Behalf-Of フロー
• JSON Web Token (JWT)
• JSON Web Token ビューアー