Office アドインでシングルサインオン (SSO) を有効にする

[アーティクル]
01/22/2024

ユーザーは、個人の Microsoft アカウントまたはMicrosoft 365 Educationまたは職場アカウントを使用して Office にサインインします。これとシングルサインオン (SSO) を使用すれば、ユーザーに 2 度目のサインインを求めずに、アドインを承認しユーザーを認証できます。

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

実行時の SSO の動作のしくみ

次の図は、SSO の動作のしくみを示しています。青い要素は、Office または Microsoft ID プラットフォームを表します。灰色の要素は、書き込むコードを表し、アドインのクライアント側コード (作業ウィンドウ) とサーバー側コードを含みます。

SSO プロセスを示す図。

アドインでは、JavaScript コードは Office.js API である getAccessToken Office.js を呼び出します。ユーザーが既に Office にサインインしている場合、Office ホストは、サインインしているユーザーの要求を含むアクセストークンを返します。
ユーザーがサインインしていない場合、ユーザーにサインインを求めるダイアログボックスが Office ホストアプリケーションによって開かれます。サインインプロセスを完了するために、Office は Microsoft ID プラットフォームにリダイレクトします。
現在のユーザーが初めてアドインを使用する場合は、そのユーザーに同意を求めるダイアログが表示されます。
Office ホストアプリケーションは、Microsoft Identity プラットフォームから現在のユーザーのアクセストークンを要求します。
Microsoft ID プラットフォームは、アクセストークンを Office に返します。 Office はユーザーの代わりにトークンをキャッシュし、getAccessToken への今後の呼び出しが、キャッシュされたトークンを返すようにします。
Office ホストアプリケーションが、 getAccessToken 呼び出しによって返される結果オブジェクトの一部として、アドインにアクセストークンを送信します。
トークンは、アクセストークン と ID トークンの両方です。 ID トークンとして使用して、ユーザーの名前や電子メールアドレスなど、ユーザーに関する要求を解析して調べることができます。
必要に応じて、アドインはトークンを アクセストークンとして使用して、サーバー側の API に対して認証された HTTPS 要求を行うことができます。アクセストークンには ID 要求が含まれているため、サーバーはユーザー設定などのユーザーの ID に関連付けられた情報を格納できます。

要件とベストプラクティス

アクセストークンをキャッシュしない

クライアント側のコードにアクセストークンをキャッシュしたり格納したりしないでください。アクセストークンが必要な場合は、常に getAccessToken を呼び出します。 Office はアクセストークンをキャッシュします (または、有効期限が切れた場合は新しいトークンを要求します)。これにより、誤ってアドインからトークンが漏洩するのを防ぐことができます。

Outlook の先進認証を有効にする

Outlook アドインを使用している場合は、Microsoft 365 テナントの先進認証を有効にしてください。これを行う方法については、「Exchange Onlineで Outlook の先進認証を有効または無効にする」を参照してください。

フォールバック認証システムを実装する

SSO をアドインの唯一の認証方法としないようにする必要があります。特定のエラー状況でアドインが切り替えることができる、別の認証システムを実装する必要があります。たとえば、SSO をサポートしていない以前のバージョンの Office にアドインが読み込まれている場合、 getAccessToken 呼び出しは失敗します。

Excel、Word、PowerPoint アドインの場合は、通常、Microsoft ID プラットフォームを使用するためにフォールバックする必要があります。詳細情報については、「Microsoft ID プラットフォームを使用して認証する」を参照してください。

Outlook アドインの場合は、推奨されるフォールバックシステムがあります。詳細については、「シナリオ: Outlook アドインでサービスにシングルサインオンを実装する」を参照してください。

ユーザーテーブルと認証のシステムを使用するか、ソーシャルログインプロバイダーの 1 つを活用することもできます。 Office アドインでこれを実行する方法の詳細については、「Office アドインで外部サービスを承認する」を参照してください。

代替システムとして Microsoft ID プラットフォームを使用するコードサンプルについては、「Office アドイン NodeJS SSO」と「Office アドイン ASP.NET SSO」を参照してください。

SSO アドインの開発

このセクションでは、SSO を使用する Office アドインの作成に関連するタスクについて説明します。これらのタスクについては、言語やフレームワークとは別に説明します。詳しい手順については、次のトピックを参照してください。

Microsoft ID プラットフォームにアドインを登録する

SSO を使用するには、Microsoft ID プラットフォームにアドインを登録する必要があります。これにより、Microsoft ID プラットフォームがアドインの認証サービスと認可サービスを提供できるようになります。アプリ登録の作成には、次のタスクが含まれます。

Microsoft ID プラットフォームへのアドインを識別するアプリケーション (クライアント) ID を取得します。
トークンを要求するときにアドインのパスワードとして機能するクライアントシークレットを生成します。
アドインに必要なアクセス許可を指定します。 Microsoft Graph "プロファイル" および "openid"のアクセス許可は常に必要です。アドインの実行内容によっては、追加のアクセス許可が必要になる場合があります。
Office アプリケーションにアドインへの信頼を付与します。
既定のスコープ access_as_user を使用して、Office アプリケーションのアドインへのアクセスを事前承認します。

この手順の詳細については、「Microsoft ID プラットフォームに SSO を使用する Office アドインを登録する」をご覧ください。

アドインを構成する

新しいマークアップをアドインマニフェストに追加します。

<WebApplicationInfo> - 次の要素の親。
<Id> - アドインをMicrosoft ID プラットフォームに登録したときに受け取ったアプリケーション (クライアント) ID。詳細情報については、「Microsoft ID プラットフォームに SSO を使用する Office アドインを登録する」をご覧ください。
<リソース> - アドインの URI。これは、Microsoft ID プラットフォームを使ってアドインを登録したときに使用したのと同じ URI (api: プロトコルを含む) です。この URI のドメイン部分は、アドインのマニフェストの [リソース>] セクションの URL で<使用されるサブドメインを含むドメインと一致する必要があり、URI は Id> 要素で指定されたクライアント ID で<終わる必要があります。
<>スコープ - 1 つ以上<の Scope> 要素の親。
<スコープ> - アドインに必要なアクセス許可を指定します。 profile と openID のアクセス許可は常に必要であり、これは唯一必要なアクセス許可である場合があります。アドインが Microsoft Graph またはその他の Microsoft 365 リソースにアクセスする必要がある場合は、追加 <の Scope> 要素が必要です。たとえば、Microsoft Graph のアクセス許可の場合は、 User.Read と Mail.Read のスコープを要求できます。コードで使用している、Microsoft Graph にアクセスするためのライブラリでは、他にもアクセス許可が必要な場合があります。詳細については、「Office アドインで Microsoft Graph へ承認」を参照してください。

Word、Excel、PowerPoint アドインの場合は、 <VersionOverrides ... xsi:type="VersionOverridesV1_0"> セクションの末尾にマークアップを追加します。 Outlook アドインでは、<VersionOverrides ... xsi:type="VersionOverridesV1_1"> セクションの末尾にマークアップを追加します。

マークアップの例を次に示します。

<WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>files.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

重要

アドインが 1 人以上の管理者によって組織に展開されている場合、マニフェストに新しいスコープを追加するには、管理者が更新プログラムに同意する必要があります。同意が付与されるまで、ユーザーはアドインからブロックされます。

注:

SSO 用マニフェストのフォーマット要件に従わない場合、アドインはフォーマット要件を満たすまで AppSource から拒否されます。

Identity API 要件セットを含める

SSO を使用するには、アドインに Identity API 1.3 要件セットが必要です。詳細については、「IdentityAPI」を参照してください。

クライアント側のコードを追加する

アドインに次のために JavaScript を追加します。

getAccessToken を呼び出します。
アクセストークンを解析するか、それをアドインのサーバー側コードに渡す。

次のコードは、 getAccessToken を呼び出し、ユーザー名やその他の資格情報のトークンを解析する簡単な例を示しています。

注:

この例では、1 種類のエラーのみを明示的に処理します。より複雑なエラー処理の例については、「Office アドイン NodeJS SSO」と「Office アドイン ASP.NET SSO」を参照してください。

async function getUserData() {
    try {
        let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
        let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
        console.log(userToken.name); // user name
        console.log(userToken.preferred_username); // email
        console.log(userToken.oid); // user id     
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // Microsoft 365 Education or work account, or a Microsoft account.
        } else {
            // Handle error
        }
    }
}

getAccessToken を呼び出す場合

アドインにサインイン済みのユーザーが必要な場合は、Office.initialize 内から getAccessToken を呼び出す必要があります。 getAccessToken の options パラメーターにも allowSignInPrompt: true を渡す必要があります。たとえば、OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); これにより、ユーザーがまだサインインしていない場合は、Office が UI からユーザーに今すぐサインインするように求めます。

アドインにサインインユーザーを必要としない機能がある場合は、サインインしているユーザーを必要とするアクションをユーザーが実行するときにを呼び出getAccessTokenすことができます。 getAccessToken の重複呼び出しによってパフォーマンスが大幅に低下することはありません。これは、Office がアクセストークンをキャッシュし、それが期限切れになるまで、getAccessToken が呼び出されるたびに Microsoft ID プラットフォームが再度呼び出すことなく再利用されるためです。このため、getAccessToken の呼び出しを、このトークンが必要とされる場所でアクションを開始するすべての関数とハンドラーに追加できます。

重要

ベストセキュリティプラクティスとして、アクセストークンが必要な場合は常に getAccessToken を呼び出します。 Office によってキャッシュされます。独自のコードを使用してアクセストークンをキャッシュまたは格納しないでください。

アクセストークンをサーバー側のコードに渡す

サーバー上の Web API や Microsoft Graph などの追加サービスにアクセスする必要がある場合は、アクセストークンをサーバー側のコードに渡す必要があります。アクセストークンは、(認証されたユーザー用の) Web API へのアクセスを提供します。また、サーバー側のコードは、必要に応じてトークンを解析して ID 情報を取得することもできます。 (以下の「アクセストークンを ID トークンとして使用する」を参照してください)。さまざまな言語やプラットフォームで使用できるライブラリが多数あり、記述するコードを簡略化するのに役立ちます。詳細については、「Microsoft 認証ライブラリ (MSAL) の概要」を参照してください。

Microsoft Graph データにアクセスする必要がある場合は、サーバー側のコードで次の操作を行う必要があります。

アクセストークンを検証します (以下の「アクセストークンを検証する」を参照)。
Microsoft ID プラットフォームを呼び出して、OAuth 2.0 On-Behalf-Of flow フローを開始します。これには、アクセストークン、ユーザーに関するメタデータ、およびアドインの資格情報 (ID とシークレット) を含めます。 Microsoft ID プラットフォームは、Microsoft Graph へのアクセスに使用できる新しいアクセストークンを返します。
新しいトークンを使用して Microsoft Graph からデータを取得します。
複数の呼び出しに対して新しいアクセストークンをキャッシュする必要がある場合は、[MSAL.NET でトークンキャッシュのシリアル化する] を使用することをお勧めします。

重要

ベストセキュリティプラクティスとして、常にサーバー側のコードを使用して、Microsoft Graph 呼び出し、またはアクセストークンを渡す必要があるその他の呼び出しを行います。クライアントから Microsoft Graph への直接呼び出しを有効にするために、クライアントに OBO トークンを返しません。これにより、トークンが傍受またはリークされないように保護できます。適切なプロトコルフローの詳細については、「OAuth 2.0 プロトコルの図」を参照してください。

次のコードは、アクセストークンをサーバー側に渡す例を示しています。トークンは、サーバー側の Web API に要求を送信するときに Authorization ヘッダーに渡されます。この例では JSON データを送信するため、POST メソッドを使用していますが、サーバーに書き込まない場合は、アクセストークンの送信には GET で十分です。

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

ユーザーの Microsoft Graph のデータへのアクセス許可を取得するには、「Microsoft Graph への認証」を参照してください。

アクセストークンを検証する

サーバー上の WebAPI は、アクセストークンがクライアントから送信された場合、それを検証する必要があります。このトークンは、JSON Web トークン (JWT) です。そのため、この検証は最も標準的な OAuth でのトークンの検証とまったく同様に動作します。 JWT の検証を処理できるライブラリが複数入手可能ですが、その基本は次のとおりです。

トークンが整形式であることを確認する
トークンが意図した証明機関から発行されたことを確認する
トークンが Web API を対象にしていることを確認する

トークンの検証時には、次のガイドラインに留意してください。

有効な SSO トークンは Azure 証明機関 https://login.microsoftonline.com から発行されます。トークン内の iss クレームは、この値で始まっている必要があります。
トークンの aud パラメーターは、アドインの Azure アプリ登録のアプリケーション ID に設定されます。
トークンの scp パラメーターは access_as_user に設定します。

トークンの検証の詳細については、「Microsoft ID プラットフォームアクセストークン」参照してください。

アクセストークンを ID トークンとして使用する

アドインでユーザーの ID を検証する必要がある場合、getAccessToken() から返されたアクセストークンには ID を確定するために使用できる情報が含まれています。 ID に関連するトークン内のクレームは次のとおりです。

name: ユーザーの表示名。
preferred_username: ユーザーの電子メールアドレス。
oid - Microsoft ID システム内のユーザーの ID を表す GUID。
tid - ユーザーがサインインしているテナントを表す GUID。

これらのクレームと他のクレームの詳細については、「Microsoft ID プラットフォームの ID トークン」を参照してください。システム内のユーザーを表す一意の ID を作成する必要がある場合は、「クレームを使用してユーザーを確実に識別する」を参照してください。

アクセストークンの例

アクセストークンの標準的なデコードされたペイロードを次に示します。プロパティの詳細情報については、「Microsoft ID プラットフォームのアクセストークン」を参照してください。

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    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: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Outlook のアドインで SSO を使用する

Excel、PowerPoint、または Word のアドインで SSO を使用する場合と Outlook のアドインでそれを使用する場合とでは、小さいけれど重要な違いがいくつかあります。「Authenticate a user with a single sign-on token in an Outlook add-in」 (Outlook アドインでシングルサインオントークンを使用してユーザーを認証する) と「シナリオ: Outlook アドインでサービスにシングルサインオンを実装する」を参照してください。

Google Chrome は、2024 年にサードパーティの Cookie を段階的に廃止し、トラッキング防止という名前の機能を導入しています。 Chrome ブラウザーでトラッキング防止が有効になっている場合、アドインはサードパーティの Cookie を使用できません。アドインでは、複数のサインオン要求やエラーなど、ユーザーを認証するときに問題が発生する可能性があります。

認証エクスペリエンスの向上については、「デバイスの状態を使用した、ブロックされたサードパーティの Cookie を使用したブラウザーでの SSO エクスペリエンスの向上」を参照してください。

Google Chrome ロールアウトの詳細については、次のリソースを参照してください。

Office アドインでシングルサインオン (SSO) を有効にする

実行時の SSO の動作のしくみ

要件とベストプラクティス

アクセストークンをキャッシュしない

Outlook の先進認証を有効にする

フォールバック認証システムを実装する

SSO アドインの開発

Microsoft ID プラットフォームにアドインを登録する

アドインを構成する

Identity API 要件セットを含める

クライアント側のコードを追加する

getAccessToken を呼び出す場合

アクセストークンをサーバー側のコードに渡す

アクセストークンを検証する

アクセストークンを ID トークンとして使用する

アクセストークンの例

Outlook のアドインで SSO を使用する

関連項目

フィードバック

その他のリソース

Office アドインでシングル サインオン (SSO) を有効にする

実行時の SSO の動作のしくみ

要件とベスト プラクティス

アクセス トークンをキャッシュしない

Outlook の先進認証を有効にする

フォールバック認証システムを実装する

SSO アドインの開発

Microsoft ID プラットフォームにアドインを登録する

アドインを構成する

Identity API 要件セットを含める

クライアント側のコードを追加する

getAccessToken を呼び出す場合

アクセス トークンをサーバー側のコードに渡す

アクセス トークンを検証する

アクセス トークンを ID トークンとして使用する

アクセス トークンの例

Outlook のアドインで SSO を使用する

Google Chrome サードパーティ Cookie のサポート

関連項目

フィードバック

その他のリソース

Office アドインでシングルサインオン (SSO) を有効にする

要件とベストプラクティス

アクセストークンをキャッシュしない

アクセストークンをサーバー側のコードに渡す

アクセストークンを検証する

アクセストークンを ID トークンとして使用する

アクセストークンの例