выдача новых oauth токенов в яндекс почте что это
Выдача новых oauth токенов в яндекс почте что это
Сегодня мы подробно разберем процесс получения OAuth-токена для доступа к Яндекс.Директ API. Впервые сталкиваясь с процессом получения токена, будь-то API от Google или Яндекса, я по-началу терялся в заявках, регистрациях и прочей бюрократической вакханалии. Поэтому я, буквально, за руку проведу тебя к заветному апи-токену, который мы сразу и проверим.
Как следует из справки Яндекс.Директ API, вся процедура делится на два этапа:
Регистрируем приложение в Яндекс.Директ API
Авторизуемся из под аккаунта с кабинетом Яндекс.Директ, данные которого нас интересуют. Переходим на страницу oauth.yandex.ru, и жмем на желтую кнопку «Зарегистрировать новое приложение». И заполняем поля, согласно плану:
Отлично, приложение создано, на выходе получится что-то похожее на это:
Отлично, пол дела сделано, осталось запросить доступ к API.
Создаем заявку на доступ к Яндекс.Директ API
Теперь создадим заявку, тут всё довольно просто. Идём сюда и создаем заявку на доступ. Начинаем заполнять:
Бум! Всё готово, отправляем на рассмотрение. После прохождения, в итоге получим такую картину:
Получаем OAuth-токен Яндекс.Директ:
Существует 2 способа получения API-токена: Ручной и Автоматический
Так как мы не пишем приложение, которое будут использовать десятки авторизованных пользователей, то нам хватит и ручного получения токена. Теперь дело за малым, делаем запрос на выдачу «API-ключа», который мы будем использовать в нашем приложении. Для этого:
Ну что, всё готово для тестового запроса, поехали?
Тестовый запрос для проверки работы Яндекс.Директ API:
Давайте запросим список текущих рекламных кампаний в кабинете?
Полезные материалы для изучения:
Веб-приложение
Получение токена для веб-приложения:
Пользователь разрешает доступ приложению.
Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации. Данные о токене передаются в URL перенаправления после символа #.
Серверная среда может не передавать веб-приложению эту часть URL. В таком случае можно выделять данные из адреса с помощью JavaScript, или получать токены с помощью кода подтверждения.
Приложение получает адрес перенаправления и извлекает токен.
Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в куках браузера, открытых конфигурационных файлах и т. п.
URL для запроса токена
Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:
Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства.
Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126).
Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства.
Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.
Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д.
URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения ( Платформы → Веб-сервисы → Callback URI ).
В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется.
Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена.
Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:
Если пользователь уже авторизован с нужным аккаунтом, Яндекс.OAuth просто запрашивает разрешение на доступ.
Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим.
Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново.
Список необходимых приложению в данный момент прав доступа, разделенных пробелом. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/ /info, указав вместо идентификатор приложения.
Если параметры scope и optional_scope не переданы, то токен будет выдан с правами, указанными при регистрации приложения.
Параметр позволяет получить токен только с теми правами, которые нужны приложению в данный момент.
Если параметры scope и optional_scope не переданы, то токен будет выдан с правами, указанными при регистрации приложения.
Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен.
Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.
Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту.
Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.
Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
Признак облегченной верстки (без стандартной навигации Яндекса) для страницы разрешения доступа.
Облегченную верстку стоит запрашивать, например, если страницу разрешения нужно отобразить в маленьком всплывающем окне.
Приложение запрашивает код
Пользователь разрешает доступ приложению.
Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации приложения. Код подтверждения (или описание ошибки) передается в параметре URL перенаправления.
Приложение получает адрес перенаправления и извлекает код подтверждения.
Яндекс.OAuth возвращает токен в теле ответа.
Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в куках браузера, открытых конфигурационных файлах и т. п.
Запрос кода подтверждения
Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:
Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства.
Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126).
Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства.
Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.
Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д.
URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения ( Платформы → Веб-сервисы → Callback URI ).
В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется.
Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена.
Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:
Если пользователь уже авторизован с нужным аккаунтом, Яндекс.OAuth просто запрашивает разрешение на доступ.
Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим.
Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново.
Список необходимых приложению в данный момент прав доступа, разделенных пробелом. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/ /info, указав вместо идентификатор приложения.
Если параметры scope и optional_scope не переданы, то токен будет выдан с правами, указанными при регистрации приложения.
Параметр позволяет получить токен только с теми правами, которые нужны приложению в данный момент.
Если параметры scope и optional_scope не переданы, то токен будет выдан с правами, указанными при регистрации приложения.
Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен.
Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.
Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту.
Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.
Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
Тонкости авторизации: обзор технологии OAuth 2.0
Информационная система Dodo IS состоит из 44 различных сервисов, таких как Трекер, Кассы ресторана или Базы знаний и многих других. Чтобы не отвлекаться на несколько аккаунтов, 3 года назад мы написали сервис Auth для реализации сквозной аутентификации, а сейчас пишем уже вторую версию, в основе которого лежит стандарт авторизации OAuth 2.0. Этот стандарт довольно сложный, но если у вас сложная архитектура с множеством сервисов, то OAuth 2.0 вам пригодится при разработке своего сервиса аутентификации. В этой статье я постарался рассказать о стандарте максимально просто и понятно, чтобы вы сэкономили время на его изучение.
Задача Auth
Проблема авторизации в десятках сервисов встречалась ещё несколько лет назад — в начале «эпохи распила монолита». Эту проблему решили новым сервисом, который назвали – Auth. Он помог реализовать бесшовную аутентификацию в различных сервисах и перенести данные о пользователях в отдельные базы данных.
У сервиса Auth есть три основные задачи:
Проблемы
Первая версия Auth — часть монолита. Он использует свой собственный протокол общения с сервисами. Такая «схема» была необходима в тот момент, но за несколько лет работы проявились проблемы.
Auth — часть монолита. Следовательно, сервис привязан к релизному циклу, что лишает возможности независимой разработки и деплоя. Кроме того, придется разворачивать весь монолит, если захотелось развернуть Auth, например, при масштабировании сервиса.
Dodo IS зависит от Auth. В старой реализации внешние сервисы обращаются к Auth при каждом действии пользователя, чтобы валидировать данные о нём. Настолько сильная привязка может привести к остановке работы всей Dodo IS, если Auth «приляжет» по какой-то причине.
Auth зависит от Redis. Притом достаточно сильно — неисправность работы Redis’а приведёт к падению Auth’а. Мы используем Azure Redis, для которого заявленный SLA 99,9%. Это значит, что сервис может быть недоступен до 44 минут в месяц. Такие простои не позволительны.
Текущая реализация Auth использует свой протокол аутентификации, не опираясь на стандарты. В большинстве своих сервисов мы используем C# (если говорим о backend) и у нас нет проблем с поддержкой библиотеки для нашего протокола. Но если вдруг появятся сервисы на Python, Go или Rust, разработка и поддержка библиотек под эти языки потребует дополнительных затрат времени и принесет дополнительные сложности.
Текущий Auth использует схему Roles Based Access Control, которая базируется на ролях. Обычно с ролью выдаётся полный доступ к определённому сервису, вместо привязки к конкретному функционалу. Например, в пиццериях есть заместители управляющего, которые могут вести определенные проекты: составлять графики или учитывать сырьё. Но у нас нет выдачи прав на конкретные компоненты системы. Приходится выдавать полный доступ к сервису, чтобы сотрудники могли получить доступ к составлению графиков или настройкам какого-либо компонента учёта.
Проблемы подтолкнули к тому, чтобы спроектировать и написать новую версию Auth. На старте проекта мы потратили 3 недели только на изучение стандартов авторизации и аутентификации OAuth 2.0 и OpenID Connect 1.0.
Примечание. Утрированно, статья — это пересказ RFC, который приходилось перечитывать несколько раз, чтобы понять, что происходит вокруг. Здесь я постарался уйти от этой сложности и рассказать всё максимально просто, структурировано, кратко и без описания сложных вещей, например, какие символы может содержать в себе ответ сервиса. В отличии от RFC, прочитав это один раз, можно во всём разобраться. Надеюсь, статья будет полезна и сэкономит время при выборе решения для реализации сервиса аутентификации, а может, кого-то заставит задуматься о его необходимости.
Что такое ОAuth2.0?
Разработку нового Auth мы решили начать с изучения доступных протоколов и технологий. Самый распространённый стандарт авторизации — фреймворк авторизации OAuth2.0.
Стандарт был принят в 2012 году, и за 8 лет протокол меняли и дополняли. RFC стало настолько много, что авторы оригинального протокола решили написать OAuth 2.1, который объединит все текущие изменения по OAuth 2.0 в одном документе. Пока он на стадии черновика.
Актуальная версия OAuth описанна в RFC 6749. Именно его мы и разберем.
OAuth 2.0 — это фреймворк авторизации.
Он описывает, как должно реализовываться взаимодействие между сервисами для обеспечения безопасной авторизации. Многие нюансы описаны достаточно подробно, например, flow взаимодействия узлов между собой, но некоторые отдаются на откуп конкретной реализации.
В OAuth 2.0 определены четыре роли:
Важно: клиент должен быть заранее зарегистрирован в сервисе. Как это сделать?
Регистрация клиента
Способ регистрации клиента, например, ручной или service discovery, вы выбираете сами, в зависимости от фантазии конкретной реализации. Но при любом способе при регистрации, кроме ID клиента, должны быть обязательно указаны 2 параметра: redirection URI и client type.
Redirection URI — адрес, на который отправится владелец ресурса после успешной авторизации. Кроме авторизации, адрес используется для подтверждения, что сервис, который обратился за авторизацией, тот, за кого себя выдаёт.
Client type — тип клиента, от которого зависит способ взаимодействия с ним. Тип клиента определяется его возможностью безопасно хранить свои учётные данные для авторизации — токен. Поэтому существует всего 2 типа клиентов:
Токены
Токен в OAuth 2.0 — это строка, непрозрачная для клиента. Обычно строка выглядит как случайно сгенерированная — её формат не имеет значения для клиента. Токен — это ключ доступа к чему-либо, например, к защищённому ресурсу (access token) или к новому токену (refresh Token).
У каждого токена своё время жизни. Но у refresh token оно должно быть больше, т.к. он используется для получения access token. Например, если срок жизни access token около часа, то refresh token можно оставить жить на целую неделю.
Refresh token опционален и доступен только для confedential клиентов. Пользуясь опциональностью токена, в некоторых реализациях время жизни access token сделано очень большим, а refresh token вообще не используется, чтобы не заморачиваться с обновлением. Но это не безопасно. Если access token был скомпрометирован, его можно обнулить, а сервис получит новый Access token с помощью refresh token. В случае, если refresh token нет, то потребуется проходить процесс авторизации заново.
За access token закреплён определённый набор прав доступа, который выдаётся клиенту во время авторизации. Давайте разберёмся, как выглядят права доступа в OAuth 2.0.
Права доступа
Права доступа выдаются клиенту в виде scope. Scope – это параметр, который состоит из разделённых пробелами строк — scope-token.
На этапе регистрации клиента, в настройках сервиса авторизации клиенту выдаётся стандартный scope по умолчанию. Но клиент может запросить у сервера авторизации scope, отличный от стандартного. В зависимости от политик на сервере авторизации и выбора владельца ресурса, итоговый набор scope может выглядеть совсем иначе. В дальнейшем, после авторизации клиента, владелец ресурсов может отобрать часть прав без повторной авторизации сервиса, но, чтобы выдать дополнительные разрешения, потребуется повторная авторизация клиента.
Абстрактный OAuth 2.0. Flow c применением Access token
Мы рассмотрели роли, рассмотрели виды токенов, а также как выглядят scope. Посмотрим на flow предоставления доступа к сервису.
Ниже представлена абстрактная схема (или flow) взаимодействия между участниками. Все шаги на данной схеме выполняются строго сверху вниз. Разберём детальнее.
Абстрактный OAuth 2.0. Flow c применением Refresh token
Первый и второй шаги опущены из данной схемы — они ничем не отличаются от схемы абстрактного flow выше.
Что такое grant?
Grant — это данные, которые представляют из себя успешную авторизацию клиента владельцем ресурса, используемые клиентом для получения access token.
Например, когда мы где-либо аутентифицируемся с помощью Google, перед глазами всплывает уведомление. В нём говорится, что такой-то сервис хочет получить доступ к данным о вас или к вашим ресурсам (выводятся запрашиваемые scope-token). Это уведомление называется «Consent Screen».
В момент, когда нажимаем «ОК», в базу данных попадает тот самый grant: записываются данные о том, что такой-то пользователь дал такие-то доступы такому-то сервису. Клиент получает какой-то идентификатор успешной аутентификации, например строку, которая ассоциируется с данными в базе данных.
Существует 4 + 1 способа получения grant — grant type:
Client credentials grant flow
Имеет самый простой flow, напоминающий обычную авторизацию на любом сервисе. Она выполняется с помощью учётных данных клиента, которые представляют собой client id и client secret — аналог логина и пароля для пользователя. Так как для аутентификации требуется client secret, который должен соответствующе храниться, данный flow могут использовать только confedential клиенты.
Схема проста: клиент аутентифицируется на сервере авторизации передавая client id и client secret. В ответ получает access token, с которым уже может получить доступ к нужному сервису.
Этот flow требуется, когда клиент пытается получить доступ к своим ресурсам или ресурсам, заранее согласованным с сервером авторизации. Например, сервису А нужно время от времени ходить в сервис Б и актуализировать там данные о количестве пиццерий в сети.
Resource owner password credentials flow
По текущим рекомендациям безопасности описанных в данном RFC, данный flow не рекомендуется использовать вовсе из-за явных проблем с безопасностью.
Resource owner передаёт свой логин и пароль клиенту, например, через формы на клиенте. Клиент, в свою очередь, с помощью него получает access token (и, опционально, refresh token).
Здесь есть проблема. Resource owner просто берёт и отдаёт в открытом виде свой логин и пароль клиенту, что не безопасно. Изначально он был сделан только для клиентов, которым вы доверяете или тех, что являются частью операционной системы. Позже он был разрешён только для миграции с аутентификации по логину и паролю на OAuth 2.0. Текущие рекомендации по безопасности запрещают его использование.
Authorization code
Самый распространённый flow на данный момент. В основном используется для confidential клиентов, но с появлением дополнительной проверки с помощью PKCE, может применяться и для public-клиентов.
В данном flow взаимодействие client с resource owner проходит через user-agent (браузер). К user-agent есть одно требование: он должен уметь работать с HTTP-редиректами. Без этого resource owner не сможет попасть к серверу авторизации и вернуться обратно с grant.
Данный flow сложнее, чем предыдущие, поэтому будем разбирать по шагам. Для начала представим, что мы — resource owner и перешли на страницу сервиса онлайн-обучения, который хочет сохранять результаты обучения к нам в облако. Ему требуется получить доступ к нашему ресурсу, например, определённой директории в облаке. Мы нажимаем на «Авторизоваться» и начинается путешествие по Authorization code grant flow:
Следующий flow построен на основе этого.
Implicit grant
Это оптимизация Authorization code grant flow для public-клиентов, которые умеют работать с redirection URI. Например, для браузерных приложений на JavaScript, или мобильных приложений. Требование к user-agent, с помощью которого взаимодействуют клиент и resource owner, сохраняется: он должен уметь работать с HTTP-редиректами.
Между authorization code и implicit есть основное отличие: вместо получения authorization code и access token по нему, мы сразу получаем access token после успешной авторизации resource owner. Кроме того, здесь не используется client secret из соображений безопасности — приложение можно дизассемблировать и получить его. Подлинность проверяется только по redirection URI.
Многие шаги из данной схемы похожи на шаги из authorization code, но предлагаю их разобрать также подробно. Представим, что некое браузерное приложение хочет сохранять свои настройки в нашем Git-репозитории. Мы нажимаете «Войти в GitHub» и на этом этапе начинается работа Implicit flow:
Device authorization (RFC 8628)
С 2012 до 2019 появилось много умных устройств, на которых неудобно авторизоваться. Например, неудобно вводить сложный логин и пароль на телевизоре каждый раз при открытии ресурса. На некоторых устройствах это невозможно, например на серверных ОС без графического интерфейса. В августе 2019 этот flow появился как раз для таких сценариев.
Есть, как минимум, 3 требования к устройствам, чтобы работа с помощью Device authoraztion grant flow была возможна:
Возможно, схема кажется сложной из-за обилия стрелок. Разберём её также пошагово, как и разбирали сложные flow до него.
Представим, что мы пытаемся авторизоваться на web-сервисе с помощью телевизора. Мы видим кнопку «Авторизоваться как устройство» и нажимаем. В этот момент начинается наш Device flow:
Вместо вывода
В этой статье я опустил много подробностей, чтобы максимально просто и доступно рассказать о самом важном. Например, типы запросов, как и в каком виде передавать параметры, какие символы допустимы в качестве значений для того.
Если хотите погрузиться в тематику детальнее, то рекомендую в RFC 6749 (для OAuth 2.0) и RFC 8628 (для Device Flow). Кроме того, следить за актуальными версиями RFC можно на ресурсе, посвящённому OAuth.
Если статья была полезна и захотите подробностей — пишите в комментариях, и в следующих статьях расскажу о PKCE, о протоколе аутентификации OpenID Connect 1.0, о нашей реализации сервера аутентификации и многом другом.