OAuth2 Migrations-Guide

Alles was du brauchst, um auf OAuth2 zu wechseln.

🇬🇧  English Version

Einleitung

Sicherheit ist einer der wichtigsten nicht-funktionalen Anforderungen an eine Plattform wie Europace, die Finanzdaten von Verbrauchern verwendet. Wir nehmen diese Verantwortung sehr ernst. Und gleichzeitig glauben wir daran, dass eine technische Anbindung an die Europace-Technologie leichtgewichtig und schnell passieren kann.

Deshalb räumen wir mit den bislang proprietären Authentifizierungsverfahren auf und führen OAuth2 als Standard-Technologie für Europace ein. Dieses Verfahren ist weit verbreitet - fast jeder Software-Entwickler hat damit schon einmal gearbeitet. Durch diese Bekanntheit und Einfachheit werden der Entwicklungsaufwand bei der Anbindung reduziert und die Nerven der Entwickler geschont.

Wir erhöhen damit die Sicherheit, indem API-Keys noch einfacher erneuert werden können und der Zugriff auf die Europace-Technologie noch nachvollziehbarer wird.

Außerdem ermöglichen wir mit OAuth2 zukünftig echtes Single Sign On über die Einbindung eigener Benutzerdatenbanken für das Anmeldeverfahren. Zudem können Toolhersteller ihre Anwendungen nach Rücksprache mit den Europace-Partnern noch einfacher für alle im Self-Service einbinden, ohne Benutzername und Passwort zu kennen.

Wir sind davon überzeugt, die Einführung von OAuth2 bei Europace ist ein entscheidender Basis-Baustein für unsere Partner und uns, um die Digitalisierung der Baufinanzierung voranzutreiben.

Bis wann muss die Migration erfolgen?

Alle aktuellen APIs werden noch bis Ende Juli 2021 die alten Authentifizierungsverfahren auf Basis von API-Key unterstützen.

Was ist zu tun?

  • die Authentifizierung für alle APIs muss auf OAuth2 umgestellt werden
  • wenn die BEX-API (Vorgang anlegen) verwendet wird, muss auf die Kundenangaben-API umgestellt werden
  • wenn Reports über API abgerufen werden, muss auf die Report-API umgestellt werden
  • wenn die partner.csv als Report abgerufen wird, muss auf die Partner-API umgestellt werden

Wie benutze ich OAuth2?

Alle Europace-APIs sind zugangsbeschränkt, d.h. um sie verwenden zu können muss zuvor eine Anmeldung (Authentifizierung) bei Europace erfolgen.

Dabei müssen folgende Schritte durchlaufen werden:

  • Einmalig musst du deinen Client in Europace registrieren lassen, woraufhin du die Client_ID und das Client-Secret für den Client erhältst
  • Für die Anmeldung an Europace rufst du https://api.europace.de/auth/token mit der Client_ID und dem Client_Secret als Basic-Auth auf, um einen Access_Token zu erhalten.
  • Mit dem Access_Token als Bearer-Token kannst du Requests an den Europace APIs durchführen. Request-Header-Variable: `Authorization: Bearer [Access_Token]

Die meisten HTTP Clients unterstützen OAuth2 bereits, lediglich Client_ID, Client_Secret sowie die Adresse des Authorization Servers musst du in der Config hinterlegen.

Wie bekomme ich einen Client registriert?

zur Client-Registrierung

Bitte wende dich an helpdesk@europace.de mit folgenden Daten:

  • EP2-PartnerId
  • Client-Name
  • Client-Beschreibung:
  • Kontakt-Email-Adresse für betriebliche Rückfragen
  • Kurze Beschreibung des Anwendungsfalls (Ziel)
  • benötigte Scopes

Nach einer kurzen Prüfung beim Eigentümer (Europace Partner) registrieren wir dir deinen Client umgehend und stellen dir die Client-ID und das Client-Secret in deiner persönlichen Linkliste in Europace zur Verfügung.



Bitte beachte, dass du dich mit der Benutzung der APIs automatisch mit den Europace API-Nutzungsbedingungen einverstanden erklärst.

Wie bekomme ich einen Access-Token?

Für die Anmeldung an Europace rufst du https://api.europace.de/auth/token mit der Client_ID und dem Client_Secret als Basic-Auth auf, um einen Access_Token zu erhalten.

Request:

curl --location --request POST 'https://api.europace.de/auth/token' \
--user '[Client_ID]:[Client_Secret]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Response:

{  "access_token": <Access_Token>,
   "scope": <verfügbare Scopes>,
   "token_type": "Bearer",
   "expires_in": 3600   }

In diesem Fall wird ein Access-Token im Namen und im Auftrag des Partners erstellt an dem der Client registriert ist. Weitere Anwendungsfälle werden in “Alte Welt - neue Welt” behandelt.

Wie rufe ich eine API mit Access-Token auf?

Mit dem Access_Token als Bearer-Token kannst du Requests an den Europace APIs durchführen. Request-Header-Variable: Authorization: Bearer [Access_Token]

Am Beispiel der Vorgaenge-API in curl:

curl --location --request GET 'https://api.europace2.de/v2/vorgaenge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [Access_Token]

Alte Welt - neue Welt

Bislang standen dir verschiedene Authentifizierungsverfahren zur Verfügung. In diesem Abschnitt zeigen wir dir, wie du am Besten in den unterschiedlichen Anwendungsfällen auf OAuth2 wechselst und so von der Vereinfachung und Standardisierung des OAuth2-Authentifizierungsverfahrens profitierst.

API-Key

Damit du keine Passwörter von Benutzern speichern und verwenden musst, werden für den Zugriff auf Schnittstellen API-Keys verwendet. Mit großer Wahrscheinlichkeit hast auch du diese Methode für deine Anbindung verwendet.

häufig genutzt bei diesen APIs:

  • Vorgaenge-API
  • Antraege-API
  • Reporting-API

Dieses Verfahren wird noch bis Ende Juli 2021 unterstützt.

Beispiel bisher:

curl --location --request POST 'https://api.europace.de/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=[PartnerID] \
--data-urlencode 'password=[API-Key]'

Beispiel neu: \

curl --location --request POST 'https://api.europace.de/auth/token' \
--user '[Client_ID]:[Client_Secret]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

API-Key (Impersionieren)

Das impersionierte API-Key-Verfahren wird dann verwendet, wenn die API den konkreten Benutzer benötigt und man nicht für jeden einen API-Key anfordern möchte. Es reicht einen API-Key einer Organisation zu besitzen, der als Generalsschlüssel fungiert und mit dem Benutzer, auf die die Organisation Zugriff hat, angemeldet werden können.

häufig genutzt bei diesen APIs:

  • Silent Sign On
  • Angebote-API
  • Unterlagen-API

Dieses Verfahren wird noch bis Ende Juli 2021 unterstützt.

Beispiel bisher:

curl --location --request POST 'https://www.europace2.de/partnermanagement/login.api' \
--header 'x-partnerid: [anzumeldende PartnerID]' \
--header 'x-apikey: [Super API-Key]'

mit x-partnerid des anzumeldenden Benutzers und x-apikey des Partners (mit weitreichenden Zugriffsrechten (Generalschlüssel)). Der x-apikey muss in der Partnermanagement-Struktur über der x-partnerid angeordnet sein, da sonst die notwendigen Zugriffsrechte fehlen.

Beispiel neu:

curl --location --request POST 'https://api.europace.de/auth/token' \
--user '[ClientID]:[ClientSecret]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=impersonieren baufinanzierung:echtgeschaeft baufinanzierung:vorgang:lesen baufinanzierung:ereignis:lesen baufinanzierung:antrag:lesen' \
--data-urlencode 'subject=[anzumeldende PartnerID]' \
--data-urlencode 'actor=[registrierte PartnerID]'
ParameterBeschreibung
Subjectdie Partnerid des anzumeldenden Benutzers
Actordie Partnerid des registrierten Clients
Hinweisdie Actor-Partnerid muss in der Partnermanagementstruktur über der Subject-Partnerid angeordnet sein, da sonst die notwendigen Zugriffsrechte fehlen.
Scopemuss impersonieren enthalten (Hinweis: Wenn ein Scope angegeben wird, müssen alle erforderlichen Rechte angegeben werden, d.h. impersonieren allein macht keinen Sinn.)

Diese Methode wird meistens verwendet, wenn du die angebotene Login-Maske von Europace oder eine eigene Loginmaske auf deiner Website/Intranet eingebunden hast.

Beispiel bisher:

curl --location --request POST 'https://www.europace2.de/partnermanagement/login.do' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=[Username]' \
--data-urlencode 'password=[Password]'

Wir akzeptieren keine Passworte aus “externen Quellen” mehr, da unsere Nutzungsbedingungen das benutzen von Europace-Passworten in “fremden Systemen” untersagt. Als Alternative übernehmen wir den Benutzernamen und zeigen anschließend die Passwort-Eingabe-Seite an.

Beispiel neu:

curl --location --request POST 'https://www.europace2.de/partnermanagement/login.do' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=[Username]

Silent Sign On

Um die Einbindung von Europace in Intranet oder CRM-System nahtlos zu ermöglichen, bietet Europace die Möglichkeit des Silent Sign On, d.h. ein System kann ihm bekannte Europace-Benutzer mittels API-Key (Generalschlüssel) anmelden und die Oberfläche von Europace anzeigen. Damit entfällt der Schritt der Anmeldung für den Benutzer.

Beispiel bisher:
Anmeldung des Benutzers mit PartnerID und Super-API-Key:
siehe bisheriges Beispiel API-Key (Impersionieren), dann mit JWT im Browser aufrufen:

https://www.europace2.de/partnermanagement/login?redirectTo=/uebersicht&authentication=[JWT]

Beipiel neu: siehe Silent Sign In API

BEX-API (Vorgang anlegen)

Wenn die BEX-API verwendet wird, so muss für die OAuth-Migration auf die neue Kundenangaben-API umgestellt werden. Die BEX-API unterstützt keine OAuth-Authentifizierung. Die Umstellung kann mehrere Tage bis Wochen in Anspruch nehmen, da abhängig von der Menge der verwendeten Datenfelder, der Mapping-Aufwand zu berücksichtigen ist.

Beschreibung Kundenangaben-API

Report-API

Wenn Reports über APIs heruntergeladen werden, so muss für die OAuth-Migration auf die neue Report-API umgestellt werden. Die bisherigen URLs unterstützen keine OAuth-Authentifizierung. Die Umstellung kann 2-3 Tage in Anspruch nehmen, da das Verfahren von snychron auf asynchron umgestellt wurde und nun mehrere API-Aufrufe erfordert.

Beschreibung Report-API

Partner.csv abrufen

Der Report partner.csv steht nicht mehr zum Abruf über API zur Verfügung, da er ausschließlich zur Unterstützung der Administratoren für Prüfungszwecke dient. Wenn Daten aus dem Report benötigt werden, so ist die Partner-API zu verwenden.

Beschreibung Partner-API

Support

Bei Problemen, Fragen oder speziellen Anwendungsfällen, die hier nicht aufgeführt sind, wende dich gern an helpdesk@europace2.de