Loading
Identifizieren der Benutzer und Verwalten des Zugriffs
OAuth 2.0-JWT-Bearer-Flow für die Integration zwischen zwei Servern

Sie befinden sich hier:

  1. Salesforce-Hilfe
  2. Dokumente
  3. Identifizieren der Benutzer und Verwalten des Zugriffs

OAuth 2.0-JWT-Bearer-Flow für die Integration zwischen zwei Servern

In einigen Fällen möchten Sie möglicherweise Server für den Datenzugriff autorisieren, ohne sich jedes Mal interaktiv anmelden zu müssen, wenn die Server Informationen austauschen. In diesen Fällen können Sie den OAuth 2.0-JWT-Bearer-Flow (JSON-Webtoken) verwenden. Dieser Flow nutzt ein Zertifikat, um die JWT-Anforderung zu signieren, und es ist keine explizite Benutzerinteraktion erforderlich. Für diesen Flow ist jedoch eine vorherige Genehmigung der Clientanwendung erforderlich.

Erforderliche Editionen

Verfügbarkeit: Salesforce Classic und Lightning Experience
Verfügbarkeit: Alle Editionen

Mit dem OAuth 2.0-JWT-Bearer-Token-Flow postet der Client ein JWT an den Salesforce-OAuth-Token-Endpunkt. Salesforce verarbeitet das JSON-Webtoken, das eine digitale Signatur enthält, und stellt basierend auf einer vorangegangenen Genehmigung der Anwendung ein Zugriffstoken aus.

In diesem Beispiel werden die im Flow durchgeführten Schritte gezeigt.

  1. Ein Berichtsservice startet seinen nächtlichen Batch-Bericht.
  2. Die verbundene Anwendung sendet das JWT an den Salesforce-Token-Endpunkt. Das JWT ermöglicht es, dass Identitäts- und Sicherheitsinformationen sicherheitsdomänenübergreifend freigegeben werden.
  3. Salesforce überprüft das JWT anhand einer Signatur, eines vorab konfigurierten Zertifikats und zusätzlicher Parameter.
  4. Vorausgesetzt, das JWT ist gültig und die verbundene Anwendung wurde zuvor genehmigt, stellt Salesforce ein Zugriffstoken aus. Die vorherige Genehmigung erfolgt auf eine dieser beiden Arten:
    • Wenn Ihre Richtlinie für die verbundene Anwendung auf Vom Administrator genehmigte Benutzer sind vorab autorisiert festgelegt ist, können Sie Profile und Berechtigungssätze verwenden.
    • Wenn Ihre Richtlinie für die verbundene Anwendung auf Alle Benutzer können sich selbst autorisieren festgelegt ist, können Sie die Endbenutzergenehmigung und die Ausstellung eines Aktualisierungstokens verwenden. Der Client benötigt jedoch kein aktuelles oder gespeichertes Aktualisierungstoken. Der Client muss auch kein Client-Geheimnis an einen Token-Endpunkt übergeben.
    Hinweis
    Hinweis Bei beiden Optionen stellt Salesforce nur dann ein neues Zugriffstoken aus, wenn das ursprüngliche Zugriffstoken mindestens einen anderen Standardgeltungsbereich als den Geltungsbereich refresh_token enthält.
  5. Die verbundene Anwendung verwendet das Zugriffstoken für den Zugriff auf die geschützten Daten auf dem Salesforce-Server.
  6. Der Berichtsservice ruft die autorisierten Daten in seinem nächtlichen Bericht ab.
Hinweis
Hinweis Von diesem Flow wird niemals ein Aktualisierungstoken ausgestellt.

Gehen wir nun die einzelnen Schritte dieses Autorisierungs-Flows durch.

Erstellen eines JWTs

In Salesforce muss ein JWT mit RSA SHA256 signiert werden, wobei ein hochgeladenes Zertifikat als Signiergeheimnis verwendet wird. Bevor Sie diesen Autorisierungs-Flow verwenden, stellen Sie sicher, dass Sie diese Schritte ausführen.

  • Laden Sie ein X509-Zertifikat in einen Java Key Store (JKS) hoch. Das Zertifikat darf nicht größer als 4 KB sein. Wenn es größer ist, versuchen Sie, eine DER-codierte Datei zu verwenden, um die Größe zu reduzieren.
  • Registrieren Sie das X509-Zertifikat für die verbundene Anwendung. Das Zertifikat stimmt mit dem privaten Schlüssel der Anwendung überein. Beim Speichern der verbundenen Anwendung werden client_id und client_secret generiert und der Anwendung zugewiesen.
  • Erstellen Sie eine Anwendung, die ein JWT generiert, das mit dem privaten Schlüssel des X509-Zertifikats signiert ist. Die zugeordnete verbundene Anwendung verwendet das Zertifikat zum Überprüfen der Signatur. Das JWT muss mit den in https://tools.ietf.org/html/rfc7519 angegebenen allgemeinen Formatregeln konform sein.
    Hinweis
    Hinweis In Salesforce sind keine JWT-ID (JTI)-Ansprüche in JWT-Bearer-Token erforderlich. Wenn Sie jedoch einen JTI-Anspruch in Ihrem JWT-Bearer-Token übergeben, stellt Salesforce sicher, dass der JTI-Anspruch zuvor noch nicht gesendet wurde. Dadurch werden JWT-Replay-Angriffe verhindert.

Führen Sie zum Erstellen eines gültigen JWT die folgenden Schritte aus.

  1. Erstellen Sie eine JWT-Kopfzeile im folgenden Format: {"alg":"RS256"} hinzu.
  2. Nehmen Sie eine base64url-Codierung der JWT-Kopfzeile vor, wie in http://tools.ietf.org/html/rfc4648#page-7 definiert. Das Ergebnis sieht in etwa wie eyJhbGciOiJSUzI1NiJ9 aus.
  3. Erstellen Sie ein JSON-Claims-Set für das JWT mit den folgenden Parametern.
    ParameterBeschreibung
    iss Der Aussteller muss die OAuth-client_id der verbundenen Anwendung enthalten, für die Sie das Zertifikat registriert haben.
    aud

    Die Zielgruppe identifiziert den Autorisierungsserver als entsprechende Zielgruppe. Der Autorisierungsserver muss überprüfen, ob es sich um eine für das Token vorgesehene Zielgruppe handelt.

    Verwenden Sie den URL des Autorisierungsservers als Zielgruppenwert: https://login.salesforce.com, https://test.salesforce.com oder https://site.force.com/customers im Falle einer Implementierung für eine Experience Cloud-Site.
    sub

    Wenn Sie diesen Flow für eine Experience Cloud-Site implementieren, muss das Subjekt den Benutzernamen des Benutzers enthalten.

    Aus Abwärtskompatibilitätsgründen können Sie anstelle des Subjekts (prn) den Prinzipal (sub) verwenden. Werden beide angegeben, wird prn verwendet.
    exp Der Zeitpunkt (Datum und Uhrzeit), zu dem das Token abläuft, ausgedrückt in UTC als Anzahl der Sekunden ab 1970-01-01T0:0:0Z. Salesforce lässt einen Zeitversatz von 3 Minuten zu. Wenn die Ablaufzeit beispielsweise auf 1,735,743,600 Sekunden oder den 1. Januar 2025 15:00:00 UTC festgelegt ist, ist das Token noch bis15:03:00 UTC an diesem Datum gültig.
    Hier ein Beispiel für ein JSON-Claim-Set für das JWT.
    {"iss": "3MVG99OxTyEMCQ3gNp2PjkqeZKxnmAiG1xV4oHh9AKL_rSK.BoSVPGZHQ
ukXnVjzRgSuQqGn75NL7yfkQcyy7", 
"sub": "my@email.com", 
"aud": "https://login.salesforce.com", 
"exp": "1333685628"}
  4. Codieren Sie das JWT-Claims-Set mit base64url ohne Zeilenumbrüche. Beispiel: 
    eyJpc3MiOiAiM01WRzk5T3hUeUVNQ1EzZ05wMlBqa3FlWkt4bm1BaUcxeFY0b0hoOUFLTF9yU0su
Qm9TVlBHWkhRdWtYblZqelJnU3VRcUduNzVOTDd5ZmtRY3l5NyIsICJwcm4iOiAibXlAZW1haWwu
Y29tIiwgImF1ZCI6ICJodHRwczovL2xvZ2luLnNhbGVzZm9yY2UuY29tIiwgImV4cCI6ICIxMzMz
Njg1NjI4In0=
  5. Erstellen Sie für den codierten JWT-Header und das codierte JWT-Claims-Set eine Zeichenfolge im nachfolgenden Format.
    encoded_JWT_Header + "." + encoded_JWT_Claims_Set
    In diesem Beispiel ist der codierte JWT-Header hervorgehoben.
    eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiM01WRzk5T3hUeUVNQ1EzZ05wMlBqa3FlWkt4bm1BaUcxeFY0b0hoOUFLTF9yU0su
Qm9TVlBHWkhRdWtYblZqelJnU3VRcUduNzVOTDd5ZmtRY3l5NyIsICJwcm4iOiAibXlAZW1haWwu
Y29tIiwgImF1ZCI6ICJodHRwczovL2xvZ2luLnNhbGVzZm9yY2UuY29tIiwgImV4cCI6ICIxMzMz
Njg1NjI4In0=
  6. Laden Sie das X509-Zertifikat aus dem JKS herunter.
  7. Signieren Sie die sich daraus ergebende Zeichenfolge unter Verwendung von RSA SHA256.
  8. Erstellen Sie auf der Grundlage dieses Formats eine neue Zeichenfolge der Zeichenfolge aus diesem Schritt.
    existing_string + "." + base64_encoded_signature
    In diesem Beispiel ist die base64-codierte Signatur hervorgehoben.
    eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiM01WRzk5T3hUeUVNQ1EzZ05wMlBqa3FlWkt4bm1BaUcxeFY0b0hoOUFLTF9yU0su
Qm9TVlBHWkhRdWtYblZqelJnU3VRcUduNzVOTDd5ZmtRY3l5NyIsICJwcm4iOiAibXlAZW1haWwu
Y29tIiwgImF1ZCI6ICJodHRwczovL2xvZ2luLnNhbGVzZm9yY2UuY29tIiwgImV4cCI6ICIxMzMz
Njg1NjI4In0=.iYCthqWCQucwi35yFs-nWNgpF5NA_a46fXDTNIY8ACko6BaEtQ9E6h4Hn1l_pcwcK​
I_GlmfUO2dJDg1A610t09TeoPagJsZDm_H83bsoZUoI8LpAA1s-2aj_Wbysqb1j4uDToz​
480WtEbkwIv09sIeS_-QuWak2RXOl1Krnf72mpVGS4WWSULodgNzlKHHyjAMAHiBHIDNt​
36y2L2Bh7M8TNWiKa_BNM6s1FNKDAwHEWQrNtAeReXgRy0MZgQY2rZtqT2FcDyjY3JVQb​
En_CSjH2WV7ZlUwsKHqGfI7hzeEvVdfOjH9NuaJozxvhPF489IgW6cntPuT2V647JWi7ng

Dieser Java-Code ist ein einfaches Beispiel für die Erstellung eines JWT-Bearer-Tokens.

import org.apache.commons.codec.binary.Base64;
import java.io.*; 
import java.security.*; 
import java.text.MessageFormat;  

public class JWTExample {

  public static void main(String[] args) {

    String header = "{\"alg\":\"RS256\"}";
    String claimTemplate = "'{'\"iss\": \"{0}\", \"sub\": \"{1}\", \"aud\": \"{2}\", \"exp\": \"{3}\", \"jti\": \"{4}\"'}'";

    try {
      StringBuffer token = new StringBuffer();

      //Encode the JWT Header and add it to our string to sign
      token.append(Base64.encodeBase64URLSafeString(header.getBytes("UTF-8")));

      //Separate with a period
      token.append(".");

      //Create the JWT Claims Object
      String[] claimArray = new String[5];
      claimArray[0] = "3MVG99OxTyEMCQ3gNp2PjkqeZKxnmAiG1xV4oHh9AKL_rSK.BoSVPGZHQukXnVjzRgSuQqGn75NL7yfkQcyy7";
      claimArray[1] = "my@email.com";
      claimArray[2] = "https://login.salesforce.com";
      claimArray[3] = Long.toString( ( System.currentTimeMillis()/1000 ) + 300);
      claimArray[4]=<JTI>
      MessageFormat claims;
      claims = new MessageFormat(claimTemplate);
      String payload = claims.format(claimArray);

      //Add the encoded claims object
      token.append(Base64.encodeBase64URLSafeString(payload.getBytes("UTF-8")));

      //Load the private key from a keystore
      KeyStore keystore = KeyStore.getInstance("JKS");
      keystore.load(new FileInputStream("./path/to/keystore.jks"), "keystorepassword".toCharArray());
      PrivateKey privateKey = (PrivateKey) keystore.getKey("certalias", "privatekeypassword".toCharArray());

      //Sign the JWT Header + "." + JWT Claims Object
      Signature signature = Signature.getInstance("SHA256withRSA");
      signature.initSign(privateKey);
      signature.update(token.toString().getBytes("UTF-8"));
      String signedPayload = Base64.encodeBase64URLSafeString(signature.sign());

      //Separate with a period
      token.append(".");

      //Add the encoded signature
      token.append(signedPayload);

      System.out.println(token.toString());

    } catch (Exception e) {
        e.printStackTrace();
    }
  }
}

Anfordern eines Zugriffstokens

Zum Anfordern eines Zugriffstokens postet die verbundene Anwendung eine Tokenanforderung an den Token-Endpunkt der Salesforce-Instanz. Die Post-Anforderung enthält das JWT.

In diesem Beispiel ist eine Beispiel-Tokenanforderung dargestellt.

POST /services/oauth2/token HTTP/1.1
Host: login.example.com
Content-Type: application/x-www-form-urlencoded

grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=eyJpc3MiOiAiM01WRz...[omitted for brevity]...ZT
Wichtig
Wichtig Übergeben Sie beim Entwickeln von OAuth-Integrationen immer vertrauliche Informationen im Text einer POST-Anforderung oder in einer Anforderungskopfzeile. Verwenden Sie keine GET-Parameter in der URL-Abfragezeichenfolge, um vertrauliche Informationen weiterzugeben. Zu den vertraulichen Informationen zählen Benutzernamen, Kennwörter, OAuth-Token, Client-Geheimnisse und alle personenbezogenen Informationen. Weitere Informationen zu bewährten Vorgehensweisen für die Sicherheit finden Sie im Secure Coding Guide unter Speichern vertraulicher Daten.

Fügen Sie diese Parameter in den Flow ein.

Parameter Beschreibung
grant_type Verwenden Sie für den Gewährungstyp die folgenden Werte: urn:ietf:params:oauth:grant-type:jwt-bearer hinzu.
assertion Die Behauptung ist der gesamte JWT-Wert.
format

(Optional) Geben Sie hiermit das erwartete Rückgabeformat an. Dieser Parameter überschreibt den Anforderungskopf. Die folgenden Formate werden unterstützt.

  • urlencoded
  • json (Standard)
  • xml

Umfangsparameter

Sie können keine Geltungsbereiche in einem JWT-Bearer-Token-Flow angeben. Umfänge werden, wie in dieser Tabelle zu sehen, entsprechend der Richtlinie "Zulässige Benutzer" der verbundenen Anwendung oder den API-Zugriffssteuerungseinstellungen Ihrer Organisation ausgestellt.

Einstellung Ergebnis
Richtlinie für zulässige Benutzer: Alle Benutzer können sich selbst autorisieren Bei einer erfolgreichen Autorisierung werden die mit dem Zugriffstoken zurückgegebenen Umfänge aus den Umfängen der vorigen Genehmigungen abgeleitet.
Richtlinie für zulässige Benutzer: Vom Administrator genehmigte Benutzer sind vorab autorisiert Die der verbundenen Anwendung zugewiesenen Standard- und benutzerdefinierten Umfänge werden mit dem Zugriffstoken zurückgegeben.
API-Zugriffssteuerung: Zulassungsliste für verbundene Anwendungen in Ihrer Organisation

Die der verbundenen Anwendung zugewiesenen Standard- und benutzerdefinierten Umfänge werden mit dem Zugriffstoken zurückgegeben. Wenn Sie verbundene Anwendungen in Ihrer Organisation zulassen, aber nicht die erwarteten Umfänge erhalten, gehen Sie wie folgt vor:

  • Geben Sie unter "Setup" im Feld "Schnellsuche" den Text OAuth ein und wählen Sie OAuth-Verwendung verbundener Anwendungen aus.
  • Klicken Sie für die auf die Zulassungsliste gesetzte verbundene Anwendung auf Blockieren.
  • Klicken Sie bei der auf die Zulassungsliste gesetzten verbundenen Anwendung auf Blockierung aufheben.

Salesforce gewährt Zugriffstoken

Die Flow-Anforderungen der OAuth 2.0-JWT-Bearer und SAML-Behauptungs-Bearer durchsuchen alle vorherigen Genehmigungen auf den Benutzer mit einem Aktualisierungstoken. Wenn Salesforce übereinstimmende Genehmigungen findet, werden die Werte der genehmigten Umfänge kombiniert. Anschließend stellt Salesforce ein Zugriffstoken aus. Wenn Salesforce keine früheren Genehmigungen findet, in denen ein Aktualisierungstoken oder verfügbare genehmigte Umfänge enthalten sind, schlägt die Anforderung als nicht autorisiert fehl.

Nach einer erfolgreichen Überprüfung sendet die Salesforce-Instanz eine Antwort an die verbundene Anwendung. Eine Token-Antwort für den OAuth 2.0-Flow für JWT-Bearer-Token weist dasselbe Format auf wie ein Autorisierungscode-Flow, obwohl niemals ein Aktualisierungstoken ausgegeben wird.

Dieses Beispiel zeigt eine Antwort von Salesforce.

{"access_token":"00Dxx0000001gPL!AR8AQJXg5oj8jXSgxJfA0lBog.
39AsX.LVpxezPwuX5VAIrrbbHMuol7GQxnMeYMN7cj8EoWr78nt1u44zU31
IbYNNJguseu",
"scope":"web openid api id","instance_url":"
https://yourInstance.salesforce.com","id":"
https://yourInstance.salesforce.com
/id/00Dxx0000001gPLEAY/005xx000001SwiUAAS","token_type":"Bearer"}

Der Text der Antwort enthält diese Parameter.

ParameterBeschreibung
access_token OAuth-Token, das von einer verbundenen Anwendung verwendet wird, um im Auftrag der Client-Anwendung den Zugriff auf eine geschützte Ressource anzufordern. Zusätzliche Berechtigungen in Form von Geltungsbereichen können mit dem Zugriffstoken einhergehen.
token_type Ein Bearer-Tokentyp, der für alle Antworten verwendet wird, die ein Zugriffstoken enthalten.
scope Umfänge werden entsprechend der Richtlinie "Zulässige Benutzer" der verbundenen Anwendung oder den API-Zugriffssteuerungseinstellungen Ihrer Organisation ausgestellt. Entsprechende Informationen finden Sie unter Umfangsparameter.
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.
sfdc_site_url Wenn der Benutzer Mitglied einer Experience Cloud-Site ist, wird der Site-URL angegeben.
sfdc_site_id Wenn der Benutzer Mitglied einer Experience Cloud-Site ist, wird die Site-ID des Benutzers angegeben. Für Experience Cloud-Sites enthält dieser Flow den Wert "sfdc_site_id" im Token-Endpunkt. Diese Site-ID ist in Connect-REST-API-Anforderungen möglicherweise erforderlich.

Zugreifen auf geschützte Daten

Nachdem die verbundene Anwendung das access_token empfangen hat, kann sie es als ein Bearer-Token in der Anforderung der Autorisierungskopfzeile weitergeben. Dieses Beispiel zeigt einen REST-API-Aufruf an Experience Cloud-Sites: 


          https://site.force.com/customers/services/data/v32.0/ -H 
"Authorization: Bearer 00D50000000IehZ\!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6 LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM"

Siehe auch:

 
Laden
Salesforce Help | Article