Работа с Yandex API 360 для управления двухфакторной аутентификацией (2FA) Яндекс почты на домене (Яндекс 360 для бизнеса и организаций)
В данной статье мы разберем, как включать и выключать двухфакторную аутентификацию для доменов с использованием Yandex API 360.
Первым шагом будет создание приложения в Яндекс.OAuth. Авторизоваться в системе необходимо под тем аккаунтом, который управляет Организациями в сервисе Яндекс 360 по адресу https://admin.yandex.ru/.
Нужно сделать, в первую очередь правильное приложение. Почему правильное? Потому, что перейдя по ссылке OAuth - Яндекс невозможно создать приложение с правами, отличными от “Доступ к дате рождения”, “Доступ к адресу электронной почты”, “Доступ к логину, имени и фамилии, полу”, “Доступ к портрету пользователя” или “Доступ к номеру телефона” ничего больше нельзя ни добавить ни отнять. Только эти 5 пунктов, которые явно не могут помочь нам получить ответ на запрос вида:
GET /security/v1/org/{orgId}/domain_2fa
Который указан в документации по ссылке: Безопасность: двухфакторная аутентификация
Весь фокус кроется в том, что находясь у себя на странице при нажатии на кнопку “Создать приложение” она ведёт не на адрес https://oauth.yandex.ru/client/new/ который указан в документации здесь https://yandex.ru/dev/api360/doc/concepts/access.html
а на совершенно другой URL, который подразумевает под собой уже создание другого типа приложения, в которое нельзя добавлять другие, от перечисленных выше параметров API.
Кнопка “Создать приложение” на сайте https://oauth.yandex.ru/ ведёт по адресу https://oauth.yandex.ru/client/new/id Её нам надо избегать, по возможности, иначе мы не сможем создать необходимое нам приложение для управления Яндекс почтой на домене через API.
Добавляем в раздел “Доступ к данным” те параметры, которыми планируем управлять. Весь список параметров доступен по адресу.
Важно отметить, что если вы не добавите сразу все необходимые вам параметры, а сделаете это позже, то старый токен уже не будет работать с новыми доступами. Надо делать новый токен.
Следующим шагом будет получение кода подтверждения. Это можно сделать, отправив GET-запрос по следующему URL:
https://oauth.yandex.ru/authorize?response_type=code&client_id={client_id}&device_id={device_id}&device_name={device_name}&scope=ya360_security:domain_2fa_writeЯ использую метод Получения кода подтверждения из URL Здесь:
- {client_id} это идентификатор вашего приложения
- {device_id} и {device_name} это идентификатор и название вашего устройства
- scope=ya360_security:domain_2fa_write это права доступа, которые вы хотите получить.
Если делать через программу типа RapidAPI, то в поле Response получаем как раз во вкладке RAW внизу URL, перейдя по которому и авторизовавшись под своим акаунтом администратора, можно будет увидеть код подтверждения. Код действует только 10 минут. Это важно учитывать. Это как получение временного пароля для двухфакторной аутентификации.
Теперь, когда у нас есть код подтверждения, мы можем обменять его на OAuth-токен. Для этого мы отправим POST-запрос к https://oauth.yandex.ru/token с использованием следующей команды curl:
curl -d 'grant_type=authorization_code&code={confirmation_code}&client_id={client_id}&client_secret={client_secret}' -H 'Content-Type: application/x-www-form-urlencoded' -X POST https://oauth.yandex.ru/tokenВ результате запроса мы получим JSON, содержащий наш access_token, который будет использоваться для авторизации в API Яндекса.
{
"access_token": "AgAAAAA...",
"expires_in": 31536000,
"token_type": "bearer",
"refresh_token": "1:MmY..."
}
Где:
- grant_type: Должно быть authorization_code.
- code: Ваш код подтверждения, полученный на шаге 2.
- client_id: Идентификатор вашего приложения.
- client_secret: Секрет вашего приложения.
- scope: Значение: ya360_security:domain_2fa_write
Если необходимо добавить больше разрешений, то можно их указать последовательно внутри параметра scope. Стоит обратить внимание на то, что несмотря на то, что в ответе мы получаем "token_type": "bearer", при формировании запросов мы используем метод аутентификации OAuth. Полученный в процессе аутентификации токен следует указывать в каждом вызове API в HTTP-заголовке Authorization, причем перед самим значением токена следует указать его тип.
--header 'Authorization: OAuth <OAuth-токен>'
Теперь, когда у нас есть OAuth-токен, мы можем использовать его для управления двухфакторной аутентификацией наших доменов. Вот примеры запросов, которые мы можем сделать:
-
Получить статус 2FA
curl -H 'Authorization: OAuth {your_oauth_token}' -X GET https://api360.yandex.ru/security/v1/org/{orgId}/domain_2fa
-
Включить 2FA
curl -H 'Authorization: OAuth {your_oauth_token}' -H 'Content-Type: text/plain; charset=utf-8' -X POST -d '{ "duration": 3600, "logoutUsers": false, "validationMethod": "sms" }' https://api360.yandex.ru/security/v1/org/{orgId}/domain_2fa
-
Выключить 2FA
curl -H 'Authorization: OAuth {your_oauth_token}' -X DELETE https://api360.yandex.ru/security/v1/org/{orgId}/domain_2fa
Каждый из этих запросов влияет на состояние двухфакторной аутентификации для указанного домена. Получить статус 2FA позволяет узнать, включена ли двухфакторная аутентификация. Включить 2FA позволяет включить двухфакторную аутентификацию с указанными параметрами. Выключить 2FA позволяет отключить двухфакторную аутентификацию. Более подробно про методы можно прочитать на официальной странице документации.
-
Что такое OAuth-токен и зачем он мне нужен?
OAuth-токен — это уникальный идентификатор, который дает приложению ограниченный доступ к данным пользователя. В контексте этой статьи он необходим для взаимодействия с API Яндекса. Подробнее об OAuth-авторизации читайте в документации OAuth-сервиса Яндекса. -
Что произойдет, если мой OAuth-токен истечет?
Если ваш OAuth-токен истек, вам потребуется получить новый. Это можно сделать, повторив шаги, описанные в этой статье. -
Могу ли я использовать один и тот же токен для управления 2FA в разных доменах?
Да, токен не привязан к конкретному домену и может быть использован для управления 2FA в любых доменах, доступ к которым открыт для вашего приложения. -
Могу ли я использовать этот метод для управления другими настройками безопасности?
Этот метод специфически направлен на управление двухфакторной аутентификацией. Другие настройки безопасности могут требовать других методов и разрешений. -
Какие методы валидации поддерживаются при включении 2FA?
При включении двухфакторной аутентификации Яндекс поддерживает два метода валидации: через SMS и через звонок на телефон. В этой статье мы использовали метод валидации через SMS. Если вы хотите использовать звонок на телефон вместо SMS, замените "sms" на "phone" в параметре "validationMethod" в запросе для включения 2FA.
API 360 от Яндекс предоставляет мне и другим разработчикам большой спектр возможностей для управления различными аспектами наших доменных учетных записей, включая настройку двухфакторной аутентификации. В этом руководстве я подробно рассмотрел процесс включения 2FA для Яндекс почты на домене через API, начиная с создания приложения и получения OAuth-токена до отправки запросов для получения статуса, включения и выключения 2FA.
Однако я понимаю, что этот процесс может вызвать вопросы или проблемы. Я надеюсь, что моя статья и раздел FAQ помогут вам разобраться в некоторых из них. Если у вас возникнут дополнительные вопросы или замечания, не стесняйтесь оставлять их в разделе "Issues" этого репозитория на GitHub.
Я понимаю, что этот API может измениться со временем, и я постараюсь обновить это руководство по мере возникновения значительных изменений. Если вы обнаружите любые неточности или устаревшую информацию, пожалуйста, сделайте pull request или сообщите мне об этом.
Я надеюсь, что это руководство будет полезным для тех, кто ищет информацию о работе с API 360 от Яндекс, и способствует более широкому использованию этого полезного инструмента. Спасибо за чтение, и желаю вам удачи в ваших проектах!