Сервисные приложения

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

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

Сервисные приложения используются, чтобы управлять ресурсами пользователей в организации по API. Например, с их помощью вы сможете создать резервную копию писем или управлять событиями в Календаре пользователя. Всего можно создать до 20 сервисных приложений.

Внимание

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

Подключение сервисных приложений

  1. Войдите в аккаунт владельца организации.

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

    1. Откройте страницу создания OAuth-приложения.

    2. Укажите название вашего сервиса и при необходимости прикрепите иконку.

    3. В блоке Платформы приложения выберите Веб-сервисы. В поле Redirect URI нажмите ссылку Подставить URL для отладки.

    4. В разделе Доступ к данным укажите права доступа, которые необходимы для управления сервисными приложениями в организации:

      • ya360_security:service_applications_read — чтение списка сервисных приложений;

      • ya360_security:service_applications_write — управление списком сервисных приложений (чтение и запись).

    5. Добавьте электронную почту для связи. Внизу страницы нажмите Создать приложение. На экране появятся его описание.

    6. Скопируйте идентификатор приложения из поля ClientID — он потребуется для получения OAuth-токена. В дальнейшем открыть страницу со всеми вашими приложениями вы сможете по ссылке oauth.yandex.ru/.

  3. Запросите OAuth-токен любым подходящим способом. Он понадобится для дальнейшей регистрации всех сервисных приложений в организации.

    Отладочный OAuth-токен можно получить вручную:

    1. Перейдите по ссылке

      https://oauth.yandex.ru/authorize?response_type=token&client_id=<main_app_client_id>

      Вместо <main_app_client_id> подставьте значение ClientID из п. 2.6.

    2. Если OAuth-токен вашему приложению выдается впервые, откроется экран авторизации. После входа Яндекс OAuth перенаправит вас на страницу с токеном. Подробнее об отладочных токенах.

  4. Уведомите пользователей и получите от них согласие, если они не давали его ранее, на доступ администратора к управлению их ресурсами согласно пункту 3.7 оферты.

  5. Активируйте функцию сервисных приложений с помощью запроса:

    POST https://api360.yandex.net/security/v1/org/<org_id>/service_applications/activate

    Вместо <org_id> подставьте идентификатор вашей организации.

  6. Зарегистрируйте сервисное приложение. С его помощью можно будет получать временные OAuth-токены пользователей. Срок действия временного токена — 1 час.

    1. Создайте отдельное OAuth-приложение по аналогии с созданием основного приложения (п. 2). В качестве прав доступа этого приложения укажите те, которые будут использоваться в API-запросах .

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

      Пример
      curl --location \
--request POST 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications' \ 
--header 'Authorization: OAuth <owner_token_to_manage_service_app>’ \
--header 'Content-Type: application/json' \
--data-raw '{ \
  "applications": [ \
    { \
      "id": “<OAuth_service_app_client_id>”, \
      "scopes": [ \
        "cloud_api:disk.app_folder", \
        "cloud_api:disk.read", \
        "cloud_api:disk.write", \
        "cloud_api:disk.info" \
      ] \
    } \
  ] \
}'

      В код подставьте значения:

      • <org_id> — идентификатор вашей организации;

      • <owner_token_to_manage_service_app> — OAuth-токен из п. 3;

      • <OAuth_service_app_client_id> — ClientID сервисного приложения из п. 6.1.

    3. Проверьте, что приложение добавилось как сервисное корректно.

      Пример
      curl --location  \
--request GET 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications'  \ 
--header 'Authorization: OAuth <owner_token_to_manage_service_app>'

    Чтобы подключить другие сервисные приложения, повторите шаги п. 6.

  7. Получите временный токен пользователя. Это можно сделать с помощью API-запроса:

    POST /token HTTP/1.1
   Host: http://oauth.yandex.ru
   Content-type: application/x-www-form-urlencoded
    Пример
    curl --location \
--request POST 'https://oauth.yandex.ru/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_id>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:uid'

    или

    curl --location
--request POST 'https://oauth.yandex.ru/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_email>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:email'

    В код подставьте значения:

    • <OAuth_service_app_client_id> — ClientID сервисного приложения из п. 6.1.

    • <OAuth_service_app_client_secret> — Client secret сервисного приложения;

    • <user_id> — идентификатор пользователя, для которого необходимо получить токен;

    • <user_email> — электронный адрес пользователя, для которого необходимо получить токен, вида username@domain.ru.

    Ответ будет содержать токен, который надо использовать в запросах к API сервисов Яндекс 360.

Подробнее программная работа с сервисными приложениями описана в Cправочнике API 360.

Примеры запросов для работы с ресурсами пользователей

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

Яндекс Диск

API Яндекс Диска предназначен для работы с файлами и управления доступом к ним. Вы можете направлять запросы к API Диска при помощи сервиса Полигон.

Пример

Запрос метаинформации о Диске сотрудника:

curl --request GET 'https://cloud-api.yandex.net/v1/disk' \ 
--header 'Accept: application/json' \
--header 'Authorization: OAuth <oauth_token>'

Вместо <oauth_token> подставьте значение временного токена пользователя из п. 7.

Подробнее о работе с REST-API Диска.

Яндекс Почта

Приложения могут получать доступ к ящикам Яндекс Почты по протоколу OAuth. OAuth-авторизацию поддерживают IMAP- и SMTP-серверы Яндекс Почты.

Пример

Скрипт Python для подсчета писем у пользователя по протоколу IMAP:

import imaplib

def generate_oauth2_string(username, access_token):
    auth_string = 'user=%s\1auth=Bearer %s\1\1' % (username, access_token)
    return auth_string

def get_imap_connector(username="<user_email>", token="<oauth_token>"):
    auth_string = generate_oauth2_string(username, token)
    imap_connector = imaplib.IMAP4_SSL("imap.yandex.com", 993)
    imap_connector.authenticate('XOAUTH2', lambda x: auth_string)
    return imap_connector

def get_total_emails(imap_connector):
    mailboxes = []
    ttl_emails = 0
    for mailbox in imap_connector.list()[1]:
        mailboxes.append(mailbox.decode("utf-8").split()[-1].replace('"', ''))
        for mailbox in mailboxes:
            try:
                imap_connector.select(mailbox)
                resp_code, mail_count = imap_connector.select(mailbox=mailbox, readonly=True)
                ttl_emails += int(mail_count[0].decode("utf-8"))
            except imaplib.IMAP4.error:
                print(f"Folder: {folder} Error reading emails")
            except ValueError:
                print(f"Folder: {folder} Error reading emails")
    user_logout(imap_connector)
    return ttl_emails

get_total_emails(get_imap_connector())

В код подставьте значения:

  • <user_email> — электронный адрес пользователя, для которого необходимо получить данные, вида username@domain.ru;
  • <oauth_token> — временный токен пользователя из п. 7.

Подробнее о работе почтовых протоколов см. в описании IMAP и в спецификации SMTP.

Яндекс Календарь

С использованием OAuth-токенов можно взаимодействовать с Яндекс Календарем пользователей по протоколу CalDAV.

Пример 1

Cкрипт Python для удаления выбранного Календаря пользователя:

import caldav

def get_principal(username, leg_token):
    client = caldav.DAVClient(url="https://caldav.yandex.ru/", username=username, password=leg_token)
    principal = client.principal()
    return principal

my_principal = get_principal("<user_email>", "<oauth_token>")

def find_delete_calendar(my_principal, calendar_name="Мой календарь"):
    try:
        calendar = my_principal.calendar(name=calendar_name)
        assert calendar
        print(f"We found an existing calendar with name {calendar_name}, now deleting it")
        calendar.delete()
    except caldav.error.NotFoundError:
        print("Calendar was not found")

find_delete_calendar(my_principal)

В код подставьте значения:

  • <user_email> — электронный адрес пользователя вида username@domain.ru, для которого необходимо получить данные;

  • <oauth_token> — временный токен пользователя из п. 7.

Примечание

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

Пример 2

Запросы создания встречи в Календаре со ссылкой на видеовстречу в Телемосте:

  • Конференция для одиночного события.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
-H "Authorization: OAuth <oauth_token>" \
-H "Content-type: text/ics" \
-X PUT \
--data-binary "
BEGIN:VCALENDAR
BEGIN:VEVENT
X-TELEMOST-REQUIRED:TRUE
DESCRIPTION:Single event
UID:<event_uid>
DTSTART:20230417T120000Z
END:VEVENT
END:VCALENDAR"

    В код подставьте значения:

    • <user_email> — электронный адрес пользователя, для которого необходимо получить данные, вида username@domain.ru;
    • <event_uid> — идентификатор встречи и имени файла (например, a5e3e7b0-dd11-11ed);
    • <oauth_token> — временный токен пользователя из п. 7.

    Пример успешного ответа:

    HTTP/1.1 201 Created

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>"

    В код подставьте значения:

    • <user_email> — электронный адрес пользователя вида username@domain.ru, для которого необходимо получить данные;

    • <event_uid> — идентификатор встречи и имени файла (например, a5e3e7b0-dd11-11ed);

    • <oauth_token> — временный токен пользователя из п. 7.

    Пример успешного ответа:

    HTTP/1.1 200 OK
BEGIN:VCALENDAR
...
BEGIN:VEVENT
DTSTART:20230417T120000Z
DTEND:20230417T120000Z
SUMMARY:Без названия
UID:a5e3e7b0-dd11-11ed
DESCRIPTION:Link to video conference: https://telemost.yandex.ru/j/78566269088286\n\nSingle event 
X-TELEMOST-CONFERENCE:https://telemost.yandex.ru/j/78566269088286
...
END:VEVENT
END:VCALENDAR

  • Конференция для повторяющегося события.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
-H "Authorization: OAuth <oauth_token>" \
-H "Content-type: text/ics" \
-X PUT \
--data-binary "
BEGIN:VCALENDAR
BEGIN:VEVENT
X-TELEMOST-REQUIRED:TRUE
DESCRIPTION:Weekly event
UID:<event_uid>
DTSTART:20230411T200000Z
RRULE:FREQ=WEEKLY
END:VEVENT
END:VCALENDAR"

    В код подставьте значения:

    • <user_email> — электронный адрес пользователя вида username@domain.ru, для которого необходимо получить данные;

    • <event_uid> — идентификатор встречи и имени файла (например, a5e3e7b0-dd11-11ed);

    • <oauth_token> — временный токен пользователя из п. 7.

    Пример успешного ответа:

    HTTP/1.1 201 Created

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>"

    В код подставьте значения:

    • <user_email> — электронный адрес пользователя вида username@domain.ru, для которого необходимо получить данные;

    • <event_uid> — идентификатор встречи и имени файла (например, a5e3e7b0-dd11-11ed);

    • <oauth_token> — временный токен пользователя из п. 7.

    Пример успешного ответа:

    BEGIN:VCALENDAR
...
BEGIN:VEVENT
RECURRENCE-ID:20230411T200000Z
X-TELEMOST-CONFERENCE:https://telemost.yandex.ru/j/39864310386563
DESCRIPTION:Ссылка на видеовстречу: https://telemost.yandex.ru/j/39864310386563\n\nWeekly event 
...
END:VEVENT
BEGIN:VEVENT
RRULE:FREQ=WEEKLY;BYDAY=TU;INTERVAL=1
DESCRIPTION:Ссылка на видеовстречу: https://telemost.yandex.ru/j/39864310386563\n\nWeekly event 
...
END:VEVENT

При отправке PUT-запроса для создания или изменения события в Календаре клиент добавляет внутрь компонентов VEVENT нестандартное свойство X-TELEMOST-REQUIRED. Сервер, получая такой запрос, генерирует ссылку на видеовстречу в Телемосте и добавляет ее в описание встречи в виде текста.

При чтении клиентом встреч сервер не указывает свойство X-TELEMOST-REQUIRED. Но, если ссылка на видеовстречу в Телемосте была сгенерирована, возвращает эту ссылку в нестандартном свойстве X-TELEMOST-CONFERENCE.

Подробнее о работе с протоколом CalDAV см. в его спецификации.

Написать в службу поддержки
Предыдущая
Защита исходящей почты от утечек
Следующая
API-сценарии