Workplace용 외부 콘텐츠 공유

개요

Workplace용 외부 콘텐츠 공유를 사용하면 소스 자료의 개인정보를 보호하는 방식으로 사용자가 Workplace에서 안전하고 손쉽게 정보를 공유할 수 있습니다.

외부 콘텐츠 공유를 지원하면 Workplace에서 콘텐츠의 미리 보기가 바르게 표시되고, 사용자가 폴더를 Workplace 그룹과 링크하며, Workplace의 그룹 구성 도구에 콘텐츠를 제공함으로써 최근에 만든 콘텐츠를 그룹 내에서 바로 손쉽게 공유할 수 있습니다.

비공개 URL 공유

사용자는 Workplace에서 특정인만 볼 수 있어야 하는 사내 리소스 링크를 공유하는 경우가 많습니다. 이는 사용자가 일반적으로 신문 기사나 블로그 게시물과 같은 공개 콘텐츠를 공유하는 Facebook과는 대조적입니다.

Workplace의 공개 및 비공개 URL

Workplace가 회사 비공개 콘텐츠에 대한 미리 보기를 생성하려면 일부 메타데이터를 제공해야 합니다. 제공업체는 콘텐츠를 볼 수 있도록 허용되는지 여부에 따라 Workplace에서 현재 보고 있는 사람에 대한 메타데이터를 제공할지 여부를 선택할 수 있습니다.

문서 내용

이 문서에서는 외부 콘텐츠 공유를 활성화하기 위한 구성 요소를 간략히 설명합니다. 주요 구성 요소는 3가지가 있습니다.

• 인증된 미리 보기
• ID 매핑
• 구성 도구 확장 기능

이 문서에서는 외부 콘텐츠 공유 지원을 추가하도록 앱을 구성하는 방법도 설명합니다.

앱 구성

외부 콘텐츠 공유 지원을 위해 앱을 설정하려면 다음의 필드 3개를 제공해야 합니다.

• 도메인 또는 도메인 세트 - 통합이 인증된 미리 보기를 제공할 모든 URL의 루트에 있습니다.

  • 주어진 도메인(예 example.com)에는 하위 도메인(예: acme.example.com)도 포함됩니다.
• 통합에서 지원하는 모든 URL의 상대 경로를 매핑하는 정규 표현식.

  • 예를 들어 www.example.com/download?id=123 또는 www.example.com/file/456를 매칭하고자 하지만 www.example.com/blog는 매칭하고 싶지 않다면 \/(download?|file\/).+/와 같은 정규식을 사용할 수 있습니다.
  • 도메인 또는 도메인 세트에 모든 URL이 포함되는 경우, 이곳을 비워두거나 모두 매칭 정규식(예: /.*/)을 사용해도 됩니다.
• ID 매핑 엔드포인트 - 미리 보기를 봐야 하는 Workplace 사용자의 ID 매핑에 사용합니다.

앱은 Link Webhooks 주제와 preview를 구독하도록 설정해야 하고 링크 펼치기 권한이 활성화되어 있어야 합니다.

인증된 미리 보기

외부 콘텐츠 공유의 주요 기능은 Workplace에서 콘텐츠를 올바르게 미리 볼 수 있도록 하는 것입니다. 이는 인증된 미리 보기 메타데이터에 대한 지원을 Workplace에서 기대하는 형식으로 제공하는 것을 포함합니다. 예를 들어, 콘텐츠 URL이 공유되면 Workplace에서 해당 메타데이터를 가져와 미리 보기를 생성할 수 있습니다. 이 프로세스를 종종 링크 펼치기라고 부릅니다.

Meta는 오픈 그래프 프로토콜과 Facebook 크롤러를 사용하여 공개 URL을 펼치기 위한 메타데이터를 가져올 수 있지만 Workplace로 보다 일반적으로 공유되는 비공개 URL에는 이 프로세스를 적용할 수 없습니다. 대신, 누군가 Workplace에 비공개 URL을 공유하면 정의한 콜백 URL에 Webhooks가 발행됩니다. 그러면 URL을 공유하는 사람에 대해 URL을 설명하는 메타데이터 페이로드로 응답하여 링크 미리 보기를 렌더링할 수 있게 됩니다.

이 동일한 프로세스는 Workplace에서 공유된 URL을 보는 각 사용자에 대해 반복되므로 사용자별로 미리 보기 가시성을 관리할 수 있습니다.

구성

인증된 미리 보기를 지원하려면 다음에 대해 앱을 구성해야 합니다.

• Workplace 커뮤니티 또는 하나 이상의 그룹에 설치
• 링크 펼치기 권한(현재 허용 리스트에서 제공)
• 통합을 통해 펼쳐질 URL로 구성된 도메인 또는 도메인 집합
• 필드 미리 보기의 경우 Webhooks 주제인 링크를 구독, 메타데이터를 제공하는 경우 콜백 URL을 구독

Webhooks

Webhooks 수신하기

Facebook은 다음과 같은 여러 가지 상황에서 제공업체에 요청을 보냅니다.

1. 처음 보는 새로운 URL을 공유하는 경우(항상 작성 도구에서 공유).
2. 새로운 사용자가 콘텐츠를 보고 있고 Facebook에서 사용자에게 액세스 권한이 있는지 모르는 경우(항상 피드에서 공유).
3. 기존 콘텐츠가 다시 공유되거나 만료된 경우(작성 도구 또는 피드에서 공유).

Webhooks 요청 형식

위의 모든 상황에서 Webhooks는 다음과 같은 형식에 따라 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"
            }
        }]
    }]
}
    

Webhooks 응답 형식

Webhooks 요청을 수신하면 특정 응답 형식으로 메타데이터 페이로드를 제공해야 합니다.

{
  "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
}
    

공개 범위 모드

공개 범위 모드는 현재 사용자와 이후 사용자에 대해 사용자 인증이 필요한지 여부를 나타내는 가시성을 결정합니다.

1. organization: 사용자에게 표시, 사용자 인증 불필요
   사용자에게 표시되는 경우 Facebook에서 콘텐츠를 직접 보여줄 수 있습니다. 이는 도메인(회사)에 있는 모든 사람에게 콘텐츠를 표시해야 하는 경우에 유용합니다. 새로운 사용자가 신규 콘텐츠를 볼 때마다 Webhooks가 전송되지는 않습니다.
2. accessible: 현재 사용자에게 표시, 다른 사용자의 경우 사용자 ID 매핑이 필요할 수 있음
   제공업체에서 이 특정 사용자가 해당 콘텐츠를 보도록 허용되었다는 것을 알고 있지만 그 외 다른 사람이 볼 수 있다는 의미는 아닙니다. Facebook에서는 미리 보기를 보여주지만 다른 사용자에 대해서는 계속 Webhooks를 보낼 것입니다.
3. inaccessible: 사용자에게 표시하지 않음
   제공업체에서 사용자를 알고 있고, 해당 사용자가 콘텐츠를 보도록 허용되지 않았다는 것을 알고 있습니다. Facebook에서는 공개 범위 알림(예: 사용 불가, 비공개)을 렌더링합니다.

추가 데이터

링크 미리 보기에서 자세한 정보를 추가하려면 추가 데이터 항목을 **3개**까지 보낼 수 있습니다. 추가 데이터 항목은 일련의 키-값 요소로 구성됩니다. 하지만 값은 다양한 방식으로 형식을 지정할 수 있습니다.

현재 다음과 같은 네 가지 형식이 지원됩니다.

• text: 값을 있는 그대로 렌더링합니다. 이 값은 반드시 문자열이어야 합니다. 이 형식의 경우 추가 데이터에는 color 속성도 포함될 수 있습니다. 이는 blue, green, yellow, orange, red 값 중 하나여야 합니다. 값이 있을 경우, 배경으로 색을 포함하여 값을 렌더링합니다.
• date: 시간 없이 ISO-8601 날짜 형식으로 값을 파싱하고 시간 표시 없이 이를 렌더링합니다.
• datetime: 시간 및 시간대를 포함하여 ISO-8601 날짜 형식으로 값을 파싱하고 사용자 시간대의 시간 표시를 포함하여 렌더링합니다.
• user: 사용자 ID로 값을 파싱하고 사용자 이름을 렌더링합니다.

렌더링 파일 미리 보기(선택 사항)

문서의 공개 범위 모드가 organization 또는 accessible로 표시되고 다운로드 URL이 제공되는 경우 Facebook에서 데이터를 다운로드하기 위한 추가 요청을 전송합니다.

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를 저장하고 테넌트 또는 서비스 내부의 조직 식별자에 매핑할 수 있습니다. 그러면 Workplace 커뮤니티와 서비스 범위 내의 조직 간에 매핑이 생성됩니다.

그런 다음, 인증된 미리 보기 Webhooks 요청에 응답할 때 Webhooks 페이로드의 커뮤니티 ID가 조직에 연결된 커뮤니티 ID와 일치한지 확인한 후 메타데이터 페이로드를 반환해도 안전한지 결정할 수 있습니다. 페이로드의 공개 범위를 ORGANIZATION으로 표시하면 Facebook이 해당 Webhooks 커뮤니티에서 각 사용자에 대해 추가적인 Webhooks를 전송할 필요가 없습니다.

사용자별 매핑

추가적인 권한 세분화가 필요한 경우 사용자별 매핑을 지원하여 Workplace에서 개별적으로 각각의 보는 사람에 대해 메타데이터를 렌더링할지 여부를 선택할 수 있습니다. Workplace는 인증된 미리 보기에 대해 각 Webhooks 페이로드에서 사용자 ID를 전송합니다. 사용자별 매핑을 지원하려면 시스템의 어떤 사용자 기록이 Webhooks 페이로드에서 전송된 Workplace 사용자 ID에 매핑되는지 알아야 합니다.

특정 Workplace 사용자 ID를 처음 접하는 경우 부울 필드 linked_user를 false로 설정하여 응답할 수 있습니다. 그러면 Workplace에서 사용자가 자신의 계정을 연결하도록 유도하는 미리 보기 활성화 버튼이 표시됩니다.

이 버튼을 누르면 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. 첫 번째 부분인 서명을 base64url에서 디코딩합니다.
3. 두 번째 부분인 페이로드를 base64url에서 디코딩하고, 그 결과로 얻은 JSON 개체를 디코딩합니다.
4. 서명이 앱 시크릿 코드를 기반으로 인코딩한 페이로드의 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로 설정하여 응답하고 필요한 메타데이터를 제공합니다.

구성 도구 확장 기능

사용자가 Workplace에 공유하는 링크의 인증된 미리 보기를 제공하는 것은 그 자체만으로도 매우 강력한 기능입니다. 하지만 구성 도구 확장 기능을 지원하면 사용자가 앱에서 작업하던 콘텐츠를 Workplace에서 직접 공유하는 것을 훨씬 쉽게 만들 수 있습니다.

통합이 구성 도구 확장 기능을 지원할 경우, 사용자가 활성화된 Workplace 그룹에서 게시물을 작성하기 시작할 때 최근 또는 관련 문서의 리스트를 제공할 수 있고 Workplace는 해당 리스트를 렌더링하여 사용자가 URL을 복사해서 붙여 넣을 필요 없이 공유할 수 있도록 합니다. 그 과정에서 얻은 공유 개체는 인증된 미리 보기 기능의 권한을 따르는 등, 수동으로 공유한 개체와 동일하게 작동합니다.

구성 도구 확장 기능은 ID가 매핑된 사용자를 필요로 하므로 개인화된 문서 리스트를 구성 도구에 반환할 수 있습니다.

구성

구성 도구 확장 기능을 지원하려면 앱에 다음과 같은 구성이 필요합니다.

• link 주제 및 collection 필드에 대한 Webhooks 구독.
• 계정 링크 URL(앱 구성 시 제공).

Webhooks 요청 형식

링크된 사용자가 통합의 구성 도구 확장 기능을 호출하면 Workplace가 Webhooks를 보내서 다음의 형식으로 문서 리스트를 가져오도록 합니다.

{
  "object": "link",
  "entry": [
    {
      "time": int,
      "changes": [
        {
          "field": "collection",
          "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": "collection",
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
            }
        }]
    }]
}
    

응답 형식

이 요청을 처리하려면 콜백 URL이 'X-Hub-Signature'을 인증하고 구성 도구에서 다음의 형식으로 표시될 개체 세트를 포함하여 응답해야 합니다.

{
  "data": [
    {
      "link": string,
      "title": string,
      ?"description": string,
      ?"icon": string,
      ?"download_url": string,
      "privacy": ORGANIZATION | ACCESSIBLE,
      "type": DOCUMENT | FOLDER | TASK | LINK,
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

이 페이로드에는 다음의 필드를 포함해야 합니다.

예:

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

{
  "data": [
    {
      "link": "https://company.third-party.com/document-A",
      "title": "Slides for Project A",
      "description": "Short summary of the slides.",
      "download_url": "https://company.provider.com/download/document-A",
      "privacy": "accessible",
      "type": "document"
    },
    {
      "link": "https://company.third-party.com/folder-B",
      "title": "Folder B",
      "privacy": "public",
      "type": "folder",
    }
  ],
  "linked_user": true
}