シナリオ: Outlook アドインでサービスにシングル サインオンを実装する

  • [アーティクル]

この記事では、独自のバックエンド サービスにシングル サインオンの実装を提供するために、シングル サインオン アクセス トークンと Exchange ID トークンを同時に使用する推奨の方法について説明します。 両方のトークンを同時に使用することで、SSO アクセス トークンが使用できる場合はその利点を活用し、そのトークンが使用できない場合でもアドインが確実に動作するようにします。SSO アクセス トークンは、ユーザーがそのトークンをサポートしていないクライアントに切り替えたときや、ユーザーのメールボックスがオンプレミスの Exchange サーバーにある場合などは使用できません。

注:

現在、シングル サインオン API は Word、Excel、Outlook, および PowerPoint でサポートされています。 シングル サインオン API の現在のサポート状態に関する詳細は、「IdentityAPI の要件セット」を参照してください。 Outlook アドインを使用している場合は、Microsoft 365 テナントの先進認証を有効にしてください。 これを行う方法については、「Exchange Onlineで Outlook の先進認証を有効または無効にする」を参照してください。

SSO アクセス トークンを使用する理由

Exchange ID トークンはアドインの API のすべての要件セットで使用できるため、このトークンだけを使用して、SSO トークンは完全に無視してしまうことがあります。 ただし、SSO トークンには Exchange ID トークンよりも優れた点がいくつかあるため、使用できるときには SSO トークンが推奨の方法になります。

  • SSO トークンは、標準の OpenID 形式を使用して、Azure が発行します。 そのため、このトークンの検証プロセスは、とても簡単になります。 それに比べて、Exchange ID トークンは JSON Web トークン標準に基づいたカスタム形式を使用するため、トークンの検証にカスタムの操作が必要になります。
  • SSO トークンは、Microsoft Graph のトークンを取得するためにバックエンドで使用できます。このとき、ユーザーが追加のサインイン操作を実行する必要はありません。
  • SSO トークンは、ユーザーの表示名など豊富な ID 情報を提供します。

アドインのシナリオ

この例では、アドイン UI およびスクリプト (HTML + JavaScript) の両方で構成されているアドインと、そのアドインで呼び出すバックエンド Web API について考えてみます。 バックエンド Web API は、Microsoft Graph API と Contoso Data API (架空のサード パーティ製 API) の両方を呼び出します。 Microsoft Graph API と同じように、Contoso Data API も OAuth 認証を必要とします。 要件は、アクセス トークンの有効期限が切れるたびに バックエンド Web API がユーザーに資格情報を求めるダイアログを表示することなく、両方の API を呼び出せるようにすることです。

そのために、バックエンド API は、ユーザーに関するセキュリティで保護されたデータベースを作成します。 それぞれのユーザーごとに、このデータベース内のエントリが割り当てられます。バックエンドは、このデータベースに Microsoft Graph API と Contoso Data API の長期間有効な更新トークンを保存します。 次に示す JSON マークアップは、データベース内のユーザーのエントリを表しています。

{
  "userDisplayName": "...",
  "ssoId": "...",
  "exchangeId": "...",
  "graphRefreshToken": "...",
  "contosoRefreshToken": "..."
}

アドインは、バックエンド Web API を呼び出すたびに、SSO アクセス トークン (使用可能な場合) または Exchange ID トークン (SSO トークンが使用不可の場合) のどちらかを含めます。

アドインのスタートアップ

  1. アドインの起動時に、アドインはバックエンド Web API に要求を送信して、ユーザーが登録されているかどうか (ユーザー データベースに関連付けられたレコードがあるか) と、その API が Graph および Contoso の更新トークンを保持しているかを判断します。 アドインは、この呼び出に SSO トークン (使用可能な場合) と ID トークンの両方を含めます。

  2. Web API は、「Outlook アドインでシングル サインオン トークンを使用してユーザーを認証する」と「Exchange の ID トークンを使用してユーザーを認証する」に示した方法を使用して、両方のトークンを検証して一意の ID を生成します。

  3. SSO トークンが提供された場合、Web API は SSO トークンから生成された一意の ID と一致する ssoId 値を保持するエントリについて、ユーザー データベースを照会します。

    • エントリが存在しない場合は、次の手順に進みます。
    • エントリが存在する場合は、手順 5 に進みます。

  4. Web API は、Exchange ID トークンから生成された一意の ID と一致する exchangeId 値を保持するエントリについて、データベースを照会します。

    • エントリが存在しているときに、SSO トークンが提供されていた場合は、データベース内のユーザーのレコードを更新して、ssoId の値を SSO トークンから生成された一意の ID に設定して、手順 5 に進みます。
    • エントリが存在しているときに、SSO トークンが提供されていなかった場合は、手順 5 に進みます。
    • エントリが存在しないときには、新しいエントリを作成します。 ssoId を SSO トークン (使用可能な場合) から生成された一意の ID に設定し、exchangeId を Exchange ID トークンから生成された一意の ID に設定します。

  5. ユーザーの graphRefreshToken 値で有効な更新トークンについて調べます。

    • この値が無効または見つからないときに、SSO トークンが提供されていた場合は、OAuth2 On-Behalf-Of フローを使用して Graph のアクセス トークンと更新トークンを取得します。 ユーザーの graphRefreshToken 値に更新トークンを保存します。

  6. graphRefreshToken と contosoRefreshToken の両方で有効な更新トークンについて調べます。

    • 両方の値が有効な場合は、ユーザーが既に登録および構成されていることを示す応答をアドインに返します。
    • どちらかの値が無効な場合は、ユーザーの設定が必要なことと、構成が必要になるサービスがどちらか (Graph または Contoso) を示す応答をアドインに返します。

  7. アドインは、この応答を確認します。

    • ユーザーが既に登録および構成されている場合、アドインは通常の操作を続行します。
    • ユーザーの設定が必要な場合、アドインは「セットアップ」モードに移行して、ユーザーにアドインを承認するように求めるダイアログを表示します。

バックエンド Web API の承認

Microsoft Graph API と Contoso Data API を呼び出すバックエンド Web API を承認する手順は、1 回だけ実施されるようにすることが理想的です。そうすることで、ユーザーにサインインを求めるダイアログの表示を最小限に抑えるようにします。

バックエンド Web API からの応答に基づいて、アドインは Microsoft Graph API または Contoso Data API、またはその両方のユーザーを承認することが必要になる場合があります。 どちらの API も OAuth2 認証を使用するため、その方法はどちらも同様になります。

  1. アドインは、API の使用を承認する必要があることをユーザーに通知して、そのプロセスを開始するためにリンクまたはボタンをクリックするように求めます。

  2. このフローが完了すると、アドインは更新トークンをバックエンド Web API に送信し、SSO トークン (使用可能な場合) または Exchange ID トークンを含めます。

  3. バックエンド Web API はデータベース内でユーザーを見つけて、該当する更新トークンを更新します。

  4. アドインは、通常の操作を続行します。

通常の操作

アドインがバックエンド Web API を呼び出すときには、SSO トークンまたは Exchange ID トークンを必ず含めます。 バックエンド Web API は、このトークンでユーザーを見つけて、保存されている更新トークンを使用して Microsoft Graph API と Contoso Data API のアクセス トークンを取得します。 更新トークンが有効な間、ユーザーは再度サインインする必要がなくなります。