Автентифікація через OAuth 2.0 для API eSputnik

Використовуйте OAuth 2.0, коли вашому серверному застосунку потрібно отримати доступ до API eSputnik від імені користувача eSputnik — без збереження його облікових даних або статичного API-ключа.

OAuth 2.0 дозволяє користувачу надати вашому застосунку доступ до певних ресурсів API eSputnik. Застосунок отримує токени та використовує їх для звернень до API відповідно до обраних областей доступу.

Швидкий старт

1. Зареєструйте OAuth-застосунок.
2. Отримайте Client ID та Client Secret.
3. Сформуйте URL авторизації та перенаправте користувача.
4. Обміняйте код авторизації на токени.
5. Звертайтеся до API з токеном доступу.
6. Оновлюйте токени за потреби.
7. Перевіряйте статус токена за потреби.

Як працює OAuth 2.0

OAuth 2.0 дозволяє стороннім застосункам отримувати доступ до API eSputnik від імені користувача — без передачі логіна чи пароля.

Приклад процесу:

1. Користувач підключає ваш застосунок до свого акаунту eSputnik.
2. eSputnik відображає форму авторизації.
3. Користувач входить і надає доступ.
4. eSputnik перенаправляє користувача назад до вашого застосунку з кодом авторизації.
5. Ваш застосунок обмінює цей код на токен доступу та токен оновлення.
6. Ваш застосунок використовує токен доступу для звернень до API eSputnik.

Зверніть увагу: реалізація підтримана лише для застосунків із серверною частиною, тобто response_type=code.

Області доступу

Доступ до ресурсів API eSputnik визначається областями доступу, обраними під час реєстрації застосунку.

Обирайте лише ті області, які дійсно потрібні вашому застосунку. Область доступу обмежує те, що може робити токен доступу.

Зверніть увагу: якщо змінити область доступу після реєстрації, вже видані токени продовжать працювати зі старим набором прав. Щоб отримати токен з оновленими правами, користувач повинен пройти авторизацію повторно.

Реєстрація OAuth-застосунку

Перед початком інтеграції з OAuth 2.0 зареєструйте свій застосунок в eSputnik.

1. Натисніть меню акаунту у верхньому правому куті та відкрийте Для партнерів.

2. На сторінці Партнерські застосунки натисніть Зареєструвати застосунок.

3. Заповніть інформацію про застосунок:

   • Назва
   • Callback URL — адреса, на яку eSputnik перенаправить користувача після підтвердження або відхилення авторизації (можна залишити порожнім і додати пізніше)
   • Області доступу — оберіть із таблиці вище

4. Натисніть Зареєструватися.

Після реєстрації eSputnik генерує Client ID та Client Secret для вашого застосунку. Збережіть їх у надійному місці — вони знадобляться для отримання токенів.

Налаштування форми авторизації

Ви можете налаштувати, як ваш застосунок відображається у формі авторизації eSputnik. Це допомагає користувачам впізнати ваш застосунок перед наданням доступу.

1. Натисніть меню акаунту у верхньому правому куті та відкрийте Для партнерів.
2. Знайдіть свій OAuth-застосунок на сторінці Партнерські застосунки.
3. Натисніть Редагувати.

4. Перейдіть на вкладку Форма авторизації.
5. Оновіть дані форми:
   • Назва застосунку — змініть за потреби
   • Логотип — завантажте логотип застосунку
6. Натисніть Зберегти.

Вимоги до логотипу:

• Підтримувані формати: JPG, GIF, PNG
• Максимальний розмір файлу: 1 МБ
• Рекомендоване співвідношення сторін: 1:1
• Рекомендований розмір: 96 × 96 пікселів
• Зображення більшого розміру будуть обрізані до 100% ширини та вирівняні по центру

Керування OAuth-застосунком

Після реєстрації застосунок з'являється на сторінці Партнерські застосунки.

Звідси ви можете:

• скопіювати Client ID та Client Secret
• редагувати налаштування застосунку
• налаштувати форму авторизації
• переглянути форму авторизації
• видалити застосунок

Увага: після видалення OAuth-застосунку всі пов'язані ключі, токени та інтеграції стають недійсними. Будь-яка інтеграція, що використовує цей застосунок, припинить працювати — її потрібно буде налаштувати заново з новим OAuth-застосунком.

Процес авторизації

Крок 1 — Формування URL авторизації

Перенаправте користувача на:

https://uaa.esputnik.com/uaa/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL

Параметри:

Крок 2 — Авторизація користувача

Користувач входить в eSputnik та надає доступ вашому застосунку.

Після успішної авторизації eSputnik перенаправляє на Callback URL із кодом авторизації:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?code=YOUR_CODE

Збережіть значення code — воно знадобиться на наступному кроці.

Крок 3 — Отримання токенів

Надішліть POST-запит на https://uaa.esputnik.com/uaa/oauth/token.

Передайте такі параметри в тілі запиту:

Параметри передавайте у тілі запиту з заголовком Content-Type: application/x-www-form-urlencoded. Передача параметрів через рядок запиту (query string) також підтримується для зворотної сумісності, але не рекомендується.

Автентифікація запиту — Basic Auth: username це ваш Client ID, password це ваш Client Secret.

Відповідь:

{
  "access_token": "OvVWMW5Lh-GLCyASZXrEYtoIkUHQveP-fvtR5oYb41cY9LFlpGMjiQjNllxGUxZf6x4IW3MH_-7u4bOLPFEKPx7wIK35PXYjPVsaAWdhPByqeSRPYcU5gVTYJ0BvB7qV",
  "token_type": "Bearer",
  "refresh_token": "HLrduDsdL0BkJx1BkcDM_W_-ONoukTX7vToccDgagW-An9CLxORnVSdCtQ3l9I8NwhEquJXKSSxDqPfE4puMETI2-e0Npijn1Ve5GXklbu-2bXh6zoe296CqFtXf88yu",
  "scope": "role.full.api.methods",
  "expires_in": 172799
}

Термін дії токенів:

• Токен доступу: 48 годин
• Токен оновлення: 30 днів

Відлік починається з моменту видачі токена.

Крок 4 — Звернення до API eSputnik

Передавайте токен доступу в заголовку Authorization кожного запиту до API:

Authorization: Bearer YOUR_ACCESS_TOKEN

Доступні методи API залежать від області доступу, налаштованої під час реєстрації застосунку.

Крок 5 — Оновлення токена доступу

Коли токен доступу закінчується, використайте токен оновлення, щоб отримати нову пару токенів — без повторного входу користувача.

Надішліть POST-запит на https://uaa.esputnik.com/uaa/oauth/token.

Передайте такі параметри в тілі запиту:

Параметри передавайте у тілі запиту з заголовком Content-Type: application/x-www-form-urlencoded. Передача параметрів через рядок запиту (query string) також підтримується для зворотної сумісності, але не рекомендується.

Автентифікація запиту — Basic Auth: username це ваш Client ID, password це ваш Client Secret.

Відповідь:

{
  "access_token": "OvVWMW5Lh-GLCyASZXrEYtoIkUHQveP-fvtR5oYb41cY9LFlpGMjiQjNllxGUxZf6x4IW3MH_-7u4bOLPFEKPx7wIK35PXYjPVsaAWdhPByqeSRPYcU5gVTYJ0BvB7qV",
  "token_type": "Bearer",
  "refresh_token": "HLrduDsdL0BkJx1BkcDM_W_-ONoukTX7vToccDgagW-An9CLxORnVSdCtQ3l9I8NwhEquJXKSSxDqPfE4puMETI2-e0Npijn1Ve5GXklbu-2bXh6zoe296CqFtXf88yu",
  "scope": "role.full.api.methods",
  "expires_in": 172799
}

Після успішного оновлення попередній токен доступу стає недійсним — використовувати можна лише новий. Для наступного оновлення використовуйте новий токен оновлення.

Крок 6 — Перевірка токена

Щоб отримати інформацію про токен — чи він активний, коли закінчується, які права має — надішліть POST-запит на https://uaa.esputnik.com/uaa/oauth/introspect.

Передайте один параметр у тілі запиту з Content-Type: application/x-www-form-urlencoded:

Автентифікація запиту — Basic Auth: username це ваш Client ID, password це ваш Client Secret.

Відповідь містить метадані токена: статус активності, час закінчення, видані права та іншу інформацію.

Застарілий ендпоінт /oauth/check_token залишається доступним для зворотної сумісності.

Приклад коду

Python

import requests, json

authorize_url = "https://uaa.esputnik.com/uaa/oauth/authorize"
token_url = "https://uaa.esputnik.com/uaa/oauth/token"
callback_uri = "http://my_host:8081/test/callback"
protected_api_contacts = "https://esputnik.com/api/v1/contacts"

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'

authorization_redirect_url = authorize_url + '?response_type=code&client_id=' + client_id + '&redirect_uri=' + callback_uri
print("go to the following url on the browser and enter the code from the returned url: ")
print("---  " + authorization_redirect_url + "  ---")
authorization_code = input('code: ')

data = {'grant_type': 'authorization_code', 'code': authorization_code, 'redirect_uri': callback_uri}
access_token_response = requests.post(token_url, data=data, allow_redirects=False, auth=(client_id, client_secret))

tokens = json.loads(access_token_response.text)
access_token = tokens['access_token']
print("access token: " + access_token)

api_call_headers = {'Authorization': 'Bearer ' + access_token}
api_call_response = requests.get(protected_api_contacts, headers=api_call_headers)
print(api_call_response.text)

Підключені застосунки

Щоб переглянути застосунки, яким надано доступ до вашого акаунту, натисніть меню акаунту у верхньому правому куті, відкрийте Налаштування та перейдіть до Підключені застосунки.

Щоб відключити застосунок, натисніть три крапки поряд із ним та оберіть відповідний пункт.

Пов'язані статті

• Початок роботи з API
• Підключення HTTP-запиту як зовнішнього джерела даних