OAuth 2.0-Anmeldeinformationen
Um in MapForce ein Mapping ausführen zu können, für das eine OAuth 2.0-Authentifizierung erforderlich ist, müssen Sie über den Anmeldeinformationen-Manager Anmeldeinformationen vom Typ OAuth 2.0 erstellen, die OAuth 2.0-Informationen ausfüllen und die unten beschriebene manuelle Autorisierung durchführen. Das unten gezeigte Dialogfeld Anmeldeinformationen hinzufügen/bearbeiten wird angezeigt, wenn Sie OAuth 2.0-Anmeldeinformationen erstellen oder bestehende OAuth 2.0-Anmeldeinformationen bearbeiten. Nähere Informationen zu den einzelnen Eigenschaften finden Sie im Unterabschnitt Verfügbare Parameter weiter unten.
Info zum OAuth 2.0 Workflow
OAuth steht für Open Authorization und ist ein offenes Autorisierungsprotokoll, das Applikationen im Namen eines Benutzers den Zugriff auf bestimmte Benutzerressourcen gestattet. Der OAuth 2.0 Workflow ist in groben Zügen der folgende:
1.Eine Drittanbieter-Applikation (Client) wird bei einem Authorization Server registriert. Der Authorization Server vergibt eine Client-ID und gegebenenfalls ein Client Secret.
2.Der Client gibt eine Redirect URI (Umleitungs-URI) an, an die ein Benutzer weitergeleitet wird, nachdem er dem Client die Berechtigung dazu erteilt oder verwehrt hat.
3.Der Benutzer initiiert in der Client-Applikation eine Aktion, für die Zugriff auf die Ressourcen des Benutzers benötigt wird. So könnte sich der Benutzer etwa über sein Facebook-Konto bei der Client-Applikation anmelden.
4.Der Client sendet einen Request an den Authorization Server und leitet den Benutzer an den Autorisierungsendpunkt des Authorization Servers um, wo sich der Benutzer anmeldet und dem Client die Berechtigung erteilt oder verwehrt. Der Client Request an den Authorization Server enthält die Client-ID, die benötigten Rechte und die Redirect URI.
5.Wenn der Benutzer dem Client die Berechtigung erteilt hat, erhält der Client einen Authorization Grant und sendet die Anmeldeinformationen des Benutzers oder die Autorisierungsinformationen (dies ist vom Grant-Typ abhängig) für ein Access Token und, falls nötig, ein Refresh Token.
6.Mit Hilfe dieses Access Tokens erhält der Benutzer anschließend Zugriff auf die Ressourcen des Benutzers auf dem Ressourcen-Server.
7.Falls das Access Token abgelaufen ist, kann der Client mit Hilfe des Refresh Tokens weiterhin auf die Ressourcen des Benutzers zugreifen, ohne dass sich der Benutzer erneut authentifizieren muss. Ob der Client das Refresh Token verwendet oder nicht, hängt vom ausgewählten Grant Type ab. Nähere Informationen dazu finden Sie weiter unten unter Access Token.
Verfügbare Parameter
Unten sehen Sie eine Liste der mit einem OAuth 2.0-Anmeldeinformationsobjekt verknüpften Felder. Um diese Werte zu erhalten, müssen Sie sich zuerst bei einem Webservice-Anbieter (z.B. Google API Console, FaceBook API, BitBucket API) registrieren.
OAuth Grant Types geben an, wie eine Client-Applikation (in diesem Fall MapForce) mit dem OAuth-Dienst kommuniziert und ein Access Token erhält. Die folgenden Grant Types werden unterstützt:
•Passwort-Anmeldeinformationen des Ressourcenbesitzers
Je nachdem, welcher Grant Type ausgewählt wurde, stehen unterschiedliche Eigenschaften zur Verfügung. Nähere Informationen zu den einzelnen Eigenschaften finden Sie in den Optionen weiter unten.
|
Ein Autorisierungsendpunkt ist eine URI, an die der Eigentümer einer Ressource (d.h. ein Benutzer) umgeleitet wird, um die Authentifizierung, Einwilligung und Autorisierung zu initiieren. Der Autorisierungsendpunkt wird von einem Authorization Server bereitgestellt. Wenn MapForce Zugriff auf die Ressourcen des Benutzers erhalten will, leitet MapForce den Browser des Benutzers an den Autorisierungsendpunkt weiter. Nach erfolgter Authentifizierung entscheidet der Benutzer, ob er MapForce die Berechtigung erteilen oder verwehren will. Im Anschluss daran leitet der Authorization Server den Benutzer an den im Parameter Redirect URI definierten Pfad weiter.
Sie können den Autorisierungsendpunkt abrufen, nachdem Sie sich beim Webservice-Anbieter registriert haben.
|
Ein Token-Endpunkt ist eine Adresse, an die eine Client-Applikation (in diesen Fall MapForce) einen Request sendet, um im Austausch gegen bestimmte Anmeldeinformationen oder Autorisierungsinformationen ein Access Token zu erhalten. Sie erhalten diesen Wert, nachdem Sie sich beim Webservice-Anbieter registriert haben.
|
Eine Client-ID ist ein eindeutige öffentliche ID einer Client-Applikation (in diesem Fall von MapForce. Die Client-ID wird von einem Authorization Server vergeben. Anhand der Client-ID und des Secret (Beschreibung siehe unten) überprüft der Authorization Server die Identität des Client. Sie erhalten diesen Wert, nachdem Sie sich beim Webservice-Anbieter registriert haben.
|
Ein Client Secret ist eine vertrauliche Information, anhand der sich eine Client-Applikation (in diesem Fall MapForce) authentifiziert. Das Client Secret wird von einem Authorization Server ausgestellt. Anhand der Client-ID und des Client Secret überprüft der Authorization Server die Identität des Client. Mit Hilfe des Client Secret wird verhindert, dass sich nicht autorisierte Applikationen als der Client ausgeben und auf die Ressourcen des Benutzers zugreifen. Sie können das Client Secret abrufen, nachdem Sie sich beim Webservice-Anbieter registriert haben.
|
Mit dem Geltungsbereich wird definiert, welche Art von Zugriff ein Client (in diesem Fall MapForce) auf die Ressourcen eines Benutzers erhält (z.B. Lese- und Schreibrechte). Sie erhalten diesen Wert, nachdem Sie sich beim Webservice-Anbieter registriert haben.
|
Beim Access Token handelt es sich um Daten, die der Client (d.h. MapForce) nach erfolgreich abgeschlossener Autorisierung vom Authorization Server erhält. Mit Hilfe des Access Tokens kann MapForce auf die Ressourcen des Benutzers zugreifen. Das Mapping kann nur dann erfolgreich ausgeführt werden, wenn der Resource Server das Access Token als korrekt und gültig erkennt. Das Access Token verliert nach einer bestimmten vom Webservice-Anbieter festgelegten Zeit seine Gültigkeit. Damit das Token aktualisiert werden kann, müssen bestimmte Bedingungen erfüllt werden (nähere Informationen siehe "Wie werden Token aktualisiert" weiter unten).
|
Access Tokens (siehe oben) haben aus Sicherheitsgründen nur eine kurze Gültigkeitsdauer. Diese Gültigkeitsdauer wurde vom Authorization Server festgelegt. Wenn der Authorization Server Refresh Tokens unterstützt, stellt er während der Autorisierung zusammen mit dem Access Token ein Refresh Token aus. Nähere Informationen zur Token-Aktualisierung finden Sie weiter unten im Unterabschnitt Wie Token aktualisiert werden.
|
Die Felder Benutzername und Passwort stehen zur Verfügung, wenn Sie als Grant Type Passwort-Anmeldeinformationen des Ressourcenbesitzers auswählen. Bei diesem Grant Type erhält die Client-Applikation direkt gegen die Benutzer-Anmeldeinformationen (Benutzername und Passwort) ein Access Token und optional ein Refresh Token. Sobald der Client die Anmeldeinformationen des Benutzers erhält, sendet er einen POST Request an den Authorization Server. Wenn der Request erfolgreich ist, stellt der Authorization Server ein Access Token aus, über das der Client auf die Ressourcen des Benutzers zugreifen kann.
|
Der Abschnitt Autorisierung enthält Informationen über eine Redirect URI (Umleitungs-URI). Außerdem können Sie hier angeben, wie die Authentifizierungsinformationen gesendet werden sollen.
Umleitungs-URIEine Redirect URI ist die Adresse, an die ein Authorization Server einen Benutzer umleitet, nachdem dieser einem Client (in diesem Fall MapForce) die Berechtigung erteilt oder verwehrt hat Dies ist auch die Adresse, an die der Authorization Server den für den Erhalt eines Access Tokens erforderlichen Autorisierungscode sendet. In MapForce ist standardmäßig eine URI für die Kommunikation mit dem Authorization Server definiert. Wenn für den Authorization Server ein anderer Port erforderlich ist, aktivieren Sie das Kontrollkästchen Spezifischer Port und geben Sie den entsprechenden Port ein.
Stellen Sie sicher, dass Sie die Redirect URI kopieren und auf der Plattform, auf der Sie Ihre Client-Applikation registrieren, zur Liste der zulässigen Redirect URI hinzufügen.
Token-Endpunkt-AuthentifizierungMit Token-Endpunkt-Authentifizierung (auch Client-Authentifzierung ) wird der Vorgang bezeichnet, bei dem die Identität einer Client-Applikation (d.h. MapForce) von einem Authorization Server überprüft wird. Der Authorization Server entscheidet anschließend, ob der Client die Berechtigung dazu erhält, ein Access Token vom Token-Endpunkt abzurufen, bzw. ob diese Berechtigung verwehrt wird. Mit Hilfe der Client-Authentifizierung wird sichergestellt, dass der Authorization Server nur dazu berechtigten Clients ein Access Token ausstellt.
Für die meisten OAuth 2.0 Authorization Server müssen die Authentifizierungsinformationen im POST Request Header übermittelt werden. Einige OAuth 2.0 Authorization Server akzeptieren Authentifizierungsinformationen nur im Body des POST Request. Wählen Sie die gewünschte Option je nach Anforderung des Authorization Servers aus der Dropdown-Liste aus.
|
Nachdem Sie die obigen Felder ausgefüllt haben, klicken Sie auf Access Token anfordern, um ein für die Ausführung des Mappings erforderliches Access Token abzurufen. Der genaue Ablauf des Autorisierungsverfahrens hängt vom Webservice-Anbieter und Grant Type ab. Wenn Sie z.B. den Grant Type Autorisierungscode ausgewählt haben, müssen Sie normalerweise in einem Browser-Fenster manuell bestätigen, dass Sie dem Webservice erlauben, Ihre Identität festzustellen (z.B. Ihrem Google-Konto, wenn im Mapping eine Google API aufgerufen wird). Nach Abschluss der Autorisierung wird in MapForce eine Bestätigungsmeldung angezeigt, dass das Access Token vom Server abgerufen wurde.
Beachten Sie, dass das Access Token nur dann gespeichert wird, wenn Sie das Kontrollkästchen Verschlüsselt in MFD-Datei speichern, wie unter Anmeldeinformationen beschrieben, aktiviert haben. Falls Sie dieses Kontrollkästchen nicht aktiviert haben, müssen Sie die Autorisierung bei jeder Ausführung des Mappings manuell durchführen.
Wie Token aktualisiert werden
Das Access Token kann nach einiger Zeit seine Gültigkeit verlieren. Die Zeitspanne, nach der das Token abläuft, hängt vom Webservice-Anbieter ab. Das Access Token kann vom Webservice-Anbieter explizit widerrufen werden. In diesem Fall werden im Fenster "Meldungen" Autorisierungsfehler angezeigt, wenn Sie versuchen, eine Vorschau auf das Mapping anzuzeigen.
Beachten Sie, dass MapForce OAuth 2.0-Token nicht aktualisiert. Wenn das Access Token abgelaufen ist, können Sie unabhängig vom Grant Type über die Schaltfläche Access Token anfordern und erneutes Durchlaufen der Autorisierung ein neues Access Token anfordern, bevor Sie das Mapping ausführen können. Wenn Sie Ihr Mapping unter Verwaltung von FlowForce Server ausführen, versucht FlowForce Server das Token unter bestimmten Umständen, die vom ausgewählten Grant Type abhängig sind, zu aktualisieren (siehe Unterabschnitte weiter unten).
Grant Type Autorisierungscode
Wenn Sie Ihr Mapping unter Verwaltung von FlowForce Server ausführen und als Grant Type Autorisierungscode ausgewählt haben, versucht FlowForce Server, das Token nur unter den folgenden Bedingungen zu aktualisieren:
•Ein Mapping, in dem OAuth 2.0-Anmeldeinformationen verwendet werden, muss auf FlowForce Server bereitgestellt werden.
•Die mit dem Mapping verknüpften OAuth 2.0-Anmeldeinformationen müssen auf FlowForce Server bereitgestellt werden, oder Sie können diese OAuth 2.0-Anmeldeinformationen direkt in FlowForce Server erstellen.
•Ein FlowForce-Auftrag, der das Mapping ausführt, muss die entsprechenden OAuth 2.0-Anmeldeinformationen, die Sie bereitgestellt oder zuvor in FlowForce Server erstellt haben, referenzieren (Abbildung unten). Auf diese Art wird das OAuth 2.0-Anmeldeinformationen-Objekt mit dem Mapping-Schritt verknüpft.
•Das OAuth 2.0-Anmeldeinformationen-Objekt muss einen gültigen nicht leeren Refresh Token-Wert in FlowForce Server haben.
Grant Types "Client-Anmeldeinformationen" und "Passwort-Anmeldeinformationen des Ressourcenbesitzers"
Wenn Sie den Grant Type "Client-Anmeldeinformationen" oder "Passwort-Anmeldeinformationen des Ressourcenbesitzers" ausgewählt haben, versucht FlowForce Server nur unter folgenden Bedingungen, ein neues Token abzurufen:
•Es müssen alle relevanten Autorisierungsinformationen des ausgewählten Grant Type bereitgestellt werden (z.B. Client-ID, Client Secret, usw.).
•Ein Mapping, in dem OAuth 2.0-Anmeldeinformationen verwendet werden, muss auf FlowForce Server bereitgestellt werden.
•Die mit dem Mapping verknüpften OAuth 2.0-Anmeldeinformationen müssen auf FlowForce Server bereitgestellt werden, oder Sie können diese OAuth 2.0-Anmeldeinformationen direkt in FlowForce Server erstellen.
•Ein FlowForce-Auftrag, der das Mapping ausführt, muss die entsprechenden OAuth 2.0-Anmeldeinformationen, die Sie bereitgestellt oder zuvor in FlowForce Server erstellt haben, referenzieren (Abbildung oben). Auf diese Art wird das OAuth 2.0-Anmeldeinformationen-Objekt mit dem Mapping-Schritt verknüpft.
Wenn das Token abgelaufen ist, versucht FlowForce Server ein neues abzurufen, indem er einen Request an den Token-Endpunkt sendet.