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 for Word, Excel, Outlook, and PowerPoint. 開発者が試すことはできますが、実際に運用するアドインでは使用できません。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.

一部の Office アプリケーションは、SSO プレビューをサポートしていません。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: テナントの先進認証を有効にする方法」を参照してください。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. ユーザー テーブルと認証のシステムを使用することも、ソーシャル ログイン プロバイダのいずれかを活用することもできます。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 details, see Scenario: Implement single sign-on to your service in an Outlook add-in.

実行時に SSO が動作する仕組みHow it 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 . これにより、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: This is a 5–10 minute process that includes the following tasks: これは、次のタスクを含む 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 に必要とするアクセス許可を指定します。Specify the permissions that your add-in needs to Microsoft Graph. (オプションで Microsoft Graph)。2.0 endpoint (and optionally to Microsoft Graph). [プロファイル] のアクセス許可は、常に必要です。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 information, 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 アドインを登録する」をご覧ください。Details are at: Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint.
  • Resource - アドインの URL。Resource - The URL of the add-in.
  • Scopes - 1 つ以上の Scope 要素の親。Scopes - The parent of one or more Scope elements.
  • Scope - アドインが AAD に必要とするアクセス許可を指定します。Scope - Specifies a permission that the add-in needs to Microsoft Graph. 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 へのアクセス許可を得るには Scope 要素も必要です。たとえば、 User.ReadMail.Read などです。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. たとえば、Microsoft 認証ライブラリ (MSAL) for .NET は、 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. より詳細なエラー処理の例については、「Office-Add-in-ASPNET-SSO の Home.js」および「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) のエラー メッセージのトラブルシューティング」 もご覧ください。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 a no user is logged into Office and Office does not have an access token to your add-in, then you should call getAccessTokenAsync when the add-in launches.

アドインにログイン ユーザーを必要としない機能がある場合、ユーザーがログイン ユーザーを必要とするアクションを実行するときに getAccessTokenAsync を呼び出します。If the add-in has some functionality that doesn't require access to Microsoft Graph or even a logged in user, then you call getAccessTokenAsync when the user takes an action that requires access to Microsoft Graph or, at least, a logged in user. getAccessTokenAsync の重複呼び出しによってパフォーマンスが大幅に低下することはありません。これは、Office ではアクセス トークンがキャッシュされ、それが期限切れになるまで、AAD V が再度呼び出されることなく、再利用されるためです。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. 2.0 endpoint whenever is called. 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).
    • アクセス トークン、ユーザーに関するメタデータ、アドインの認証情報 (ID とシークレット) を含む Azure AD v2.0 エンドポイントへの呼び出しを使用して "On-Behalf-Of" フローを開始します。Initiate the “on behalf of” flow with a call to the Azure AD v2.0 endpoint that includes the add-in 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.
    • "On-Behalf-Of" フローから返された新しいアクセス トークンをキャッシュします。Cache the new access token that is returned from the on-behalf-of flow.
    • 新しいトークンを使用して Microsoft Graph からデータを取得します。Get data from Microsoft Graph by using the MSG token.

    ユーザーの Microsoft Graph データへの承認済みアクセスを取得する方法の詳細については、「Office アドインで 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.

アクセス トークンを検証するFor more information, see 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_usernameThe 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 の値は変化することがあるため、oidtid の値を ID とバックエンドの承認サービスを関連付けるために使用するようにしてください。Since the name and preferred_username values could change, it's recommended 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 and Outlook add-in

SSO を Outlook アドインとして使用する場合と、Excel、PowerPoint、Word アドインとして使用する場合には、ささやかですが重要な違いがあります。There are some small, but important differences in using SSO in and Outlook add-in from using it in as Excel, PowerPoint, or Word 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 の認証の名前空間 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, enable 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 アプリケーションへのアクセス トークンを取得します。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 はサポートされていません。]

HostsHostsExcel、OneNote、Outlook、PowerPoint、WordExcel, Outlook, PowerPoint, Word
要件セットRequirement setsIdentityAPIIdentityAPI


options - 省略可能。options - Optional. サインオン時の動作を定義するために、AuthOptions オブジェクト (下記参照) を受け入れます。Accepts an AuthOptions object (see below) to define sign-on behaviors.

callback - 省略可能。callback - Optional. ユーザーの ID のトークンを解析したり、"On-Behalf-Of" フローのトークンを使用して 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 が「成功した」場合は、 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 が AAD v からアドインへのアクセス トークンを取得する場合に、ユーザー エクスペリエンスのオプションを提供します。The AuthOptions interface provides options for the user experience when Office obtains an access token to the add-in from AAD v. getAccessTokenAsync メソッドを持つ 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