Разрешения

Обзор

Системный администратор Workplace может управлять возможностями и функциями, доступными в рамках отдельных интеграций, создавая приложения и предоставляя им определенные разрешения. Каждое приложение получает название в соответствии с услугами, которые с ним связаны. С приложениями связываются уникальные маркеры доступа и разрешения, от которых зависит, какую именно информацию это приложение может считывать и записывать.

В этом руководстве подробнее описана модель приложений и разрешений.

Настройка разрешений при редактировании приложения пользовательской интеграции

Доступные разрешения

Каждому приложению Workplace можно предоставить собственный набор разрешений, позволяющих контролировать доступные ему функции Graph API и Account Management API.

Разрешения, которое вы предоставляете новому приложению, действуют для всех аккаунтов в пределах вашего сообщества. Владельцам аккаунтов не требуется предоставлять приложению какие-либо дополнительные разрешения, чтобы воспользоваться его функциями. В этом заключается отличие от модели разрешений Facebook, где каждый пользователь отдельно предоставляет приложению разрешения при входе.

Ниже приведен полный список всех разрешений, которые доступны для интеграций, а также сведения о возможном использовании каждого из них.

Разрешения уровня группы

Некоторые разрешения можно предоставлять интеграциям только для заданного набора групп. Благодаря этому у интеграции будет доступ только к определенному массиву контента.

Например, можно позволить интеграции публиковать уведомления только в собственной группе команды или разрешить интеграции приложения для сотрудников считывать контент только из определенных открытых групп.

Задать разрешения уровня группы для пользовательской интеграции можно с помощью панели доступа к группам в диалоге редактирования интеграции.

Предоставление разрешений уровня группы для этой интеграции

На уровне группы можно задать следующие разрешения:

• чтение контента группы — чтение публикаций, комментариев и профилей участников выбранных групп;
• управление контентом группы — управление публикациями и комментариями в выбранных группах;
• управление группами — редактирование и удаление выбранных групп и их участников.

Интеграцию можно настроить таким образом, чтобы разрешения уровня группы применялись для всех групп, определенных групп, выбранных системным администратором, или на усмотрение администраторов соответствующих групп.

Процедура установки администратором

Если выбран режим, в котором администраторы групп могут включать для них интеграции, администратор группы увидит новую вкладку Интеграции на экране Управление группой, где сможет включить нужные интеграции для своей группы.

Пример приложения, которое теперь может активировать администратор группы

Маркеры приложений и их использование

При создании нового приложения для Workplace генерируется маркер доступа для использования с Graph API, Account Management API или Webhooks.

Этот маркер доступа отображается только один раз, поэтому его необходимо надежно сохранить для дальнейшего использования в коде.

Процедура сброса маркера для приложения пользовательской интеграции

Срок действия маркеров приложений в Workplace никогда не истекает, и их не требуется обновлять, если только они не были сброшены вручную. После редактирования разрешений, предоставленных определенному приложению, существующий маркер остается действительным. Генерировать новый не требуется.

Если вам потребуется сделать маркер недействительным, его можно сбросить, нажав кнопку Сбросить маркер доступа в диалоге Редактирование приложения. Будет сгенерирован и отображен новый маркер, а существующий сразу же станет недействительным.

Безопасность маркеров

Маркеры доступа очень функциональны. Они служат для доступа к данным вашей компании в Workplace. При создании приложения определите минимальный набор разрешений, необходимый для реализации функций интеграции, и не предоставляйте разрешений, которые не нужны.

При сохранении маркеров или добавлении их в репозитории кода уделите самое пристальное внимание их защите от несанкционированного доступа.

Для дополнительной защиты интеграции реализуйте белый список IP-адресов, чтобы ограничить область использования маркеров только серверами, адреса которых в него входят.

Добавление белого списка IP-адресов с целью ограничить область применения маркеров определенными серверами, а также включение проверочного кода на базе секрета приложения

Автоматическое удаление неиспользуемых разрешений

Если пользовательская интеграция не совершает никаких вызовов с использованием определенного разрешения в течение 30 дней, это разрешение удаляется. После того как это произойдет для пользовательской интеграции в первый раз, такое удаление можно будет запретить.

Если у вас настроена действительная подписка на Webhooks, отправляемые объекты Webhooks учитываются в качестве случаев использования соответствующего разрешения.

Средства контроля автоматического удаления разрешений

Проверочный код на базе секрета приложения

Срок действия маркеров приложений для Workplace не ограничен. Для дополнительной защиты в пользовательской интеграции можно настроить требование проверочного кода на базе секрета приложения. Если соответствующий параметр включен, вызовы API выполняются только из серверного кода, причем помимо маркера доступа в вызове потребуется указать проверочный код на базе секрета приложения, срок действия которого ограничен.

Чтобы сгенерировать проверочный код с ограниченным сроком действия, необходимо объединить маркер с меткой времени Unix, разделив их символом |, а затем создать из полученной строки хэш SHA-256, используя в качестве ключа секрет приложения. Вот пример на PHP:

$appsecret_proof = hash_hmac('sha256', $access_token.'|'.time(), $app_secret); 

Чтобы выполнить вызов API с использованием проверочного кода на базе секрета приложения, передайте сгенерированный хэш в параметре appsecret_proof вместе с параметром appsecret_time, задав в качестве его значения метку времени, которая использовалась при хэшировании секрета приложения, а также маркер доступа.

GET https://graph.facebook.com/v2.9/community/groups?
&access_token={access-token}
&appsecret_proof={appsecret_proof}
&appsecret_time={appsecret_time}

Исследование функций API с помощью Postman

Postman — это инструмент, который широко используется для работы с веб-API. Вы можете воспользоваться Postman для исследования возможностей Workplace API, однако при этом возникает сложность, связанная с параметром $appsecret_proof: это значение рассчитывается и действует в течение пяти минут, поэтому было бы проще, если бы Postman мог генерировать его в момент запроса. Это можно реализовать с помощью выполняемых перед запросом скриптов и параметров Postman. В качестве отправной точки можно воспользоваться таким скриптом:

// Add to Postman's Pre-request Script Tab
var access_token = "replace-me";
var app_secret = "replace-me";
var time = (new Date().getTime()/1000|0);
postman.setEnvironmentVariable("access_token", access_token)
postman.setEnvironmentVariable("appsecret_time", time);
postman.setEnvironmentVariable("appsecret_proof", CryptoJS.HmacSHA256(access_token + '|' + time, app_secret));

Создайте активную среду (по умолчанию ее нет), а затем добавьте эти три параметра, которые рассчитываются в выполняемом перед запросом скрипте