アクセス認証プレビュー

概要

アクセス認証プレビューは、Workplaceでコンテンツが正しくプレビューされるようにします。そのためには、Workplaceで予期される形式でアクセス認証プレビューのメタデータのサポートを提供する必要があります。これにより、コンテンツのURLがシェアされたときに、Workplaceはそのメタデータをフェッチしてプレビューを作成できます。このプロセスはよくリンク展開と呼ばれます。

Facebookは、Open GraphプロトコルとFacebookクローラーでメタデータを取得して公開URLを展開できますが、より頻繁にWorkplaceにシェアされる非公開URLでは、このプロセスは不可能です。他のユーザーが非公開URLをWorkplaceにシェアした場合、あなたが設定するコールバックURLにWebhookが送信されます。そして、それをシェアしているユーザーのURLを記述したメタデータペイロードが記載された応答を返して、リンクプレビューをレンダリングすることができます。

Workplace上でシェアされたURLを表示する各ユーザーに対してこれと同じプロセスが繰り返され、ユーザーごとにプレビューの表示を制御することができます。

Workplace用のアクセス認証プレビューでは、ソースマテリアルのプライバシーが尊重される方法で、ユーザーはWorkplaceで情報を安全かつ容易にシェアできます。Workplace用のアクセス認証プレビューをサポートすると、プライバシーを意識した安全な方法で、コンテンツがWorkplaceで正しくプレビューされるようになります。

非公開URLのシェア

Workplaceでは、ユーザーは多くの場合、社内リソースへのリンクをシェアします。この種のリソースは、特定のユーザーだけが表示できるようにする必要があります。これは、利用者がニュース記事やブログ投稿などの公開コンテンツをシェアすることが多いFacebookとは対照的です。

Workplace上の公開URLと非公開URL

Workplaceが社内限定の非公開コンテンツのプレビューを生成するためには、いくつかのメタデータを提供する必要があります。提供者は、Workplaceの現在の閲覧者がコンテンツの表示を許可されているかどうかに応じて、彼らのためにメタデータを提供するかどうかを選択できます。

このドキュメントの内容

このドキュメントでは、アクセス認証プレビューを有効にする以下のようなコンポーネントについて概説します。

• アクセス認証プレビュー
• IDマッピング

構成

アクセス認証プレビューを有効にするには、以下が設定されるようにアプリを構成する必要があります。

• Workplaceコミュニティまたは1つ以上のグループへのアプリのインストール
• リンク展開のアクセス許可
• 統合によって展開されるURLを構成するドメインまたはドメインのセット
• フィールドプレビュー用の、Webhookトピックのリンクのサブスクリプション、およびメタデータを提供するためのコールバックURL

Webhooks

受信Webhook

次のように、Facebookが提供者にリクエストを送信する状況がいくつかあります。

1. Facebookがこれまで認識したことがない新しいURLがシェアされた場合(常にコンポーザーから送信)。
2. 新しいユーザーがコンテンツを表示しようとしており、そのユーザーがアクセス権限を持っているかどうかがFacebookにわからない場合(常にフィードから送信)。
3. 既存のコンテンツが再度シェアされているか期限切れになっている場合(コンポーザーまたはフィードから送信)。

Webhookリクエストの形式

上記のいずれのシナリオでも、Webhookは次の形式のPOSTリクエストとして送信されます。

{
  "object": "link",
  "entry": [
    {
      "time": int,
      "changes": [
        {
          "field": "preview",
          "value": {
            "community": {
              "id": string,
            },
            "user": {
              "id": string,
            },
            "link": string,
          }
        }
      ]
    }
  ]
}
    

このペイロードには、次のフィールドが含まれています。

例

POST /callback HTTP/1.1
Host: third-party.com
Accept: application/json
Content-Type: application/json
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587
...

{
    "object": "link",
    "entry": [{
        "time": 1501515097793,
        "changes": [{
            "field": "preview",
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
                "link": "https://company.third-party.com/document-about-this"
            }
        }]
    }]
}
    

Webhook応答の形式

Webhookリクエストを受信したら、特定の応答形式でメタデータペイロードを提供する必要があります。

{
  "data": [
    {
      "link": string,
      ?"canonical_link": string,
      ?"title": string,
      ?"description": string,
      ?"icon": string,
      ?"download_url": string,
      "privacy": 'organization' | 'accessible' | 'inaccessible',
      ?"type": 'document' | 'folder' | 'task' | 'link',
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
          ?"color" => 'blue' | 'green' | 'yellow' | 'orange' | 'red',
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

このペイロードには、次のフィールドが含まれていることになっています。

完全な応答の例

HTTP/1.1 200 OK
Content-Type: application/json
X-Hub-Signature: sha1=b5a6f32f084100ae5b355174b9bb8398f5fbe983
...

{
  "data": [
    {
      "link": "https://taaskly.herokuapp.com/task/4",
      "title": "Launch Workplace Integration for F8",
      "privacy": "organization",
      "type": "task",
      "additional_data": [
        {
          "title": "Owner",
          "format": "user",
          "value": "319922278498384"
        },
        {
          "title": "Created",
          "format": "datetime",
          "value": "2018-02-28T03:35:40.827Z"
        },
        {
          "title": "Priority",
          "format": "text",
          "value": "high",
          "color": "red"
        }
      ]
    }
  ],
  "linked_user": true
}
    

プライバシーモード

プライバシーモードは、Facebookが現在のユーザーとその後のユーザーにユーザー認証を要求するかどうかと無関係に、ユーザーがコンテンツを表示できるかどうかを決定します。

1. organization: ユーザーは表示可能、ユーザー認証は不要
   ユーザーが表示できる場合、Facebookはコンテンツを直接表示できます。コンテンツがドメイン(会社)内の誰にでも表示されることが想定されている場合は、このモードで対応できます。新しいユーザーが新しいコンテンツを表示するたびに、わざわざFacebookがWebhookを送信することはありません。
2. accessible: 現在のユーザーは表示可能だが、それ以外のユーザーにはユーザーIDマッピングが必要な場合がある
   提供者は、この特定のユーザーが当該コンテンツの表示を許可されていることを把握していますが、それ以外のユーザーが表示を許可されているとは限りません。Facebookはプレビューを表示しますが、他のユーザーについては引き続きWebhookを送信します。
3. inaccessible: ユーザーは表示不可
   提供者はユーザーを認識しており、このユーザーが当該コンテンツの表示を許可されていないことを知っています。Facebookは、プライバシー通知(利用不可、非公開など)をレンダリングします。

追加データ

リンクプレビューに情報を追加するために、最大3つの追加データアイテムを送信できます。追加データアイテムはキー/値要素のセットで構成されますが、値はさまざまな形式で設定できます。

現在のところ、次の4つの形式がサポートされています。

• text: 値はそのままレンダリングされます。文字列を指定する必要があります。この形式では、追加データにcolorプロパティを含めることもできます。blue、green、yellow、orange、redのいずれかの値を指定する必要があります。指定した場合は、その色を背景として値がレンダリングされます。
• date: 値は時刻を含まないISO-8601日付形式として解析され、時刻表示なしでレンダリングされます。
• datetime: 値は時刻と時間帯を含むISO-8601日付形式として解析され、ユーザーの時間帯の時刻表示でレンダリングされます。
• user: 値はユーザーIDとして解析され、ユーザーの名前がレンダリングされます。

追加データが設定された場合、download_urlパラメーターは無視されます。

ファイルプレビューのレンダリング(任意)

ドキュメントのプライバシーモードがorganizationまたはaccessibleとしてマークされていて、ダウンロードURLが指定されている場合は、データをダウンロードするための追加リクエストが送信されます。

GET /download/super-fancy-document HTTP/1.1
Host: provider.com
Accept: <some mime types>
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587

これにより、Workplaceはこのファイルを取得して写真に変換し、それに基づいて複数の写真を含む投稿を作成します。

IDマッピング

上記のように、アクセス認証プレビューを提供するには、何らかの種類のIDマッピングが必要です。IDマッピングは、Workplaceユーザーがプレビュー対象のコンテンツを表示するアクセス許可を持っているかどうかを制御し、Workplaceでコンテンツのアクセスルールが確実に尊重されるようにします。

組織全体のマッピング

IDマッピングの最も単純な形態は、組織全体のマッピングです。この場合、Workplaceのユーザーにプレビューが表示されるには、Workplaceコミュニティのメンバーシップがあれば十分です。このシナリオは、全社的なイントラネット、またはすべてのオブジェクト(または少なくともそれらのメタデータ)が会社全体に表示されるサービスに対してリンクをプレビューする場合によく使用されます。

Workplaceコミュニティに統合がインストールされている場合は、インストール時に取得したアクセストークンを使用して、/communityエンドポイントからコミュニティIDを確認できます。このコミュニティIDをトークンとともに保存して、サービス内のテナントまたは組織のIDにマッピングできます。そうすれば、Workplaceコミュニティとサービス内の組織との間にマッピングが作成されます。

これにより、アクセス認証プレビューのWebhookリクエストに応答する際に、WebhookペイロードのコミュニティIDがその組織にリンクされたコミュニティIDと一致することを確認して、メタデータペイロードを安全に返せるかどうかを判断できます。そのペイロードのプライバシーをORGANIZATIONとしてマークすれば、FacebookがそのWorkplaceコミュニティのユーザーごとに追加のWebhookを送信する必要がなくなります。

ユーザーごとのマッピング

よりきめ細かいアクセス許可の設定が必要な場合は、ユーザーごとのマッピングをサポートして、Workplaceの閲覧者ごとにメタデータをレンダリングするかどうかを選択できます。Workplaceは、個々のWebhookペイロードでアクセス認証プレビュー用のユーザーIDを送信します。ユーザーごとのマッピングをサポートするには、Webhookペイロードで送信されたWorkplaceユーザーIDに対して、システム内のどのユーザーレコードがマップされているかを知る必要があります。

特定のWorkplaceユーザーIDを初めて受信した場合は、ブーリアンフィールドlinked_userをfalseに設定して応答できます。そうすると、Workplaceに[プレビューを有効にする]ボタンが表示され、ユーザーは自分のアカウントをリンクするよう求められます。

ユーザーがボタンを押すと、定義したアカウントリンクエンドポイントのダイアログが開きます。このダイアログで、サービス内のユーザーセッションを検証できます。WorkplaceはPOSTリクエストを使用してこのURLを開き、署名されたリクエストパラメーターを渡します。これには現在のユーザーIDとコミュニティIDが含まれています。

POST https://www.example.com/account_linking?redirect_uri=https%3A%2F%2Ffoxfabrics.facebook.com%2Flink_complete HTTP/1.1
Host: foxfabrics.third-party.com
Origin: http://www.facebook.com
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
...

signed_request=238fsdfsd.oijdoifjsidf899
    

ペイロード内には、このユーザーに関する情報が含まれているsigned_requestパラメーターがあります。このリクエストは次のようにしてデコードできます。

1. コンテンツを「.」文字で区切られた2つの部分に分割します。
2. base64urlから最初の部分(署名)をデコードします。
3. base64urlから2番目の部分(ペイロード)をデコードし、次に結果として返されたJSONオブジェクトをデコードします。
4. app secretに基づいて、エンコードされたペイロードのHMACと署名が一致するかどうかを確認します。

このペイロードには、次のフィールドが含まれています。

{
  "algorithm": "HMAC-SHA256",
  "user_id": "88575656148087",
  "community_id": "138169208138649"
}
    

この時点で、WorkplaceユーザーID、コミュニティID、そしてサービスの検証済みユーザーセッションを取得しているので、サービスのユーザーのIDの横にユーザーのWorkplace IDを記録することができます。完了したら、元のリクエストでクエリパラメーターredirect_uriとして提供されたURLにリダイレクトします。

GET {$redirect_uri} HTTP/1.1
Host: foxfabrics.facebook.com
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
Referer: https://www.example.com/account_linking
...
    

Workplaceは、IDマッピングが完了したことを認識し、アクセス認証プレビューのメタデータを再度リクエストします。今度はlinked_userをtrueに設定して応答し、必要なメタデータを提供できます。

よくある質問