OAuth 2.0 webserverstroom voor webapp-integratie
Als u een externe webapp wilt integreren met de Salesforce-API, gebruikt u de OAuth 2.0-webserverstroom, die het toekenningstype van de OAuth 2.0-autorisatiecode implementeert. Met deze stroom moet de server die de webapp host, in staat zijn de identiteit van de verbonden app te beschermen, die wordt gedefinieerd door de client-ID en het clientgeheim.
Vereiste editions
| Beschikbaar in: Salesforce Classic (niet in alle organisaties beschikbaar) en Lightning Experience |
| Beschikbaar in: alle editions |
Zie Nieuwe verbonden apps kunnen niet meer worden gemaakt in Spring '26 voor meer informatie.
Het wordt aangeraden om voor speciale scenario's de webserverstroom met PKCE (uitgesproken als "pixy", Proof Key for Code Exchange) te gebruiken in plaats van de stroom username-password. Gebruik de parameters code_challenge en code_verifier om PKCE te implementeren met de webserverstroom. Zie de site van de Internet Engineering Task Force (IETF) voor meer informatie over PKCE. We raden ook aan om verbonden apps niet toe te staan de stroom user-agent of de stroom username-password te gebruiken. Zie Autorisatiestromen blokkeren voor verbeterde beveiliging voor stappen.
Dit is een voorbeeld van een gebruikscase voor implementatie van de webserverstroom. U hebt onlangs een webservice ontwikkeld die beveiligde toegang mogelijk maakt tot de orderstatus van klanten. De orderstatusgegevens worden beveiligd opgeslagen in uw Salesforce CRM-platform. Als u helpdeskgebruikers wilt autoriseren de orderstatus van een klant weer te geven, ontwikkelt u een app genaamd Orderstatus en configureert u deze als een verbonden app met de webserverstroom.
- Een helpdeskgebruiker klikt op de webapp Orderstatus.
- De verbonden app post een aanvraag van een autorisatiecode naar het Salesforce-autorisatie-eindpunt.
- De gebruiker wordt doorgestuurd naar de Salesforce-inlogpagina. Na een geslaagde inlogpoging wordt de gebruiker gevraagd de toegang van de app tot de orderstatusgegevens goed te keuren.
- Nadat de gebruiker heeft goedgekeurd dat de app Orderstatus toegang tot de gegevens krijgt, stuurt Salesforce een call-back met een autorisatiecode naar de app Orderstatus.
- De app Orderstatus geeft de autorisatiecode door aan het Salesforce-tokeneindpunt, om een toegangstoken aan te vragen.
- Salesforce valideert de autorisatiecode en stuurt een toegangstoken terug dat de bijbehorende machtigingen bevat in de vorm van bereiken.
- De app Orderstatus stuurt een aanvraag terug naar Salesforce om toegang te krijgen tot de orderstatusgegevens. Het verzoek bevat het toegangstoken met bijbehorende bereiken.
- Salesforce valideert het toegangstoken en de bijbehorende bereiken.
- De app Orderstatus kan toegang tot de beschermde gegevens krijgen en de orderstatus van de klant wordt in de app weergegeven.Opmerking Als het toegangstoken ongeldig wordt, kan de verbonden app een vernieuwingstoken gebruiken om een nieuw toegangstoken te krijgen.
Laten we de stappen van deze autorisatiestroom eens wat beter kijken.
- Een autorisatiecode aanvragen
- Gebruiker verifieert en autoriseert toegang
- Salesforce verleent autorisatiecode
- Toegangstoken aanvragen
- Salesforce verleent een toegangstoken
Een autorisatiecode aanvragen
De externe webservice initieert de OAuth 2.0-webserverstroom door via de verbonden app met behulp van het toekenningstype autorisatiecode een aanvraag van een autorisatiecode te posten naar het Salesforce-autorisatie-eindpunt. Met een autorisatiecode kan de verbonden app bewijzen dat deze als een veilige bezoeker van de site is geautoriseerd en gemachtigd is om een toegangstoken aan te vragen.
De autorisatiecode heeft de vorm van een HTTP-omleiding.
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=codeNeem deze parameters op in een aanvraag van een autorisatiecode.
| Parameter | Beschrijving |
|---|---|
Request Header
|
Het Salesforce OAuth 2.0-autorisatie-eindpunt. Verbonden apps sturen OAuth-autorisatieaanvragen naar dit eindpunt. |
client_id
|
De consumentensleutel van de verbonden app. Als u toegang wilt tot de consumentensleutel, zoekt u in Appbeheer de verbonden app en selecteert u Weergeven in de vervolgkeuzelijst. Klik vervolgens op Consumentengegevens beheren. Soms wordt u gevraagd uw identiteit te verifiëren voordat u de consumentensleutel kunt weergeven. |
redirect_uri
|
De URL waar gebruikers naartoe worden omgeleid na een succesvolle authenticatie. De omleidings-URI moet overeenkomen met een van de waarden in het veld Call-back-URL van de verbonden app. Als dat niet het geval is, mislukt de goedkeuring. U vindt de omleidings-URI op de pagina Verbonden apps beheren van de verbonden app of in de definitie van de verbonden app. Deze waarde moet een URL-codering hebben. |
response_type
|
Het OAuth 2.0-toekenningstype dat de verbonden app aanvraagt. De waarde voor deze stroom moet code zijn om aan te geven dat de verbonden app een autorisatiecode aanvraagt. |
U kunt ook deze parameters in een aanvraag van een autorisatiecode opnemen.
| Parameter | Beschrijving |
|---|---|
scope
|
Machtigingen die het type beschermde resources definiëren waartoe een verbonden app toegang kan krijgen. U wijst bereiken toe aan een verbonden app wanneer u deze samenstelt; tevens worden deze opgenomen bij de OAuth-tokens tijdens de autorisatiestroom. Als u deze parameter niet opneemt, wordt om alle bereiken gevraagd, die zijn toegewezen aan de verbonden app. De bereiken die worden doorgegeven in deze parameter, moeten een subset vormen van de geregistreerde bereiken. |
sso_provider
|
De naam van de ontwikkelaar van een Single Sign-On-identiteitsleverancier (SSO) die is geconfigureerd met een inlog-URL voor Mijn domein of een URL voor een Experience Cloud-site. U kunt deze parameter gebruiken om een SSO-omgeving te maken die aanvoelt alsof uw app is geïntegreerd met de SSO-leverancier. U kunt deze parameter bijvoorbeeld gebruiken om SSO aan te bieden in een Headless Identity-implementatie. |
state
|
De status waarvan de externe webservice vraagt dat deze naar de call-back-URL wordt verzonden. Deze waarde moet een URL-codering hebben. |
immediate
|
Een booleaanse waarde om te bepalen of de gebruiker een aanwijzing krijgt voor inloggen en goedkeuring. De standaardwaarde is
De optie |
code_challenge
|
Geeft de SHA256-hashwaarde aan van de Deze parameter is verplicht als er een
|
display
|
Wijzigt het weergavetype van de inlog- en autorisatiepagina’s. Salesforce ondersteunt deze waarden.
|
login_hint
|
Biedt een geldige gebruikersnaamwaarde om de inlogpagina vooraf in te vullen met de gebruikersnaam, zoals Geef voor het doorgeven van de parameter |
nonce
|
Gebruik dit bij het bereik openid om een gebruikers-ID-token aan te vragen. Het ID-token van de gebruiker wordt geretourneerd in de respons. Deze parameter is optioneel, maar helpt replay-aanvallen te detecteren.
|
prompt
|
Geeft op hoe de autorisatieserver de gebruiker om hernieuwde authenticatie en hernieuwde goedkeuring vraagt. Salesforce ondersteunt deze waarden.
U kunt |
Uvid-Hint header |
Als u deze stroom wilt verbinden met de headless gaststroom, kunt u desgewenst een Als u de gastgebruikersstroom implementeert in uw app, kunt u deze header optioneel gebruiken om een op JWT (JSON Web Token) gebaseerd toegangstoken door te geven met daarin een unieke bezoekers-ID die is gekoppeld aan de identiteit van een gastgebruiker. Door de UVID door te geven aan een benoemde gebruikersstroom kunt u contextuele informatie van een gastgebruikerssessie, zoals de cookievoorkeuren van de gebruiker, overdragen aan een benoemde gebruikerssessie. |
Hoofdtekstparameter uvid_hint |
Een platte In plaats van de UVID door te geven in de hoofdtekst van de aanvraag, kunt u deze ook doorgeven in een op JWT gebaseerd token met een UVID via de |
Gebruiker verifieert en autoriseert toegang
Voordat Salesforce autorisatiecodes afgeeft aan verbonden apps, moeten gebruikers inloggen bij hun Salesforce-organisatie.
Na een geslaagde inlogpoging stuurt Salesforce gebruikers door naar de goedkeuringspagina om toegang te verlenen aan de app.
Als gebruikers eerder toegang hebben goedgekeurd, hoeven ze dat niet nog een keer te doen.
Salesforce verleent autorisatiecode
Nadat gebruikers toegang van een verbonden app hebben goedgekeurd, stuurt Salesforce gebruikers door naar de call-back-URL, waar ze de call-back met een autorisatiecode kunnen weergeven.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- Het eerste deel van de callback is de callback-URL van de verbonden app:
https://www.mycustomerorderstatus.com/oauth2/callback. - Het tweede deel is de autorisatiecode die de verbonden app gebruikt om een toegangstoken te verkrijgen:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==. De autorisatiecode verloopt na 15 minuten.
Als de parameter state is opgenomen in de oorspronkelijke querytekenreeks, wordt de opgegeven status doorgegeven aan de goedkeuringsstap.
Toegangstoken aanvragen
Als u een toegangstoken aanvraagt, geeft de verbonden app de autorisatiecode aan het Salesforce-tokeneindpunt door als een HTTP POST.
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
De POST in het voorbeeld bevat de volgende parameters.
| Parameter | Beschrijving |
|---|---|
Request Header
|
De aanvraagheader kan de volgende parameters bevatten.
De aanvraagheader ondersteunt ook deze parameters.
De parameter |
grant_type
|
Het type validatie dat de verbonden app kan bieden om te bewijzen dat het een veilige bezoeker is. Voor de webserverstroom moet de waarde authorization_code zijn. |
code
|
Een tijdelijke autorisatiecode die wordt ontvangen van de autorisatieserver. De verbonden app gebruikt deze code voor uitwisseling tegen een toegangstoken. Dit type OAuth 2.0-stroom is een beveiligde manier om het toegangstoken terug te geven aan de toepassing. |
client_id
|
De consumentensleutel van de verbonden app. Als u toegang wilt tot de consumentensleutel, zoekt u in Appbeheer de verbonden app en selecteert u Weergeven in de vervolgkeuzelijst. Klik vervolgens op Consumentengegevens beheren. Soms wordt u gevraagd uw identiteit te verifiëren voordat u de consumentensleutel kunt weergeven. |
client_secret
|
Het consumentengeheim van de verbonden app. Als u toegang wilt tot het consumentengeheim, zoekt u in Appbeheer de verbonden app en selecteert u Weergeven in de vervolgkeuzelijst. Klik vervolgens op Consumentengegevens beheren. Soms wordt u gevraagd uw identiteit te verifiëren voordat u het consumentengeheim kunt weergeven. Deze parameter is vereist tenzij voor de verbonden app Geheim vereisen voor webserverstroom niet is ingeschakeld. Als een |
redirect_uri
|
De URL waar gebruikers naartoe worden omgeleid na een succesvolle authenticatie. De omleidings-URI moet overeenkomen met een van de waarden in het veld Call-back-URL van de verbonden app. Als dat niet het geval is, mislukt de goedkeuring. U vindt de omleidings-URI op de pagina Verbonden apps beheren van de verbonden app of in de definitie van de verbonden app. Deze waarde moet een URL-codering hebben. |
U kunt ook deze parameters opnemen.
| Parameter | Beschrijving |
|---|---|
client_assertion
|
In plaats van een client_secret door te geven, kunt u een client_assertion en client_assertion_type opgeven. Als er geen parameter client_secret wordt opgegeven, controleert Salesforce op de client_assertion en client_assertion_type.
|
client_assertion_type
|
Geef deze waarde op bij gebruik van de parameter De waarde van |
code_verifier
|
Alleen verplicht als er een code_challenge-parameter is opgegeven in de autorisatieaanvraag. Geeft 128 bytes aan willekeurige gegevens met hoge entropie op om het raden van de
|
format
|
Als de verwachte retournotatie niet is opgenomen in de header van het verzoek, kunt u deze opgeven. De parameter
|
client_assertion in plaats van client_secret.Als u een client_assertion opgeeft in plaats van een client_secret, moet de waarde van client_assertion deze parameters bevatten.
iss—Declient_iduit de definitie van de verbonden app.sub—Declient_iduit de definitie van de verbonden app.aud—De URL van de tokenservlet: https://hostnaam/services/oauth2/token.exp—De vervaltijd van de definitie binnen 5 minuten, uitgedrukt als het aantal seconden vanaf 1970-01-01T0:0:0Z gemeten in UTC.
De client_assertion moet ook worden ondertekend met de privésleutel die is gekoppeld aan het geüploade certificaat van de OAuth-consument. Alleen het RS256-algoritme wordt ondersteund. Zie de OpenID Connect-specificaties voor de authenticatiemethode van de private_key_jwt.
In plaats van clientgegevens als parameters te verzenden in de hoofdtekst van de POST, ondersteunt Salesforce het authenticatieschema HTTP Basic. De indeling van dit schema vereist de volgende client_id en client_secret in de autorisatieheader van de post:
Authorization: Basic64Encode(client_id:secret)
De client_id en client_secret worden gescheiden met een dubbele punt (:). Zie het document OAuth 2.0 Authorization Framework voor meer informatie.
In dit voorbeeld ziet u een POST-verzoek voor een toegangstoken waarin het authenticatieschema HTTP Basic wordt gebruikt (in plaats van clientinloggegevens te verzenden in de hoofdtekst van het POST-verzoek).
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id en client_secret worden verzonden in de hoofdtekst van de POST, wordt de autorisatieheader genegeerd.Salesforce verleent een toegangstoken
Nadat Salesforce de inloggegevens van de verbonden app heeft gevalideerd, wordt er een respons teruggestuurd met het toegangstoken. In dit voorbeeld heeft de respons de JSON-indeling.
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
De respons bevat de volgende parameters.
| Parameter | Beschrijving |
|---|---|
access_token
|
Een OAuth-token dat een verbonden app gebruikt om toegang tot een beschermde resource aan te vragen namens de clienttoepassing. Het toegangstoken kan vergezeld gaan van aanvullende machtigingen in de vorm van bereiken. |
signature
|
Base64-gecodeerde HMAC-SHA256-handtekening ondertekend met de client_secret. De handtekening kan de aaneengeschakelde ID en issued_at value bevatten, die u kunt gebruiken om te controleren of de identiteits-URL niet is gewijzigd sinds de server deze heeft verzonden. |
scope
|
De bereiken die zijn gekoppeld aan het toegangstoken. Bereiken definiëren meer gedetailleerd het type beschermde resources waartoe de client toegang kan krijgen. U wijst bereiken toe aan een verbonden app wanneer u deze samenstelt; tevens worden deze opgenomen bij de OAuth-tokens tijdens de autorisatiestroom. |
id_token
|
Een structuur voor ondertekende gegevens, die kenmerken van de geauthenticeerde gebruiker bevat, inclusief een unieke identifier voor de gebruiker en een tijdstempel dat aangeeft wanneer het token is uitgegeven. Het identificeert ook de aanvragende clienttoepassing. Zie OpenID Connect-specificaties. Deze parameter wordt geretourneerd als de parameter scope |
instance_url
|
Een URL die het exemplaar van de organisatie van de gebruiker aangeeft. Bijvoorbeeld: https://yourInstance.salesforce.com/.
|
id
|
Een identiteits-URL die kan worden gebruikt voor het identificeren van de gebruiker en voor het uitvoeren van een query voor meer informatie over de gebruiker. Zie Identiteits-URL's. |
token_type
|
Een Bearer, dat wordt gebruikt voor alle responsen die een toegangstoken bevatten.
|
issued_at
|
Het tijdstempel voor wanneer de handtekening is gemaakt, in milliseconden. |
De respons kan ook deze parameters bevatten.
