Приложения и Аутентификация

Введение

Это руководство поможет разработчикам использовать Twitch Authentication, что позволяет вашему приложению выполнять действия от имени учетной записи Twitch или получать доступ к определенным данным об учетной записи пользователя. Существует несколько способов получить доступ к учетной записи Twitch от имени пользователя. Мы используем части протокола OAuth 2.0.

В дополнение к OAuth Twitch поддерживает OIDC (OpenID Connect) для более безопасного потока OAuth 2.0. Тонеры OIDC совместимы с услугами, созданными для соответствия требованиям OIDC, такими как Cognito от Amazon Web Services.

Аутентификация включает:

• 1. Зарегистрируйте свое приложение, чтобы получить идентификатор клиента и секрет клиента.
• 2. Получение токена. Это включает указание областей или разрешений, требуемых вашим приложением.
• 3. Отправка маркера в ваш запрос API для аутентификации запросов API.

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

Для удобства чтения часть кода с параметризованным примером показана на нескольких строках; реальные примеры находятся на одной линии.

Образцы кода доступны на странице Get Started на веб-сайте Twitch.

Предупреждение: обрабатывайте свой токен как пароль. Например, никогда не используйте токены доступа в любом общедоступном URL-адресе и никогда не показывайте маркеры на любой веб-странице, не требуя щелчка, чтобы удалить обфускацию. Держите жетоны в секрете!

Проверка запросов

Для разработчиков, которые используют аутентификацию Twitch для целей входа в систему, токены доступа должны быть проверены на повторяющийся интервал. Если ваша служба использует Twitch в качестве формы аутентификации (чтобы убедиться, что пользователи - те, кого они говорят в своем приложении), периодическая проверка ранее выпущенных токенов OAuth гарантирует, что пользователи, которые разрешили ваше приложение, не решили отключить интеграцию.

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

Twitch периодически проводит аудит. Если мы обнаружим приложение, которое не повторяет проверку токенов доступа (то есть приложение, которое проверяет только для входа в систему, а не после этого), мы будем обращаться к разработчикам и работать с ними для решения проблемы. Если проблема не устранена, мы можем предпринять карательные действия, такие как аннулирование ключа API разработчика или дросселирование производительности приложения.

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

При проверке каждого из ваших запросов отправьте запрос конечной точке проверки (https://id.twitch.tv/oauth2/validate) с вашим токеном OAuth в заголовке. Если вы аутентифицированы, ответ включает статус вашего токена. Успешный ответ указывает, что ваш токен доступа действителен.

Вот пример запроса:

					curl -H "Authorization: OAuth <Токен доступа>" https://id.twitch.tv/oauth2/validate
			

И вот пример ответа:

				{
					"client_id": "<Ваш клиент ID>",
					"login": "<Авторизованный пользователь login>",
					"scopes": [
						"<Запрошенные области>"
				 	],
					"user_id": "<ID Авторизованного пользователя>"
				}
			

Регистрация

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

После создания приложения-разработчика вам присваивается идентификатор клиента. Некоторые потоки аутентификации также требуют секретности клиента, которую вы можете создать на той же странице, что и идентификатор клиента.

• Склиент ID являются общедоступными и могут быть колективными (например, встроены в источник веб-страницы).
• Секреты клиента эквивалентны паролю для вашего приложения и должны быть конфиденциальными. Никогда не выставляйте его пользователям, даже в неясной форме.

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

Предупреждение: Идентификаторы клиентов должны быть уникальными для каждого приложения: не используйте повторно идентификаторы клиентов в нескольких приложениях. Кроме того, приложения должны запросить соответствующий набор областей для целевых API-интерфейсов. Несоблюдение этих рекомендаций может привести к приостановке доступа вашего приложения к API Twitch.

Типы токенов

Twitch поддерживает несколько типов токенов:

Получение токенов

Домен, посвященный аутентификации Twitch, - https://id.twitch.tv. (Предыдущие посетители этой страницы будут замечать, что URL-адреса были обновлены, чтобы заменить https://api.twitch.tv/kraken на https://id.twitch.tv. Код, который использует старый домен kraken для проверки подлинности Twitch, будет продолжен работать до конца 2018 года, когда мы удаляем функциональность Twitch API v5. Twitch API v5 в настоящее время устарел.)

Мы поддерживаем несколько потоков аутентификации:

Процедура, которую вы должны использовать для получения токенов, зависит от типов) тонов, которые вы хотите:

В целях безопасности в примерах в этих разделах используется токен поддельного доступа, 0123456789abcdefghijABCDEFGHIJ.

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

Когда запрос API требует аутентификации, отправьте токен доступа в виде заголовка. Заголовок отличается, в зависимости от того, какой API вы используете:

В новом Twitch API:

				curl -H "Authorization: Bearer <access token>" https://api.twitch.tv/helix/
			

В Twitch v5:

				curl -H "Authorization: OAuth <access token>" https://api.twitch.tv/kraken/
			

Отмена токенов доступа

Чтобы очистить ранее полученные токены доступа, используйте конечную точку торможения токена Twitch OAuth. Его реализация соответствует стандарту OAuth.

На своем сервере отмените токен доступа, выполнив этот запрос:

				POST
				https://id.twitch.tv/oauth2/revoke
    			?client_id=<your client ID>
    			&token=<your OAuth token>
			

Например, используя вашего ранее аутентифицированного пользователя, запрос:

POST https://id.twitch.tv/oauth2/revoke?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&token=0123456789abcdefghijABCDEFGHIJ

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

POST https://id.twitch.tv/oauth2/revoke?client_id=uo6dggojyb8d6soh92zknwmi5ej1q2&token=prau3ol6mg5glgek8m89ec2s9q5i3i

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

Запрошенные неверные запросы возвращают 400 Bad Request, а также информацию о том, как исправить запрос, как правило, напоминание запрашивающего, чтобы включить client_id.

Обновление токенов доступа

Новые токены доступа OAuth2 истекают. Периоды истечения срока действия токена различаются по длине, основываясь на том, как был получен токен. Токены возвращают поле expires_in, указывающее, как долго должен продолжаться токен. Однако вы должны создавать свои приложения таким образом, чтобы они были устойчивыми к ошибкам аутентификации токена. Другими словами, приложение, способное обновлять токены, не должно знать, как долго будет действовать токен. Скорее, он должен быть готов к тому, чтобы токен стал недействительным в любое время.

Чтобы позволить приложениям оставаться аутентифицированными в течение длительного времени в мире истекающих токенов, мы разрешаем обновлять сеансы в соответствии с рекомендациями в разделе «Обновление токена доступа» в RFC OAuth2. Как правило, обновлять токены используются для продления срока службы заданной авторизации.

Выходы токена не влияют на существующие токены. В будущем мы будем отзывать постоянно живущие сессии.

(Обратите внимание, что токены доступа и токены доступа не могут быть обновлены.)

How to Refresh

Чтобы обновить токен, вам нужна пара токенов доступа / обновления, исходящая из тела. Например:

				{
				  "access_token": "0123456789abcdefghijABCDEFGHIJ",
				  "refresh_token": "eyJfaWQmNzMtNGCJ9%6VFV5LNrZFUj8oU231/3Aj",
				  "expires_in": 3600,
				  "scope": "viewing_activity_read",
				  "token_type": "bearer"
				}
			

Вам также нужны client_id и client_secret, используемые для создания указанной пары токенов доступа / обновления доступа

Чтобы обновить, используйте этот запрос:

				curl -X POST https://id.twitch.tv/oauth2/token
			    --data-urlencode
			    ?grant_type=refresh_token
			    &refresh_token=<your refresh token>
			    &client_id=<your client ID>
			    &client_secret=<your client secret>
			

Существует несколько требуемых параметров и один необязательный параметр: