26  /  36

Полный протокол OAuth 2.0

Просмотров: 16064 (Статистика ведётся с 06.02.2017)
Дата последнего изменения: 26.03.2018

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

Примечание: Реализация полного протокола необходима только для серверных приложений со включенной опцией "Использовать только API". Статические приложения и серверные приложения с интерфейсом внутри Битрикс24 получают авторизацию при подключении js-библиотеки, а также в данных POST-запроса на URL-приложения при открытии приложения.

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

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

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

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

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

Внимание! Время жизни первого авторизационного кода code составляет всего 30 секунд, то есть, он должен быть использован сразу после получения.

Общий порядок работы с 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"
    }
Примеры, реализующие полный протокол OAuth 2.0 были даны в разделах "Быстрый старт" для локального и публичного приложений.
2
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии