Sie befinden sich hier:
OAuth 2.0-Webserver-Flow für die Integration von Webanwendungen
Um eine externe Webanwendung in die Salesforce-API zu integrieren, verwenden Sie den OAuth 2.0-Webserver-Flow, der den OAuth 2.0-Gewährungstyp mit Autorisierungscode implementiert. Bei diesem Flow muss der Server, der die Webanwendung hostet, in der Lage sein, die Identität der externen Client-Anwendung zu schützen, die durch die Client-ID und das Client-Geheimnis definiert ist.
Erforderliche Editionen
| Verfügbarkeit: Salesforce Classic (nicht in allen Organisationen verfügbar) und Lightning Experience |
| Verfügbarkeit: alle Editionen |
Es wird empfohlen, für spezielle Szenarien anstelle des Benutzeragent-Flows oder des Flows für Benutzername und Kennwort den Webserver-Flow mit PKCE (Proof Key for Code for Exchange, ausgesprochen "pixy") zu verwenden. Verwenden Sie die Parameter code_challenge und code_verifier, um PKCE mit dem Webserver-Flow zu implementieren. Weitere Informationen zu PKCE finden Sie unter Internet Engineering Task Force (IETF). Außerdem wird empfohlen, dass Sie alle externen Client-Anwendungen daran hindern, den Benutzeragent-Flow oder den Flow für Benutzername und Kennwort zu verwenden. Die Schritte finden Sie unter Blockieren von Autorisierungs-Flows zum Verbessern der Sicherheit.
Hier ein Beispiel eines Anwendungsfalls für die Implementierung des Webserver-Flows. Sie haben kürzlich einen Webservice entwickelt, der sicheren Zugriff auf den Auftragsstatus von Kunden ermöglicht. Die Auftragsstatusdaten werden sicher in Ihrer Salesforce CRM-Plattform gespeichert. Wenn Sie Helpdesk-Benutzer autorisieren möchten, den Auftragsstatus eines Kunden anzuzeigen, entwickeln Sie eine Auftragsstatusanwendung und konfigurieren Sie sie als externe Client-Anwendung mit dem Webserver-Flow.
- Ein Helpdesk-Benutzer klickt auf die Webanwendung "Auftragsstatus".
- Die externe Client-Anwendung postet eine Autorisierungscodeanforderung an den Salesforce-Autorisierungsendpunkt.
- Der Benutzer wird zur Salesforce-Anmeldeseite weitergeleitet. Nach einer erfolgreichen Anmeldung wird der Benutzer gebeten, den Zugriff der Anwendung auf Auftragsstatusdaten zu genehmigen.
- Nachdem der Benutzer der Auftragsstatus-Anwendung den Zugriff auf die Daten genehmigt hat, sendet Salesforce eine Rückmeldung mit einem Autorisierungscode an die Auftragsstatus-Anwendung.
- Die Auftragsstatus-Anwendung leitet den Autorisierungscode an den Salesforce-Token-Endpunkt und fordert so ein Zugriffstoken an.
- Salesforce validiert den Autorisierungscode und sendet ein Zugriffstoken zurück das die entsprechenden Berechtigungen in Form von Geltungsbereichen enthält.
- Die Auftragsstatus-Anwendung sendet eine Anforderung zurück an Salesforce, um auf die Auftragsstatusdaten zuzugreifen. Die Anforderung enthält das Zugriffstoken mit den zugehörigen Umfängen.
- Salesforce validiert das Zugriffstoken und die zugehörigen Umfänge.
- Die Auftragsstatus-Anwendung kann auf die geschützten Daten zugreifen und der Auftragsstatus des Kunden wird in der Anwendung angezeigt.
Hinweis Wenn das Zugriffstoken ungültig wird, kann die externe Client-Anwendung ein Aktualisierungstoken verwenden, um ein neues Zugriffstoken abzurufen.
Im Folgenden sind die einzelnen Schritte dieses Autorisierungs-Flows näher erläutert.
- Anfordern eines Autorisierungscodes
- Benutzer authentifiziert und autorisiert Zugriff
- Salesforce gewährt Autorisierungscode
- Zugriffstoken anfordern
- Salesforce gewährt ein Zugriffstoken
Anfordern eines Autorisierungscodes
Zum Initiieren des OAuth 2.0-Webserver-Flows postet der externe Webservice über die externe Client-Anwendung eine Autorisierungscode-Anforderung mit dem Autorisierungscode-Gewährungstyp an den Salesforce-Autorisierungsendpunkt. Mit einem Autorisierungscode kann die externe Client-Anwendung nachweisen, dass sie als sicherer Besucher der Site autorisiert wurde und über die Berechtigung zum Anfordern eines Zugriffstokens verfügt.
Der Autorisierungscode hat die Form einer HTTP-Umleitung.
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=codeFügen Sie diese Parameter in eine Autorisierungscode-Anforderung ein.
| Parameter | Beschreibung |
|---|---|
Request Header
|
Den OAuth 2.0-Autorisierungsendpunkt von Salesforce. Externe Client-Anwendungen senden OAuth-Autorisierungsanforderungen an diesen Endpunkt. |
client_id
|
Der Verbraucherschlüssel der externen Client-Anwendung. Suchen Sie im Anwendungs-Manager nach der externen Client-Anwendung und wählen Sie im Dropdown-Menü Anzeigen aus, um auf den Verbraucherschlüssel zuzugreifen. Klicken Sie dann auf Verbraucherdetails verwalten. Manchmal werden Sie aufgefordert, Ihre Identität zu bestätigen, bevor Sie den Verbraucherschlüssel anzeigen können. |
redirect_uri
|
Der URL, an den Benutzer nach einer erfolgreichen Authentifizierung umgeleitet werden. Der Umleitungs-URI muss mit einem der Werte im Feld "Rückmeldungs-URL" der externen Client-Anwendung übereinstimmen. Andernfalls tritt bei der Genehmigung ein Fehler auf. Sie finden den Umleitungs-URI auf der Seite "OAuth-Einstellungen" der externen Client-Anwendung. Dieser Wert muss URL-codiert sein. |
response_type
|
Der OAuth 2.0-Gewährungstyp, den die externe Client-Anwendung anfordert. Der Wert für diesen Flow muss code sein, um anzugeben, dass die externe Client-Anwendung einen Autorisierungscode anfordert. |
Sie können diese Parameter auch in eine Autorisierungscode-Anforderung einfügen.
| Parameter | Beschreibung |
|---|---|
scope
|
Berechtigungen, die den Typ der geschützten Ressourcen definieren, auf die eine externe Client-Anwendung zugreifen kann. Sie weisen einer externen Client-Anwendung beim Erstellen Geltungsbereiche zu, die während des Autorisierungs-Flows in die OAuth-Token aufgenommen werden. Wenn Sie diesen Parameter nicht einschließen, werden alle Umfänge angefordert, die der externen Client-Anwendung zugewiesen sind. Die in diesem Parameter übergebenen Bereiche müssen eine Teilmenge der registrierten Geltungsbereiche sein. Gültige Parameter finden Sie unter OAuth-Token und -Geltungsbereiche. |
sso_provider
|
Der Entwicklername eines Single Sign-On-Identitätsanbieters (SSO), der für eine "Meine Domäne" oder eine Experience Cloud-Site konfiguriert ist. Mit diesem Parameter können Sie eine SSO-Erfahrung erstellen, die den Eindruck erweckt, als wäre Ihre Anwendung beim SSO-Anbieter integriert. Mit diesem Parameter können Sie beispielsweise SSO in einer Headless-Identitätsimplementierung anbieten. Weitere Informationen finden Sie unter Erstellen einer nativen Single Sign-On-Erfahrung in Ihrer Anwendung. |
state
|
Der vom externen Webservice an den Rückmeldungs-URL zu sendende beliebige Zustand. Dieser Wert muss URL-codiert sein. |
immediate
|
Ein boolescher Wert, der bestimmt, ob der Benutzer zum Anmelden und Genehmigen aufgefordert wird. Der Standardwert ist
Die Option |
code_challenge
|
Gibt den SHA256-Hash-Wert des Dieser Parameter ist erforderlich, wenn in der Token-Anforderung ein
|
display
|
Ändert den Anzeigetyp der Anmelde- und Autorisierungsseiten. Die folgenden Werte werden von Salesforce unterstützt.
|
login_hint
|
Gibt einen gültigen Benutzernamenwert an, damit die Anmeldeseite vorab mit dem Benutzernamen ausgefüllt wird, beispielsweise " Wenn Sie den Parameter " |
nonce
|
Verwenden Sie dies mit dem Geltungsbereich "openid", um ein Benutzer-ID-Token anzufordern. Das Benutzer-ID-Token wird in der Antwort zurückgegeben. Dieser Parameter ist optional. Er hilft jedoch bei der Ermittlung von Replay-Angriffen.
|
prompt
|
Gibt an, wie der Autorisierungsserver den Benutzer zur erneuten Authentifizierung und erneuten Genehmigung auffordert. Die folgenden Werte werden von Salesforce unterstützt.
Die Werte " |
Uvid-Hint Kopfzeile |
Wenn Sie diesen Flow mit dem Headless-Gast-Flow verbinden möchten, können Sie optional eine Wenn Sie den Gastbenutzer-Flow in Ihrer Anwendung implementieren, können Sie optional diese Kopfzeile verwenden, um ein JSON Web Token (JWT)-basiertes Zugriffstoken weiterzugeben, das eine eindeutige Besucher-ID (UVID) enthält, die an die Identität eines Gastbenutzers gebunden ist. Durch die Weitergabe der UVID an einen Flow für einen benannten Benutzer können Sie Kontextinformationen aus einer Gastbenutzersitzung, beispielsweise die Cookie-Voreinstellungen des Benutzers, in einer Benutzersitzung übernehmen. |
uvid_hint-Textparameter |
Ein einfacher Statt die UVID-Instanz im Anforderungstext weiterzugeben, können Sie sie auch in einem JWT-basierten Token mit einer UVID-Instanz über die |
Benutzer authentifiziert und autorisiert Zugriff
Bevor Salesforce Autorisierungscodes für externe Client-Anwendungen bereitstellt, werden die authentifizierenden Benutzer aufgefordert, sich bei Salesforce anzumelden.
Nach einer erfolgreichen Anmeldung leitet Salesforce Benutzer zur Genehmigungsseite um, um Zugriff auf die Anwendung zu gewähren.
Wenn Benutzer den Zugriff bereits erteilt haben, ist es nicht notwendig, dies erneut zu tun.
Salesforce gewährt Autorisierungscode
Nachdem Benutzer den Zugriff auf eine externe Client-Anwendung genehmigt haben, leitet Salesforce Benutzer zum Rückmeldungs-URL um, wo sie die Rückmeldung mit einem Autorisierungscode anzeigen können.
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- Der erste Teil der Rückmeldung ist der Rückmeldungs-URL der externen Client-Anwendung:
https://www.mycustomerorderstatus.com/oauth2/callbackhinzu. - Der zweite Teil ist der Autorisierungscode, den die externe Client-Anwendung zum Abrufen eines Zugriffstokens:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==verwendet. Der Autorisierungscode läuft nach 15 Minuten ab.
Wenn der Parameter state in der ursprünglichen Abfragezeichenfolge enthalten ist, wird der angegebene Status an den Genehmigungsschritt weitergegeben.
Zugriffstoken anfordern
Zum Anfordern eines Zugriffstokens übergibt die externe Client-Anwendung den Autorisierungscode als HTTP-POST an den Salesforce-Token-Endpunkt.
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
Die POST-Anforderung im Beispiel enthält folgende Parameter.
| Parameter | Beschreibung |
|---|---|
Request Header
|
Die Anforderungskopfzeile kann die folgenden Parameter aufweisen.
Die Abfragezeichenfolge unterstützt folgende Parameter.
Der Parameter " |
grant_type
|
Der Validierungstyp, den die externe Client-Anwendung bereitstellen kann, um nachzuweisen, dass sie ein sicherer Besucher ist. Der Wert für den Webserver-Flow muss authorization_code lauten. |
code
|
Einen temporären Autorisierungscode, der vom Autorisierungsserver empfangen wurde. Die externe Client-Anwendung verwendet diesen Code im Austausch gegen ein Zugriffstoken. Diese Art von OAuth 2.0-Flow stellt eine sichere Möglichkeit dar, das Zugriffstoken wieder an die Anwendung zu übergeben. |
client_id
|
Der Verbraucherschlüssel der externen Client-Anwendung. Suchen Sie im Anwendungs-Manager nach der externen Client-Anwendung und wählen Sie im Dropdown-Menü Anzeigen aus, um auf den Verbraucherschlüssel zuzugreifen. Klicken Sie dann auf Verbraucherdetails verwalten. Manchmal werden Sie aufgefordert, Ihre Identität zu bestätigen, bevor Sie den Verbraucherschlüssel anzeigen können. |
client_secret
|
Das Verbrauchergeheimnis der externen Client-Anwendung. Suchen Sie im Anwendungs-Manager nach der externen Client-Anwendung und wählen Sie im Dropdown-Menü Anzeigen aus, um auf das Verbrauchergeheimnis zuzugreifen. Klicken Sie dann auf Verbraucherdetails verwalten. Manchmal werden Sie aufgefordert, Ihre Identität zu bestätigen, bevor Sie das Verbrauchergeheimnis anzeigen können. Dieser Parameter ist erforderlich, es sei denn, für die externe Client-Anwendung ist "Geheimnis für Webserver-Flow erforderlich" nicht aktiviert. Wenn eine |
redirect_uri
|
Der URL, an den Benutzer nach einer erfolgreichen Authentifizierung umgeleitet werden. Der Umleitungs-URI muss mit einem der Werte im Feld "Rückmeldungs-URL" der externen Client-Anwendung übereinstimmen. Andernfalls tritt bei der Genehmigung ein Fehler auf. Sie finden den Umleitungs-URI auf der Seite "OAuth-Einstellungen" der externen Client-Anwendung oder in der Definition der externen Client-Anwendung. Dieser Wert muss URL-codiert sein. |
Sie können zudem die folgenden Parameter einbeziehen.
| Parameter | Beschreibung |
|---|---|
client_assertion
|
Statt client_secret weiterzugeben, können Sie client_assertion und client_assertion_type angeben. Wenn kein client_secret angegeben ist, sucht Salesforce nach client_assertion und client_assertion_type. Entsprechende Informationen finden Sie im Thema über das Verwenden von client_assertion anstelle von client_secret. |
client_assertion_type
|
Geben Sie diesen Wert an, wenn Sie den Parameter Der Wert von |
code_verifier
|
Nur dann erforderlich, wenn in der Autorisierungsanforderung ein code_challenge-Parameter angegeben wurde. Gibt 128 Bytes zufälliger Daten mit ausreichend Entropie an, sodass das Ableiten des
|
format
|
Sofern nicht in der Abfragezeichenfolge enthalten, können Sie das erwartete Rückgabeformat angeben. Der Parameter "
|
client_assertion anstelle von client_secret.Wenn Sie eine client_assertion anstelle eines client_secret angeben, muss der Wert von client_assertion die folgenden Parameter enthalten.
iss: Dieclient_idaus der Definition der externen Client-Anwendung.sub: Dieclient_idaus der Definition der externen Client-Anwendung.audDer Token-Servlet-URL: https://Hostname/services/oauth2/token.exp: Die Ablaufzeit der Behauptung innerhalb einer Zeitspanne von 5 Minuten, die in UTC gemessen als Anzahl der Sekunden ab 1970-01-01T0:0:0Z ausgedrückt wird.
Die client_assertion muss auch mit dem privaten Schlüssel signiert sein, der dem hochgeladenen Zertifikat des OAuth-Verbrauchers zugeordnet ist. Es wird nur der RS256-Algorithmus unterstützt. Informationen zur Client-Authentifizierungsmethode private_key_jwt finden Sie in den OpenID Connect-Spezifikationen.
Anstatt die Client-Anmeldeinformationen als Parameter im Textkörper der POST-Anforderung zu senden, unterstützt Salesforce das grundlegende HTTP-Authentifizierungsschema. Das Format dieses Schemas erfordert "client_id" und "client_secret" in der Autorisierungskopfzeile des Posts wie folgt:
Authorization: Basic64Encode(client_id:secret)
"client_id" und "client_secret" werden durch einen Doppelpunkt (:) getrennt. Weitere Informationen finden Sie im Dokument OAuth 2.0 Authorization Framework.
In diesem Beispiel wird eine POST-Anforderung eines Zugriffstokens gezeigt, die das grundlegende HTTP-Authentifizierungsschema verwendet, statt die Client-Anmeldeinformationen im Textkörper der POST-Anforderung zu senden.
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 und client_secret im POST-Text gesendet werden, wird die Autorisierungskopfzeile ignoriert.Salesforce gewährt ein Zugriffstoken
Nachdem Salesforce die Anmeldeinformationen der externen Client-Anwendung validiert hat, wird eine Antwort mit dem Zugriffstoken zurückgegeben. In diesem Beispiel liegt die Antwort im JSON-Format vor.
{
"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"
}
Die Antwort enthält folgende Parameter.
| Parameter | Beschreibung |
|---|---|
access_token
|
OAuth-Token, das von einer externen Client-Anwendung verwendet wird, um im Namen der Client-Anwendung Zugriff auf eine geschützte Ressource anzufordern. Zusätzliche Berechtigungen in Form von Geltungsbereichen können mit dem Zugriffstoken einhergehen. |
signature
|
Mit "client_secret" signierte Base64-codierte HMAC-SHA256-Signatur. Die Signatur kann die verkettete ID und "issued_at value" enthalten, mit denen Sie überprüfen können, ob sich der Identitäts-URL nicht geändert hat, nachdem er vom Server gesendet wurde. |
scope
|
Die dem Zugriffstoken zugeordneten Geltungsbereiche. Geltungsbereiche definieren außerdem den Typ der geschützten Ressourcen, auf die der Client zugreifen kann. Sie weisen einer externen Client-Anwendung beim Erstellen Geltungsbereiche zu, die während des Autorisierungs-Flows in die OAuth-Token aufgenommen werden. Gültige Parameter finden Sie unter OAuth-Token und -Geltungsbereiche. |
id_token
|
Eine signierte Datenstruktur, die authentifizierte Benutzerattribute enthält, einschließlich einer eindeutigen Kennung für den Benutzer und eines Zeitstempels, der angibt, wann das Token ausgestellt wurde. Darüber hinaus gibt es die anfordernde Client-Anwendung an. Entsprechende Informationen finden Sie unter OpenID Connect-Spezifikationen. Dieser Parameter wird zurückgegeben, wenn der Parameter scope " |
instance_url
|
Ein URL, der die Instanz der Organisation des Benutzers angibt. Beispiel: https://yourInstance.salesforce.com/.
|
id
|
Identitäts-URL, der zur Identifizierung des Benutzers sowie zur Abfrage weiterer Informationen über den Benutzer verwendet werden kann. Entsprechende Informationen finden Sie unter Identitäts-URLs. |
token_type
|
Ein Bearer-Tokentyp, der für alle Antworten verwendet wird, die ein Zugriffstoken enthalten.
|
issued_at
|
Zeitstempel der Signaturerstellung in Millisekunden. |
Die Antwort kann auch die folgenden Parameter enthalten.
