Headless Identity API -rajapinnat: Vieraskäyttäjien headless-kulku yksityisille asiakkaille
Voit käyttää Headless Guest Flow -kulkua tunnistaaksesi käyttäjät, joilla on yksilöllinen vierailijan tunnus (UVID), kun he käyttävät sovellustasi offline-tilassa, mutta eivät välttämättä kirjaudu sisään. Kun käyttäjä kirjautuu sisään tai rekisteröityy, voit siirtää UVID-tunnuksen eteenpäin ja ylläpitää siihen liittyviä asiayhteystietoja, kuten käyttäjän valintoja. Tämä kulku on valtuutuskoodin ja tunnuksen kulun variaatio.
Vaaditut versiot
| Käytettävissä: Salesforce Classicissa (ei kaikissa organisaatioissa) ja Lightning Experiencessa |
| Käytettävissä: Enterprise Edition-, Unlimited Edition- ja Developer Edition -versioissa. |
Suorita seuraavat vaiheet ennen tämän kulun määrittämistä.
- Headless Identityn täydelliset edellytykset
- Integroi sovellusalustan ulkopuolinen sovelluksesi Salesforceen käyttämällä jotakin seuraavista vaihtoehdoista. Muista määrittää vieraskäyttäjien kululle lisäkäytäntöjä.
Oletetaan esimerkiksi, että isännöit verkkokauppasovellusta Salesforce Platformin ulkopuolella. Haluat, että käyttäjät voivat tallentaa kohteita ostoskoriin kirjautumatta sisään. Voit käyttää vieraskäyttäjän kulkua luodaksesi UVID-tunnuksen käyttäjälle, ja voit tallentaa käyttäjän ostoskorin tiedot ja liittää ne UVID-tunnukseen. Kun käyttäjä kirjautuu sisään tai rekisteröityy, välität UVID-tunnuksen headless-sisäänkirjautumis- tai rekisteröintikulkuun. Koska sinulla on ostoskorin konteksti UVID:stä, voit tallentaa käyttäjän kohteet ja tarjota heille paremman käyttökokemuksen.
Ostoskorin esimerkki on vain yksi monista mahdollisuuksista UVID- ja vieraskäyttäjien kulussa. Muita mahdollisuuksia on ymmärtää, miksi käyttäjäsi haluavat rekisteröityä sovellukseesi ja muistaa valintansa.
Vieraskulkua ja UVID-tunnusta tuetaan vain JSON Web Token (JWT) -pohjaisille käyttöoikeusvaltuuksille. Jos haluat yhdistää UVID:n nimettyyn käyttäjään, sinun täytyy määrittää nimetty käyttäjäkulku antamaan myös JWT-pohjaiset käyttöoikeusvaltuudet.
Nämä ohjeet kertovat, miten voit toteuttaa kulun yksityiselle asiakassovellukselle sen omalla taustalla. Yksityisillä asiakkailla on turvallinen paikka sovelluksesi kuluttajasalaisuuden säilyttämiseen, joka toimii salasanana koodinvaihdolle, joten suosittelemme lähettämään kuluttajasalaisuuden, kun pyydät käyttöoikeusvaltuutta.
Suosittelemme myös, että suojaat kulkusi tarkemmin ottamalla käyttöön OAuth 2.0 Proof Key for Code Exchange (PKCE) -laajennus. PKCE auttaa varmistamaan, että kulun käynnistänyt asiakassovellus on sama asiakassovellus, joka suorittaa kulun. Lisätietoja siitä, miten PKCE toimii ja miten voit noudattaa sitä, on kohdassa Proof Key for Code Exchange (PKCE) -laajennus.
Alla on vieraskäyttäjien kulun yleiskatsaus. Nämä vaiheet kattavat kulun, kunnes vieraskäyttäjä on tunnistettu, mutta ei kirjautunut sisään.
- Tuntematon vierailija saapuu sovellukseen tai suorittaa toiminnon, kuten napsauttaa painiketta (1).
- Sovellus etsii UVID-tunnuksen. Jos se ei löydä sellaista, se pyytää UVID-tunnusta asiakassovelluksen taustalta (2).
- Asiakassovelluksen taustajärjestelmä luo UVID-tunnuksen ja lähettää sen sovellukseesi tarvittaessa (3).
- Sovelluksesi saa UVID-tunnuksen (4a).
- Jos käytät PKCE-metodia, sovelluksesi luo PKCE-parametrit (4b).
- Sovelluksesi lähettää UVID-koodin headless GET- tai POST-pyynnössä valtuutuksen päätepisteeseen (
services/oauth2/authorize) saadakseen valtuutuskoodin (5). - Salesforce vahvistaa UVID-tunnuksen ja palauttaa 302-uudelleenohjauksen esimääritettyyn URL-osoitteeseen, joka sisältää valtuutuskoodin (6).
- Sovelluksesi asiakassovelluksen taustaohjelma noutaa koodin ja muut parametrit 302-uudelleenohjauksesta ja vaihtaa koodin käyttöoikeusvaltuuden kanssa pyynnön Salesforce-valtuuden päätepisteeseen (
services/oauth2/token) (7). - Salesforce palauttaa JWT-pohjaisen vieraskäyttöoikeusvaltuuden, jonka UVID on aihe-lausekkeessa (8).
- Sovelluksesi asiakassovelluksen taustaohjelma käsittelee vieraskäyttäjien JWT-käyttöoikeusvaltuuden ja tallentaa UVID-arvon, jonka se voi pitää yksityisenä. Se palauttaa vieraskäyttäjäistunnon ja halutessasi vierasvaltuuden (9).
- Sovelluksesi vastaanottaa valtuuden vastauksen ja luo vieraskäyttäjäistunnon (10).
- Aiemmin tuntematon vierailija on nyt vierastapaaminen, joka on sidottu käyttöoikeusvaltuuden UVID-arvoon (11).
Kuten yksityisen asiakassovelluksen vaiheessa 7 mainittiin, rakennat palvelinpuolen callback-kutsun käsittelijän, joka voi noutaa 302-uudelleenohjauksen ja palauttaa sovellukseesi valtuutuskoodin. Katso miten voit rakentaa tämän käsittelijän kohdasta Yksityisten asiakkaiden valtuutuskoodi- ja tunnusten kulku, joka sisältää esimerkin Apex-käsittelijästä, joka näytetään REST-resurssina.
Tuntematon loppukäyttäjä saapuu sovellukseesi
Kulku käynnistyy, kun loppukäyttäjä vierailee sovelluksessasi. Voit myös määrittää sen käynnistymään, kun käyttäjä suorittaa toiminnon, esimerkiksi tallentaakseen kohteen ostoskoriin.
Sovellus pyytää UVID-tunnusta tarvittaessa
Sovelluksesi yrittää löytää UVID-tunnuksen sovellukseen tehdyistä aiemmista vierailuista. Se määrittää esimerkiksi, voiko se noutaa UVID-tunnuksen evästeestä vai selaimen paikallisesta tallennustilasta. Jos sovellus ei löydä UVID-tunnusta, se pyytää sellaista asiakassovelluksen taustalta.
Asiakkaan taustalla luodaan UVID
Asiakassovelluksen taustalla luodaan UVID-arvo pyydettäessä. Salesforce ei luo, säilytä tai ylläpidä UVID-tunnusta. Se riippuu täysin sovelluksestasi. Ainoa vaatimus on, että UVID-tunnuksen täytyy olla yleisesti yksilöllinen version 4 tunnus (v4 UUID).
Sovellus vastaanottaa UVID-tunnuksen
Sovelluksesi saa UVID-tunnuksen asiakassovelluksen taustalta.
Sovellus luo PKCE-parametrit
Jos käytät PKCE-metodia, sovelluksesi luo code_verifier- ja code_challenge-parametrit.
RFC 7636:ssa määritetty PKCE-määritys sisältää myös valinnaisen code_challenge_method-parametrin, jonka voit lähettää valtuutuspyynnössä. Salesforce ei huomioi kaikkia tässä parametrissä lähettämiäsi arvoja ja käyttää oletusarvoisesti arvoa SHA256.
Sovellus vaihtaa UVID-tunnuksen valtuutuskoodille
Sovelluksesi lähettää GET- tai POST-pyynnön Experience Cloud -sivuston Salesforce-valtuutuksen päätepisteeseen ilman otsaketta. Pyyntö sisältää UVID-tunnuksen ja muita parametrejä, jotka tunnistavat sovelluksen ja määrittävät pyynnön tyypin.
Voit lähettää UVID-tunnuksen tässä pyynnössä kahdella eri tavalla. Voit lähettää tavallisen UVID-arvon tai lähettää JWT-pohjaisen käyttöoikeusvaltuuden, johon UVID on lisätty. Jos sinulla on esimerkiksi JWT-pohjainen käyttöoikeusvaltuus edellisestä istunnosta, valtuuden lähettäminen valtuutuksen päätepisteeseen on helppo tapa käyttää sitä uudelleen jäsentämättä sitä tarkalleen UVID-tunnukselle.
Lisää pyyntöösi nämä otsikot.
| Ylätunniste | Pakollinen? | Kuvaus |
|---|---|---|
Uvid-Hint
|
Pakollinen, jos et lähetä UVID-tunnusta pyynnön tekstiosassa. Sinun täytyy aina sisällyttää UVID — olipa se lähetetty ylätunnisteessa tai pyynnön tekstiosassa. | Sisältää joko UVID:n pelkkänä arvona tai JWT-pohjaisen käyttöoikeusvaltuuden, johon on lisätty UVID. Jos lähetät UVID-arvon pelkkänä arvona, lisää arvoon Jos lähetät JWT-pohjaisen käyttöoikeusvaltuuden UVID-tunnuksella, lisää arvoa ennen etuliite |
Auth-Request-Type
|
Kyllä. | Määrittää Salesforcelle lähetettävän pyynnön tyypin. Jos kirjaudut sisään ilman salasanaa, tämän arvon täytyy olla guest. |
Lisää pyynnön tekstiosaan nämä parametrit.
| Parametri | Pakollinen? | Kuvaus |
|---|---|---|
uvid_hint
|
Pakollinen, jos et sisällytä yläpalkkiin UVID-tunnusta. | Sisältää joko UVID:n pelkkänä arvona tai JWT-pohjaisen käyttöoikeusvaltuuden, johon on lisätty UVID. Jos lähetät UVID-arvon pelkkänä arvona, lisää arvoon Jos lähetät JWT-pohjaisen käyttöoikeusvaltuuden UVID-tunnuksella, lisää arvoa ennen etuliite |
client_id
|
Kyllä. | Ulkoisen asiakassovelluksen tai yhdistetyn sovelluksen kuluttaja-avain. |
response_type
|
Kyllä. | OAuth 2.0 -tarjoustyyppi, jota sovelluksesi pyytää. Koska tämä kulku on valtuutuskoodin ja tunnuksen kulun variaatio, tämän arvon täytyy olla code_credentials. |
redirect_uri
|
Kyllä. | URL-osoite, johon käyttäjät ohjataan onnistuneen todennuksen jälkeen. Käytä yksityisille asiakkaille |
code_challenge
|
Vain, jos käytät PKCE:tä, jota suosittelemme aina, varsinkin julkisille asiakkaille. | Määrittää valtuuspyynnössä olevan Jos valtuutuspyynnössä on Jos |
scope
|
Kyllä. | Käyttöoikeudet, jotka määrittävät, minkätyyppisiä suojattuja resursseja sovellus voi käyttää. Tässä pyynnössä lähettämiesi arvojen täytyy vastata ulkoiseen asiakassovellukseesi tai yhdistettyyn sovellukseesi kohdistettuja vaikutusalueita tai olla osa niitä. Lisätietoja kustakin vaikutusalueesta ja sen käyttötarkoituksesta on kohdassa OAuth-valtuudet ja vaikutusalueet. |
Nämä esimerkkivaltuutuspyynnöt toteuttavat kaikki PKCE:n.
Alla on esimerkki pyynnöstä, jossa UVID välitetään pelkkänä arvona pyynnön otsakkeessa.
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
Alla on esimerkki pyynnöstä, jossa UVID välitetään JWT-pohjaisessa käyttöoikeusvaltuudessa yläpalkissa.
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
Tässä esimerkissä UVID välitetään pelkkänä arvona pyynnön tekstiosassa.
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 palauttaa 302-uudelleenohjauksen
Salesforce vahvistaa UVID-tunnuksen. Jos UVID-arvo välitettiin pelkkänä arvona, Salesforce vahvistaa sen muodon. Jos se välitettiin JWT-pohjaisena käyttöoikeusvaltuutena, Salesforce tarkastaa valtuuden voimassaolon.
Salesforce palauttaa sitten HTTP 302 -uudelleenohjauksen esimääritettyyn URL-osoitteeseen, joka sisältää valtuutuskoodin. Jos kulku tapahtuu selaimessa, 302-uudelleenohjaus käsitellään selaimessa ja Salesforce lähettää uudelleenohjauksen vastauksen automaattisesti uudelleenohjauksen URL-osoitteeseen, joka osoittaa palvelinpuolen callback-kutsun käsittelijään asiakassovelluksen taustalla. Alla on esimerkki esimääritetystä URL-osoitteesta.
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 noutaa koodin ja vaihtaa sen käyttöoikeusvaltuudeksi
Asiakassovelluksen taustaohjelma noutaa valtuutuskoodin ja muut parametrit esimääritetystä URL-osoitteesta. Sen jälkeen se käynnistää koodinvaihdon lähettämällä koodin ja muut headless POST -pyynnön parametrit /services/oauth2/token-päätepisteeseen.
Lisää pyyntöön nämä otsikot.
| Parametri | Pakollinen? | Kuvaus |
|---|---|---|
Uvid-Hint
|
Kyllä. | Sisältää joko UVID:n pelkkänä arvona tai JWT-pohjaisen käyttöoikeusvaltuuden, johon on lisätty UVID. Älä sisällytä koodin vaihtoon UVID-osoitteen etuliitettä. Jos esimerkiksi välität UVID-arvon pelkkänä arvona, otsake on vain |
Auth-Request-Type
|
Kyllä. | Määrittää Salesforcelle lähetettävän pyynnön tyypin. Jos kirjaudut sisään ilman salasanaa, tämän arvon täytyy olla guest. |
Lisää pyynnön tekstiosaan nämä parametrit.
| Parametri | Pakollinen? | Kuvaus |
|---|---|---|
code
|
Kyllä. | Valtuutuspalvelin luo valtuutuskoodin, joka on väliaikainen valtuus, ja välittää sen asiakassovellukselle onnistuneen todennuksen jälkeen. Asiakassovellus lähettää valtuutuskoodin valtuutuspalvelimelle saadakseen käyttöoikeusvaltuuden ja mahdollisesti päivitysvaltuuden. |
client_id
|
Kyllä. | Ulkoisen asiakassovelluksen tai yhdistetyn sovelluksen kuluttaja-avain. |
client_secret
|
Kyllä. | Ulkoisen asiakassovelluksen tai yhdistetyn sovelluksen kuluttajasalaisuus. |
redirect_uri
|
Kyllä. | URL-osoite, johon käyttäjät ohjataan onnistuneen todennuksen jälkeen. Uudelleenohjauksen URI-osoitteen täytyy vastata jotakin ulkoisen asiakassovelluksen tai yhdistetyn sovelluksen Callback-URL-kentän arvoa. Muussa tapauksessa hyväksyntä epäonnistuu. Arvon tulee olla URL-koodattu. Käytä yksityisille asiakkaille |
grant_type
|
Kyllä. | Vahvistustyyppi, jonka sovellus voi tarjota todistaakseen, että se on turvallinen vierailija. Koska tämä kulku on valtuutuskoodin ja tunnuksen kulun variaatio, arvon täytyy olla authorization_code. |
code_verifier
|
Vain, jos käytät PKCE:tä. | Määrittää 128 tavua satunnaista ja tehokkaasti hajautettua dataa, jotta code-arvo olisi vaikea arvata. Määritä tämä parametri välttyäksesi valtuutuskoodien kaappaushyökkäyksiltä. Arvon täytyy olla base64url-koodattu kohdassa https://datatracker.ietf.org/doc/html/rfc4648#section-5 määritettynä. Jos valtuuspyynnössä on arvo Jos |
Alla on esimerkki valtuuspyynnöstä, joka toteuttaa PKCE:n. Tässä esimerkissä UVID lähetetään pelkkänä arvona.
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 myöntää JWT-pohjaisen käyttöoikeusvaltuuden
Kun olet vahvistanut sovelluksen tunnukset. Salesforce palauttaa vieraskäyttäjien JWT-käyttöoikeusvaltuuden ja osavaltion asiakassovelluksen taustalle. Vieraskäyttöoikeusvaltuus sisältää UVID-arvon aihelausekkeessa (sub). Alla on esimerkki JWT-pohjaisen käyttöoikeusvaltuuden koodikatkelmasta. Muistutuksena näillä valtuuksilla on kolme komponenttia: ylätunniste, hyötykuorma ja allekirjoitus. Tämä esimerkki näyttää sinulle hyötykuorman. Kuten näet, sub-lausekkeen UVID-arvo on etuliitteenä 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": "**********"
}Lisätietoja JWT-käyttöoikeusvaltuuden jokaisesta vaatimuksesta on Salesforce-ohjeen aiheessa JWT-käyttöoikeusvaltuudet.
Asiakkaan taustaprosessin käyttöoikeusvaltuuden vastaus
Asiakassovelluksen taustalla käsitellään käyttöoikeusvaltuuden vastaus ja tallennetaan UVID-arvo. Se palauttaa sovellukseesi vieraskäyttäjäistunnon. Se voi myös palauttaa JWT-pohjaisen käyttöoikeusvaltuuden, mutta sitä ei tarvita.
Sovellus luo vieraskäyttäjäistunnon
Sovelluksesi vastaanottaa valtuuden vastauksen asiakassovelluksen taustalta ja luo vieraskäyttäjäistunnon.
Tuntematon käyttäjä on nyt tunnistettu
Tuntematon loppukäyttäjä on nyt vieraskäyttäjäistunto sidottu UVID-arvoon, joka palautetaan JWT-pohjaisessa käyttöoikeusvaltuudessa. Sinä päätät tässä vaiheessa, mitä haluat tehdä UVID-tunnuksella. Lisätietoja sen välittämisestä nimettyyn käyttäjän valtuutuskulkuun on kohdassa Vieraskäyttäjä-kulun laajentaminen nimettyyn käyttäjäkulkuun.
