OAuth 2.0 för program från första part: Sidhuvudlös lösenordsfri inloggning för privata klienter
Med sidhuvudlös lösenordsfri inloggning loggar användare in i din app utanför plattformen via sin e-postadress eller telefonnummer och ett engångslösenord. För att konfigurera lösenordsfri inloggning för en app utanför plattformen som utvecklats av ditt företag, använd detta sidhuvudlösa lösenordsfria inloggningsflöde, som implementerar utkastprotokollet OAuth 2.0 för program från första part. Med detta flöde kan du helt styra frontend-inloggningsupplevelsen i din förstapartsapp medan Salesforce hanterar backendarbetet med att autentisera användare och bevilja åtkomst till skyddade resurser. Detta flöde stöds endast för privata klienter, som klient-server-appar, och stöds endast för externa användare.
Versioner som krävs
| Tillgängliga i: både Salesforce Classic och Lightning Experience |
| Tillgängliga i: Enterprise, Unlimited och Developer Edition |
För att konfigurera sidhuvudlös lösenordsfri inloggning för en privat klient kan du även använda den lösenordsfria inloggningsvarianten av auktoriseringskoden och inloggningsuppgifterflödet, som implementerar Sidhuvudlös identitet API:n. Båda flödena åstadkommer samma användningsfall—sidhuvudlös lösenordsfri inloggning för en app utanför Salesforce Platform. Men det finns några viktiga skillnader att tänka på.
| OAuth för appar från första part | Sidhuvudlös identitets-APIS |
|---|---|
| Stöds endast för privata klienter. | Stöds för offentliga och privata klienter. |
| Uppfyller utkastet till OAuth 2.0 för program från första part. | Egenutvecklat Salesforce-flöde som är byggt på OAuth 2.0-standarden. |
| Stöds endast för Salesforces ramverk för externa klientappar. Det enda sättet att konfigurera externa klientappinställningar för detta flöde är via Metadata API. | Stöds för både Salesforces externa klientapp och ramverk för anslutna appar. |
| För säkerhet kräver detta flöde alltid en JWT för klientintyg. Salesforce använder klientintyget JWT för att validera att appen har utvecklats av ditt företag. | Kräver antingen autentisering eller reCAPTCHA, men inte en JWT för klientintyg. |
Innan du konfigurerar detta flöde, utför dessa steg.
- Uppfyll förkraven för sidhuvudlös identitet.
- Skapa en JWT för klientintyg.
- Konfigurera en extern Salesforce-klientapp.
- Konfigurera Experience Cloud-inställningar.
Som standard anger användare sitt användarnamn för att logga in. För att ge användare fler alternativ, konfigurera sidhuvudlös användarupptäckt. Utveckla till exempel ett flöde där användare anger sin e-postadress, telefonnummer eller till och med ett ordernummer. Se Sidhuvudlös inloggning utan användarnamn.
Här är en översikt av hur flödet fungerar.
- Steg 1: En slutanvändare går till din förstapartsapp och anger sin e-postadress eller telefonnummer. Eller, om du använder sidhuvudlös användarupptäckt, anger de en identifierare som en e-postadress, ett telefonnummer eller ett ordernummer, tillsammans med sitt lösenord.
- Steg 2: Din app hittar användarnamnet som är associerat med användarens telefonnummer eller e-postadress.
- Steg 3: Din app skapar en JWT för klientintyg. Den skapar även parametrar för Proof Key for Code Exchange (PKCE).
- Steg 4: Din app från första part skickar en sidhuvudlös POST-begäran till slutpunkten services/oauth2/v1/authorization_challenge på din Experience Cloud-webbplats. Begäran innehåller användarens JWT för klientintyg och den information som användaren har skickat, tillsammans med andra parametrar.
- Steg 5: För att bekräfta att din förstapartsapp skickade begäran validerar Salesforce JWT för klientintyg och validerar sedan de andra parametrarna i begäran. Om begäran är framgångsrik returnerar Salesforce ett felmeddelande med en
auth_session, men svaret indikerar att Salesforce skickade en OTP till användaren. - (Valfritt) Om du använder sidhuvudlös användarupptäckt hittar din Apex hanterare användaren baserat på den identifierare som de använde för att logga in. Om användaruppgifterna är giltiga och användaren har en verifierad e-postadress eller telefonnummer fortsätter inloggningen.
- Steg 6: Salesforce skickar en OTP till användarens e-postadress eller telefonnummer.
- Steg 7: Din app visar inbyggt ett verifieringsformulär.
- Steg 8: Användaren anger sin OTP i verifieringsformuläret.
- Steg 9: Din app skickar en annan POST-begäran till slutpunkten services/oauth2/v1/authorization_challenge, denna gång för att begära en auktoriseringskod. Denna begäran inkluderar
auth_sessionsom returnerades från den första begäran tillsammans med den OTP som användaren angav. - Steg 10: Salesforce bekräftar begäran, returnerar auktoriseringskoden och avslutar
auth_session. - Steg 11: För att byta ut koden mot en åtkomsttoken skickar din förstapartsapp en begäran till slutpunkten /services/oauth2/token.
- Steg 12: Salesforce returnerar ett tokensvar som innehåller åtkomsttoken.
- Steg 13: Din app från första part bearbetar tokensvaret och skapar användarens session.
- Steg 14: Slutanvändaren är nu inloggad och utför en åtgärd i din app som kräver åtkomst till en skyddad Salesforce-resurs.
- Steg 15: Din förstapartsapp gör ett autentiserat anrop till en Salesforce API.
- Steg 16: Användaren kan nu komma åt sina Salesforce-data i din förstapartsapp.
Steg 1: Slutanvändare anger sin e-postadress eller telefonnummer för inloggning
En slutanvändare besöker din app från första part. Din app visar inbyggt ett inloggningsformulär som endast begär användarens e-postadress eller telefonnummer. Användaren anger sin e-postadress eller telefonnummer i formuläret.
Steg 2: Förstapartsapp hittar användarnamnet
Din app från första part hittar användarnamnet som är associerat med användarens telefonnummer eller e-postadress.
Steg 3: Förstapartsapp skapar en JWT för klientintyg och skapar code_verifier och code_challenge för PKCE
Appen startar en JWT för klientintyg.
Appen skapar även värden för de PKCE-parametrar som används för att bekräfta auktoriseringskoden.
Mer information om PKCE finns i specifikationenRFC 7636: Proof Key for Code Exchange by OAuth Public Clients som tillhandahålls av Internet Engineering Task Force (IETF).
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.
Steg 4: App skickar en inledande begäran till slutpunkten för auktoriseringsutmaning
För att inleda lösenordsfri inloggning skickar din app användarens inloggningsuppgifter tillsammans med andra parametrar till slutpunkten services/oauth2/v1/authorization_challenge på din Experience Cloud-webbplats via en sidhuvudlös POST-begäran.
Det finns inga obligatoriska sidhuvuden för denna begäran. Om du vill ansluta detta flöde till det sidhuvudlösa gästflödet kan du inkludera ett Uvid-Hint med en JWT-baserad åtkomsttoken som innehåller ett värde för unikt besökar-ID (UVID).
| Sidhuvud | Obligatorisk? | Beskrivning |
|---|---|---|
Uvid-Hint
|
Nej. Om du implementerar gästanvändarflödet i din app kan du om du vill använda detta sidhuvud för att skicka in en JWT-baserad åtkomsttoken som innehåller en UVID knuten till en gästanvändares identitet. Genom att skicka Istället för att skicka en JWT-baserad token med en |
En JWT-baserad åtkomsttoken som innehåller ett UVID, vilket är en universellt unik identifierare (UUID) av version 4 som skapas och hanteras helt av din app. För att få en åtkomsttoken med en UVID måste du aktivera din externa klientapp eller anslutna app för att utfärda JWT-baserade åtkomsttokens och implementera det sidhuvudlösa gästflödet i din app. |
Inkludera dessa parametrar i begärans brödtext.
| Parameter | Obligatorisk? | Beskrivning |
|---|---|---|
username
|
Ja. | Användarnamnet som är associerat med användarens e-postadress eller telefonnummer. |
login_type
|
Ja. | Metoden som användaren använder för att logga in. Värdet kan antingen vara sms eller email. |
client_assertion
|
Ja. | Den JWT för klientintyg som du skapade, signerad av certifikatet som konfigurerats för din externa klientapp. |
recaptcha_token
|
Krävs om dessa villkor gäller för din konfiguration:
|
En krypterad token utfärdad av Google reCAPTCHA API när en användare slutför en reCAPTCHA-utmaning. |
recaptchaevent
|
Krävs om dessa villkor gäller för din konfiguration:
|
Ett JSON-objekt som innehåller dessa underparametrar.
Mer information finns i Googles reCAPTCHA-dokumentation. |
scope
|
Nej. | Behörigheter som definierar vilken typ av skyddade resurser som den externa klientappen har åtkomst till. Du tilldelar omfattningar till den externa klientappen när du bygger den, och de inkluderas med OAuth-tokens under auktoriseringsflödet. Använd denna parameter för att begära en underuppsättning av de omfattningar som är tilldelade din externa klientapp. Om du inte inkluderar denna parameter begärs alla omfattningar som är tilldelade till appen. |
client_id
|
Ja. | Konsumentnyckeln för den externa klientappen. |
code_challenge
|
Krävs om du behöver PKCE för din externa klientapp. För att detta flödes säkerhetsfunktioner ska fungera korrekt rekommenderar vi starkt att du alltid kräver PKCE. | Anger SHA256-hashvärdet för Om en Om |
email_template
|
Krävs för att specificera flera e-postmallar om tillåtelselista för e-postmallar har aktiverats. Om du inte aktiverade tillåtelselista för e-postmallar kan du inte inkludera denna parameter. Om du inte inkluderar denna parameter använder Salesforce standardmallen för e-post konfigurerad i dina Experience Cloud-inställningar, oavsett om tillåtelselistning har aktiverats eller inte. Om det inte finns någon mall konfigurerad använder Salesforce en standardmall för e-post med OTP. Språket för e-postmallar för standardmallar styrs av användarens språkinställningar i Salesforce. |
Det egna namnet på utvecklaren för e-postmallar. Denna parameter kan endast inkludera en e-postmall från tillåtelselistan. För att styra språket för egna e-postmallar, skapa mallar på önskat språk. |
login_hint
|
Krävs om du använder en Apex hanterare för sidhuvudlös användarupptäckt. | En identifierare som din Apex hanterare använder för att hitta en användares Salesforce-konto. Samla till exempel in en användares ordernummer i din app och skicka det till login_hint. Vi skickar login_hint direkt till din Apex hanterare. |
customdata
|
Krävs om du använder en sidhuvudlös användares upptäckarhanterare som hanterar egna data. Om du till exempel även använder hanteraren med ett inloggningsflöde som hanterar egna data måste du skicka egna data i flödet för glömt lösenord. Annars är det valfritt men kan vara användbart för att hjälpa din hanterare hitta användaren. |
En JSON-sträng som innehåller ytterligare data som din Apex sidhuvudlösa upptäckare använder för att hitta en användares Salesforce-konto. Skicka till exempel information om användarens plats. |
Här är ett exempel på en begäran.
POST /services/oauth2/v1/authorization_challenge HTTP/1.1
Host: MyExperienceCloudSite.my.site.com
username=janice.edwards@example.com&
login_type=sms&
client_assertion=**********&
recaptcha_token=********&
scope=profile&
client_id=******&
code_challenge=********Steg 5: Salesforce validerar begäran
Salesforce försöker först validera JWT för klientintyg genom att kontrollera att signaturen som skickas i client_asssertion matchar signaturen för certifikatet som konfigurerats för den externa klientappen.
Om JWT för klientintyg inte är giltig returnerar Salesforce ett invalid_attestation och du måste skicka in begäran igen med alla de parametrar du ursprungligen skickade in. Här är ett exempel på ett felsvar.
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error": "invalid_attestation",
"error_code": "client_attestation_failed"
}
Om JWT för klientintyg är giltig men det finns andra problem med begäran returnerar Salesforce ett felmeddelande som specificerar vad som gick fel. Här är ett exempelsvar som returneras om Salesforce inte kan hitta ett användarnamn som matchar det som skickas i begäran.
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error": "authorization_required",
"auth_session": "uY29tL2F1d*****",
"error_code": "invalid_credentials"
}Svaret innehåller en auth_session som förblir giltig i 5 minuter efter att den utfärdats. Under tidsperioden medan auth_session är giltig kan du använda den för att skicka in begäran igen. I de korrigerade versioner du skickar in igen, inkludera auth-session och de korrigerade värdena för de parametrar som gjorde att begäran misslyckades. Du måste även skicka in password igen med varje begäran eftersom Salesforce inte lagrar detta känsliga värde. Men för andra parametrar, om de inte orsakade att begäran misslyckades, kan du utelämna dem. Salesforce vet redan att du har skickat dessa parametrar eftersom de är länkade till auth_session.
auth_session, men du kan skicka in begäran igen utan dem om de inte orsakade att begäran misslyckades.Till exempel, om din JWT för klientintyg är giltig men begäran misslyckas på grund av att användarnamnet var felaktigt, skicka in en begäran igen som endast innehåller auth_session, username och password.
(Valfritt) Sidhuvudlös användare Discovery-hanterare hittar användaren
Om du använder en upptäckare utan sidhuvud tar hanteraren login_hint och customdataparametrarna och hittar den associerade användaren. Hanteraren bekräftar att e-postadressen eller telefonnumret till användaren har verifierats.
För ett exempel på en hanterare, se Auth.HeadlessUserDiscoveryHandler.
Steg 6: Salesforce skickar en OTP till användaren
Om begäran är framgångsrik returnerar Salesforce fortfarande ett felsvar eftersom det ännu inte kan bevilja auktoriseringskoden. Men den här gången indikerar felmeddelandet att inloggning har inletts och att Salesforce har skickat en OTP till användarens e-postadress eller telefonnummer. För att bekräfta att begäran lyckades, se upp för login_initialized av felkod och otp_sent av delstat. Svaret innehåller även en auth_session, vilket är viktigt för nästa steg.
Här är ett exempelsvar.
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"
}
}Steg 7: Din app visar ett verifieringsformulär inbyggt
I din förstapartsapp visar du ett verifieringsformulär där slutanvändaren kan ange sin OTP. Utseendet och känslan för detta formulär är helt upp till dig.
Steg 8: Användare anger OTP i verifieringsformulär
Användaren får OTP på sin e-postadress eller telefonnummer och anger det i verifieringsformuläret i din förstapartsapp.
Steg 9: Din app begär en auktoriseringskod
För att begära en auktoriseringskod skickar din app en annan POST-begäran till slutpunkten /services/oauth2/v1/authorization_challenge. Denna begäran har inga obligatoriska sidhuvuden. Inkludera dessa parametrar i begärans brödtext.
| Parameter | Obligatorisk? | Beskrivning |
|---|---|---|
auth_session
|
Ja. | Representerar det aktuella inloggningsförsöket. Använd det auth_session som du fick i svaret från din första begäran till slutpunkten för auktoriseringsutmaningen. Se till att använda auth_session från begäran som indikerade att inloggning initierades och OTP skickades. |
login_otp
|
Ja. | Den OTP som slutanvändaren angav i din apps verifieringsformulär. |
Här är ett exempel på en begäran.
POST /services/oauth2/v1/authorization_challenge HTTP/1.1
Host: MyExperienceCloudSite.my.site.com
auth_session=uY29tL2F1dGhlbnRpY*
login_otp=<otp_from_sms>Steg 10: Salesforce returnerar en auktoriseringskod
Om OTP är korrekt och auth_session är giltig returnerar Salesforce en auktoriseringskod och avslutar auth_session. Här är ett exempel på ett svar för auktoriseringskod.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
{
"authorization_code": "uY29tL2F1d******"
}Steg 11: Din app byter ut auktoriseringskoden mot en åtkomsttoken
När du har fått auktoriseringskoden skickar din app en begäran till slutpunkten services/oauth2/token.
Denna begäran har inga sidhuvuden. 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. |
client_secret
|
Ja. | Konsumenthemligheten för den externa klientappen. I detta flöde fungerar det som ett lösenord som appen använder för att komma åt Salesforce. |
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 klientappens fält Callback-URL. Annars misslyckas godkännandet. Detta värde måste vara URL-kodat. |
grant_type
|
Ja. | Den typ av validering som appen kan tillhandahålla för att bevisa att den är en säker besökare. För detta flöde måste värdet vara authorization_code. |
code_verifier
|
Krävs om du behöver PKCE för din externa klientapp. För att detta flödes säkerhetsfunktioner ska fungera korrekt rekommenderar vi starkt att du alltid kräver 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.
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=*******Steg 12: Salesforce beviljar en åtkomsttoken
Efter validering av appens inloggningsuppgifter. Salesforce returnerar en åtkomsttoken. Här är ett exempel på ett svar för åtkomsttoken i JSON-format.
{
"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"
}Åtkomsttokensvaret innehåller dessa parametrar.
| Parameter | Obligatorisk? | Beskrivning |
|---|---|---|
access_token
|
Ja. | OAuth-token som en extern klientapp använder för att begära åtkomst till en skyddad resurs åt klientprogrammet. Ytterligare behörigheter i form av omfattningar kan medfölja åtkomsttoken. |
id
|
Ja. | En identitets-URL som kan användas både för att identifiera användaren och som en sökfråga för mer information om användaren. Se Identitets-URL:er. |
id_token
|
Nej. | En signerad datastruktur som innehåller autentiserade användarattribut, inklusive en unik identifierare för användaren och en tidsstämpel som anger när token utfärdades. Den identifierar även den begärande appen. Se Specifikationer för OpenID Connect. |
instance_url
|
Ja. | En URL som anger instansen för användarens organisation. Till exempel https://yourInstance.salesforce.com/. |
issued_at
|
Ja. | Tidsstämpel för när signaturen skapades, uttryckt som antal millisekunder från 1970-01-01T0:0:0Z UTC. |
refresh_token
|
Nej. | Token som fåtts från webbservern, användaragenten eller hybridappens tokenflöde. Detta värde är en hemlighet. Vidta lämpliga åtgärder för att skydda det. Denna parameter returneras endast om din externa klientapp eller anslutna app har konfigurerats med ett refresh_token. |
signature
|
Ja. | Base64-kodad HMAC-SHA256-signatur signerad med client_secret. Signaturen kan innehålla det sammanlänkade ID:t och issued_at, som du kan använda för att bekräfta att identitets-URL:en inte har ändrats sedan servern skickade den. |
sfdc_community_url
|
Ja. | URL för Experience Cloud-webbplatsen. |
sfdc_community_id
|
Ja. | Användarens webbplats-ID för Experience Cloud. |
state
|
Nej. | Det läge som begärs av klienten. Detta värde inkluderas endast om parametern state inkluderas i den ursprungliga sökfrågesträngen. |
token_type
|
Ja. | En Bearer som används för alla svar som inkluderar en åtkomsttoken. |
Steg 13: Appen skapar användarens session
Din app tar emot åtkomsttokensvaret, bearbetar det och skapar användarens session.
Steg 14: Användare är inloggad och utför en åtgärd i appen
Slutanvändaren är nu inloggad och utför en åtgärd i din app som kräver åtkomst till Salesforce-data. Till exempel klickar de på en knapp för att se sin orderhistorik, som lagras i Salesforce.
Steg 15: Appen gör ett autentiserat samtal till en Salesforce-slutpunkt
För att komma åt användarens Salesforce-data använder din app åtkomsttoken för att göra ett autentiserat anrop till en skyddad Salesforce-slutpunkt, till exempel en Salesforce API.
Steg 16: Användare kan komma åt Salesforce-data
Användaren kan nu komma åt skyddade Salesforce-data i din app. De kan till exempel se sin orderhistorik. Från användarens perspektiv inträffade hela processen från att logga in till att komma åt deras data utan att behöva att de någonsin behöver lämna appen.
