Выдача новых oauth токенов в яндекс почте что это
Выдача новых oauth токенов в яндекс почте что это
Сегодня мы подробно разберем процесс получения OAuth-токена для доступа к Яндекс.Директ API. Впервые сталкиваясь с процессом получения токена, будь-то API от Google или Яндекса, я по-началу терялся в заявках, регистрациях и прочей бюрократической вакханалии. Поэтому я, буквально, за руку проведу тебя к заветному апи-токену, который мы сразу и проверим.
Как следует из справки Яндекс.Директ API, вся процедура делится на два этапа:
Регистрируем приложение в Яндекс.Директ API
Авторизуемся из под аккаунта с кабинетом Яндекс.Директ, данные которого нас интересуют. Переходим на страницу oauth.yandex.ru, и жмем на желтую кнопку «Зарегистрировать новое приложение». И заполняем поля, согласно плану:
Отлично, приложение создано, на выходе получится что-то похожее на это:
Отлично, пол дела сделано, осталось запросить доступ к API.
Создаем заявку на доступ к Яндекс.Директ API
Теперь создадим заявку, тут всё довольно просто. Идём сюда и создаем заявку на доступ. Начинаем заполнять:
Бум! Всё готово, отправляем на рассмотрение. После прохождения, в итоге получим такую картину:
Получаем OAuth-токен Яндекс.Директ:
Существует 2 способа получения API-токена: Ручной и Автоматический
Так как мы не пишем приложение, которое будут использовать десятки авторизованных пользователей, то нам хватит и ручного получения токена. Теперь дело за малым, делаем запрос на выдачу «API-ключа», который мы будем использовать в нашем приложении. Для этого:
Ну что, всё готово для тестового запроса, поехали?
Тестовый запрос для проверки работы Яндекс.Директ API:
Давайте запросим список текущих рекламных кампаний в кабинете?
Полезные материалы для изучения:
Пользователь вводит код в приложении
Некоторые приложения (например, консольные или установленные на телевизорах Smart TV) не могут получить код подтверждения из URL. В этом случае пользователь должен самостоятельно получить код от Яндекс.OAuth и ввести его в приложении.
Получение токена в обмен на код, введенный пользователем:
Если на устройстве, где установлено приложение, недоступен браузер, пользователю придется перейти по нужному адресу на своем компьютере. Чтобы вводить адрес было удобнее, предоставьте пользователю QR-код или короткую ссылку.
Пользователь переходит на открывшуюся страницу, или по короткой ссылке и разрешает доступ приложению.
Яндекс.OAuth выводит код подтверждения. (Для этого в свойстве приложения Callback URL нужно указать адрес https://oauth.yandex.ru/verification_code ).
Яндекс.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 перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации приложения. Данные о токене передаются в URL перенаправления после символа #.
Приложение получает адрес перенаправления и извлекает токен.
Полученный токен можно сохранить в приложении и использовать для запросов к 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 перенаправления после символа #.
Серверная среда может не передавать веб-приложению эту часть 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 2.0?
Социальные сети, потоковая передача контента, воркспейсы – везде мы заходим через учетные записи, которые могут содержать личную информацию. Изолированные приложения становятся взаимосвязанными: Twitter позволяет новостным сайтам твитить напрямую, Discord ищет предполагаемых друзей на Facebook, а Jira создает учетки с помощью профилей Github.
Раньше для авторизации сайты и приложения использовали простую схему логин/пароль. Это существенно усложняло задачу взаимодействия приложений: чтобы позволить приложению получить доступ к данным другого приложения, требовалось передать учетные данные. Но это порождало множество проблем, связанных с небезопасным хранением учетных данных и получением неограниченного доступа. Для обеспечения делегированного доступа был создан открытый протокол авторизации OAuth.
Терминология OAuth
Разберем несколько общих терминов. Для упрощения под OAuth будем подразумевать OAuth 2.0.
Функционирование протокола OAuth
В том же ключе OAuth используется в социальных сетях. Например, при авторизации в Spotify через Facebook приложение Spotify получает доступ лишь к ограниченному набору данных.
Рис. 1. Используя OAuth, клиент (Spotify) может получить доступ к ресурсному серверу (Facebook) без учетных данных от имени владельца ресурса (Боба).
При выводе всплывающего окна OAuth работает в фоновом режиме (Рис. 2):
Заглянем под капот OAuth
Области и токены OAuth
Области и токены OAuth реализуют детализированное управление доступом. Похоже на киносеанс: область – название фильма, который вы имеете право смотреть, токен – билет, что может проверить лишь сотрудник конкретного кинотеатра.
Вернемся к Рис. 2. Сервер авторизации имеет API, отличающийся от ресурсного сервера. Сервер авторизации служит для проверки и авторизации клиента, в то время как сервер ресурсов хранит запрашиваемые ресурсы. Чтобы ресурсный сервер знал, следует ли выполнять запрос на получение информации, он должен знать, авторизован ли запрашивающий. Тут и появляется токен, чтобы сообщить серверу ресурсов, что запрашивающий был проверен сервером авторизации и имеет разрешение на выполнение запроса. При использовании токенов в качестве прокси-сервера необходимость предоставления учетных данных отпадает. Данные маркеры зашифрованы, но при декодировании сервером ресурсов из них можно вытащить значение области.
Условно можно выделить четыре типа областей:
Рис. 3. OAuth поток
Разрешения и потоки OAuth
Возвращаясь к аналогии с кинотеатром, есть два способа получить билет: покупка в кинотеатре и покупка онлайн. Выбранный метод влияет на последовательнось действий для получения билета. Покупка в театре выглядит так:
Разрешения (grants) диктуют клиенту порядок операций по получению access-токена. Этот уникальный порядок называется потоком.
Вся коммуникация между владельцем ресурса, клиентом и сервером авторизации происходит через строки запроса с параметрами. В этих параметрах содержится информация, необходимая серверу авторизации для понимания того, какому потоку следовать:
Пример: GitHub SSO
Изучим описанные концепции на примере. Teleport – опенсорсный инструмент удаленного доступа, позволяющий юзерам входить в систему через Github single sign-on (SSO) с использованием OAuth. Действующие лица :
Рассмотрим поток шаг за шагом.
Шаг 1. Пользователь Teleport получает доступ к приложению Teleport.
Шаг 2. Приложение предлагает пользователю Teleport войти с помощью Github SSO.
Шаг 3. Пользователь Teleport нажимает «Войти» и перенаправляется на другую страницу со своими параметрами, передаваемыми в HTTPS GET запросе:
Собрав воедино все, получим следующую строку приглашения:
Шаг 4. Как только GAS получит запрос, он проверит client_id в реестре. Зная, что Teleport ожидает код авторизации, GAS отправит пользователя обратно на URL-адрес с переданными параметрами:
Шаг 7. Теперь, когда маркер получен, делаем запрос к API от имени пользователя Teleport и получаем желаемое:
Шаг 8. Н аконец, GitHub API пропускает юзера.
Заключение
Несмотря на часто упускаемое из виду удобство, OAuth-это сложный протокол, реализация которого потребует времени. Пример, который мы рассмотрели выше – один из сотен вариантов того, как может выглядеть поток OAuth.
Если вы увлеклись веб-разработкой, но ищите помощь наставника, мы советуем обратить внимание на курс факультета Веб-разработки GeekBrains, где вы получите готовую базу навыков и необходимую поддержку. Кстати, на курсе большое внимание уделяется безопасности как клиентской, так и серверной части веб-приложения.
Курс поможет освоить профессию веб-разработчика, получить диплом и создать портфолио с рабочими проектами. В случае успешного прохождения команда университета поможет с трудоустройством. Ознакомиться с программой и отзывами можно, нажав расположенную ниже кнопку.