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, de identiteit van de externe clientapp kunnen beschermen, 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 |
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 dat u alle externe clientapps blokkeert voor het gebruik van de stroom user-agent of de stroom username-password. 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 Help Desk-gebruikers de orderstatus van een klant wilt laten weergeven, ontwikkelt u een app Orderstatus en configureert u deze als een externe clientapp met de webserverstroom.
- Een helpdeskgebruiker klikt op de webapp Orderstatus.
- De externe clientapp 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 externe clientapp een vernieuwingstoken gebruiken om een nieuw toegangstoken te verkrijgen.
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
Om de OAuth 2.0-webserverstroom te initiëren post de externe webservice via de externe clientapp een aanvraag voor een autorisatiecode met behulp van het toekenningstype van de autorisatiecode naar het Salesforce-autorisatie-eindpunt. Met een autorisatiecode kan de externe clientapp bewijzen dat deze is geautoriseerd als een veilige bezoeker van de site en dat deze de machtiging heeft 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. Externe clientapps verzenden OAuth-autorisatieaanvragen naar dit eindpunt. |
client_id
|
De consumentensleutel van de externe clientapp. Zoek voor toegang tot de consumentensleutel vanuit Appbeheer de externe clientapp en selecteer 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 externe clientapp. Als dat niet het geval is, mislukt de goedkeuring. U vindt de omleidings-URI op de pagina OAuth-instellingen van de externe clientapp. Deze waarde moet een URL-codering hebben. |
response_type
|
Het OAuth 2.0-toekenningstype dat de externe clientapp aanvraagt. De waarde voor deze stroom moet code zijn om aan te geven dat de externe clientapp 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 externe clientapp toegang heeft. U wijst bereiken toe aan een externe clientapp wanneer u deze samenstelt, en ze worden opgenomen in de OAuth-tokens tijdens de autorisatiestroom. Als u deze parameter niet opneemt, worden alle bereiken aangevraagd die zijn toegewezen aan de externe clientapp. De bereiken die worden doorgegeven in deze parameter, moeten een subset vormen van de geregistreerde bereiken. Zie OAuth-tokens en -bereiken voor geldige parameters. |
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. Zie voor meer informatie Een eigen omgeving voor Single Sign-On maken in uw app. |
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 verstrekt aan externe clientapps, wordt de authenticerende gebruikers gevraagd in te loggen bij Salesforce.
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 tot een externe clientapp hebben goedgekeurd, leidt Salesforce gebruikers om naar de call-back-URL, waar ze de call-back kunnen weergeven met een autorisatiecode.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- Het eerste deel van de callback is de callback-URL van de externe clientapp:
https://www.mycustomerorderstatus.com/oauth2/callback. - Het tweede deel is de autorisatiecode die de externe clientapp 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
Voor het aanvragen van een toegangstoken geeft de externe clientapp de autorisatiecode door aan het Salesforce-tokeneindpunt 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 externe clientapp 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 externe clientapp gebruikt deze code in ruil voor 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 externe clientapp. Zoek voor toegang tot de consumentensleutel vanuit Appbeheer de externe clientapp en selecteer 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 externe clientapp. Als u toegang wilt tot het consumentengeheim, zoekt u vanuit Appbeheer de externe clientapp 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 verplicht, tenzij voor de externe clientapp 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 externe clientapp. Als dat niet het geval is, mislukt de goedkeuring. U vindt de omleidings-URI op de pagina OAuth-instellingen van de externe clientapp of in de definitie van de externe clientapp. 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. Zie client_assertion gebruiken in plaats van client_secret. |
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 externe clientapp.sub—Declient_iduit de definitie van de externe clientapp.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 externe clientapp heeft gevalideerd, retourneert Salesforce een respons 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
|
OAuth-token dat een externe clientapp gebruikt om namens de clienttoepassing toegang tot een beschermde resource aan te vragen. 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 externe clientapp wanneer u deze samenstelt, en ze worden opgenomen in de OAuth-tokens tijdens de autorisatiestroom. Zie OAuth-tokens en -bereiken voor geldige parameters. |
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.
