Настройка потока обмена маркерами

Конечный пользователь запрашивает доступ к данным Salesforce (1)

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

Приложение содержит действительный маркер (2)

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

• Маркеры доступа
• Маркеры обновления
• Веб-маркеры JSON (JWT)
• Утверждения SAML
• Маркеры кода

Приложение запрашивает обмен на маркер Salesforce (3)

Чтобы получить маркер Salesforce, приложение отправляет запрос POST в конечную точку /services/oauth2/token в URL-адресе входа в «Мой домен» или URL-адресе сайта Experience Cloud.

Важно! При разработке интеграций OAuth всегда передавайте конфиденциальные сведения в текст запроса POST или в заголовок запроса. Не используйте параметры GET в строке URL-запроса для передачи конфиденциальной информации. Конфиденциальная информация содержит имена пользователей, пароли, маркеры OAuth, секреты клиентов и любую персональную информацию, но не ограничивается ими. Дополнительные сведения о рекомендациях по безопасности см. в разделе «Хранение конфиденциальных данных» в Руководстве по безопасному кодированию.

Запрос поддерживает один заголовок.

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

Ниже указан пример запроса маркера, содержащего маркер доступа.

POST /services/oauth2/token? HTTP 1.1
Host: MyDomainName.my.site.com
Uvid-Hint: UVID abcd-1234-efgh

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=*************&
subject_token_type=urn:ietf:params:oauth:token-type:access_token&
client_id=***********&
client_secret=************&
scope=web&
token_handler=MyTokenHandler

Salesforce OAuth Runtime завершил первичную проверку (4)

Среда выполнения OAuth Salesforce получает запрос и запускает его посредством первичной проверки. Проверка основана на следующих требованиях.

• Связанное приложение или приложение внешнего клиента должно быть включено для потока обмена маркерами. См. Интеграция приложения для потока обмена маркерами.
• subject_token_type в запросе должна быть включена для средства обработки обмена маркерами. Чтобы включить средство обработки для типа маркера, задайте соответствующее поле в определении метаданных OauthTokenExchangeHandler средства обработки на true.

  Значение subject_token_type	OauthTokenExchangeHandler Field
  urn:ietf:params:oauth:token-type:access_token	isAccessTokenSupported
  urn:ietf:params:oauth:token-type:refresh_token	isRefreshTokenSupported
  urn:ietf:params:oauth:token-type:id_token	isIdTokenSupported
  urn:ietf:params:oauth:token-type:saml2	isSaml2Supported
  urn:ietf:params:oauth:token-type:jwt	isJwtSupported

• Если запрос содержит client_secret, он должен соответствовать секрету пользователя связанного приложения или приложения внешнего клиента.
• Если запрос содержит token_handler, организация должна иметь поддерживаемое средство обмена маркерами Apex, соответствующее имени в запросе.
• Обработчик обмена маркерами должен быть включен, то есть поле isEnabled в определении метаданных OauthTokenExchangeHandler должно быть установлено на true.

Если запрос соответствует этим первичным требованиям, Salesforce отправляет маркер от внешнего поставщика удостоверений в средство обмена маркерами Apex.

Обработчик Apex проверяет маркер (5)

Обработчик Apex получает маркер поставщика удостоверений и проверяет его с помощью настраиваемой логики проверки. Способ проверки маркера зависит только от вас.

(Дополнительно) Обработчик Apex вызывает поставщика удостоверений для проверки (6)

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

Обработчик Apex соотносит маркер с субъектом Salesforce (7)

Обработчик Apex определяет субъект маркера, являющийся конечным пользователем, которому он был выдан, и соотносит его с субъектом Salesforce.

(Дополнительно) Обработчик Apex вызывает поставщика удостоверений для получения сведений о пользователе (8)

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

Обработчик Apex находит или настраивает пользователя (9)

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

Если поле isUserCreationAllowed установлено на true в определении метаданных OauthTokenExchangeHandler средства обработки, то средство обработки настраивает новый объект User и возвращает его в Salesforce. Это действие фактически не создает пользователя - вместо этого объект User возвращается в Salesforce для автоматической вставки.

Дополнительные сведения о настройке средства обработки для проверки маркеров и соотнесения тем см. в разделе «Проверка средства обработки обмена маркерами и соотнесение тем» в Руководстве разработчика Apex.

Среда выполнения Salesforce OAuth завершила соотнесение пользователей (10)

Среда выполнения Salesforce OAuth проверяет, вернуло ли средство обработки пользователя. Если да, он подтверждает наличие пользователя и завершает соотнесение. Если пользователь не существует и средство обработки настроено на настройку пользователей, Salesforce автоматически вставляет пользователя от имени средства обработки обмена маркерами.

Ответ маркера возврата среды выполнения Salesforce OAuth (11)

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

Если вы передали UVID в запросе маркера, он также передается в потоке. Для ответа на непрозрачный маркер UVID отображается в конечной точке services/oauth2/userinfo в URL-адресе входа в «Мой домен» или URL-адресе сайта Experience Cloud. В ответе на маркер на основе JWT UVID чеканится в новом маркере доступа.

Приложение получает ответ (12)

Ваше приложение получает ответ маркера, включительно с маркером доступа и другими маркерами и параметрами. Ниже указан пример ответа на маркер.

{
    "access_token":"*******************",
    "signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
    "scope":"openid api",
    "id_token":"XXXXXX",
    "instance_url":"https://MyDomainName.my.salesforce.com",
    "id":"https://MyDomainName.my.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
    "token_type":"Bearer",
    "issued_at":"1667600739962"
}

Конечная точка сведений о пользователе вызовов приложения (13)

При необходимости для завершения входа пользователя приложение может вызвать конечную точку /services/oauth2/userinfo в URL-адресе входа «Моего домена» или URL-адресе сайта Experience Cloud. Например, если вы передали UVID в запросе на маркер, а Salesforce вернул ответ с непрозрачным маркером доступа, позвоните в конечную точку сведений о пользователе для получения UVID.

Приложение запрашивает доступ к данным Salesforce (14)

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

Конечный пользователь открывает данные Salesforce (15)

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