Headless Identity API: Код авторизации и поток регистрационных данных для общедоступных клиентов

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

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
}

// Gets User Info
function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

//Starts the Login Process
function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
  
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
  
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           doCodeExchange(response);
       }
   }
   return false;
}    

Другой ключевой компонент - серверное средство обработки обратного вызова, которое извлекает код из переадресации 302 и возвращает его в приложение. В данном примере обработчиком является класс Apex, открытый как общедоступная конечная точка REST, и включен общий доступ к ресурсам с запросом происхождения (CORS), чтобы предложить защиту межсайтового скриптинга. Чтобы упростить разработку, используйте конечную точку эха OAuth 2.0 для получения кода авторизации.

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
   // Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

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

Пользователь открывает стороннее приложение для входа. В приложении форма входа отображает поля имени пользователя и пароля и кнопку входа. Salesforce не предоставляет эту форму входа. Это зависит от тебя. Пользователь вводит имя пользователя и пароль и нажимает кнопку входа.

Стороннее приложение создает значения code_verifier и code_challenge (дополнительно)

Если вы используете расширение «Ключ подтверждения для обмена кодами (PKCE)», приложение создает значения, используемые для проверки кода авторизации.

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

Спецификация PKCE, определенная в RFC 7636, также содержит дополнительный параметр code_challenge_method, который можно отправить в запрос авторизации. Salesforce игнорирует любое значение, отправленное в этом параметре, и по умолчанию использует значение SHA256.

Стороннее приложение отправляет запрос кода авторизации без заголовка

В обозревателе настраиваемое приложение отправляет запрос кода авторизации без заголовка в конечную точку авторизации Salesforce Headless Login API посредством JavaScript. Если вы не используете обнаружение пользователя без заголовка, используйте метод GET или POST для этого запроса. При использовании функции обнаружения пользователей без заголовка поддерживаются только запросы POST.

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}    

Для запросов GET и POST необходимо добавить Auth-Request-Type: Named-User заголовка.

GET /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: Named-User
Authorization: Basic <encoded username:password>

response_type=code_credentials&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/apexrest/code/extraction&
client_id=******&
code_challenge=Y29kZ*******

Если вы используете запрос POST, вы можете добавить зашифрованные в Base64 регистрационные данные пользователя в заголовок авторизации или разместить их в тексте запроса.

Если вы используете обнаружение пользователя без заголовка, вы не отправляете имя пользователя и пароль. Вместо этого вы отправляете идентификатор в параметре login_hint, дополнительные настраиваемые данные и пароль. Добавьте идентификатор, настраиваемые данные и пароль в текст запроса POST. Не используйте запрос GET.

По желанию, чтобы подключить этот поток к гостевому потоку без заголовка, можно добавить заголовок Uvid-Hint с маркером доступа на основе JWT, содержащим значение UVID, являющееся универсальным уникальным идентификатором версии 4, созданным и управляемым полностью приложением. Чтобы получить маркер доступа с UVID, необходимо включить приложение внешнего клиента или связанное приложение для выпуска маркеров доступа на основе JWT и внедрения потока без заголовка гостя в вашем приложении.

Если вы внедряете поток пользователя-гостя в приложение, вы можете по желанию использовать этот заголовок для передачи в маркер доступа на основе веб-маркера JSON (JWT), содержащий уникальный код посетителя (UVID), привязанный к удостоверению пользователя-гостя. Передавая UVID-файл в поток именованного пользователя, можно перенести контекстную информацию из сеанса пользователя-гостя, например, параметры cookie-файлов пользователя, в сеанс именованного пользователя.

Можно также добавить обычное значение UVID в текст запроса.

Примечание При наличии параметра «Требовать регистрационные данные пользователя в тексте POST для кода авторизации и регистрационных данных» в приложении внешнего клиента или связанном приложении, вы можете отправить регистрационные данные пользователя только в тексте запроса. Если этот параметр включен, вы не сможете использовать метод GET для запроса кода авторизации. Можно использовать только метод POST.

В методах GET и POST добавьте следующие обязательные параметры в текст запроса на авторизацию.

Можно также добавить следующие дополнительные параметры в запрос авторизации.

(Дополнительно) Обработчик обнаружения без заголовка пользователя находит пользователя

Если вы используете средство обработки обнаружения пользователей без заголовка, средство обработки извлекает параметры login_hint и customdata и находит связанного пользователя. Обработчик подтверждает, что электронный адрес или номер телефона пользователя проверен.

Пример средства обработки см. в разделе Auth.HeadlessUserDiscoveryHandler.

Salesforce проверяет регистрационные данные и возвращает 302-переадресацию на серверное средство обработки обратного вызова

Salesforce Headless Login API получает запрос авторизации. Он проверяет регистрационные данные пользователя и возвращает переадресацию HTTP 302 на готовый URL-адрес, содержащий код авторизации. Salesforce потом автоматически отправляет ответ переадресации на URL-адрес переадресации, который указывает на серверное средство обработки обратного вызова в конечной точке /code/extraction в данном примере. Во время этого процесса обозреватель не перенаправляется - все происходит фоном.

Серверное средство обработки обратного вызова извлекает код и возвращает его приложению

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
The response wrapper sets the variables for the code response, including success and error indicators.
// Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

<?
header('Access-Control-Allow-Headers: *');
header('Access-Control-Allow-Origin: *');
header('Content-Type: application/json; charset=utf-8');
$out = [];
foreach ($_GET as $name => $value) {
   $out[$name] = $value;
}
echo json_encode($out);
?>

После извлечения кода средство обработки обратного вызова отправляет его обратно в обозреватель.

Приложение получает ответ кода и выполняет обмен кодом

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","sfdc_community_url":"https://MyExperienceCloudSite.my.site.com/vforcesite","sfdc_community_id":"0DBxxxxxxxxxxxx","errMsg":null,"code":"aPrxC1*******"}

Обозреватель без заголовка запрашивает обмен кода на маркер доступа. В примере клиентского JavaScript функция doCodeExchange отправляет код в запросе POST в конечную точку маркера Experience Cloud.

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
} 

Для запроса маркера доступа можно использовать только запрос POST — запросы GET не поддерживаются. Необходимо добавить заголовок Content-Type. Добавьте следующие обязательные параметры в текст запроса.

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

Salesforce предоставляет маркер доступа

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

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

Ответ маркера доступа может также содержать следующие параметры.

Приложение обрабатывает ответ маркера и создает сеанс пользователя

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

Примечание Убедитесь в выполнении полной проверки безопасности хранилища маркеров доступа. Не сохраняйте маркер доступа в локальном хранилище обозревателя и избегайте его сохранения в cookie-файле, если возможно.

// Gets User Info
function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

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

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

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

Приложение выполняет проверенный вызов конечной точки Salesforce

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

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

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