Вы находитесь здесь:
Процесс авторизации веб-сервера OAuth 2.0 для интеграции веб-приложения
Чтобы интегрировать внешнее веб-приложение посредством Salesforce API, используйте процесс авторизации веб-сервера OAuth 2.0, который внедряет тип предоставления «код авторизации» OAuth 2.0. Посредством этого процесса сервер, размещающий веб-приложение, должен иметь возможность защитить сертификат связанного приложения, определенный кодом клиента и секретом клиента.
Требуемые версии
| Доступно в версиях: Salesforce Classic (недоступно во всех организациях) и Lightning Experience. |
| Доступно в версиях: все версии |
Дополнительную информацию см. в разделе «Новые связанные приложения больше не могут быть созданы в выпуске Spring ‘26».
Рекомендуем использовать поток веб-сервера с «Ключ подтверждения для кода для обмена» (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
|
Конечная точка авторизации OAuth 2.0 Salesforce. Связанные приложения отправляют запросы авторизации OAuth в эту конечную точку. |
client_id
|
Ключ пользователя связанного приложения. Для доступа к ключу пользователя найдите связанное приложение в менеджере приложений и выберите «Просмотр» в раскрывающемся списке. Потом нажмите «Управление сведениями о клиенте». Иногда требуется проверить подлинность пользователя перед просмотром ключа клиента. |
redirect_uri
|
URL-адрес перенаправления пользователей после успешной проверки подлинности. URL-адрес перенаправления должен совпадать с одним из значений в поле URL-адреса обратного вызова связанного приложения. В противном случае утверждение не выполняется. URL-адрес перенаправления находится на странице управления связанными приложениям связанного приложения или в определении связанного приложения. Данное значение должно быть закодировано в URL-адресе; |
response_type
|
Тип предоставления OAuth 2.0, запрашиваемый связанным приложением. Значение этого потока должно быть code, чтобы указать, что связанное приложение запрашивает код авторизации. |
Вы можете также добавить в запрос кода авторизации следующие параметры.
| Параметр | Описание |
|---|---|
scope
|
Полномочия, определяющие тип защищенных ресурсов, которые может открыть связанное приложение. Вы назначаете области связанному приложению при его создании, они добавляются в маркеры 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-адрес перенаправления пользователей после успешной проверки подлинности. URL-адрес перенаправления должен совпадать с одним из значений в поле URL-адреса обратного вызова связанного приложения. В противном случае утверждение не выполняется. URL-адрес перенаправления находится на странице управления связанными приложениям связанного приложения или в определении связанного приложения. Данное значение должно быть закодировано в URL-адресе; |
Можно также включить следующие параметры.
| Параметр | Описание |
|---|---|
client_assertion
|
Вместо передачи client_secret можно предоставить client_assertion и client_assertion_type. Если параметр client_secret не предоставлен, Salesforce проверяет client_assertion и client_assertion_type.
|
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 во время процесса авторизации. |
id_token
|
Подписанная структура данных, содержащая атрибуты проверенных пользователей, включая уникальный идентификатор этого пользователя и отметку времени выпуска маркера. Он также определяет запрашивающее клиентское приложение. См. Спецификации OpenID Connect. Этот параметр возвращается, если параметр области содержит |
instance_url
|
URL-адрес, определяющий экземпляр организации пользователя. Например: https://yourInstance.salesforce.com/.
|
id
|
URL-адрес удостоверения, используемый для идентификации пользователя и отправки запросов на получение дополнительной информации об этом пользователе. См. раздел «URL-адреса удостоверений». |
token_type
|
Тип Bearer маркера, используемый для всех ответов, содержащих маркер доступа.
|
issued_at
|
Отметка времени создания подписи в миллисекундах. |
Ответ также может содержать данные параметры.
