Headless Identity-API's: Stroom Autorisatiecode- en inloggegevens voor privéclients

Een belangrijke component van deze stroom is de JavaScript-code aan de clientzijde die autorisatie aanvraagt en de respons met het toegangstoken ontvangt. In dit voorbeeld wordt een verbonden app gebruikt.

var clientId = '<Connected App Client ID>';
var baseURL = '<Experience Cloud Domain>';
var redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';

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

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

Een andere belangrijke component is de callback-handler aan de serverzijde, die de code extraheert en deze uitwisselt voor een toegangstoken. Dit is een voorbeeld van een callback-handler die een Apex-klasse gebruikt die zichtbaar is als een REST-resource.

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
  
   global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = null;
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }
  
   // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

Hier volgt een gedetailleerde analyse van deze stroom.

Eindgebruiker opent externe app en logt in

Uw gebruiker opent uw externe app met de bedoeling in te loggen. In uw app wordt het inlogformulier weergegeven, met velden voor gebruikersnaam en wachtwoord, en een inlogknop. Salesforce biedt dit inlogformulier niet. Hoe het eruitziet is aan u. Uw gebruiker geeft zijn of haar gebruikersnaam en wachtwoord op en klikt op de inlogknop.

Externe app genereert code_verifier en code_challenge (optioneel)

Als u de extensie Proof Key for Code Exchange (PKCE) gebruikt, genereert de app waarden die worden gebruikt om de autorisatiecode te verifiëren.

Het wordt sterk aanbevolen de PKCE-extensie te gebruiken wanneer u de stroom Autorisatiecode- en inloggegevens implementeert. Zie specificatie RFC 7636 voor meer informatie over PKCE: Bewijssleutel voor codeuitwisseling door openbare OAuth-clients, geleverd door de Internet Engineering Task Force (IETF).

De PKCE-specificatie gedefinieerd in RFC 7636 bevat ook een optionele code_challenge_method die u kunt verzenden in de autorisatieaanvraag. Salesforce negeert elke waarde die u in deze parameter verzendt en gaat standaard over op SHA256.

Als u deze stroom implementeert met behulp van een callback-handler aan de serverzijde, schakelt u de instellingen voor Geheim vereisen voor webserverstroom en Geheim vereisen voor stroom voor vernieuwingstoken in uw externe clientapp of verbonden app in. Als u deze instellingen inschakelt, moet u ervoor zorgen dat uw callback-handler de veiligheid van het consumentengeheim garandeert.

Externe app vraagt headless een autorisatiecode aan

De externe app verzendt vanuit de browser een headless autorisatieaanvraag naar het autorisatie-eindpunt van de Headless Login-API op uw Experience Cloud-site met behulp van AJAX (Asynchronous Java and XML). Als u headless gebruikers ontdekken niet gebruikt, kunt u voor dit verzoek de methode GET of POST gebruiken. Als u headless gebruikers ontdekken gebruikt, worden alleen POST-verzoeken ondersteund.

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

Voor zowel GET- als POST-aanvragen moet u de Auth-Request-Type: Named-User van de header opnemen.

Als u deze stroom wilt verbinden met de headless gaststroom, kunt u desgewenst een Uvid-Hint opnemen met een op JWT gebaseerd toegangstoken dat een UVID-waarde bevat. Dit is een universeel unieke identifier (UUID) van versie 4, die volledig door uw app wordt gegenereerd en beheerd. Als u een toegangstoken met een UVID wilt verkrijgen, moet u uw externe clientapp of verbonden app inschakelen om op JWT gebaseerde toegangstokens uit te geven en de headless gaststroom in uw app te implementeren.

Als u de gastgebruikersstroom implementeert in uw app, kunt u deze header optioneel gebruiken om een op JWT (JSON Web Token) gebaseerd toegangstoken door te geven met daarin een unieke bezoekers-ID die is gekoppeld aan de identiteit van een gastgebruiker. Door de UVID door te geven aan een benoemde gebruikersstroom kunt u contextuele informatie van een gastgebruikerssessie, zoals de cookievoorkeuren van de gebruiker, overdragen aan een benoemde gebruikerssessie.

U kunt ook de normale UVID-waarde opnemen in de hoofdtekst van de aanvraag.

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.MyDomainName.my.site.com/services/apexrest/code/exchange&
client_id=******&
code_challenge=Y29kZ*******

Als u een POST-aanvraag gebruikt, kunt u de met Base64 gecodeerde inloggegevens van de gebruiker opnemen in een autorisatieheader of kunt u ze in de hoofdtekst van de aanvraag plaatsen.

Als u ontdekking van headless gebruikers gebruikt, verzendt u geen gebruikersnaam en wachtwoord. In plaats daarvan verzendt u een identifier in de parameter login_hint, optionele aangepaste gegevens en een wachtwoord. Neem de identifier, aangepaste gegevens en het wachtwoord op in de hoofdtekst van een POST-aanvraag. Gebruik geen GET-verzoek.

Opmerking Als u de instelling Inloggegevens voor gebruikers vereisen in de POST-hoofdtekst voor autorisatiecode- en inloggegevens hebt ingeschakeld voor uw externe clientapp of verbonden app, kunt u de inloggegevens van de gebruiker alleen verzenden in de hoofdtekst van de aanvraag. Als deze instelling is ingeschakeld, kunt u de methode GET niet gebruiken voor de aanvraag van de autorisatiecode. U kunt alleen de POST-methode gebruiken.

Neem bij de GET- en POST-methoden deze verplichte parameters op in de hoofdtekst van de autorisatieaanvraag.

U kunt ook deze optionele parameters in de autorisatieaanvraag opnemen.

(Optioneel) Handler voor ontdekken van headless gebruiker vindt de gebruiker

Als u een headless handler voor ontdekking van gebruikers gebruikt, neemt de handler de parameters login_hint en customdata en zoekt de gekoppelde gebruiker. De handler bevestigt dat het e-mailadres of telefoonnummer van de gebruiker is geverifieerd.

Zie Auth.HeadlessUserDiscoveryHandler voor een voorbeeldhandler.

Salesforce valideert de inloggegevens en retourneert een 302-omleiding

https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxx

Callback-handler extraheert code en voert codeuitwisseling uit

De callback-handler aan de serverzijde extraheert de autorisatiecode en andere parameters uit de 302-omleiding. Vervolgens initieert de handler de codeuitwisseling door het headless verzenden van een POST-aanvraag naar het tokeneindpunt.

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }

global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = '<ConnecedApp Secret>';
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }

Voor de aanvraag van een toegangstoken kunt u alleen een POST-aanvraag gebruiken. GET-aanvragen worden niet ondersteund. U moet een Content-Type opnemen. Neem deze verplichte parameters op in de hoofdtekst van de aanvraag.

U kunt ook deze optionele parameters opnemen in de tokenaanvraag.

 // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

Salesforce verleent een toegangstoken

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

De respons met het toegangstoken bevat deze verplichte parameters.

De toegangstokenrespons kan ook deze parameters bevatten.

Callback-handler verwerkt tokenrespons en retourneert parameters naar app

//Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }

De callback-handler aan de serverzijde retourneert het toegangstoken en de status aan de browser, samen met gebruikersgegevens, tokens en sessiegegevens. In ons voorbeeld retourneert de responswrapper het toegangstoken naar de app. Als best practice wordt aangeraden om uw server te configureren voor opslag van het toegangstoken, een sessie voor de app te maken en de sessie terug te sturen naar de app, in plaats van het toegangstoken te retourneren. Als ontwikkelaar hebt u volledige controle over het maken van de sessie, het opslaan van het toegangstoken en het beheren van de inlogstatus. Dit betekent dat u de specifieke implementatie helemaal zelf kunt bepalen.

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","errMsg":null,"access_token":"00*******"}

App verwerkt tokenrespons en zet de gebruikerssessie op

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

Eindgebruiker is ingelogd en voert een actie in de app uit

Uw gebruiker is nu ingelogd en voert een actie in uw app uit die toegang tot Salesforce-gegevens vereist. De gebruiker klikt bijvoorbeeld op een knop om zijn of haar historie van geboekte reizen weer te geven, die is opgeslagen in Salesforce.

Opmerking Wanneer u uw externe clientapp of verbonden app instelt voor de stroom Autorisatiecode- en inloggegevens, stelt u het beleid Toegestane gebruikers in op Door beheerder goedgekeurde gebruikers en configureert u welke profielen of machtigingensets toegang hebben tot de app. Met dit beleid krijgen gebruikers toegang tot de app zonder deze te autoriseren, waardoor ze geen autorisatiescherm zien waarin hen wordt gevraagd de app toegang tot hun gegevens te verlenen.

App verstuurt een geauthenticeerde aanvraag naar een Salesforce-eindpunt

Om toegang tot de Salesforce-gegevens van de gebruiker te krijgen gebruikt uw app het toegangstoken om een geauthenticeerde aanroep te doen naar een beschermd Salesforce-eindpunt, zoals een Salesforce-API.

Eindgebruiker heeft toegang tot Salesforce-gegevens

De gebruiker heeft nu toegang tot beschermde Salesforce-gegevens in uw app. De gebruiker kan bijvoorbeeld zijn of haar historie van geboekte reizen zien. Vanuit het perspectief van de eindgebruiker heeft het hele proces, van inloggen tot toegang tot de gebruikersgegevens, plaatsgevonden zonder dat de gebruiker ooit de app heeft hoeven verlaten.