Устранение проблем настройки OAuth-приложений
В статье рассмотрены типичные проблемы, с которыми может столкнуться пользователь при настройке интеграции с веб-сервисом с использованием аутентификации OAuth 2.0. Детальное описание настройки читайте в статье “Настройка приложения OAuth 2.0”.
Содержание
•Указанные настройки соединения некорректны или неактуальны
•Во внешнем приложении указан некорректный адрес перенаправления (redirect URL)
•Недостаточно разрешений (scopes) на выполнение нужной операции
•Разрешения должны быть указаны в настройках приложения
•Разрешения, запрошенные bpm’online, отклонены при входе в приложение
•Установлены другие ограничения доступа в настройках веб-сервиса
•Приложение ожидает client ID и client secret в другой части запроса
Указанные настройки соединения некорректны или неактуальны
Настройки отличаются от настроек соединения в интегрированном приложении. Ошибка может быть в значениях Client ID, Client secret, а также в URL запроса кода авторизации, URL запроса токена или в URL отзыва токена.
Когда возникает ошибка?
•При добавлении пользователя на странице OAuth-приложения.
•При вызове веб-сервиса (когда bpm’online пытается вызвать веб-сервис, используя некорректные настройки).
Что делать?
Проверьте, чтобы все поля на странице настройки OAuth-приложения были заполнены корректно. Убедитесь, что указанные значения совпадают с соответствующими настройками во внешнем приложении. После этого попробуйте добавить нового пользователя повторно.
Во внешнем приложении указан некорректный адрес перенаправления (redirect URL)
Настройка OAuth-аутентификации выполняется на стороне bpm’online и во внешнем приложении. По требованиям безопасности используется специальный адрес (redirect URL) для перенаправления пользователей после получения токена доступа от сервера аутентификации. Домен, на который выполняется перенаправление, часто требует отдельной проверки.
Корректный redirect URL отображается на странице настройки OAuth-приложения в bpm’online (Рис. 1).
Рис. 1 — Redirect URL на странице настройки OAuth-аутентификации в bpm’online
Этот же URL-адрес необходимо скопировать в настройки внешнего приложения (Рис. 2).
Рис. 2 — Добавление redirect URL в Google API
Если ссылка во внешней системе не совпадает со ссылкой, указанной на странице настройки OAuth-приложения в bpm’online, то токен доступа не будет получен.
Когда возникает ошибка?
При добавлении пользователя на странице OAuth-приложения.
Что делать?
Скопируйте корректную ссылку (redirect URL) со страницы настройки OAuth-приложения в bpm’online и укажите ее в соответствующем поле в настройках внешнего приложения.
Недостаточно разрешений (scopes) на выполнение нужной операции
В OAuth 2.0 токен доступа часто выдается с определенными ограничениями к функциональности вызова внешнего приложения. Например, приложения могут потребовать отдельных разрешений на чтение и изменение данных. В таком случае список необходимых разрешений необходимо указать в bpm’online, во внешнем приложении или при авторизации пользователя.
В bpm’online необходимые разрешения указываются на детали [Разрешения (scopes)] страницы настройки OAuth-приложения. Bpm’online будет запрашивать эти разрешения при выполнении пользователем OAuth-аутентификации. Если необходимое разрешение не было добавлено на деталь [Разрешения (scopes)], то, скорее всего, пользователь не сможет авторизоваться.
Когда возникает ошибка?
Если при попытке вызвать веб-сервис, например, для изменения его данных, нет разрешения на изменение, то внешнее приложение выдаст ошибку доступа на изменение.
Что делать?
1.Добавьте необходимые разрешения на деталь [Разрешения (scopes)] на странице настройки свойств OAuth-приложения в bpm’online.
2.Удалите из bpm’online пользователя веб-сервиса, чтобы ранее выданный токен доступа был отозван.
3.Отмените доступ к приложению bpm’online в настройках веб-сервиса (например, вы можете отменить доступ к определенным приложениям в настройках своей учетной записи Google).
4.Добавьте пользователя повторно.
Разрешения должны быть указаны в настройках приложения
Иногда разрешения (scopes) должны быть указаны в интегрированном приложении. Например, уровень доступа можно установить в процессе настройки приложения в интегрированном веб-сервисе. В этом случае разрешения в bpm’online должны совпадать с разрешениями, установленными в настройках приложения в интегрированном веб-сервисе.
Когда возникает ошибка?
В зависимости от архитектуры приложения, возможны следующие ошибки, если разрешения в bpm’online превышают разрешения в настройках веб-сервиса:
•Пользователь не сможет авторизоваться.
•При попытке вызвать веб-сервис с целью изменения его данных внешнее приложение выдаст ошибку.
Что делать?
Если пользователь не может авторизоваться:
1.Добавьте необходимое разрешение в настройках внешнего приложения.
2.Повторите попытку авторизации.
Если при попытке вызвать веб-сервис для изменения данных внешнее приложение выдает ошибку:
1.Добавьте необходимое разрешение в настройках внешнего приложения.
2.Удалите пользователя веб-сервиса из bpm’online, чтобы отменить ранее выданный токен доступа.
3.Отмените доступ к приложению bpm’online в настройках веб-сервиса (например, вы можете отменить доступ к определенным приложениям в настройках своей учетной записи Google).
4.Добавьте пользователя повторно.
Разрешения, запрошенные bpm’online, отклонены при входе в приложение
Корректно указанные разрешения в bpm’online могут быть не приняты при авторизации. В некоторых приложениях, например, в Facebook, список выданных разрешений может быть изменен пользователем веб-сервиса во время логина.
Например, чтение и изменение данных (2 записи на детали [Разрешения (scopes)] по умолчанию разрешены в настройках приложения. После авторизации пользователь в настройках снимает признак (чекбокс), разрешающий изменение данных. В таком случае, когда bpm’online запросит доступ на чтение и изменение данных, приложение выдаст только токен доступа на чтение данных.
Когда возникает ошибка?
При попытке вызвать веб-сервис с целью изменения его данных внешнее приложение выдаст ошибку.
Что делать?
1.Удалите пользователя веб-сервиса из bpm’online, чтобы отменить ранее выданный токен доступа.
2.Отмените доступ к приложению bpm’online в настройках веб-сервиса (например, вы можете отменить доступ к определенным приложениям в настройках своей учетной записи Google).
3.Добавьте пользователя в bpm’online еще раз, отметив все нужные разрешения scopes во время авторизации.
Не установлен признак [Использовать аутентификацию] в методе веб-сервиса или способ аутентификации выбран неверно
Этот случай в большей степени относится ко всему процессу настройки интеграции с веб-сервисами, чем к OAuth-аутентификации. В подобной ситуации веб-сервис возвращает ошибку авторизации 403.
Когда возникает ошибка?
Ошибка происходит при вызове веб-сервиса, поскольку bpm’online пытается подключиться без передачи токена доступа.
Что делать?
Выберите корректный вид аутентификации на вкладке [Аутентификация] страницы настройки веб-сервиса. Или установите признак [Использовать аутентификацию] в методах веб-сервиса.
Установлены другие ограничения доступа в настройках веб-сервиса
Например, некоторые сервисы могут ограничивать доступ по IP или доменам, с которых выполняется авторизация. Например, в Facebook есть ограничения по доменам.
Когда возникает ошибка?
При добавлении пользователя на странице OAuth-приложения.
Что делать?
На стороне веб-сервиса добавьте и корректно настройте IP и/или домен вашего приложения bpm’online.
Приложение ожидает client ID и client secret в другой части запроса
При запросе или обновлении токена bpm’online по умолчанию включает идентификатор клиента (client id) и секретный ключ (client secret) в тело запроса.
Пример
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
Большинство сервисов, например, Google, LinkedIn, Salesforce, JIRA и т. д. обрабатывают такие запросы.
Однако, существуют сервисы, которые не принимают сlient id и client secret в теле запроса. Протокол OAuth допускает разные варианты.
Например, QuickBooks, Docusign, GoToWebinar передают client id и client secret в форме базовой аутентификации.
Пример
curl -X POST "https://api.getgo.com/oauth/v2/token" \:
-H "Authorization: Basic {Base64 Encoded consumerKey and consumerSecret}" \
-H "Accept:application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code={responseKey}&redirect_uri=http%3A%2F%2Fcode.example.com"
Этот способ описан в формате RFC (документация, содержащая технические спецификации и стандарты, которые применяются в сети интернет), как альтернатива подходу, используемому в bpm’online.
Некоторые сервисы выполняют аутентификацию другим способом. Например, вместо POST-запроса с параметрами, содержащимися в теле и заголовках, Facebook использует GET-запрос токена со всеми параметрами в URL запроса.
Когда возникает ошибка?
При попытке пользователя авторизоваться в приложении. Авторизация не происходит.
Что делать?
На сегодняшний день нет других способов отправить идентификатор клиента (client id) и секретный ключ (client secret) в bpm’online.
При авторизации в приложении отсутствует токен обновления (refresh token)
Refresh token нужен для автоматического обновления токена доступа. В результате интеграция будет работать без необходимости подтверждать доступ до тех пор, пока токен доступа обновляется автоматически. Токен обновления используется не всегда. В зависимости от архитектуры внешнего приложения такие случаи не всегда являются ошибкой интеграции.
Ниже приведены типовые примеры, когда токен обновления не используется.
•Токен доступа не имеет срока действия
•В приложении не предусмотрено обновление токенов доступа
•Обновление токена доступа необходимо включить в настройках приложения
•Приложение выдает токен обновления (refresh token) однократно на каждого пользователя
Токен доступа не имеет срока действия
Внешнее приложение выдает токен доступа (access token), который не требует обновления, т. к. не имеет срока действия. Такие случаи достаточно редки. Несмотря на предупреждающее уведомление, интеграция может работать в течение длительного времени.
Что делать?
Изучите документацию веб-сервиса. Убедитесь, что приложение не выдает токен обновления, а токен доступа к приложению не имеет срока действия. В таком случае можно проигнорировать предупреждение о необходимости обновления токена доступа и продолжать работать с веб-сервисом.
В приложении не предусмотрено обновление токенов доступа
Внешнее приложение выдает токен доступа с определенным сроком действия. Но такой токен нельзя обновить в связи с ограничениями в настройках приложения (требования безопасности). Такие случаи возможны при интеграции с платежными приложениями, предусматривающими лишь кратковременный доступ пользователя.
Подобные приложения не работают с общим пользователем, поскольку общий доступ — это возможность избежать необходимости авторизоваться в веб-сервисе для каждого отдельного пользователя bpm’online.
Что делать?
Изучите документацию веб-сервиса. Убедитесь, что приложение не выдает токен обновления, а токен доступа к приложению имеет срок действия.
Обновление токена доступа необходимо включить в настройках приложения
Внешнее приложение выдает токен доступа, который имеет срок действия. Токен доступа не может быть обновлен, т. к. в приложении не настроена возможность его обновления. Например, в приложении необходимо настроить отдельное разрешение на запрос токена обновления (refresh token).
Что делать?
1.Изучите документацию веб-сервиса. Убедитесь, что приложение выдает токены обновления.
2.Определите, где в настройках приложения добавляются разрешения на выдачу токена обновления и заполните эти настройки
3.Выполните отзыв текущего токена доступа.
4.Добавьте общего пользователя в bpm’online.
Приложение выдает токен обновления (refresh token) однократно на каждого пользователя
Внешнее приложение может выдавать токен обновления только один раз. Т. е. пользователь, получив токен обновления и войдя в приложение, повторно получить его не может.
Пример
Администратор добавил в bpm’online токен этого же внешнего приложения.
Администратор удалил токен из bpm’online, не отозвав его (например, удалил токен из базы данных, не заполнив поле [URL отзыва токена]).
Когда администратор добавляет новый токен в в bpm’online, внешнее приложение не выдаст токен обновления повторно, так как ранее такой токен уже был выдан, но не был отменен.
Также проблема может возникнуть, если администратор вошел во внешнее приложение из другой системы, а затем пытается войти в него же из bpm’online.
Что делать?
Изучите документацию веб-сервиса. Убедитесь, что приложение выдает токены обновления. Определите, как отменить доступ к веб-сервису. Обычно в веб-сервисах есть форма или пользовательский интерфейс для управления доступом внешних систем. Удалите токен приложения, который пользователь добавляет в bpm’online (например, удалите интеграцию с bpm’online).
В результате при добавлении токена доступа в bpm’online интегрированное приложение выдаст токен обновления.
Токен обновления (refresh token) был аннулирован во внешнем приложении, но все еще хранится в bpm’online
Это может произойти, если администратор вошел и bpm’online, и в интегрированное приложение, а затем удалил токен доступа на странице управления токеном веб-сервиса. В результате в bpm’online будут храниться устаревшие токены доступа и обновления (access token и refresh token).
Когда возникает ошибка?
Во время вызова веб-сервиса в bpm’online возникает ошибка авторизации
Что делать?
1.Удалите пользователя со страницы настройки OAuth-приложения в bpm’online.
2.Добавьте пользователя повторно.
Смотрите далее
