API-er for headless-identitet: Headless-gjesteflyt for private kunder
For brukere som samhandler med appen din utenfor plattformen, men ikke nødvendigvis er logget på, kan du bruke gjesteflyten uten hode til å identifisere brukere med en unik besøks-ID (UVID). Når brukeren logger seg på eller registrerer seg, kan du føre UVIDen fremover og vedlikeholde eventuell kontekstinformasjon som er knyttet til den, som en brukers preferanser. Denne flyten er en variasjon av godkjenningskode- og legitimasjonsflyten.
Nødvendige utgaver
| Tilgjengelig i både Salesforce Classic (ikke tilgjengelig i alle organisasjoner) og Lightning Experience |
| Tilgjengelig i Enterprise, Unlimited og Developer Edition |
Utfør disse trinnene før du konfigurerer denne flyten.
- Komplette forutsetninger for Headless Identity
- Integrer din offline app med Salesforce ved å bruke et av disse alternativene. Pass på at du konfigurerer flere policyer for gjesteflyten.
Du er for eksempel vert for en e-handelsapp utenfor Salesforce-plattformen. Du vil at brukere skal kunne lagre elementer i en handlevogn uten å logge seg på. Du kan bruke gjestebrukerflyten til å generere en UVID for brukeren, og du kan lagre brukerens handlevogninformasjon og knytte den til UVID-en. Når brukeren til slutt logger seg på eller registrerer seg, overfører du UVID-en til en påloggings- eller registreringsflyt uten hode. Fordi du har handlevognkonteksten fra UVID-en, kan du lagre brukerens elementer og gi dem en bedre opplevelse.
Eksempelet i handlevognen er bare en av mange muligheter når det gjelder UVID- og gjesteflyten. Andre muligheter inkluderer å forstå hva som gjør at brukerne ønsker å registrere seg for appen og huske preferansene deres.
Gjesteflyten og UVID støttes bare for JSON Web Token-baserte tilgangstokener (JWT). For å koble UVID til en navngitt bruker må du konfigurere den navngitte brukerflyten til også å utstede JWT-baserte tilgangstokener.
Disse instruksjonene forteller deg hvordan du implementerer flyten for en privat klient med sin egen serverdel. Private klienter har et sikkert sted å lagre appens forbrukerhemmelighet, som fungerer som et passord for kodeutvekslingen, så vi anbefaler å sende forbrukerhemmeligheten når du ber om et tilgangstoken.
Vi anbefaler også at du beskytter flyten ytterligere ved å implementere utvidelsen OAuth 2.0 Proof Key for Code Exchange (PKCE). PKCE bidrar til å sikre at klienten som starter flyten, er den samme klienten som fullfører den. Hvis du vil vite mer om hvordan PKCE fungerer og hvordan du kan håndheve det, kan du se Bygge PKCE-utvidelsen i implementeringer.
Her er en oversikt over gjesteflyten. Disse trinnene dekker flyten inntil gjestebrukeren er identifisert, men ikke logget på.
- Den ukjente besøkende ankommer appen eller utfører en handling som å klikke på en knapp (1).
- Appen ser etter en UVID. Hvis den ikke finner en, ber den om en UVID fra klientens serverdel (2).
- Hvis du blir bedt om det, genererer klientens serverdel en UVID og sender den til appen (3).
- Appen mottar UVID (4a).
- Hvis du bruker PKCE, genererer appen PKCE-parametere (4b).
- For å få en godkjenningskode sender appen UVID-koden i en headless GET- eller POST-forespørsel til godkjenningssluttpunktet (
services/oauth2/authorize) (5). - Salesforce validerer UVID og returnerer en 302-omdirigering til en forhåndskonfigurert URL-adresse som inneholder godkjenningskoden (6).
- Appens klientdash-enhet trekker ut koden og andre parametere fra 302-omdirigeringen og utveksler koden for et tilgangstoken med en forespørsel til Salesforce-tokenendepunktet (
services/oauth2/token) (7). - Salesforce returnerer et gjeste-JWT-basert tilgangstoken med UVID i emnekravet (8).
- Appens serverdel behandler det gjeste-JWT-baserte tilgangstokenet og lagrer UVID-verdien, som den kan holde privat. Den returnerer en gjesteøkt og eventuelt gjestetokenet (9).
- Appen mottar tokensvaret og oppretter gjesteøkten (10).
- Den tidligere ukjente besøkende har nå en gjesteøkt knyttet til UVID-verdien i tilgangstokenet (11).
Som nevnt i trinn 7 for en privat klient bygger du en tilbakekallbehandler på serversiden som kan trekke ut 302-omdirigeringen og returnere en godkjenningskode til appen. Hvis du vil se hvordan du kan bygge denne behandleren, kan du se Godkjenningskode og legitimasjonsflyt for private klienter, som inkluderer et eksempel på en Apex-behandler som vises som en REST-ressurs.
Ukjent sluttbruker ankommer appen
Flyten starter når en sluttbruker besøker appen. Du kan også konfigurere den til å starte når brukeren utfører en handling, som å lagre et element i en handlevogn.
App ber om en UVID hvis det er nødvendig
Appen prøver å finne en UVID fra tidligere besøk i appen. Den bestemmer for eksempel om den kan trekke ut UVID-en fra en informasjonskapsel eller fra lokal lagring i nettleseren. Hvis appen ikke finner en UVID, ber den om en fra serverdelen for klienten.
Client Backend genererer en UVID
Hvis du blir bedt om det, genererer klientens serverdel en UVID-verdi. Salesforce er ikke involvert i generering, lagring eller vedlikehold av UVID. Det er helt opp til appen din. Det eneste kravet er at UVID-koden må være en universelt unik identifikator i versjon 4 (v4 UUID).
App mottar UVID
Appen din mottar UVID-koden fra klientens serverdel.
App genererer PKCE-parametere
Hvis du bruker PKCE, genererer appen code_verifier- og code_challenge-parametere.
PKCE-spesifikasjonen definert i RFC 7636 inkluderer også en valgfri code_challenge_method-parameter som du kan sende i godkjenningsforespørselen. Salesforce ignorerer alle verdier som du sender i denne parameteren, og bruker som standard SHA256.
App utveksler UVID for en godkjenningskode
Appen sender en GET- eller POST-forespørsel direkte til Salesforce-godkjenningssluttpunktet på Experience Cloud-nettstedet. Forespørselen inneholder UVID og andre parametere for å identifisere appen og angi typen forespørsel.
Du har to alternativer for hvordan du sender UVID-en i denne forespørselen. Du kan sende en ren UVID-verdi, eller du kan sende et JWT-basert tilgangstoken med UVID-knappen i det. Hvis du for eksempel har et JWT-basert tilgangstoken fra en tidligere økt, er det enkelt å sende tokenet til godkjenningssluttpunktet for å gjenbruke det uten å spesifikt analysere det for UVID-en.
Inkluder disse topptekstene i forespørselen.
| Hode | Obligatorisk? | Beskrivelse |
|---|---|---|
Uvid-Hint
|
Kreves hvis du ikke sender UVID-koden i forespørselsteksten. Du må alltid inkludere en UVID – enten den sendes i toppteksten eller i forespørselsteksten. | Inneholder enten UVID-koden som en ren verdi eller et JWT-basert tilgangstoken med et UVID-kode tilpasset den. Hvis du sender UVID som en ren verdi, inkluderer du et Hvis du sender et JWT-basert tilgangstoken med en UVID, inkluderer du et |
Auth-Request-Type
|
Ja. | Angir typen forespørsel du vil sende til Salesforce. For headless-pålogging uten passord må denne verdien settes til guest. |
Inkluder disse parameterne i forespørselsteksten.
| Parameter | Obligatorisk? | Beskrivelse |
|---|---|---|
uvid_hint
|
Kreves hvis du ikke inkluderer UVID i toppteksten. | Inneholder enten UVID-koden som en ren verdi eller et JWT-basert tilgangstoken med et UVID-kode tilpasset den. Hvis du sender UVID som en ren verdi, inkluderer du et Hvis du sender et JWT-basert tilgangstoken med en UVID, inkluderer du et |
client_id
|
Ja. | Forbrukernøkkelen til den eksterne klientappen eller den tilkoblede appen. |
response_type
|
Ja. | OAuth 2.0-utstedelsestypen som appen ber om. Fordi denne flyten er en variasjon av godkjenningskoden og legitimasjonsflyten, må denne verdien være code_credentials. |
redirect_uri
|
Ja. | URL-adressen som brukere omdirigeres til etter vellykket godkjenning. For private klienter bruker du et |
code_challenge
|
Bare hvis du bruker PKCE, som vi alltid anbefaler, spesielt for en felles klient. | Angir SHA256-hash-verdien for Hvis det oppgis en Hvis |
scope
|
Ja. | Tillatelser som definerer hvilke typer beskyttede ressurser appen kan få tilgang til. Verdiene som du sender i denne forespørselen, må samsvare med eller være et delsett av omfangene som er tildelt den eksterne klientappen eller den tilkoblede appen. Hvis du vil ha mer informasjon om hvert omfang og dets formål, kan du se OAuth-tokener og -omfang. |
Disse eksemplene på godkjenningsforespørsler implementerer alle PKCE.
Her er et eksempel på en forespørsel der UVID overføres som en ren verdi i forespørselshodet.
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
Her er et eksempel på en forespørsel der UVID overføres i et JWT-basert tilgangstoken i toppteksten.
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.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=********
scope=openid
I dette eksemplet overføres UVID som en ren verdi i forespørselsteksten.
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.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=********
scope=openid
Salesforce returnerer en 302-omdirigering
Salesforce validerer UVID. Hvis UVID-koden ble overført som en ren verdi, validerer Salesforce formatet. Hvis det ble overført som et JWT-basert tilgangstoken, kontrollerer Salesforce gyldigheten av tokenet.
Salesforce returnerer deretter en HTTP 302-omdirigering til en forhåndskonfigurert URL-adresse som inneholder godkjenningskoden. Hvis flyten skjer i nettleseren, behandles 302-omdirigeringen i nettleseren, og Salesforce sender automatisk omdirigeringssvaret til omdirigerings-URL-adressen, som peker til tilbakekallbehandleren på serversiden på klientsider. Her er et eksempel på en forhåndskonfigurert URL-adresse.
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=0DBxxxxxxxxxxxxClient Backend trekker ut koden og utveksler den mot et tilgangstoken
Klientserverdelen trekker ut godkjenningskoden og andre parametere fra den forhåndskonfigurerte URL-adressen. Den starter deretter en kodeutveksling ved å sende koden og andre parametere i en headless POST-forespørsel til /services/oauth2/token sluttpunkt.
Inkluder disse topptekstene i forespørselen.
| Parameter | Obligatorisk? | Beskrivelse |
|---|---|---|
Uvid-Hint
|
Ja. | Inneholder enten UVID-koden som en ren verdi eller et JWT-basert tilgangstoken med et UVID-kode tilpasset den. Ikke inkluder et prefiks for UVID for kodeutvekslingen. Hvis du for eksempel sender UVID som en ren verdi, er toppteksten bare |
Auth-Request-Type
|
Ja. | Angir typen forespørsel du vil sende til Salesforce. For headless-pålogging uten passord må denne verdien settes til guest. |
Inkluder disse parameterne i forespørselsteksten.
| Parameter | Obligatorisk? | Beskrivelse |
|---|---|---|
code
|
Ja. | Godkjenningsserveren oppretter en godkjenningskode med begrenset levetid og overfører den til klienten etter vellykket godkjenning. Klienten sender godkjenningskoden til godkjenningsserveren for å få et tilgangstoken og eventuelt et oppdateringstoken. |
client_id
|
Ja. | Forbrukernøkkelen til den eksterne klientappen eller den tilkoblede appen. |
client_secret
|
Ja. | Forbrukerhemmeligheten for den eksterne klientappen eller den tilkoblede appen. |
redirect_uri
|
Ja. | URL-adressen dit brukere omdirigeres etter en vellykket godkjenning. URI-adressen for omdirigering må stemme med en av verdiene feltet URL-adresse for tilbakekall i den tilkoblede appen. Hvis ikke, mislykkes godkjenningen. Denne verdien må være URL-kodet. For private klienter bruker du et |
grant_type
|
Ja. | Valideringstypen som appen kan levere for å bevise at den er en sikker besøkende. Fordi denne flyten er en variasjon av godkjenningskoden og legitimasjonsflyten, må verdien være authorization_code. |
code_verifier
|
Bare hvis du bruker PKCE. | Angir 128 byte vilkårlige data med høy entropi for å gjøre det vanskelig å gjette code-verdien. Angi denne parameteren for å hindre oppfangingsangrep på godkjenningskoden. Verdien må være base64url-kodet som definert i https://datatracker.ietf.org/doc/html/rfc4648#section-5. Hvis det er en Hvis |
Her er et eksempel på en tokenforespørsel som implementerer PKCE. I dette eksemplet sendes UVID som en ren verdi.
POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: guest
Uvid_Hint: abcd-1234-efgh
code=********&
client_id=**********&
client_secret=*********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
grant_type=authorization_code&
code_verifier=*******Salesforce utsteder et JWT-basert tilgangstoken
Etter at du har validert appens legitimasjon. Salesforce returnerer et gjeste-JWT-basert tilgangstoken og en stat til klientens serverdel. Gjestetilgangstokenet inneholder UVID i emnekravet (sub). Her er et eksempel på en snutt av et JWT-basert tilgangstoken. Som en påminnelse har disse tokenene tre komponenter: et hode, en last og en signatur Dette eksemplet viser belastningen. Som du kan se er UVID-verdien i sub prefikset 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": "**********"
}Hvis du vil ha en fullstendig forklaring av hvert krav i et JWT-basert tilgangstoken, kan du se JWT-baserte tilgangstokener i Salesforce Hjelp.
Tilgangstokensvar for klientens serverdelprosesser
Klientserverdelen behandler tilgangstokensvaret og lagrer UVID-verdien. Den returnerer en gjesteøkt til appen. Det kan også returnere det JWT-baserte tilgangstokenet, men det er ikke nødvendig.
App oppretter gjesteøkten
Appen mottar tokensvaret fra klientens serverdel og oppretter en gjesteøkt.
Ukjent bruker er nå identifisert
Den ukjente sluttbrukeren har nå en gjesteøkt knyttet til UVID-verdien som returneres i det JWT-baserte tilgangstokenet. På dette punktet er det opp til deg hva du vil gjøre med UVID-en. Hvis du vil vite hvordan du overfører den til en navngitt brukergodkjenningsflyt, kan du se Utvide gjestebrukerflyten til en navngitt brukerflyt.
