OAuth 2.0 voor toepassingen van eerste partij: Stroom Headless registratie voor privéclients

Stap 1: Gebruiker opent externe app en klikt op Registreren

Een gebruiker opent uw eigen app en klikt op een registratiekoppeling. Of ze klikken op een koppeling voor toegang tot een resource die registratie vereist.

Stap 2: Registratieformulier voor weergaven van apps van eerste partij

In uw eigen app geeft u een eigen registratieformulier weer om informatie over de gebruiker te verzamelen. U hebt volledige controle over dit formulier, inclusief het uiterlijk en de werking ervan, en de gebruikersgegevens die u wilt verzamelen.

Er zijn enkele punten van belang als u gaat beslissen welke gegevens van gebruikers u wilt verzamelen. Wanneer uw app gebruikersgegevens indient bij het eindpunt van de autorisatie-uitdaging, controleert Salesforce op de aanwezigheid van een e-mailadres, gebruikersnaam, achternaam en wachtwoord. U kunt deze gegevens verzamelen van gebruikers of automatisch genereren, maar deze gegevens moeten worden opgenomen in uw POST-aanvraag. Wanneer u besluit welke gegevens u wilt opnemen, moet u een e-mailadres of telefoonnummer verzamelen zodat de gebruiker zijn of haar identiteit kan verifiëren.

Stap 3: Gebruiker voert gegevens in

De gebruiker voert in het registratieformulier van uw app zijn of haar gegevens in.

Stap 4: First-Party App Mint een Client Attestation JWT en genereert code_verifier en code_challenge voor PKCE

De app maakt een klantenattest JWT.

De app genereert ook waarden voor de PKCE-parameters die worden gebruikt om de autorisatiecode te verifiëren.

Opmerking Het wordt sterk aanbevolen om PKCE altijd te implementeren voor deze stroom. Anders krijgt u de beveiligingsvoordelen ervan niet.

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.

Stap 5: App verzendt initiële aanvraag naar het eindpunt Autorisatie-uitdaging

Vanuit de browser verzendt uw app een POST-aanvraag naar het eindpunt services/oauth2/v1/authorization_challenge op uw Experience Cloud-site.

Neem deze header indien nodig op in uw verzoek.

Neem deze parameters op in de hoofdtekst van de aanvraag.

Hier is een voorbeeld van een eerste registratieaanvraag.

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
{
    "userdata": {
        "firstname": "Janice"
        "lastname": "Edwards"
        "email": "janice.edwards@example.com"
        "username": "jedwards@myapp.com"
        }
    "customdata": {
        "mobilePhone"="<mobile phone number>"
        }
    "password":"*********"
    "recaptcha": "*******"
    "login_type": "email"
    "emailtemplate": "unfiled$public/SalesNewCustomerEmail"
    "client_assertion": "Y2xpZW50YXNzZXJ0aW9u..."
}

Stap 6: Salesforce valideert het verzoek

Salesforce probeert eerst het JWT van het clientattest te valideren door te valideren dat de handtekening die wordt doorgegeven in de parameter client_asssertion, overeenkomt met de handtekening voor het certificaat dat is geconfigureerd voor de externe clientapp.

Als het JWT van het clientattest niet geldig is, retourneert Salesforce een invalid_attestation en moet u de aanvraag opnieuw indienen met alle parameters die u oorspronkelijk hebt ingediend. Hier is een voorbeeld van een foutreactie.

Als het JWT van het clientattest geldig is, maar er andere problemen zijn met het verzoek, retourneert Salesforce een foutrespons die aangeeft wat er mis was met het verzoek. De respons bevat ook een parameter auth_session die 5 minuten geldig blijft nadat deze is uitgegeven. Gedurende de periode dat de auth_session geldig is, kunt u deze gebruiken om de aanvraag opnieuw in te dienen. Neem in de gecorrigeerde versies die u opnieuw indient, alleen de gecorrigeerde waarden op voor de parameters die ervoor hebben gezorgd dat het verzoek is mislukt. U moet de password ook bij elk verzoek opnieuw indienen, omdat Salesforce deze niet opslaat. Maar voor andere parameters geldt dat als ze niet hebben geleid tot het mislukken van het verzoek, u ze kunt weglaten. Ze worden al vertegenwoordigd door de auth_session.

Opmerking reCAPTCHA-parameters worden niet gekoppeld aan de auth_session, maar u kunt de aanvraag opnieuw indienen zonder deze parameters, tenzij deze ertoe hebben geleid dat de aanvraag is mislukt.

Als bijvoorbeeld uw JWT van het cliëntenattest geldig is, maar het verzoek mislukt omdat de gebruikersnaam onjuist is, dient u opnieuw een verzoek in dat alleen de auth_session, username en password bevat.

Stap 7: Salesforce verzendt een eenmalig wachtwoord naar de gebruiker

Als het verzoek slaagt, retourneert Salesforce nog steeds een foutrespons omdat de autorisatiecode nog niet kan worden verleend. Maar deze keer geeft de foutrespons aan dat het inloggen is geïnitialiseerd en dat Salesforce een eenmalig wachtwoord heeft verzonden naar het e-mailadres of telefoonnummer van de gebruiker. Let op de login_initialized van de foutcode en de otp_sent van de staat om te controleren of de aanvraag is geslaagd. De respons bevat ook een parameter auth_session, die belangrijk is voor de volgende stap.

Hier is een voorbeeld van een respons.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "authorization_required",
  "auth_session": "uY29tL2F1dGhlbnRpY",
  "error_code": "login_initialized",
  "login_status": {
    "type": "SMS",
    "state": "otp_sent",
    "displayData": "+120******58"
   }
}

Stap 8: In de app wordt een verificatieformulier weergegeven

In uw eigen app geeft u een verificatieformulier weer waarin de eindgebruiker zijn of haar eenmalig wachtwoord kan opgeven. Het uiterlijk van dit formulier is volledig aan u.

Stap 9: Gebruiker geeft het eenmalige wachtwoord op in het verificatieformulier

De gebruiker ontvangt het eenmalige wachtwoord en voert het in op het verificatieformulier in uw eigen app.

Stap 10: Uw app vraagt een autorisatiecode aan

Als u een autorisatiecode wilt aanvragen, stuurt uw app de auth_session en het eenmalige wachtwoord die de gebruiker heeft opgegeven, naar het eindpunt van de autorisatie-uitdaging met behulp van een andere POST-aanvraag naar services/oauth2/v1/authorization_challenge Dit verzoek heeft geen verplichte headers. Neem deze parameters op in de hoofdtekst van de aanvraag.

Hier is een voorbeeld van een verzoek.

POST /authorize HTTP/1.1
Host: MyExperienceCloudSite.my.site.com

auth_session=uY29tL2F1dGhlbnRpY*
login_otp=<otp_from_sms>

Stap 11: Salesforce retourneert een autorisatiecode

Als het eenmalige wachtwoord correct is en het auth_session geldig is, retourneert Salesforce een autorisatiecode en wordt de auth_session beëindigd. Hier is een voorbeeld van een respons met autorisatiecode.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "authorization_code": "uY29tL2F1d******"
}

Stap 12: Uw app wisselt de autorisatiecode uit voor een toegangstoken

Nadat u de autorisatiecode hebt ontvangen, stuurt uw app een aanvraag naar het Salesforce-tokeneindpunt.

Dit verzoek heeft geen headers. Neem deze parameters op in de hoofdtekst van de aanvraag.

Hier is een voorbeeld van een tokenaanvraag.

POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

code=********&
client_id=**********&
client_secret=*********&
redirect_uri=<callback_URL>&
grant_type=authorization_code&
code_verifier=*******

Stap 13: Salesforce verleent een toegangstoken

Na het valideren van de inloggegevens van de app. Salesforce retourneert een toegangstoken. Dit is een voorbeeld van een respons met een toegangstoken in de JSON-indeling.

{
"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 toegangstokenrespons bevat deze parameters.

Stap 14: App maakt de sessie van de gebruiker

Uw externe app verwerkt de tokenrespons en zet de gebruikerssessie op.

Stap 15: Gebruiker is geregistreerd en voert een actie uit in de app

De gebruiker is nu geregistreerd en ingelogd. De gebruiker voert een actie uit in uw app waarvoor toegang tot Salesforce-gegevens nodig is. 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.

Stap 16: 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.

Stap 17: Gebruiker 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.