OAuth 2.0

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

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

Протокол очень распространён, используется огромным количеством сервисов по всему миру, поскольку позволяет приложению получить доступ к API от имени конкретного пользователя конкретного портала.

Для OAuth-сервера авторизация - это указание на то, что пользователь дал доступ приложению. Приложение предоставляет свой секрет. Портал это всё объединяет и выдаёт приложению соответствующий тип доступа.

Протокол состоит из двух шагов:

• Пользователь сообщает порталу, что он авторизован. Приложение добавляет свой идентификатор: client id. В ответ сервер передаёт пользователю, а через него и приложению, первый авторизационный код: code.
• Этот код приложение, уже скрыто от пользователя, передаёт обратно порталу Важно! Запрос code не может делаться ajax запросом со страниц другого сайта, так как браузер его будет блокировать. Запрос для получения access token должен исходить именно от серверной части приложения. , присоединяя к нему свой секретный ключ: client secret. Приложение таким образом подтверждает, что оно то самое приложение, которое известно порталу и которое может с ним работать. В ответ портал сообщает два параметра: access_token - параметр, который собственно требуется для доступа к авторизации и refresh_token - токен, который требуется для продления авторизации.
• После использования refresh_token и выданный вместе с ним access_token становятся недействительными. Для доступа к REST API следует использовать новый полученный access_token, а для продления доступа - новый refresh_token.

Общий порядок работы с OAuth

• добавляется и устанавливается тиражное приложение, либо локальное в своем отдельном Битрикс24;
• запрашиваются с удаленного сервера ключи;
• сервер перенаправляет браузер на зарегистрированный приложением URL;
• обрабатывается ответ;
• подписываются полученным ключом все запросы к Rest API.

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

В качестве сервера данных и держателя пользовательской авторизации выступает конкретный Битрикс24. В качестве держателя авторизации приложения служит сервер авторизации, доступный по адресу https://oauth.bitrix.info/.

Полный сценарий OAuth-авторизации проходит в несколько шагов:

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

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

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

   Параметры:

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

   По данной ссылке пользователю будет выведена форма авторизации. После авторизации (либо при наличии авторизованной сессии), если приложение с переданным client_id установлено на портале, портал вернет пользователя на redirect_uri приложения. Если же приложение на портал не установлено, пользователю будет выведено соответствующее сообщение об ошибке.

   Итогом успешной пользовательской авторизации должен стать возврат пользователя на зарегистрированный адрес приложения с дополнительными параметрами:

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

   Параметры:

   • code - первый авторизационный код, см. ниже;
   • state - значение переданное в первом запросе;
   • domain - домен портала, на котором происходит авторизация;
   • member_id - уникальный идентификатор портала, на котором происходит авторизация;
   • scope - разделенный запятыми список прав доступа к REST API, которые портал предоставляет приложению;
   • server_domain - домен сервера авторизации.
   Внимание! В партнерском кабинете можно зарегистрировать приложение, которое не будет иметь "обратного адреса" redirect_uri. (По redirect_uri получаются авторизационные данные.) Такой сценарий возможен для тиражных решений, которые не имеют постоянного адреса. В этом случае предполагается, что пользователь вручную передает первый авторизационный код приложению. Упрощенный первый авторизационный код будет выведен пользователю непосредственно на странице, а приложение должно предоставить пользователю поле для ввода значения кода.

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

   Внимание! Предыдущая реализация протокола предполагала отдачу client_secret приложения непосредственно Битрикс24. В связи с расширением механизма REST API на коробочные установки Битрикс24 такое действие становится небезопасным. Все операции, предполагающие участие секретного кода приложения, должны проводиться исключительно с сервером авторизации oauth.bitrix.info. По той же причине этот сервер авторизации должен быть единственным доверенным источником информации о платежном статусе приложения на портале.

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

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

   Параметры (все - обязательны):

   • grant_type - параметр, показывающий тип авторизационных данных, подлежащих валидации. Должен иметь значение authorization_code;
   • client_id - код приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
   • client_secret - секретный ключ приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
   • code - значение параметра code, переданного приложению в конце предыдущего шага.
   Внимание! Время жизни первого авторизационного кода code - всего 30 секунд, и он должен быть использован сразу после получения.

   В ответ на такой запрос приложение получит json следующего содержания:

   GET /oauth/token/
   
   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
   	"access_token": "s1morf609228iwyjjpvfv6wsvuja4p8u",  
   	"client_endpoint": "https://portal.bitrix24.com/rest/",  
   	"domain": "oauth.bitrix.info",  
   	"expires_in": 3600,  
   	"member_id": "a223c6b3710f85df22e9377d6c4f7553",  
   	"refresh_token": "4f9k4jpmg13usmybzuqknt2v9fh0q6rl",  
   	"scope": "app",  
   	"server_endpoint": "https://oauth.bitrix.info/rest/",  
   	"status": "T"
   }

   Значимые параметры:

   • access_token - основной авторизационный токен, требуемый для доступа к REST API;
   • refresh_token - дополнительный авторизационный токен, служащий для продления сохраненной авторизации;
   • client_endpoint - адрес REST-интерфейса портала;
   • server_endpoint - адрес REST-интерфейса сервера;
   • status - статус приложения на портале.

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

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