Для интеграции требуется ошибка разногласия по предоставлению кода

Обновлено: 21.11.2024

OAuth2 – это определенная спецификация авторизации, которую мы используем для включения сторонних приложений для интеграции с Webflow. Прежде чем взаимодействовать с API, разработчики должны зарегистрировать свои приложения, где будут созданы client_id и client_secret.

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

Авторизация пользователя

Направить пользователя на URL-адрес авторизации с правильными параметрами. Когда они примут или отклонят запрос на авторизацию, пользователь будет перенаправлен обратно на redirect_url, указанный во время настройки приложения OAuth.

Запрос

Вы получаете ответ на запрос авторизации через URL-адрес перенаправления, который вы указываете во время настройки приложения, и его можно обновить на панели управления

Ответ

Ответ об ошибке

ПАРАМЕТР ОПИСАНИЕ
code Используемый код авторизации чтобы получить access_token для пользователя. Может использоваться только один раз.
state То же, что и исходное значение, если указано.
ПАРАМЕТР ОПИСАНИЕ
состояние То же, что и исходное значение, если указано.
error Код ошибки, указывающий, какая ошибка произошла.
error_description Удобочитаемое описание возникшей ошибки.

Запросить токен доступа

  • После получения кода с URL-адреса перенаправления для завершения авторизации ваше приложение должно запросить access_token .
  • Запрос access_token следует выполнять как можно скорее после авторизации, поскольку неподтвержденные авторизации действительны только в течение 30 минут.

Запрос

Ответ

< /таблица>

Ответ об ошибке

ПАРАМЕТР ОПИСАНИЕ
token_type Всегда будет «bearer»
access_token Токен для использования при выполнении запросов API от имени пользователя

Отменить авторизацию

Запрос

Ответ

ПАРАМЕТР ОПИСАНИЕ
ошибка Код ошибки с указанием возникшей ошибки.
error_description Удобочитаемое описание возникшей ошибки.
ПАРАМЕТР ОПИСАНИЕ
didRevoke True при успешном завершении отзыв

Ответ об ошибке

В дополнение к предоставлению кода авторизации также можно получить access_tokens для личных приложений.

Если вы разрабатываете частную интеграцию с Webflow и взаимодействуете только со своей учетной записью, существует упрощенный процесс получения access_token без необходимости регистрации и приложения OAuth, а также реализации полного потока предоставления кода авторизации. Вы просто можете сгенерировать ключ API (эквивалентный access_token ) на панели управления Webflow.

Ключи API можно создавать для каждого сайта отдельно.

Имейте в виду, что ключи API фактически аналогичны вашему паролю Webflow, поэтому обращайтесь с ними с таким же уровнем осторожности!

Ключи API сайта

Чтобы сгенерировать ключ API для сайта, откройте сайт на панели инструментов и перейдите на панель «Настройки». Существует раздел под названием «Доступ к API», где вы можете сгенерировать новый ключ API.

Зарегистрировать приложение

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

Чтобы зарегистрировать приложение в качестве пользователя, откройте вкладку интеграции в настройках учетной записи и нажмите кнопку «Зарегистрировать новое приложение».

Команда или рабочее пространство

Чтобы зарегистрировать приложение в качестве группы или рабочей области, откройте страницу настроек для своей группы или рабочей области, щелкнув ее на странице обзора панели инструментов. Затем перейдите в раздел интеграции и нажмите кнопку «Зарегистрировать новое приложение».

Для регистрации необходимы следующие поля:

При регистрации вы должны увидеть токены client_id и client_secret для вашего приложения. Они понадобятся вам для создания авторизаций для пользователей в вашем приложении.

Ошибки, возвращаемые в строке запроса к настройке URL-адреса перенаправления для вашего приложения

Ошибки авторизации

ПАРАМЕТР ОПИСАНИЕ
ошибка Код ошибки с указанием возникшей ошибки.
error_description Удобочитаемое описание возникшей ошибки.
< tr>
Код ошибки Описание
invalid_request
unsupported_response_type
отказано в доступе

Ошибки, возвращаемые API для конечной точки POST /oauth/access_token

Переход на OAuth 2.0 состоит из трех основных шагов:

  1. Запросить у пользователя разрешение на доступ к его данным.
  2. Запрос данных пользователя с помощью предоставленного токена доступа.
  3. Обновите токены доступа с истекшим сроком действия с помощью соответствующего токена обновления.

Поток предоставления кода авторизации с помощью PKCE

Существует несколько процессов авторизации, специфичных для протокола OAuth 2.0. Для лучшей безопасности Fitbit рекомендует использовать поток предоставления кода авторизации с ключом подтверждения для обмена кодами (PKCE), определенный в RFC 7636. PKCE дополняет поток предоставления кода авторизации динамически создаваемым криптографически случайным ключом («верификатором кода») и его преобразованием. значение («вызов кода») для проверки клиента. Любое общедоступное клиентское приложение получит дополнительную защиту с возможностью смягчения атак с перехватом кода авторизации. В этом разделе за 5 шагов будет показано, как приложение получает авторизацию пользователя с помощью PKCE.

Шаг 1. Создание проверки кода и проверки кода

  • Криптографически случайное значение длиной от 43 до 128 символов, называемое верификатором кода
    • .
  • Хэш SHA-256 верификатора кода, URL-адрес base64, закодированный с опущенным дополнением, называемый вызовом кода

Преобразование верификатора кода в вызов кода требует использования библиотек, реализующих спецификации хэширования SHA-256 и кодирования Base64Url. Необязательные символы заполнения Base64Url ( = ) следует опустить. Например, если верификатор кода — 01234567890123456789012345678901234567890123456789, псевдокод base64UrlEncode(sha256Hash(code_verifier)) должен выдать запрос кода -4cf-Mzo_qg9-uq0F4QwWhRh4AjcAqNx7Sb>MpYcAqNx7Sb.

Шаг 2. Запрос авторизации для данных пользователя Fitbit

Используя веб-браузер, приложение вызывает конечную точку авторизации, чтобы отобразить страницу авторизации Fitbit для пользователя. При необходимости пользователю может потребоваться войти в систему со своими учетными данными Fitbit.

Мобильная разработка: используйте настраиваемые вкладки (Android) или SFSafariViewController (iOS) вместо их аналогов в веб-просмотре. Это позволяет пользователю Fitbit знать, что он входит на защищенный сайт Fitbit.

Например, следующий URL загрузит страницу авторизации

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

ПРИМЕЧАНИЕ. Приложению не разрешено включать все области по умолчанию или заставлять пользователя включать все области. Вместо этого мы предлагаем поощрять пользователей включать все области, указав что-то вроде «Для лучшего взаимодействия с пользователем мы рекомендуем вам включить все перечисленные области». См. Условия обслуживания платформы Fitbit для получения более подробной информации. В конечном счете, от пользователя Fitbit зависит, включены все области или нет. Поэтому приложение не должно прерываться, если область действия не предоставлена.

Шаг 3. Получение кода авторизации

Мобильная разработка: Fitbit рекомендует использовать универсальную ссылку (iOS) или ссылку на приложение (Android) при перенаправлении обратно в приложение.

Шаг 4. Обмен кода авторизации на токены доступа и обновления

Тип приложения (серверное, клиентское или личное), определенный в настройках зарегистрированного приложения, определяет, как конечная точка Token API авторизуется для Fitbit.

Тип серверного приложения

Типы серверных приложений должны аутентифицировать себя, используя секрет клиента, доступный в настройках приложения. Это обеспечивает высочайший уровень безопасности потока OAuth2. Однако его следует использовать только приложениям, которые могут безопасно хранить секрет клиента, например, приложениям, работающим на веб-сервере. Примечательно, что секрет клиента никогда не должен включаться в исходный код приложения или храниться на устройстве конечного пользователя, где его можно обнаружить.

Эти приложения аутентифицируются, указывая заголовок авторизации в запросе и включая токен "Basic". Базовый токен представляет собой объединение идентификатора клиента и секрета в кодировке base64, разделенных двоеточием:

Например, с идентификатором клиента "ABC123" и секретом "DEF456"

Типы клиентских и личных приложений

Клиентские и персональные приложения могут вызывать /oauth2/token без каких-либо дополнительных требований безопасности. Это следует использовать только в том случае, если приложение не может безопасно хранить секрет клиента. Например,

Шаг 5. Получите токены доступа и обновления

Конечная точка токена возвращает ответ в формате JSON, который включает:

  • Идентификатор пользователя, разрешившего доступ
  • Токен доступа, используемый для запроса данных пользователя.
  • Токен обновления, который приложение будет использовать для получения новой пары токенов доступа и обновления.
  • Срок действия токена доступа в секундах
  • Области действия, которые пользователь включил на странице авторизации Fitbit.

Мы рекомендуем приложению сохранять эту информацию и обращаться к ней по мере необходимости. Если приложение потеряет маркер обновления для пользователя, пользователю потребуется снова повторно авторизовать приложение.

Другие поддерживаемые потоки авторизации

Поток предоставления кода авторизации (без PKCE)

Это исходный вариант потока предоставления кода авторизации, определенный RFC 6749, который заменен PKCE. В отличие от PKCE, этот вариант не поддерживает верификатор кода или контрольные значения при запросе авторизации пользователя. Вместо этого для защиты этого потока используются два других метода.

  1. Только типы приложений server могут не использовать PKCE. Это означает, что при получении маркеров доступа и обновления необходимо использовать секрет клиента.
  2. Для защиты от атак с подделкой межсайтовых запросов (CSRF) приложение должно передавать маркер защиты от подделки в параметре «state» при отображении страницы авторизации. Это должно быть неугадываемое значение, связанное с пользователем. Fitbit вернет это значение в качестве параметра запроса в URL-адресе перенаправления, и ваше приложение должно убедиться, что оно совпадает.

Неявный поток грантов

Определенный в RFC 6749, этот поток авторизации больше не рекомендуется в качестве передовой практики OAuth2. В отличие от потока предоставления кода авторизации, страница авторизации напрямую возвращает токен доступа, что делает процесс получения согласия очень уязвимым для ряда атак безопасности. При использовании потока неявного предоставления

  • Зарегистрированное приложение должно быть настроено с типом приложения OAuth 2.0 "клиент".
  • Пользователь может указать срок действия токена доступа до одного года.
  • После того как пользователь дает согласие, URL-адрес перенаправления содержит токен доступа. Токен обновления не предоставляется.
  • После истечения срока действия токена доступа пользователю потребуется снова авторизовать приложение.

access_token Токен доступа, который ваше приложение должно использовать для вызова конечных точек от имени пользователя.
expires_in Время жизни токена доступа в секундах.
область Список областей, разделенных пробелами, авторизованных пользователем.
состояние
рекомендуется		 Предоставляет любое состояние, которое может быть полезно для вашего приложения, когда пользователь перенаправляется обратно к вашему приложению. Этот параметр будет добавлен к URI перенаправления точно так, как указывает ваше приложение. Fitbit настоятельно рекомендует включать в этот параметр токен защиты от подделки и подтверждать его значение в перенаправлении для предотвращения подделки межсайтовых запросов (CSRF).
token_type Поддерживается: Bearer
user_id Идентификатор пользователя Fitbit

Учетные данные клиента

Определенный RFC 6749, этот поток авторизации используется с определенными конечными точками API Fitbit, связанными с бизнес-операциями. Он не поддерживается общедоступными веб-API для получения пользовательских данных Fitbit. См. учетные данные клиента

Одностраничные приложения (также называемые браузерными приложениями) полностью запускаются в браузере после загрузки исходного кода JavaScript и HTML с веб-страницы. Поскольку браузеру доступен весь исходный код, они не могут сохранять конфиденциальность секрета клиента, поэтому для этих приложений секрет не используется. Поскольку они не могут использовать секрет клиента, лучшим вариантом является использование расширения PKCE для защиты кода авторизации в перенаправлении. Это похоже на решение для мобильных приложений, которые также не могут использовать секрет клиента.

Уведомление об устаревании

На диаграмме ниже показан пример, когда пользователь взаимодействует со своим браузером, который, в свою очередь, отправляет запросы API непосредственно в службу. После первой загрузки исходного кода Javascript и HTML с клиента браузер отправляет прямые запросы API к службе. В этом случае сервер приложения никогда не отправляет API-запросы к сервису, поскольку все обрабатывается непосредственно в браузере.

Браузер пользователя связывается напрямую с сервером API

Авторизация

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

Первым этапом веб-потока является запрос авторизации у пользователя. Это достигается путем создания ссылки запроса авторизации, по которой пользователь может щелкнуть.

URL-адрес авторизации обычно имеет следующий формат:

После того как пользователь посещает страницу авторизации, служба показывает пользователю объяснение запроса, включая имя приложения, область действия и т. д. Если пользователь нажимает "одобрить", сервер перенаправляет обратно на веб-сайт с авторизацией код и значение состояния в строке запроса URL.

Параметры предоставления авторизации

Для запроса авторизации используются следующие параметры.

тип_ответа

response_type имеет значение code, указывающее, что в качестве ответа вы хотите использовать код авторизации.

идентификатор_клиента

client_id — это идентификатор вашего приложения. Вы получите client_id при первой регистрации приложения в службе.

redirect_uri (необязательно)

Redirect_uri является необязательным в спецификации, но требуется для некоторых служб. Это URL-адрес, на который вы хотите перенаправить пользователя после завершения авторизации. Он должен соответствовать URL-адресу перенаправления, который вы ранее зарегистрировали в службе.

область действия (необязательно)

Включите одно или несколько значений области, чтобы запросить дополнительные уровни доступа. Значения будут зависеть от конкретной службы.

состояние (рекомендуется)

Параметр состояния выполняет две функции. Когда пользователь перенаправляется обратно в ваше приложение, любое значение, которое вы включаете в качестве состояния, также будет включено в перенаправление. Это дает вашему приложению возможность сохранять данные между пользователем, направляемым на сервер авторизации, и обратно, например, используя параметр состояния в качестве ключа сеанса. Это может быть использовано для указания того, какое действие в приложении выполнить после завершения авторизации, например, указать, на какую из страниц вашего приложения перенаправить после авторизации. Это также служит механизмом защиты от CSRF.

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

Пример схемы

В следующем пошаговом примере показано использование типа предоставления авторизации для одностраничных приложений.

Приложение инициирует запрос авторизации

Приложение инициирует поток, создавая URL-адрес, содержащий идентификатор, а также, при необходимости, область действия и состояние. Приложение может поместить это в тег.

Пользователь одобряет запрос

После перехода на сервер авторизации пользователь видит запрос на авторизацию.

Пример запроса авторизации

После того как пользователь попадет в службу и увидит запрос, он либо разрешит, либо отклонит запрос. Если они разрешат запрос, они будут перенаправлены обратно на URL-адрес перенаправления, указанный вместе с кодом авторизации в строке запроса. Затем приложению необходимо обменять этот код авторизации на токен доступа.

Если вы включите параметр «состояние» в исходный URL-адрес авторизации, служба вернет его вам после того, как пользователь авторизует ваше приложение. Ваше приложение должно сравнить состояние с состоянием, созданным в исходном запросе. Это помогает гарантировать, что вы обмениваетесь только запрошенными кодами авторизации, предотвращая перенаправление злоумышленников на ваш URL обратного вызова с произвольными или украденными кодами авторизации.

Обменять код авторизации на токен доступа

Чтобы обменять код авторизации на токен доступа, приложение отправляет запрос POST к конечной точке токена службы. Запрос будет иметь следующие параметры.

grant_type (обязательно)

Для параметра Grant_type должно быть установлено значение «authorization_code».

код (обязательно)

Этот параметр предназначен для кода авторизации, полученного от сервера авторизации, который будет указан в параметре строки запроса «code» в этом запросе.

redirect_uri (возможно, требуется)

Если URL-адрес перенаправления был включен в первоначальный запрос авторизации, он должен быть включен и в запрос токена и должен быть идентичным. Некоторые службы поддерживают регистрацию нескольких URL-адресов перенаправления, а некоторые требуют указания URL-адреса перенаправления в каждом запросе. Подробности смотрите в документации по сервису.

Идентификация клиента (обязательно)

Неявный поток

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

Неявный поток обходит этап обмена кодом, и вместо этого маркер доступа немедленно возвращается клиенту во фрагменте строки запроса.

На практике это необходимо лишь в очень ограниченном числе случаев. Несколько основных реализаций (Keycloak, Deutsche Telekom, Smart Health IT) решили полностью отказаться от неявного потока и вместо этого использовать поток кода авторизации.

Чтобы одностраничное приложение могло использовать поток кода авторизации, оно должно иметь возможность отправлять запрос POST на сервер авторизации. Это означает, что если сервер авторизации находится в другом домене, сервер должен будет поддерживать соответствующие заголовки CORS. Если поддержка заголовков CORS невозможна, вместо этого служба может использовать неявный поток.

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

Вопросы безопасности

Единственный способ обеспечить безопасность предоставления кода авторизации без секрета клиента – это использовать параметр "state" и ограничить URL-адрес перенаправления доверенными клиентами. Поскольку секрет не используется, нет другого способа проверить личность клиента, кроме как с помощью зарегистрированного URL-адреса перенаправления. Вот почему вам необходимо предварительно зарегистрировать URL-адрес перенаправления в службе OAuth 2.0.

Хотите без проблем внедрить OAuth 2.0?

Мы создали управление доступом к API как безопасную, масштабируемую и всегда активную услугу, чтобы вы могли быстрее выпускать более безопасный продукт.

Промежуточное ПО Dapr OAuth 2.0 позволяет включить авторизацию OAuth на конечных точках Dapr для ваших веб-API с помощью потока предоставления кода авторизации. Вы также можете внедрить токены авторизации в свои API-интерфейсы конечных точек, которые можно использовать для авторизации внешних API-интерфейсов, вызываемых вашими API-интерфейсами с помощью потока предоставления учетных данных клиента. Когда промежуточное программное обеспечение включено, любой вызов метода через Dapr должен быть авторизован, прежде чем он будет передан коду пользователя.

Основное различие между двумя потоками заключается в том, что поток предоставления кода авторизации требует взаимодействия с пользователем и авторизует пользователя, в то время как поток предоставления учетных данных клиента не требует взаимодействия с пользователем и авторизует службу/приложение.

Зарегистрируйте свое приложение на сервере авторизации

Разные серверы авторизации предоставляют разные возможности регистрации приложений. Вот несколько примеров:

Чтобы определить промежуточное ПО Dapr OAuth, вам необходимо собрать следующую информацию:

  • Идентификатор клиента (см. здесь)
  • Клиентский секрет (см. здесь)
  • Области действия (см. здесь)
  • URL-адрес авторизации
  • URL токена

URL-адреса авторизации/токена некоторых популярных серверов авторизации:

Определить определение компонента промежуточного программного обеспечения

Определить компонент предоставления кода авторизации

Промежуточное ПО OAuth (код авторизации) определяется компонентом:

Определить пользовательский конвейер для предоставления кода авторизации

Чтобы использовать ПО промежуточного слоя OAuth (код авторизации), необходимо создать собственный конвейер с использованием конфигурации Dapr, как показано в следующем примере:

Определить компонент предоставления учетных данных клиента

Промежуточное ПО OAuth (учетные данные клиента) определяется компонентом:

Определить пользовательский конвейер для предоставления учетных данных клиента

Чтобы использовать ПО промежуточного слоя OAuth (учетные данные клиента), необходимо создать собственный конвейер с использованием конфигурации Dapr, как показано в следующем примере:

Применить конфигурацию

Чтобы применить приведенную выше конфигурацию (независимо от типа гранта) к вашему дополнению Dapr, добавьте аннотацию dapr.io/config к спецификации вашего модуля:

Доступ к токену доступа

Предоставление кода авторизации

После того, как все будет готово, всякий раз, когда клиент попытается вызвать метод API через вспомогательную функцию Dapr (например, вызов конечной точки v1.0/invoke/), он будет перенаправлен на согласие авторизации. страницу, если токен доступа не найден. В противном случае токен доступа записывается в заголовок authHeaderName и становится доступным для кода приложения.

Предоставление учетных данных клиента

После того, как все будет готово, всякий раз, когда клиент попытается вызвать метод API через вспомогательную функцию Dapr (например, вызов конечной точки v1.0/invoke/), он получит новый токен доступа, если существующий действительный не найден. Маркер доступа записывается в заголовок headerName и становится доступным для кода приложения. Таким образом, приложение может пересылать токен в заголовке авторизации при вызовах внешнего API, запрашивающего этот токен.

Читайте также: