Sidhuvudlösa identitets-API:n: Auktoriseringskod och inloggningsuppgifter för offentliga klienter

En nyckelkomponent i detta flöde är JavaScript på klientsidan som skickar auktoriseringsbegäran, utför kodutbytet och bearbetar åtkomsttoken. Här är ett JavaScript-exempel som använder en ansluten app.

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;
}    

En annan nyckelkomponent är callbackhanteraren på serversidan som extraherar koden från 302-omdirigeringen och returnerar den till appen. I detta exempel är hanteraren en Apex klass som visas som en offentlig REST-slutpunkt och har Cross Origin Resource Sharing (CORS) aktiverat för att erbjuda skydd för skript för flera webbplatser. För att förenkla utveckling, använd OAuth 2.0-ekoslutpunkten för att hämta auktoriseringskoden.

@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;
       }       
   }
}

Slutanvändare öppnar tredjepartsappar och loggar in

Din användare öppnar din tredjepartsapp för att logga in. I din app visas ditt inloggningsformulär med fält för användarnamn och lösenord och en inloggningsknapp. Salesforce tillhandahåller inte detta inloggningsformulär. Dess utseende och känsla är upp till dig. Din användare anger sitt användarnamn och lösenord och klickar på inloggningsknappen.

Tredjepartsapp skapar code_verifier och code_challenge (valfritt)

Om du använder tillägget Proof Key for Code Exchange (PKCE) skapar appen värden som används för att verifiera auktoriseringskoden.

Ditt flöde inkluderar endast detta steg om du använder tillägget Proof Key for Code Exchange (PKCE). Som en rekommenderad metod för säkerhet rekommenderar vi starkt att använda tillägget PKCE när du implementerar auktoriseringskoden och inloggningsuppgifter, särskilt för appar med en sida. Mer information om PKCE finns i specifikationenRFC 7636: Proof Key for Code Exchange by OAuth Public Clients som tillhandahålls av Internet Engineering Task Force (IETF).

PKCE-specifikationen som definieras i RFC 7636 innehåller även en valfri code_challenge_method som du kan skicka i auktoriseringsbegäran. Salesforce ignorerar alla värden som du skickar i denna parameter och blir som standard SHA256.

Tredjepartsapp begär sidhuvudlöst en auktoriseringskod

Från webbläsaren skickar din egna app—via JavaScript—en begäran om sidhuvudlös auktorisering till Salesforces slutpunkt för auktorisering av Salesforce Headless Login API. Om du inte använder sidhuvudlös användarupptäckt, använd antingen GET- eller POST-metoden för denna begäran. Om du använder sidhuvudlös användarupptäckt stöds endast POST-begäranden.

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;
}    

För både GET- och POST-begäranden måste du inkludera sidhuvudets 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*******

Om du använder en POST-begäran kan du inkludera Base64-kodade användaruppgifter i ett auktoriseringssidhuvud, eller så kan du placera dem i begärans brödtext.

Om du använder sidhuvudlös användarupptäckt skickar du inte användarnamn och lösenord. Istället skickar du en identifierare i login_hint, valfria egna data och ett lösenord. Inkludera identifierare, egna data och lösenord i brödtexten i en POST-begäran. Använd inte en GET-begäran.

Om du vill ansluta detta flöde till det sidhuvudlösa gästflödet kan du inkludera ett Uvid-Hint med en JWT-baserad åtkomsttoken som innehåller ett UVID-värde, vilket är en universellt unik identifierare (UUID) av version 4 som skapas och hanteras helt av din app. För att få en åtkomsttoken med en UVID måste du aktivera din externa klientapp eller anslutna app för att utfärda JWT-baserade åtkomsttokens och implementera det sidhuvudlösa gästflödet i din app.

Om du implementerar gästanvändarflödet i din app kan du om du vill använda detta sidhuvud för att skicka in en JSON Web Token-baserad åtkomsttoken (JWT) som innehåller ett unikt besökar-ID (UVID) knutet till en gästanvändares identitet. Genom att skicka UVID till ett namngivet användarflöde kan du överföra sammanhangsinformation från en gästanvändarsession, som användarens cookie-inställningar, till en namngiven användarsession.

Du kan även inkludera det vanliga UVID-värdet i begärans brödtext.

Anteckning Om du har inställningen Kräv användaruppgifter i POST-brödtexten för auktoriseringskod och inloggningsuppgifter-flöde aktiverad i din externa klientapp eller anslutna app kan du endast skicka användaruppgifterna i begärans brödtext. Med denna inställning aktiverad kan du inte använda GET-metoden för begäran om en auktoriseringskod. Du kan endast använda POST-metoden.

För både GET- och POST-metoder, inkludera dessa begärda parametrar i brödtexten i auktoriseringsbegäran.

Du kan även inkludera dessa valfria parametrar i auktoriseringsbegäran.

(Valfritt) Sidhuvudlös användare Discovery-hanterare hittar användaren

Om du använder en upptäckare utan sidhuvud tar hanteraren parametrarna login_hint och customdata och hittar den associerade användaren. Hanteraren bekräftar att e-postadressen eller telefonnumret till användaren har verifierats.

För ett exempel på en hanterare, se Auth.HeadlessUserDiscoveryHandler.

Salesforce validerar inloggningsuppgifter och returnerar en 302-omdirigering till callbackhanterare på serversidan

Salesforce Headless Login API tar emot auktoriseringsbegäran. Den validerar användaruppgifterna och returnerar en HTTP 302-omdirigering till en förkonfigurerad URL som innehåller auktoriseringskoden. Salesforce skickar sedan automatiskt omdirigeringssvaret till omdirigerings-URL:en, som pekar till callbackhanteraren på serversidan vid /code/extraction slutpunkt i detta exempel. Under denna process omdirigeras inte webbläsaren—allt händer bakom kulisserna.

Callbackhanterare på serversidan extraherar kod och returnerar den till appen

@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);
?>

Efter att koden har extraherats skickar callbackhanteraren tillbaka den till webbläsaren.

Appen får kodsvar och utför kodutbyte

{"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*******"}

Webbläsaren begär sidhuvudlöst att byta ut koden mot en åtkomsttoken. I JavaScript-exemplet på klientsidan skickar doCodeExchange koden i en POST-begäran till Experience Cloud-tokenslutpunkten.

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)
       }
   }
} 

För åtkomsttokenbegäran kan du endast använda en POST-begäran—GET-begäranden stöds inte. Du måste inkludera ett Content-Type. Inkludera dessa begärda parametrar i begärans brödtext.

Du kan även inkludera dessa valfria parametrar i tokenbegäran.

Salesforce beviljar en åtkomsttoken

{
"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"
}

Åtkomsttokensvaret innehåller dessa parametrar.

Åtkomsttokensvaret kan även inkludera dessa parametrar.

Appen bearbetar tokensvar och skapar användarsessionen

Webbläsaren lagrar informationen från tokensvaret och skapar användarsessionen. Vid denna tidpunkt är användaren inloggad och JavaScript på klientsidan anropar Salesforces slutpunkt för användarinfo för att bekräfta att inloggningen lyckades, enligt detta utdrag.

Anteckning Se till att du slutför en fullständig säkerhetsgranskning av din åtkomsttokenlagring. Lagra aldrig åtkomsttoken i webbläsarens lokala lagring och undvik att lagra den i en cookie om möjligt.

// 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";
       }
   }
}

Slutanvändare är inloggad och utför en åtgärd i appen

Din användare är nu inloggad. De utför en åtgärd i din app som kräver åtkomst till Salesforce-data. Till exempel klickar de på en knapp för att se sin historik för besöksbokning, som lagras i Salesforce.

Anteckning När du konfigurerar din externa klientapp eller anslutna app för flödet Auktoriseringskod och Inloggningsuppgifter ställer du in policyn Tillåtna användare till Administratörsgodkända användare är auktoriserade i förväg och konfigurerar vilka profiler eller behörighetsuppsättningar som kan komma åt appen. Med denna policy får användare åtkomst till appen utan att auktorisera den, så de får inte ett auktoriseringsfönster som ber dem låta appen komma åt deras data.

App gör ett inloggad samtal till en Salesforce-slutpunkt

För att komma åt användarens Salesforce-data använder din app åtkomsttoken för att göra ett autentiserat anrop till en skyddad Salesforce-slutpunkt, till exempel en Salesforce API.

Slutanvändare har åtkomst till Salesforce-data

Användaren kan nu komma åt skyddade Salesforce-data i din app. De kan till exempel se sin historik för besöksbokning. Från slutanvändarens perspektiv, inträffar hela processen från att logga in till att komma åt deras data utan att behöva att de någonsin behöver lämna appen.