Вы находитесь здесь:
Процесс веб-сервера OAuth 2.0 для интеграции веб-приложения
Чтобы интегрировать внешнее веб- приложение в Salesforce API, используйте процесс веб- сервера OAuth 2.0, который внедряет тип предоставления кода авторизации OAuth 2.0. С помощью этого процесса сервер, размещающий веб-приложение, должен иметь возможность защитить удостоверение приложения внешнего клиента, определенное кодом клиента и секретом клиента.
Требуемые версии
| Доступно в версиях: Salesforce Classic (недоступно во всех организациях) и Lightning Experience. |
| Доступно в версиях: все версии |
Рекомендуем использовать поток веб-сервера с ключом подтверждения для кода для обмена (PKCE, произносится пикси) вместо потока пользователя-агента или потока имени пользователя и пароля для специальных сценариев. Используйте параметры code_challenge и code_verifier для внедрения PKCE в процесс веб- сервера. Дополнительную информацию о PKCE см. в разделе «Целевая группа по интернет-инженерии (IETF)» Рекомендуем также блокировать все приложения внешних клиентов от использования потока пользователя-агента или потока имени пользователя и пароля. Шаги см. в разделе Блокировка потоков проверки подлинности для повышения безопасности.
Ниже указан пример сценария использования для внедрения процесса веб-сервера. Недавно вы разработали веб-службу, предоставляющую безопасный доступ к статусу заказа клиента. Данные статуса заказа безопасно хранятся на платформе Salesforce CRM. Чтобы авторизовать пользователей службы поддержки для просмотра статуса заказа клиента, разработайте приложение «Статус заказа» и настройте его в качестве приложения внешнего клиента с потоком веб-сервера.
- Пользователь службы поддержки нажимает на веб-приложение «Статус заказа».
- Приложение внешнего клиента публикует запрос кода авторизации в конечной точке авторизации Salesforce.
- Пользователь перенаправляется на страницу входа Salesforce. После успешного входа пользователю предлагается утвердить доступ приложения к данным статуса заказа.
- После утверждения пользователем приложения «Статус заказа» для доступа к данным Salesforce отправляет обратный вызов в приложение «Статус заказа» с кодом авторизации.
- Приложение «Статус заказа» передает код авторизации в конечную точку маркера Salesforce, запрашивая маркер доступа.
- Salesforce проверяет код авторизации и отправляет обратно маркер доступа, содержащий связанные полномочия в виде областей.
- Приложение «Статус заказа» отправляет запрос обратно в Salesforce для доступа к данным статуса заказа. Запрос содержит маркер доступа со связанными областями.
- Salesforce проверяет маркер доступа и связанные области.
- Приложение «Статус заказа» имеет доступ к защищенным данным, и статус заказа клиента отображается в приложении.
Примечание Если маркер доступа становится недействительным, приложение внешнего клиента может использовать маркер обновления для получения нового маркера доступа.
Рассмотрим более подробно каждый этап процесса авторизации.
- Запрос кода авторизации
- Пользователь проверяет подлинность и авторизует доступ
- Salesforce предоставляет код авторизации
- Запрос на получение маркера доступа
- Salesforce предоставляет маркер доступа
Запрос кода авторизации
Чтобы запустить процесс веб-сервера OAuth 2.0, внешняя веб-служба отправляет запрос кода авторизации посредством типа предоставления кода авторизации в конечную точку авторизации Salesforce. С помощью кода авторизации приложение внешнего клиента может подтвердить, что оно авторизовано в качестве безопасного посетителя сайта и что у него есть полномочие на запрос маркера доступа.
Код авторизации выполнен в виде переадресации HTTP.
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=codeДобавьте следующие параметры в запрос кода авторизации.
| Параметр | Описание |
|---|---|
Request Header
|
Конечная точка авторизации Salesforce OAuth 2.0. Внешние клиентские приложения отправляют запросы авторизации OAuth в эту конечную точку. |
client_id
|
Ключ пользователя приложения внешнего клиента. Чтобы получить доступ к ключу пользователя, найдите приложение внешнего клиента в менеджере приложений и выберите «Просмотр» в раскрывающемся списке. Потом нажмите «Управление сведениями о клиенте». Иногда требуется проверить подлинность перед просмотром ключа пользователя. |
redirect_uri
|
URL-адрес, куда пользователи перенаправляются после успешной проверки подлинности. URI-адрес переадресации должен соответствовать одному из значений в поле URL-адреса обратного вызова приложения внешнего клиента. В противном случае утверждение не выполняется. URI-адрес переадресации можно найти на странице параметров OAuth приложения внешнего клиента. Это значение должно быть зашифровано как URL-адрес. |
response_type
|
Тип предоставления OAuth 2.0, запрашиваемый приложением внешнего клиента. Значением для этого потока должно быть code, чтобы указать, что приложение внешнего клиента запрашивает код авторизации. |
Можно также добавить следующие параметры в запрос кода авторизации.
| Параметр | Описание |
|---|---|
scope
|
Полномочия, определяющие тип защищенных ресурсов, доступных приложению внешнего клиента. Вы назначаете области внешнему клиентскому приложению при его создании, и они добавляются в маркеры OAuth во время процесса авторизации. Если вы не добавите этот параметр, будут запрошены все области, назначенные приложению внешнего клиента. Области, переданные в этом параметре, должны быть поднабором зарегистрированных областей. Действительные параметры см. в разделе «Области и маркеры OAuth». |
sso_provider
|
Имя разработчика поставщика удостоверений единой регистрации (SSO), настроенное посредством URL-адреса входа в «Мой домен» или URL-адреса сайта Experience Cloud. Этот параметр можно использовать для создания взаимодействия единой регистрации, которое кажется, что ваше приложение интегрировано с поставщиком единой регистрации. Например, можно использовать этот параметр для предложения единого входа в реализации Headless Identity. Дополнительные сведения см. в разделе Создание нативной версии единой регистрации в приложении. |
state
|
Любое состояние, запрашиваемое внешней веб-службой для отправки на URL-адрес обратного вызова. Это значение должно быть зашифровано как URL-адрес. |
immediate
|
Логическое значение для определения запроса входа и утверждения пользователя. Значение по умолчанию:
Параметр |
code_challenge
|
Указывает хэш-значение SHA256 значения Этот параметр обязателен, если в запросе маркера указан
|
display
|
Изменение типа отображения страниц входа и авторизации. Salesforce поддерживает следующие значения.
|
login_hint
|
Данное поле содержит допустимое значение имени пользователя для предварительного заполнения страницы входа именем пользователя (например, Чтобы передать параметр |
nonce
|
Используйте область openid для запроса маркера кода пользователя. Маркер кода пользователя возвращается в ответе. Этот параметр необязателен, но помогает обнаружить атаки повтора.
|
prompt
|
Указывает, как сервер авторизации напоминает пользователю о необходимости повторной проверки подлинности и повторного утверждения. Salesforce поддерживает следующие значения.
Вы можете передать значения |
Заголовок Uvid-Hint |
По желанию, чтобы подключить этот поток к гостевому потоку без заголовка, можно добавить заголовок Если вы внедряете поток пользователя-гостя в приложение, вы можете по желанию использовать этот заголовок для передачи в маркер доступа на основе веб-маркера JSON (JWT), содержащий уникальный код посетителя (UVID), привязанный к удостоверению пользователя-гостя. Передавая UVID-файл в поток именованного пользователя, можно перенести контекстную информацию из сеанса пользователя-гостя, например, параметры cookie-файлов пользователя, в сеанс именованного пользователя. |
Параметр текста uvid_hint |
Обычное значение Вместо передачи UVID в тексте запроса можно также передать его в маркере на основе JWT с UVID посредством заголовка |
Пользователь проверяет подлинность и авторизует доступ
Прежде чем Salesforce предоставит коды авторизации внешним клиентским приложениям, проверяющим подлинность пользователям будет предложено войти в Salesforce.
После успешного входа Salesforce перенаправляет пользователей на страницу утверждения для предоставления доступа к приложению.
Если пользователи предварительно одобрили доступ, повторно утверждать доступ не нужно.
Salesforce предоставляет код авторизации
После утверждения доступа пользователей к приложению внешнего клиента Salesforce перенаправляет пользователей на URL-адрес обратного вызова, где они могут просмотреть обратный вызов с кодом авторизации.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- Первая часть обратного вызова - это URL-адрес обратного вызова приложения внешнего клиента:
https://www.mycustomerorderstatus.com/oauth2/callback. - Вторая часть - это код авторизации, используемый приложением внешнего клиента для получения маркера доступа:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==. Срок действия кода авторизации истекает через 15 минут.
Если параметр state включен в исходную строку запроса, указанное состояние передается на этап утверждения.
Запрос маркера доступа
Чтобы запросить маркер доступа, приложение внешнего клиента передает код авторизации в конечную точку маркера Salesforce в качестве HTTP POST.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
POST в примере содержит следующие параметры.
| Параметр | Описание |
|---|---|
Request Header
|
Заголовок запроса может содержать следующие параметры.
Заголовок запроса также поддерживает следующие параметры.
Параметр |
grant_type
|
Тип проверки, которую может предоставить приложение внешнего клиента для подтверждения безопасности посетителя. Для процесса веб-сервера значение должно быть authorization_code. |
code
|
Временный код авторизации, полученный от сервера авторизации. Приложение внешнего клиента использует этот код в обмен на маркер доступа. Данный тип процесса OAuth 2.0 является безопасным способом передачи маркера доступа обратно в приложение. |
client_id
|
Ключ пользователя приложения внешнего клиента. Чтобы получить доступ к ключу пользователя, найдите приложение внешнего клиента в менеджере приложений и выберите «Просмотр» в раскрывающемся списке. Потом нажмите «Управление сведениями о клиенте». Иногда требуется проверить подлинность пользователя перед просмотром ключа пользователя. |
client_secret
|
Секрет пользователя приложения внешнего клиента. Чтобы открыть секрет пользователя, найдите приложение внешнего клиента в менеджере приложений и выберите «Просмотр» в раскрывающемся списке. Потом нажмите «Управление сведениями о клиенте». Иногда требуется проверить подлинность пользователя перед просмотром секрета пользователя. Этот параметр обязателен, если в приложении внешнего клиента не включен параметр «Требовать секрет для процесса веб-сервера». Если |
redirect_uri
|
URL-адрес, куда пользователи перенаправляются после успешной проверки подлинности. URI-адрес переадресации должен соответствовать одному из значений в поле URL-адреса обратного вызова приложения внешнего клиента. В противном случае утверждение не выполняется. URI-адрес переадресации можно найти на странице параметров OAuth приложения внешнего клиента или в определении приложения внешнего клиента. Это значение должно быть зашифровано как URL-адрес. |
Можно также добавить следующие параметры.
| Параметр | Описание |
|---|---|
client_assertion
|
Вместо передачи client_secret можно предоставить client_assertion и client_assertion_type. Если параметр client_secret не предоставлен, Salesforce проверяет client_assertion и client_assertion_type. См. Использование client_assertion вместо client_secret. |
client_assertion_type
|
Введите это значение при использовании параметра Значением |
code_verifier
|
Обязательно только при наличии параметра code_challenge в запросе на авторизацию. Указывает 128 байтов случайных данных с высокой энтропией, чтобы затруднить угадывание значения
|
format
|
При отсутствии в заголовке запроса можно указать ожидаемый формат возврата. Параметр
|
client_assertion вместо client_secret.Если вы предоставляете client_assertion вместо client_secret, значение client_assertion должно содержать следующие параметры.
iss—client_idиз определения приложения внешнего клиента.sub—client_idиз определения приложения внешнего клиента.aud—URL-адрес сервлета маркера: https://hostname/services/oauth2/token.expВремя истечения срока действия утверждения в течение 5 минут, выраженное в виде количества секунд с 1970-01-01T0:0:0Z, измеренного в UTC.
client_assertion также должен быть подписан секретным ключом, связанным с загруженным сертификатом пользователя OAuth. Поддерживается только алгоритм RS256. Метод проверки подлинности клиента private_key_jwt см. в спецификациях OpenID Connect.
Вместо отправки регистрационных данных клиента в качестве параметров в теле POST, Salesforce поддерживает базовую схему проверки подлинности HTTP. Формат этой схемы требует следующего client_id и client_secret в заголовке авторизации сообщения:
Authorization: Basic64Encode(client_id:secret)
client_id и client_secret разделяются двоеточием (:). Дополнительную информацию см. в документе «Инфраструктура авторизации OAuth 2.0».
Данный пример отображает запрос POST маркера доступа, использующий базовую схему проверки подлинности HTTP, а не отправку регистрационных данных клиента в теле запроса POST.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id и client_secret отправлены в теле POST, заголовок авторизации игнорируется.Salesforce предоставляет маркер доступа
После проверки регистрационных данных приложения внешнего клиента Salesforce возвращает ответ с маркером доступа. В данном примере ответ используется в формате JSON.
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
Ответ содержит следующие параметры.
| Параметр | Описание |
|---|---|
access_token
|
Маркер OAuth, используемый внешним клиентским приложением для запроса доступа к защищенному ресурсу от имени клиентского приложения. Маркер доступа может сопровождаться дополнительными полномочиями в виде областей. |
signature
|
Подпись HMAC-SHA256, зашифрованная в Base64, подписанная client_secret. Подпись может содержать конкатенированный код и issued_at value, которые можно использовать для проверки того, что URL-адрес удостоверения не изменился с момента отправки сервером. |
scope
|
Области, связанные с маркером доступа. Области дополнительно определяют тип защищенных ресурсов, доступных клиенту. Вы назначаете области внешнему клиентскому приложению при его создании, и они добавляются в маркеры OAuth во время процесса авторизации. Действительные параметры см. в разделе «Области и маркеры OAuth». |
id_token
|
Подписанная структура данных, содержащая проверенные атрибуты пользователя, включая уникальный идентификатор пользователя и отметку времени, указывающую время выпуска маркера. Он также определяет запрашивающее клиентское приложение. См. Спецификации OpenID Connect. Этот параметр возвращается, если параметр области содержит |
instance_url
|
URL-адрес экземпляра организации пользователя. Например: https://yourInstance.salesforce.com/.
|
id
|
URL-адрес удостоверения, который может использоваться для идентификации пользователя и запроса дополнительных сведений о нем. См. URL-адреса удостоверения. |
token_type
|
Тип Bearer маркера, используемый для всех ответов, содержащих маркер доступа.
|
issued_at
|
Отметка времени создания подписи в миллисекундах. |
Ответ также может содержать следующие параметры.
