Sidhuvudlösa identitets-API:n: Sidhuvudlöst gästflöde för offentliga klienter
Vissa användare interagerar med din app utanför plattformen men loggar inte in eller registrerar sig. Du kan utfärda identifierare i form av unikt besökar-ID (UVID) för dessa okända besökare med det sidhuvudlösa gästflödet. Om användaren bestämmer sig för att logga in eller registrera sig kan du skicka identifieraren till ett namngivet användarflöde, som ett sidhuvudlöst inloggningsflöde. Använd gästanvändaridentitet som ett verktyg för att föra sammanhang från gästanvändarsessioner till namngivna användarsessioner. Detta flöde är en variant av auktoriseringskoden och inloggningsuppgifter.
Versioner som krävs
| Tillgängliga i: både Salesforce Classic (inte tillgängligt i alla organisationer) och Lightning Experience |
| Tillgängliga i: Enterprise, Unlimited och Developer Edition |
Innan du konfigurerar detta flöde, utför dessa steg.
- Uppfyll förkrav för sidhuvudlös identitet
- Integrera din app utanför plattformen med Salesforce med ett av dessa alternativ. Se till att du konfigurerar ytterligare policyer för gästflödet.
Anta till exempel att du är värd för en e-handelsapp utanför Salesforce Platform. Du vill att användare ska kunna spara objekt i en varukorg utan att logga in. Du kan använda gästanvändarflödet för att skapa en UVID för användaren, och du kan lagra användarens varukorgsinformation och knyta den till UVID. När användaren så småningom loggar in eller registrerar sig skickar du UVID till ett sidhuvudlöst inloggnings- eller registreringsflöde. Eftersom du har varukorgens sammanhang från UVID kan du spara användarens objekt, vilket ger dina användare en bättre upplevelse.
Exemplet varukorg är bara en av många möjligheter när det gäller UVID och gästflöde. Andra möjligheter inkluderar att förstå vad som gör att dina användare vill registrera sig för din app och komma ihåg deras inställningar.
Gästflödet och UVID stöds endast för JSON Web Token-baserade åtkomsttokens (JWT). För att ansluta UVID till en namngiven användare måste du konfigurera det namngivna användarflödet att även utfärda JWT-baserade åtkomsttokens.
Dessa instruktioner berättar hur du implementerar flödet för en offentlig klient, som en app på en sida, som inte kan hålla konfidentiell information privat. Offentliga klienter har några extra säkerhetsöverväganden. Jämfört med en privat klient, som en klientserverapp, har de inte en privat backend för att lagra konsumenthemligheten, som fungerar som ett lösenord för att säkra kodutbytet. Med ingenstans att lagra en konsumenthemlighet kan appen inte riskera att läcka den. För att ersätta rollen för konsumenthemligheten kan du använda tillägget Proof Key for Code Exchange (PKCE) istället. Detta tillägg skyddar din app med parametrar som endast du och Salesforce kan verifiera. Vi rekommenderar alltid att implementera PKCE för en offentlig klient.
Här är en översikt av gästflödet. Dessa steg täcker flödet fram till den punkt då gästanvändaren identifieras men inte är inloggad.
- Den okända besökaren anländer till appen eller utför en åtgärd som att klicka på en knapp (1).
- Appen letar efter en UVID och om den inte kan hitta en skapar den ett värde.
- Om du använder tillägget Proof Key for Code Exchange (PKCE), vilket vi starkt rekommenderar, skapar appen PKCE-parametrar.
- För att få en auktoriseringskod skickar din app sidhuvudlöst UVID till Salesforce-auktoriseringsslutpunkten (
services/oauth2/authorize) i en GET- eller POST-begäran. - Salesforce validerar UVID och returnerar en 302-omdirigering till en förkonfigurerad URL som innehåller auktoriseringskoden. Omdirigeringen bearbetas i webbläsaren och svaret levereras till callbackslutpunkten.
- Callbackslutpunkten extraherar auktoriseringskoden och returnerar den till din app.
- Din app får auktoriseringskoden och inleder ett kodutbyte genom att skicka koden och andra parametrar i en POST-begäran till Salesforce-tokenslutpunkten (
services/oauth2/token). - Salesforce validerar begäran och returnerar en gäst-JWT-baserad åtkomsttoken med UVID i ämnesanspråket.
- Din app bearbetar svaret och skapar en gästsession, med UVID-värdet kvar.
- Slutanvändaren har nu en gästsession nyckelad till UVID-värdet som returneras i åtkomsttoken.
Precis som andra varianter av auktoriseringskoden och inloggningsuppgifter kräver detta flöde för en offentlig klient en callbackslutpunkt som kan hantera 302-omdirigeringen och returnera auktoriseringskoden och andra parametrar till din app. Om du gör kodutbytet i din webbläsare kan du använda Salesforce /services/oauth2/echo slutpunkt. Den tolkar automatiskt 302-omdirigeringen, extraherar parametrarna och returnerar dem till din app i JSON-format. Vi använder ekoslutpunkten i kodexemplen för detta flöde.
Okänd slutanvändare anländer till din app
Flödet startar när en slutanvändare besöker din app. Du kan även konfigurera den så att den startar när användaren utför en åtgärd, som att spara ett objekt i en varukorg.
App skapar en UVID
Din app försöker hitta en UVID associerad med denna användare. Till exempel letar den efter webbläsarcookies från tidigare besök i appen. Om appen inte kan hitta en UVID skapar den en. Salesforce spelar ingen roll för att skapa UVID. Dess skapande, lagring och underhåll är helt upp till dig. Det enda kravet är att UVID måste vara en universellt unik identifierare (v4 UUID) av version 4.
App skapar PKCE-parametrar
Om du använder PKCE skapar din app parametrarna code_verifier och code_challenge.
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.
App byter UVID mot en auktoriseringskod
Din app skickar sidhuvudlöst en GET- eller POST-begäran till Salesforce-auktoriseringsslutpunkten på din Experience Cloud-webbplats. Begäran innehåller UVID och andra parametrar för att identifiera appen och specificera typen av begäran.
Det finns två alternativ för hur du skickar UVID i denna begäran. Du kan antingen skicka ett vanligt UVID-värde eller skicka en JWT-baserad åtkomsttoken med UVID inpräglat i den. Till exempel, om du har en JWT-baserad åtkomsttoken från en tidigare session är att skicka token till auktoriseringsslutpunkten ett enkelt sätt att återanvända den utan att specifikt tolka den för UVID.
Inkludera dessa sidhuvuden i din begäran.
| Sidhuvud | Obligatorisk? | Beskrivning |
|---|---|---|
Uvid-Hint
|
Krävs om du inte skickar UVID i begärans brödtext. Du måste alltid inkludera en UVID—oavsett om den skickas i sidhuvudet eller i begärans brödtext. | Innehåller antingen UVID som ett vanligt värde eller en JWT-baserad åtkomsttoken med en UVID inskriven i sig. Om du skickar UVID som ett vanligt värde, inkludera ett Om du skickar en JWT-baserad åtkomsttoken med en UVID, inkludera ett |
Auth-Request-Type
|
Ja. | Anger vilken typ av begäran du vill göra till Salesforce. För sidhuvudlös lösenordsfri inloggning måste detta värde vara satt till guest. |
Inkludera dessa parametrar i begärans brödtext.
| Parameter | Obligatorisk? | Beskrivning |
|---|---|---|
uvid_hint
|
Krävs om du inte inkluderar UVID i sidhuvudet. | Innehåller antingen UVID som ett vanligt värde eller en JWT-baserad åtkomsttoken med en UVID inskriven i sig. Om du skickar UVID som ett vanligt värde, inkludera ett Om du skickar en JWT-baserad åtkomsttoken med en UVID, inkludera ett |
client_id
|
Ja. | Konsumentnyckeln för den externa klientappen eller anslutna appen. |
response_type
|
Ja. | Den OAuth 2.0-beviljandetyp som din app begär. Eftersom detta flöde är en variant av auktoriseringskoden och inloggningsuppgifter måste detta värde vara code_credentials. |
redirect_uri
|
Ja. | URL dit användare omdirigeras efter framgångsrik autentisering. För detta flöde kan du använda ekoslutpunkten, |
code_challenge
|
Endast om du använder PKCE, vilket vi alltid rekommenderar, särskilt för en offentlig klient. | Anger SHA256-hashvärdet för Om en Om |
scope
|
Ja. | Behörigheter som definierar vilken typ av skyddade resurser en extern klientapp eller ansluten app kan komma åt. Värdena som du skickar i denna begäran måste matcha eller vara en underuppsättning av de omfattningar som tilldelats din app. Mer information om varje omfattning och dess syfte finns i OAuth-tokens och omfattningar. |
Se dessa exempel på auktoriseringsbegäranden, som alla implementerar PKCE.
Här är ett exempel på en begäran där UVID skickas som ett vanligt värde i begärans sidhuvud.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: UVID abcd-1234-efgh
Auth-Request-Type: guest
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
I detta exempel skickas UVID i en JWT-baserad åtkomsttoken i sidhuvudet.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: JWT **************
Auth-Request-Type: guest
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
Här är ett exempel där UVID skickas som ett vanligt värde i begärans brödtext.
POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: guest
uvid_hint=UVID abcd-1234-efgh&
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
Salesforce returnerar en 302-omdirigering
Salesforce validerar UVID. Om UVID skickades som ett vanligt värde validerar Salesforce dess format. Om den skickades som en JWT-baserad åtkomsttoken kontrollerar Salesforce giltigheten för token.
Salesforce returnerar sedan en HTTP 302-omdirigering till en förkonfigurerad URL som innehåller auktoriseringskoden. Om flödet sker i webbläsaren bearbetas 302-omdirigeringen i webbläsaren och Salesforce skickar automatiskt omdirigeringssvaret till omdirigerings-URL:en, vilket är callbackslutpunkten. Här är ett exempel på en förkonfigurerad URL.
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=0DBxxxxxxxxxxxxCallback-slutpunkt skickar auktoriseringskoden till din app
Callbackslutpunkten extraherar auktoriseringskoden och returnerar den till din app. I dessa kodexempel pekar omdirigerings-URL:en till /services/oauth2/echo callback-slutpunkten på Experience Cloud-webbplatsen. Denna slutpunkt tolkar automatiskt 302-omdirigeringen, extraherar auktoriseringskoden och andra parametrar och returnerar dem till din app i JSON-format.
App inleder kodutbyte
Din app får kodsvaret med auktoriseringen och andra parametrar. Den byter ut koden mot en åtkomsttoken genom att skicka en sidhuvudlös POST-begäran till /services/oauth2/token slutpunkt.
Inkludera ett sidhuvud i begäran.
| Parameter | Obligatorisk? | Beskrivning |
|---|---|---|
Auth-Request-Type
|
Ja. | Anger vilken typ av begäran du vill göra till Salesforce. För sidhuvudlös lösenordsfri inloggning måste detta värde vara satt till guest. |
Uvid-Hint
|
Ja. | Innehåller antingen UVID som ett vanligt värde eller en JWT-baserad åtkomsttoken med en UVID inpräglad i sig. För kodutbytet, inkludera inte ett prefix för UVID. Till exempel, om du skickar UVID som ett vanligt värde är rubriken bara |
Inkludera dessa parametrar i begärans brödtext.
| Parameter | Obligatorisk? | Beskrivning |
|---|---|---|
code
|
Ja. | Auktoriseringsservern skapar en auktoriseringskod, som är en kortlivad token, och skickar den till klienten efter framgångsrik autentisering. Klienten skickar auktoriseringskoden till auktoriseringsservern för att få en åtkomsttoken och, i relevanta fall, en uppdateringstoken. |
client_id
|
Ja. | Konsumentnyckeln för den externa klientappen eller anslutna appen. |
redirect_uri
|
Ja. | Den URL dit användare omdirigeras efter en framgångsrik autentisering. Omdirigerings-URI måste matcha ett av värdena i den externa klientappen eller den anslutna appens fält Callback-URL. Annars misslyckas godkännandet. Detta värde måste vara URL-kodat. För detta flöde kan du använda ekoslutpunkten, |
grant_type
|
Ja. | Den typ av validering som den externa klientappen eller anslutna appen kan tillhandahålla för att bevisa att den är en säker besökare. Eftersom detta flöde är en variant av auktoriseringskoden och inloggningsuppgifter måste värdet vara authorization_code. |
code_verifier
|
Endast om du använder PKCE. | Specificerar 128 byte slumpmässiga data med hög entropi för att göra det svårt att gissa code-värdet. Ange denna parameter för att hjälpa till att förhindra attacker med avlyssning av auktoriseringskoden. Värdet måste vara base64url-kodat enligt definitionen i https://datatracker.ietf.org/doc/html/rfc4648#section-5. Om det finns ett Om |
Här är ett exempel på en tokenbegäran som implementerar PKCE. I detta exempel skickas UVID som ett vanligt värde.
POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Uvid-Hint: abcd-1234-efgh
Auth-Request-Type: guest
code=********&
client_id=**********&
redirect_uri=https://MyExperienceCloudSite.my.site.com/services/oauth2/echo&
grant_type=authorization_code&
code_verifier=*******Salesforce beviljar en JWT-baserad åtkomsttoken
Efter validering av appens inloggningsuppgifter. Salesforce returnerar en gäst-JWT-baserad åtkomsttoken och en status till webbläsaren. Gäståtkomsttoken innehåller UVID i anspråket Subject (sub). Här är ett exempel på ett stycke av en JWT-baserad åtkomsttoken. Som en påminnelse har dessa tokens tre komponenter: ett sidhuvud, en belastning och en signatur. Detta exempel visar dig belastningen med UVID i sub. Som du kan se inleds värdet med uvid.
{
"tnk": "example/00XXXXXX",
"ver": "1.0",
"kid": "CORE_ATJWT************",
"tty": "sfdc-core-token",
"typ": "JWT",
"alg": "RS256"
}
{
"scp": "open_id",
"aud": [
"https://example.com"
],
"sub": "uvid:abcd-1234-efgh",
"nbf": "1675197036",
"iss": "https://MyExperienceCloudSite.my.site.com",
"exp": "1675198836",
"iat": "1675197036",
jti”: xRb**********”
"client_id": "**********"
}En fullständig förklaring av varje anspråk i en JWT-baserad åtkomsttoken finns i JWT-baserade åtkomsttokens i Salesforce-hjälpen.
Appen skapar en gästsession
Din app bearbetar åtkomsttokensvaret och skapar en gästsession, med UVID-värdet kvar.
Okänd användare är nu identifierad
Den okända slutanvändaren har nu en gästsession knuten till UVID-värdet som returneras i den JWT-baserade åtkomsttoken. Nu är det upp till dig vad du vill göra med UVID. För att få reda på hur du skickar det till ett namngivet användarauktoriseringsflöde, se Headless Identity APIs: Utöka gästflödet utan sidhuvud till ett namngivet användarflöde.
