Полный протокол авторизации OAuth 2.0

OAuth — открытый протокол авторизации, который позволяет предоставить третьей стороне ограниченный доступ к защищенным ресурсам пользователя без передачи логина и пароля.

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

Получение первой пары токенов описано ниже. Как продлевать токены, читайте в статье Автоматическое продление токенов OAuth 2.0, как разбирать ошибки сервера авторизации — в статье Коды ошибок.

Протокол OAuth используется для локальных и тиражных приложений. Локальные вебхуки его не используют: вебхук авторизуется кодом, встроенным в адрес запроса.

Когда нужен полный протоколКогда нужен полный протокол

Проверьте, что верны все утверждения:

• у вас есть свой веб-сервис — внешнее приложение или отдельное программное обеспечение
• пользователь уже авторизован в вашем сервисе
• пользователь должен авторизоваться в своем Битрикс24, чтобы ваш сервис получил токены для работы с REST API этого Битрикс24
• пользователь не работает с вашим сервисом внутри интерфейса Битрикс24 — сценарии остаются на стороне сервиса, а REST API нужен только для обмена данными

Если хотя бы одно утверждение неверно, выберите другой способ получить токены.

Как работает протоколКак работает протокол

В авторизации участвуют четыре стороны:

• пользователь — владелец данных, от имени которого приложение работает с REST API
• приложение — ваш сервис, который хранит токены и вызывает методы REST API
• Битрикс24 пользователя — источник данных и место, где пользователь проходит авторизацию
• сервер авторизации https://oauth.bitrix24.tech/ — держатель авторизации приложения, только он выдает и продлевает токены

Протокол состоит из пяти шагов:

1. Пользователь сообщает приложению адрес своего Битрикс24.
2. Приложение отправляет пользователя в его Битрикс24 и добавляет к запросу свой client_id.
3. Пользователь авторизуется в Битрикс24 и возвращается на адрес приложения с авторизационным кодом code. Это еще не токен для работы с REST API, а одноразовый код для получения токенов.
4. Приложение обращается напрямую к серверу авторизации и передает code, client_id и client_secret.
5. Сервер авторизации возвращает первую пару токенов: access_token для вызовов REST API и refresh_token для продления доступа.

Что подготовить до авторизацииЧто подготовить до авторизации

Зарегистрируйте приложение и получите пару client_id и client_secret:

• для тиражного приложения — в партнерском кабинете, ключи действуют для любого Битрикс24
• для локального приложения — в самом Битрикс24, ключи действуют только для этого Битрикс24

Приложение должно быть установлено в том Битрикс24, пользователь которого проходит авторизацию. Для неустановленного приложения авторизация завершится ошибкой.

В настройках приложения задается обратный адрес redirect_uri — адрес приложения, на который Битрикс24 вернет пользователя после авторизации. В запросе авторизации этот адрес не передается, Битрикс24 берет его из настроек приложения.

Там же задается список прав доступа scope. Приложение получает только те права, которые указаны в его карточке. Вызовы методов выполняются от имени пользователя, прошедшего авторизацию, и ограничены его правами в Битрикс24.

Полная OAuth-авторизация в Битрикс24Полная OAuth-авторизация в Битрикс24

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

Шаг 1. Авторизация пользователя в Битрикс24Шаг 1. Авторизация пользователя в Битрикс24

Приложение запрашивает у пользователя адрес Битрикс24 и переадресует его на URL авторизации:

https://portal.bitrix24.ru/oauth/authorize/?
     client_id=app.573ad8a0346747.09223434
     &state=JJHgsdgfkdaslg7lbadsfg

Параметры URL:

Обязательные параметры отмечены *

По этой ссылке пользователю откроется форма авторизации. Если пользователь уже авторизован в своем Битрикс24, форма не показывается.

Если авторизацию нельзя завершить, Битрикс24 покажет ошибку пользователю на своей странице. Приложение не получит ни переадресации, ни параметров ошибки, поэтому обрабатывать неудачную авторизацию на стороне redirect_uri не нужно.

После успешной авторизации Битрикс24 вернет пользователя на redirect_uri приложения и добавит к адресу параметры:

https://www.applicationhost.ru/application/?
     code=avmocpghblyi01m3h42bljvqtyd19sw1
     &state=JJHgsdgfkdaslg7lbadsfg
     &domain=portal.bitrix24.ru
     &member_id=a223c6b3710f85df22e9377d6c4f7553
     &scope=crm%2Centity%2Cim%2Ctask
     &server_domain=oauth.bitrix24.tech

Параметры:

Шаг 2. Авторизация приложенияШаг 2. Авторизация приложения

Получив авторизационный код code, приложение делает скрытый от пользователя GET-запрос к серверу авторизации:

https://oauth.bitrix24.tech/oauth/token/?
    grant_type=authorization_code
    &client_id=app.573ad8a0346747.09223434
    &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
    &code=avmocpghblyi01m3h42bljvqtyd19sw1

Параметры:

Обязательные параметры отмечены *

Сервер авторизации ответит статусом 200 OK и телом в формате application/json:

{
    "access_token": "s1morf609228iwyjjpvfv6wsvuja4p8u",
    "client_endpoint": "https://portal.bitrix24.ru/rest/",
    "domain": "oauth.bitrix24.tech",
    "expires_in": 3600,
    "member_id": "a223c6b3710f85df22e9377d6c4f7553",
    "refresh_token": "4f9k4jpmg13usmybzuqknt2v9fh0q6rl",
    "scope": "crm,entity,im,task",
    "server_endpoint": "https://oauth.bitrix24.tech/rest/",
    "status": "F"
}

Данные ответа:

Сохраните оба токена на своей стороне. refresh_token нужен, чтобы получать новые пары токенов без участия пользователя, поэтому храните его в недоступном из браузера хранилище.

Вызовы методов идут на адрес из client_endpoint: к нему добавляется имя метода, а access_token передается в параметре auth.

https://portal.bitrix24.ru/rest/crm.deal.list?auth=s1morf609228iwyjjpvfv6wsvuja4p8u

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

{
    "error": "PAYMENT_REQUIRED",
    "error_description": "Payment required"
}

Другие ошибки сервера авторизации разобраны в статье Коды ошибок.

Что делать дальшеЧто делать дальше

• вызвать метод REST API с полученным access_token — Как вызывать методы REST API
• получить новую пару токенов, когда access_token перестанет работать — Автоматическое продление токенов OAuth 2.0