Office アドインのシングル サインオンを有効化する (プレビュー)Enable single sign-on for Office Add-ins (preview)

ユーザーは個人用の Microsoft アカウントまたは職場や学校の (Office 365) アカウントのいずれかを使用して、Office (オンライン、モバイル、およびデスクトップ プラットフォーム) にサインインします。Users sign in to Office (online, mobile, and desktop platforms) using either their personal Microsoft account or their work or school (Office 365) account. これとシングル サインオン (SSO) を使用すれば、ユーザーに 2 度目のサインインを求めずに、ご自分のアドインをユーザーに許可できます。You can take advantage of this and use single sign-on (SSO) to authorize the user to your add-in without requiring the user to sign in a second time.

アドインのサインイン プロセスを示す画像

プレビューの状態Preview Status

現在、シングル サインオン API はプレビューのみでサポートされています。The Single Sign-on API is currently supported in preview only. これは、試験目的のみで開発者に提供されており、運用環境のアドインには使用してはいけません。It is available to developers for experimentation; but it should not be used in a production add-in. また、SSO を使用するアドインは AppSource では許可されていません。In addition, add-ins that use SSO are not accepted in AppSource.

SSO のプレビューは、すべての Office アプリケーションではサポートされていません。Not all Office applications support the SSO preview. これは、Word、Excel、Outlook、および PowerPoint で利用できます。It is available in Word, Excel, Outlook, and PowerPoint. シングル サインオン API の現在のサポート状態に関する詳細は、「IdentityAPI の要件セット」を参照してください。For more information about where the Single Sign-on API is currently supported, see IdentityAPI requirement sets.

要件とベスト プラクティスRequirements and Best Practices

SSO を使用するには、アドインのスタートアップ HTML ページの から Office JavaScript ライブラリのベータ版を読み込む必要があります。To use SSO, you must load the beta version of the Office JavaScript Library from in the startup HTML page of the add-in.

Outlook アドインで作業している場合は、Office 365 テナントの先進認証が有効になっていることを確認してください。If you are working with an Outlook add-in, be sure to enable Modern Authentication for the Office 365 tenancy. この方法の詳細については、「Exchange Online: How to enable your tenant for modern authentication」 (Exchange Online: テナントの先進認証を有効にする方法) を参照してください。For information about how to do this, see Exchange Online: How to enable your tenant for modern authentication.

SSO をアドインの唯一の認証方法としないようにする必要があります。You should not rely on SSO as your add-in's only method of authentication. 特定のエラー状況でアドインが切り替えることができる、別の認証システムを実装する必要があります。You should implement an alternate authentication system that your add-in can fall back to in certain error situations. ユーザー テーブルと認証のシステムを使用するか、ソーシャル ログイン プロバイダーの 1 つを活用できます。You can use a system of user tables and authentication, or you can leverage one of the social login providers. Office アドインでこれを実行する方法の詳細については、「Office アドインで外部サービスを承認する」を参照してください。For more information about how to do this with an Office add-in, see Authorize external services in your Office Add-in. Outlook には切り替えることが可能な推奨システムがあります。For Outlook, there is a recommended fall back system. 詳細については、「シナリオ: Outlook アドインでサービスにシングル サインオンを実装する」を参照してください。For more information, see Scenario: Implement single sign-on to your service in an Outlook add-in.

実行時の SSO の動作のしくみHow SSO works at runtime

次の図は、SSO の動作のしくみを示しています。The following diagram shows how the SSO process works.

SSO プロセスを示す図

  1. アドインの JavaScript により、新しい Office.js API getAccessTokenAsync が呼び出されます。In the add-in, JavaScript calls a new Office.js API getAccessTokenAsync. これにより、Office ホスト アプリケーションはアドインへのアクセス トークンを取得するよう指示されます。This tells the Office host application to obtain an access token to the add-in. アクセス トークンの例」を参照してください。See Example access token.
  2. ユーザーがサインインしていない場合、Office ホスト アプリケーションはユーザーにサインインを求めるポップアップ ウィンドウを開きます。If the user is not signed in, the Office host application opens a pop-up window for the user to sign in.
  3. 現在のユーザーが初めてアドインを使用する場合は、そのユーザーに同意を求めるダイアログを表示します。If this is the first time the current user has used your add-in, he or she is prompted to consent.
  4. Office ホスト アプリケーションは、Azure AD v2.0 エンドポイントから現在のユーザーのアドイン トークンを要求します。The Office host application requests the add-in token from the Azure AD v2.0 endpoint for the current user.
  5. Azure AD は、Office ホスト アプリケーションにアドイン トークンを送信します。Azure AD sends the add-in token to the Office host application.
  6. Office ホスト アプリケーションが、getAccessTokenAsync 呼び出しによって返される結果オブジェクトの一部として、アドインにアドイン トークンを送信します。The Office host application sends the add-in token to the add-in as part of the result object returned by the getAccessTokenAsync call.
  7. アドイン内の JavaScript が、トークンを解析し、ユーザーのメール アドレスなど必要な情報を抽出します。JavaScript in the add-in can parse the token and extract the information it needs, such as the user's email address.
  8. オプションで、アドインで HTTP 要求を送信して、ユーザー設定などユーザーに関する情報をさらにサーバー側から求めることができます。Optionally, the add-in can send HTTP request to its server-side for more data about the user; such as the user's preferences. または、アクセス トークン自体が解析および検証されるようにサーバー側に送信することができます。Alternatively, the access token itself could be sent to the server-side for parsing and validation there.

SSO アドインの開発Develop an SSO add-in

このセクションでは、SSO を使用する Office アドインの作成に関連するタスクについて説明します。This section describes the tasks involved in creating an Office Add-in that uses SSO. ここでは、これらのタスクについて、言語とフレームワークに依存しない方法で説明しています。These tasks are described here in a language- and framework-agnostic way. 詳細なチュートリアルの例については、次を参照してください。For examples of detailed walkthroughs, see:

サービス アプリケーションを作成するCreate the service application

Azure v2.0 エンドポイントの登録ポータル にアドインを登録します。Register the add-in at the registration portal for the Azure v2.0 endpoint: このプロセスには、次に示すタスクを含めて 5 分から 10 分の時間がかかります。This is a 5–10 minute process that includes the following tasks:

  • アドインのクライアント ID とシークレットを取得します。Get a client ID and secret for the add-in.
  • アドインが必要とする AAD v.2.0 エンドポイントへのアクセス許可を指定します Specify the permissions that your add-in needs to AAD v. (必要に応じて Microsoft Graph へも指定します)。2.0 endpoint (and optionally to Microsoft Graph). "profile" のアクセス許可は常に必要です。The "profile" permission is always needed.
  • Office ホスト アプリケーションにアドインへの信頼を付与します。Grant the Office host application trust to the add-in.
  • 既定のアクセス許可 access_as_user を使用して、Office ホスト アプリケーションのアドインへのアクセスを事前認証します。Preauthorize the Office host application to the add-in with the default permission access_as_user.

この手順の詳細については、「Azure AD v2.0 のエンドポイントに SSO を使用する Office アドインを登録する」をご覧ください。For more details about this process, see Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint.

アドインを構成するConfigure the add-in

新しいマークアップをアドイン マニフェストに追加します。Add new markup to the add-in manifest:

  • WebApplicationInfo - 次の要素の親。WebApplicationInfo - The parent of the following elements.
  • Id -このアドインのクライアント ID。これはアドインを登録する一貫として取得するアプリケーション ID です。Id - The client ID of the add-in This is an application ID that you obtain as part of registering the add-in. 詳細については、「Azure AD v2.0 のエンドポイントに SSO を使用する Office アドインを登録する」をご覧ください。See Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint.
  • Resource - アドインの URL。Resource - The URL of the add-in. これは、AAD にアドインを登録したときに使用したのと同じ URI (api: プロトコルを含む) です。This is the same URI (including the api: protocol) that you used when registering the add-in in AAD. この URI のドメイン部分は、アドインのマニフェストの <Resources> のセクションの URL で使用されている、すべてのサブドメインを含むドメインと一致している必要があります。The domain part of this URI should match the domain, including any subdomains, used in the URLs in the <Resources> section of the add-in's manifest.
  • Scopes - 1 つ以上の Scope 要素の親。Scopes - The parent of one or more Scope elements.
  • Scope - アドインが AAD に対して必要なアクセス許可を指定する。Scope - Specifies a permission that the add-in needs to AAD. profile のアクセス許可は常に必要です。ご使用のアドインが Microsoft Graph にアクセスしない場合、これは必要な唯一のアクセス許可になる場合があります。The profile permission is always needed and it may be the only permission needed, if your add-in does not access Microsoft Graph. アクセスする場合、Microsoft Graph へのアクセスに必要な許可として、User.ReadMail.Read など Scope 要素も必要になります。If it does, you also need Scope elements for the required Microsoft Graph permissions; for example, User.Read, Mail.Read. コードで使用している、Microsoft Graph にアクセスするためのライブラリでは、他にもアクセス許可が必要な場合があります。Libraries that you use in your code to access Microsoft Graph may need additional permissions. たとえば、.NET 用の Microsoft 認証ライブラリ (MSAL) では、offline_access のアクセス許可が必要です。For example, Microsoft Authentication Library (MSAL) for .NET requires offline_access permission. 詳細については、「Office アドインで Microsoft Graph へ承認」を参照してください。For more information, see Authorize to Microsoft Graph from an Office Add-in.

Outlook 以外の Office ホストでは、<VersionOverrides ... xsi:type="VersionOverridesV1_0"> セクションの末尾にマークアップを追加します。Outlook では、<VersionOverrides ... xsi:type="VersionOverridesV1_1"> セクションの末尾にマークアップを追加します。For Office hosts other than Outlook, add the markup to the end of the <VersionOverrides ... xsi:type="VersionOverridesV1_0"> section. For Outlook, add the markup to the end of the <VersionOverrides ... xsi:type="VersionOverridesV1_1"> section.

マークアップの例を次に示します。The following is an example of the markup:


クライアント側のコードを追加するAdd client-side code

アドインに次のために JavaScript を追加します。Add JavaScript to the add-in to:

  • getAccessTokenAsync の呼び出し。Call getAccessTokenAsync.

  • アクセス トークンを解析するか、それをアドインのサーバー側コードに渡す。Parse the access token or pass it to the add-in’s server-side code.

getAccessTokenAsync への呼び出しの単純な例を示します。Here's a simple example of a call to getAccessTokenAsync.


この例では、1 種類のエラーのみを明示的に処理します。This example handles only one kind of error explicitly. より複雑なエラー処理の例については、「Home.js in Office-Add-in-ASPNET-SSO」 (Office-Add-in-ASPNET-SSO の Home.js) と 「program.js in Office-Add-in-NodeJS-SSO」 (Office-Add-in-NodeJS-SSO の program.js) を参照してください。For examples of more elaborate error handling, see Home.js in Office-Add-in-ASPNET-SSO and program.js in Office-Add-in-NodeJS-SSO. また、「シングル サインオン (SSO) のエラー メッセージのトラブルシューティング」を参照してください。And see Troubleshoot error messages for single sign-on (SSO).

Office.context.auth.getAccessTokenAsync(function (result) {
    if (result.status === "succeeded") {
        // Use this token to call Web API
        var ssoToken = result.value;
    } else {
        if (result.error.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // work or school (Office 365) or Microsoft Account IDs.
        } else {
            // Handle error

サーバー側にアドイン トークンを渡す単純な例を次に示します。Here's a simple example of passing the add-in token to the server-side. このトークンは、サーバー側に要求を戻すときの Authorization ヘッダーとして含まれています。The token is included as an Authorization header when sending a request back to the server-side. この例では JSON データの送信が想定されているので、POST メソッドを使用しています。ただし、サーバーに書き込まない場合は、アクセス トークンの送信に GET で十分です。This example envisions sending JSON data, so it uses the POST method, but GET is sufficient to send the access token when you are not writing to the server.

    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + ssoToken
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup

メソッドを呼び出すタイミングWhen to call the method

Office にログインしているユーザーがいないときにアドインを使用できない場合、アドインを起動するときに getAccessTokenAsync を呼び出す必要があります。If your add-in cannot be used when no user is logged into Office, then you should call getAccessTokenAsync when the add-in launches.

アドインに、ログイン ユーザーを必要としない機能がある場合、ユーザーがログイン ユーザーを必要とするアクションを実行するときに getAccessTokenAsync を呼び出します。If the add-in has some functionality that doesn't require a logged in user, then you call getAccessTokenAsync when the user takes an action that requires a logged in user. getAccessTokenAsync の重複呼び出しによってパフォーマンスが大幅に低下することはありません。これは、Office ではアクセス トークンがキャッシュされ、それが期限切れになるまで、There is no significant performance degradation with redundant calls of getAccessTokenAsync because Office caches the access token and will reuse it, until it expires, without making another call to the AAD v. getAccessTokenAsync が呼び出されても AAD V.2.0 エンドポイントが再度呼び出されずに再利用されるためです。2.0 endpoint whenever getAccessTokenAsync is called. このため、getAccessTokenAsync の呼び出しを、このトークンが必要とされる場所でアクションを開始するすべての関数とハンドラーに追加できます。So you can add calls of getAccessTokenAsync to all functions and handlers that initiate an action where the token is needed.

サーバー側のコードを追加するAdd server-side code

ほとんどの場合、アドインがサーバー側に渡してそこで使用しない場合は、アクセス トークンを取得してもあまり意味はありません。In most scenarios, there would be little point to obtaining the access token, if your add-in does not pass it on to a server-side and use it there. アドインでは、次のいくつかのサーバー側のタスクを実行できます。Some server-side tasks your add-in could do:

  • ホストされている使用しているデータベースのユーザー設定を検索するメソッドなど、トークンから抽出されるユーザーに関する情報を使用する 1 つ以上の Web API メソッドを作成します。Create one or more Web API methods that use information about the user that is extracted from the token; for example, a method that looks up the user's preferences in your hosted data base. (以下の「ID として SSO トークンを使用する」を参照) 使用する言語とフレームワークによっては、記述する必要のあるコードを簡単に記述できるライブラリが使用できることがあります。(See Using the SSO token as an identity below.) Depending on your language and framework, libraries might be available that will simplify the code you have to write.
  • Microsoft Graph データを取得します。Get Microsoft Graph data. サーバー側のコードでは、次に示す操作を実行する必要があります。Your server-side code should do the following:

    • アクセス トークンを検証します (以下の「アクセス トークンを検証する」を参照)。Validate the access token (see Validate the access token below).
    • Azure AD v2.0 エンドポイントを呼び出して、「代理」フローを開始します。これには、アクセス トークン、ユーザーに関するメタデータ、およびアドインの資格情報 (ID とシークレット) を含めます。Initiate the “on behalf of” flow with a call to the Azure AD v2.0 endpoint that includes the access token, some metadata about the user, and the credentials of the add-in (its ID and secret). このコンテキストでは、アクセス トークンはブートストラップ トークンと呼ばれます。In this context, the access token is called the bootstrap token.
    • 代理フローから戻される新しいアクセス トークンをキャッシュします。Cache the new access token that is returned from the on-behalf-of flow.
    • 新しいトークンを使用して Microsoft Graph からデータを取得します。Get data from Microsoft Graph by using the new token.

    ユーザーの Microsoft Graph のデータへのアクセス許可を取得するには、「Microsoft Graph への認証」を参照してください。For more details about getting authorized access to the user's Microsoft Graph data, see Authorize to Microsoft Graph in your Office Add-in.

アクセス トークンを検証するValidate the access token

Web API でアクセス トークンを受信したら、そのアクセス トークンを使用する前に検証する必要があります。Once the Web API receives the access token, it must validate it before using it. このトークンは、JSON Web トークン (JWT) です。そのため、この検証は最も標準的な OAuth でのトークンの検証とまったく同様に動作します。The token is a JSON Web Token (JWT), which means that validation works just like token validation in most standard OAuth flows. JWT の検証を処理できるライブラリが複数入手可能ですが、その基本は次のとおりです。There are a number of libraries available that can handle JWT validation, but the basics include:

  • トークンが整形式であることを確認するChecking that the token is well-formed
  • トークンが意図した証明機関から発行されたことを確認するChecking that the token was issued by the intended authority
  • トークンが Web API を対象にしていることを確認するChecking that the token is targeted to the Web API

トークンの検証時には、次のガイドラインに注意してください。Keep in mind the following guidelines when validating the token:

  • 有効な SSO トークンは Azure 証明機関 から発行されます。Valid SSO tokens will be issued by the Azure authority, トークン内の iss クレームは、この値で始まっている必要があります。The iss claim in the token should start with this value.
  • トークンの aud パラメーターは、アドインの登録のアプリケーション ID に設定します。The token's aud parameter will be set to the application ID of the add-in's registration.
  • トークンの scp パラメーターは access_as_user に設定します。The token's scp parameter will be set to access_as_user.

ID として SSO トークンを使用するUsing the SSO token as an identity

アドインでユーザーの ID を検証する必要がある場合、SSO トークンには ID を確定するために使用できる情報が含まれています。If your add-in needs to verify the user's identity, the SSO token contains information that can be used to establish the identity. ID に関連するトークン内のクレームは次のとおりです。The following claims in the token relate to identity.

  • name: ユーザーの表示名。name - The user's display name.
  • preferred_username: ユーザーの電子メール アドレス。preferred_username - The user's email address.
  • oid: Azure Active Directory でユーザーの ID を表す GUID。oid - A GUID representing the ID of the user in the Azure Active Directory.
  • tid: Azure Active Directory でユーザーの組織の ID を表す GUID。tid - A GUID representing the ID of the user's organization in the Azure Active Directory.

namepreferred_username の値は変化することがあるため、この ID とバックエンドの承認サービスを、oidtid の値を使用して関連付けることをお勧めします。Since the name and preferred_username values could change, we recommend that the oid and tid values be used to correlate the identity with your back-end's authorization service.

たとえば、サービスでは、これらの値を {oid-value}@{tid-value} のような形式にまとめて、内部ユーザー データベースのユーザーのレコードに値として保存できます。For example, your service could format those values together like {oid-value}@{tid-value}, then store that as a value on the user's record in your internal user database. その後の要求では、同じ値を使用してユーザーを取得できるようになり、特定のリソースへのアクセスについては既存のアクセス制御メカニズムに基づいて決定できます。Then on subsequent requests, the user could be retrieved by using the same value, and access to specific resources could be determined based on your existing access control mechanisms.

アクセス トークンの例Example access token

アクセス トークンの標準的なデコードされたペイロードを次に示します。The following is a typical decoded payload of an access token. プロパティの詳細については、Azure Active Directory v2.0 トークンのリファレンスに関するページを参照してください。For information about the properties, see Azure Active Directory v2.0 tokens reference.

    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",         
    iss: "",         
    iat: 1521143967,         
    nbf: 1521143967,         
    exp: 1521147867,         
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",         
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",         
    azpacr: "0",         
    e_exp: 262800,         
    name: "Mila Nikolova",         
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",         
    preferred_username: "",         
    scp: "access_as_user",         
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",         
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",         
    uti: "MICAQyhrH02ov54bCtIDAA",         
    ver: "2.0"

Outlook のアドインで SSO を使用するUsing SSO with an Outlook add-in

Excel、PowerPoint、または Word のアドインで SSO を使用する場合と Outlook のアドインでそれを使用する場合とでは、小さいけれど重要な違いがいくつかあります。There are some small, but important differences in using SSO in an Outlook add-in from using it in an Excel, PowerPoint, or Word add-in. Authenticate a user with a single sign-on token in an Outlook add-in」 (Outlook アドインでシングル サインオン トークンを使用してユーザーを認証する) と「シナリオ: Outlook アドインでサービスにシングル サインオンを実装する」を参照してください。Be sure to read Authenticate a user with a single sign-on token in an Outlook add-in and Scenario: Implement single sign-on to your service in an Outlook add-in.

SSO API リファレンスSSO API reference


Office Auth 名前空間 (Office.context.auth) には、Office ホストがアドインの Web アプリケーションへのアクセス トークンを取得することを可能にする getAccessTokenAsync というメソッドがあります。The Office Auth namespace, Office.context.auth, provides a method, getAccessTokenAsync that enables the Office host to obtain an access token to the add-in's web application. これにより、間接的に、サインインしたユーザーの Microsoft Graph データにアドインがアクセスできるようにもなります。ユーザーがもう一度サインインする必要はありません。Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time.

getAccessTokenAsync(options?: AuthOptions, callback?: (result: AsyncResult<string>) => void): void;

このメソッドは、Azure Active Directory V 2.0 のエンドポイントを呼び出して、アドインの Web アプリケーションへのアクセス トークンを取得します。The method calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. これにより、アドインがユーザーを識別できるようになります。This enables add-ins to identify users. "on behalf of" OAuth フローを使用することにより、サーバー側のコードはこのトークンを使用して、アドインの Web アプリケーションの Microsoft Graph にアクセスできます。Server side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow.


Outlook でアドインが または Gmail のメールボックスに読み込まれている場合、この API はサポートされません。In Outlook, this API is not supported if the add-in is loaded in an or Gmail mailbox.

ホストHostsExcel、OneNote、Outlook、PowerPoint、WordExcel, OneNote, Outlook, PowerPoint, Word
要件セットRequirement setsIdentityAPIIdentityAPI


options - 省略可能。options - Optional. サインイン動作を定義する AuthOptions オブジェクトが許可されます (下記参照)。Accepts an AuthOptions object (see below) to define sign-on behaviors.

callback - 省略可能。callback - Optional. ユーザー ID 用のトークンを解析できるコールバック メソッドが許可されます。または、トークンを Microsoft Graph へのアクセスを取得するために、「代理」フローで使用します。Accepts a callback method that can parse the token for the user's ID or use the token in the "on behalf of" flow to get access to Microsoft Graph. AsyncResult.status が "succeeded" である場合、AsyncResult.value が生の AAD v.If AsyncResult.status is "succeeded", then AsyncResult.value is the raw AAD v. 2.0 形式のアクセス トークンになります。2.0-formatted access token.

AuthOptions インターフェイスには、Office がThe AuthOptions interface provides options for the user experience when Office obtains an access token to the add-in from AAD v. getAccessTokenAsync メソッドを使用して AAD v. 2.0 からアドインに対するアクセス トークンを取得する場合用のユーザー エクスペリエンス用のオプションがあります。2.0 with the getAccessTokenAsync method.

interface AuthOptions {
        * Causes Office to display the add-in consent experience. Useful if the add-in's Azure permissions have changed or if the user's consent has 
        * been revoked.
    forceConsent?: boolean,
        * Prompts the user to add their Office account (or to switch to it, if it is already added).
    forceAddAccount?: boolean,
        * Causes Office to prompt the user to provide the additional factor when the tenancy being targeted by Microsoft Graph requires multifactor 
        * authentication. The string value identifies the type of additional factor that is required. In most cases, you won't know at development 
        * time whether the user's tenant requires an additional factor or what the string should be. So this option would be used in a "second try" 
        * call of getAccessTokenAsync after Microsoft Graph has sent an error requesting the additional factor and containing the string that should 
        * be used with the authChallenge option.
    authChallenge?: string
        * A user-defined item of any type that is returned, unchanged, in the asyncContext property of the AsyncResult object that is passed to a callback.
    asyncContext?: any