HANDBUCH FÜR DIENSTEANBIETER E-POSTIDENT RELEASE 1.0 VERSION 2.6
Handbücher und Software sind urheberrechtlich geschützt und dürfen nicht ohne schriftliche Genehmigung der Deutschen Post AG kopiert, vervielfältigt, gespeichert, übersetzt oder anderweitig reproduziert werden. Dies gilt sinngemäß auch für Auszüge. Alle Rechte bleiben vorbehalten. Die Deutsche Post AG ist berechtigt, ohne vorherige Ankündigungen Änderungen vorzunehmen oder die Dokumente/Software im Sinne des technischen Fortschritts weiterzuentwickeln. Warennamen werden ohne Gewährleistung der freien Verwendbarkeit benutzt. Alle Waren- und Produktnamen sind Warenzeichen oder eingetragene Warenzeichen der jeweiligen Eigentümer. Einstufung gemäß SHB IT der DPAG: Offen 2012 Deutsche Post AG Handbuch für Diensteanbieter 2
Handbuch für Diensteanbieter 3
Inhaltsverzeichnis 1. Einführung ------------------------------------------------------------------------------------------------ 6 1.1 Zweck des Dokumentes...6 1.2 Zielgruppe...6 1.3 Leistungsbeschreibung und AGB...6 2. E-POSTIDENT: Ein Überblick ------------------------------------------------------------------------- 7 2.1 Prozessübersicht...7 2.2 Fachliche Beschreibung...8 2.3 Auslöser...8 2.4 Authentisierung...9 2.5 Authentisierung mit hohem Identitätsnachweis...9 2.6 Autorisierung der Datenfreigabe...9 2.7 Übermittlung der Daten, Datenabruf...9 2.8 Technischer Überblick...10 2.9 Browserkompatibilität...11 3. E-POSTIDENT beauftragen und konfigurieren ---------------------------------------------- 12 3.1 Selbstadministrationsbereich im E-POSTBRIEF Portal aufrufen...12 3.2 E-POSTIDENT beauftragen...12 3.3 Domain konfigurieren und aktivieren...13 3.4 Logo hochladen...16 3.5 Firmenstammdaten im öffentlichen Adressverzeichnis freigeben...17 4. E-POSTIDENT implementieren (Für Diensteanbieter) ------------------------------------- 18 4.1 E-POSTIDENT Link konfigurieren...18 4.2 Authorization Code auslesen...21 4.3 Access Ticket anfordern...22 4.4 Access Ticket entgegennehmen...23 4.5 Identitätsdaten abrufen...24 4.6 Daten entgegennehmen...24 4.7 Fehlercodes auslesen...25 5. E-POSTIDENT ID-Cards------------------------------------------------------------------------------- 26 6. E-POSTIDENT Schema (XML) ---------------------------------------------------------------------- 28 7. Fehlercodes --------------------------------------------------------------------------------------------- 29 7.1 Mögliche Fehler vor Anmeldung...29 7.2 Fehler, die zu einem unspezifizierten Zeitpunkt auftreten können...30 7.3 Mögliche Fehler vor Datenübergabe...30 7.4 Hinweise zum Umgang mit Fehlern...31 7.5 Bekannte Fehlerquellen...31 8. Textbausteine zur Moderation im Fehlerfall------------------------------------------------- 33 8.1 Textbausteine für mögliche Fehler vor Anmeldung...33 8.2 Textbausteine für mögliche Fehler zu einem unspezifiziertem Zeitpunkt...33 8.3 Textbausteine für mögliche Fehler vor Datenübergabe...33 Handbuch für Diensteanbieter 4
Einführung 9. Transaktionshistorie --------------------------------------------------------------------------------- 35 9.1 Transaktionshistorie Kunde...35 9.2 Transaktionshistorie Diensteanbieter...35 10. E-POSTIDENT testen---------------------------------------------------------------------------------- 36 10.1 Check-Connect...36 10.2 E-POSTIDENT -Implementierung kostenlos im Produktionssystem testen...38 11. Änderungen der Schnittstelle sowie dieses Nutzerhandbuches ---------------------- 41 12. Glossar --------------------------------------------------------------------------------------------------- 42 13. Anhang--------------------------------------------------------------------------------------------------- 44 13.1 Abbildungen...44 13.2 Tabellen...44 Handbuch für Diensteanbieter 5
1. EINFÜHRUNG Der E-POSTIDENT Service der Deutschen Post ermöglicht die Identifikation von Kunden gegenüber Diensteanbietern im Internet. Mit E-POSTIDENT versetzt die DPAG E-POSTBRIEF Kunden in die Lage sich mit den im Rahmen der E-POSTBRIEF Registrierung erhobenen und verifizierten Daten, gegenüber Diensteanbietern zu identifizieren. E-POSTIDENT ist beispielsweise für folgende Nutzungsanlässe geeignet: Erstidentifikation von Kunden, die einem Diensteanbieter unbekannt sind, z.b. bei der Registrierung oder vor Abschluss eines Online-Einkaufs. Authentifizierung eines Kunden zur Wiedererkennung in einem Geschäftsprozess. Überprüfung des Mindestalters, z.b. ob ein Kunde das vorgeschriebene Alter für die beabsichtigte Transaktion erreicht hat (Ü18, Ü21). Vergabe eines speziellen Kundenstatus an E-POSTIDENT geprüfte Kunden durch den Diensteanbieter, z.b. durch ein E-POSTIDENT Gütesiegel im Profil des Kunden, das die geprüfte Identität und damit die höhere Verlässlichkeit gegenüber anderen Kunden sichtbar macht. Hinweis Alle im Handbuch verwendeten Parameter unterscheiden Groß- und Kleinschreibung. 1.1 Zweck des Dokumentes Das Nutzerhandbuch E-POSTIDENT versetzt Sie in die Lage, gegen die E-POSTIDENT Schnittstelle zu programmieren, das Selbstadministrationsportal einzurichten. 1.2 Zielgruppe Das vorliegende Dokument richtet sich an: Webentwickler Portaladministratoren Systemarchitekten 1.3 Leistungsbeschreibung und AGB Die AGB E-POSTIDENT sowie die E-POSTIDENT Leistungsbeschreibung definieren in ihrer jeweils aktuellen Fassung die Nutzung und die Integration des E-POSTIDENT Services. Sie finden die Dokumente unter www.epost.de/epostident -> Einbindung -> Zum Download-Center. Handbuch für Diensteanbieter 6
E-POSTIDENT: Ein Überblick 2. E-POSTIDENT: EIN ÜBERBLICK E-POSTIDENT ist Teil der E-POSTBRIEF Internetplattform der DPAG. E-POSTBRIEF Kunden werden im Rahmen der Registrierung durch die DPAG über verschiedene Verifizierungsverfahren identifiziert; die erhobenen Daten stellen die Datenbasis von E-POSTIDENT dar. Nachfolgende Grafik zeigt die Einbettung von E-POSTIDENT im Kontext der E-POSTBRIEF Plattform und die Anbindung Ihrer Infrastruktur an das E-POSTIDENT System: Abb. 1 E-POSTIDENT im Kontext von E-POSTBRIEF 2.1 Prozessübersicht Nachdem der E-POSTIDENT Prozess auf der Website des Diensteanbieters aufgerufen wurde, wird der Kunde auf die E-POSTBRIEF Website der DPAG umgeleitet. Hier loggt sich der Kunde mit seinen E-POSTBRIEF Anmeldedaten ein (E-POSTBRIEF Adresse und Passwort). Im zweiten Schritt erfolgt die Eingabe der übermittelten HandyTAN und im dritten Schritt werden ihm vom E-POSTBRIEF System, die vom Diensteanbieter angeforderten Daten zur Freigabe und Bestätigung angezeigt. Nachdem der Kunde die Daten freigibt, werden die Daten dem Diensteanbieter für eine Dauer von 5 Minuten zur Abholung bereitgestellt. Je nach Geschäftsvorfall kann der Kunde mit seiner Transaktion fortfahren oder der Diensteanbieter verwehrt ihm die Transaktion abhängig vom Ergebnis der Datenabfrage bei E-POSTIDENT, z.b. Ü18 nicht erfüllt. Das nachfolgende Sequenzdiagramm veranschaulicht die Anfrage/Antwort (Request/Response) Beziehungen während der Authentisierungs- und Autorisierungsphasen von E-POSTIDENT: Handbuch für Diensteanbieter 7
E-POSTIDENT: Ein Überblick Abb. 2 Ablaufdiagramm E-POSTIDENT Übersicht 2.2 Fachliche Beschreibung Folgende Transaktionen werden innerhalb von E-POSTIDENT unterschieden: Authentisierungsanfrage Authentisierung mit hohem Identitätsnachweis (E-POSTBRIEF Adresse und Passwort sowie HandyTAN) Autorisierung, Freigabe der Daten durch den Kunden Abruf der freigegebenen Identitätsdaten des Kunden 2.3 Auslöser Der Kunde klickt auf Ihrer Diensteanbieter-Portalseite (Web-Applikation) auf die E-POSTIDENT Schaltfläche, um sich für einen bestimmten Geschäftsvorfall zu authentisieren; dabei wird er auf die Seite des E-POSTIDENT Systems geleitet. Handbuch für Diensteanbieter 8
E-POSTIDENT: Ein Überblick Hinweis Verwenden Sie ausschließlich, die von der DPAG im Web-Integrations- Package zur Verfügung gestellten E-POSTIDENT Schaltflächen. Alle Informationen zur Integration der E-POSTIDENT Schaltflächen finden Sie im Web-Integrations-Package unter www.epost.de/epostident -> Einbindung -> Zum Download-Center. 2.4 Authentisierung Auf der E-POSTIDENT Seite meldet sich der Kunde mit seiner E-POSTBRIEF Adresse und seinem E-POSTBRIEF Passwort an. Zur Erreichung des hohen Authentisierungsniveaus wird ihm eine HandyTAN zugesendet. 2.5 Authentisierung mit hohem Identitätsnachweis Der Kunde gibt die ihm zugesendete HandyTAN auf der Eingabemaske ein. Wurde die HandyTAN korrekt eingegeben, erscheint eine Seite mit den vom Diensteanbieter angeforderten Identitätsdaten. Der Kunde wird aufgefordert, die angezeigten Daten freizugeben; siehe Kapitel 4.1. 2.6 Autorisierung der Datenfreigabe Stimmt der Kunde der Datenfreigabe zu, wird er zurück auf die Diensteanbieter- Portalseite geleitet. Der Kunde wird mit einem Redirect (siehe Kapitel 4.1) auf die mitgelieferte Callback URI (Uniform Resource Identifier) zurückgeleitet (https://ssl.webpack.de/example.com/back), wobei example.com durch Ihre jeweilige Domain zu ersetzen ist und ggf. /back durch Ihre eigene Erweiterung. Im Redirect wird ein authorization code mitgeliefert, der vom Diensteanbieter zum anschließenden Datenabruf benötigt wird. Widerspricht der Kunde der Freigabe seiner Identitätsdaten oder bricht er den Vorgang ab, erfolgt die Weiterleitung auf die Redirect URL (Uniform Resource Locator) im Fehlerfall, siehe Kapitel 4.7. 2.7 Übermittlung der Daten, Datenabruf Um die freigegebenen Identitätsdaten des Kunden vom E-POSTIDENT Server abzurufen, muss auf Diensteanbieterseite ein POST Request ausgeführt werden. Mit dem POST Request wird der authorization code in ein access ticket umgewandelt. Mit dem access ticket können durch einen GET Request die freigegebenen und bereitgestellten Identitätsdaten auf dem E-POSTIDENT Server abgerufen werden. Zurückgeliefert wird eine XML Datei mit den angeforderten und vom Kunden freigegebenen Identitätsdaten. Hinweis Nach Datenabruf sollte dem Kunden ein Bestätigungstext angezeigt werden, der aussagt, dass er erfolgreich authentifiziert wurde und nun mit seinem Geschäftsvorfall fortfahren kann. Im Web-Integrations-Package finden Sie konkrete Textbeispiele zur Moderation sowie detaillierte Integrationsanweisungen. Sie finden das Handbuch für Diensteanbieter 9
E-POSTIDENT: Ein Überblick Web-Integrations-Package unter www.epost.de/epostident -> Einbindung -> Zum Download-Center. 2.8 Technischer Überblick Im Folgenden werden die im E-POSTIDENT System verwendeten Standards beschrieben. 2.8.1 OAuth 2.0 E-POSTIDENT verwendet für die Identifikation und Freigabe von vorher verifizierten Daten das OAuth 2.0 Protokoll. OAuth 2.0 ist ein offenes Protokoll, das eine standardisierte, API-Autorisierung für Desktop-, Web- und Mobile-Applikationen erlaubt, die einen Zugriff auf bzw. die Weitergabe von persönlichen Daten erfordern. Der Kunde kann dem Zugriff auf seine persönlichen Identitätsdaten zustimmen, bzw. die Weiterleitung der Daten erlauben, ohne dabei Zugangsberechtigungen oder Passwörter bekannt zu geben. Folgende OAuth 2.0 Begriffe werden bei E-POSTIDENT verwendet: OAuth 2.0 Bedeutung E-POSTIDENT protected resource Geschützte Ressource Identitätsdaten des Privatkunden resource owner resource server client authorization server Eine Entität, die Zugriff auf eine geschützte Ressource erlauben kann. Der Server, der die geschützten Ressourcen enthält (speichert). Eine Software, die geschützte Ressourcen im Namen des Resource Owners anfordert. Der Server, der Access- Tokens an den Client ausgibt Privatkunde E-POSTIDENT Server Die Web-Applikation des Diensteanbieters E-POSTIDENT Server Tabelle 1. OAuth 2.0 Terminologie OAuth 2.0 definiert den gesamten Prozess, d.h. von der Anmeldung bis hin zur Datenübermittlung. Es ist absolut notwendig, diesen Prozess auf Seiten des Diensteanbieters vollständig zu implementieren. Hinweis Ein impliziter Rückschluss beispielsweise auf die Volljährigkeit eines Kunden nur auf Basis eines übermittelten authorization codes ist unzulässig. Der authorization code wird über den Browser des Diensteanbieters übermittelt und kann daher zu diesem Zeitpunkt nicht als gesicherte Information gelten. Erst durch den Tausch des authorization codes gegen das access ticket wird bestätigt, dass es sich um einen validen authorization code handelt, siehe hierzu Kapitel 4.2. Handbuch für Diensteanbieter 10
E-POSTIDENT: Ein Überblick Weitere Informationen zum OAuth 2.0 Standard finden Sie unter: http://tools.ietf.org/html/draft-ietf-oauth-v2-23 2.8.2 HTTPS Verschlüsselung E-POSTIDENT verwendet ausschließlich HTTPS Verbindungen. Die Identifikationsdaten der Kunden werden seitens E-POSTBRIEF und E-POSTIDENT nach derzeitigem Stand der Technik sicher behandelt. Im gesamten Prozess wird ausschließlich über HTTPS kommuniziert. Zur Abholung der Identifikationsdaten auf der E-POSTBRIEF Plattform muss der im E-POSTIDENT Selbstadministrationsportal abgelegte Parameter client_secret übergegeben werden. 2.9 Browserkompatibilität Das Frontend für den Privatkunden ist für folgende Browser optimiert: Browser Version Microsoft Internet Explorer Version 8 Mozilla Firefox ab Version 3.6 Safari ab Version 5 Handbuch für Diensteanbieter 11
E-POSTIDENT beauftragen und konfigurieren 3. E-POSTIDENT BEAUFTRAGEN UND KONFIGURIEREN Im Selbstadministrationsportal können Sie die Nutzung von E-POSTIDENT beauftragen, sowie verschiedene Einstellungen zum Produkt E-POSTIDENT vornehmen. Der Selbstadministrationsbereich steht Ihnen nach Anmeldung am E-POSTBRIEF Portal zur Verfügung. 3.1 Selbstadministrationsbereich im E-POSTBRIEF Portal aufrufen Um den Selbstadministrationsbereich aufzurufen gehen Sie wie folgt vor: 1. Melden Sie sich im E-POSTBRIEF Portal mit der E-POSTBRIEF Adresse des Administrators an. 2. Wählen Sie im linken, oberen Bildschirmbereich Administration. Sie erhalten eine Handy-TAN auf Ihre hinterlegte Mobilfunknummer. 3. Geben Sie die Handy-TAN im dafür vorgesehenen Feld ein. Je nach Portal- Konfiguration haben Sie bereits nach der Anmeldung eine TAN erhalten und eingegeben. In dem Fall überspringen Sie diesen Schritt. 3.2 E-POSTIDENT beauftragen Voraussetzung Sie befinden sich im Selbstadministrationsbereich. Vorgehen 1. Wählen Sie im Auswahlmenü auf der linken Seite E-POSTIDENT (Abb. 3). Abb. 3 E-POSTIDENT im Selbstadministrationsbereich beauftragen 2. Klicken Sie im oberen Bildschirmbereich auf das Symbol E-Postident beauftragen (Abb. 3). Ein Dialogfenster erscheint. 3. Markieren Sie das Kontrollkästchen zum Bestätigen der AGB und wählen Sie die Schaltfläche E-Postident beauftragen. Handbuch für Diensteanbieter 12
E-POSTIDENT beauftragen und konfigurieren Ein kostenfreier E-POSTBRIEF wird an den Kundenservice der DPAG versendet, in dem die Beauftragung von E-POSTIDENT enthalten ist. Diesen E-POSTBRIEF finden Sie in Ihrem Gesendet -Ordner. Der Kundenservice der DPAG schaltet Sie innerhalb von 3 Werktagen für den Dienst E-POSTIDENT frei, und Sie erhalten einen E-POSTBRIEF, sobald der Dienst freigeschaltet ist. Den aktuellen Status Ihres Auftrags können Sie der Statusmeldung unter Administration -> E-POSTIDENT anzeigen. 4. Nach Ihrer Freischaltung für den Dienst E-POSTIDENT konfigurieren Sie die Parameter wie in den folgenden Abschnitten beschrieben. Hinweis Sie können E-POSTIDENT jederzeit im Selbstadministrationsportal kündigen. Der Vertrag wird innerhalb von drei Tagen beendet. 3.3 Domain konfigurieren und aktivieren Bevor Sie E-POSTIDENT einsetzen, müssen Sie als Diensteanbieter folgende Parameter im Selbstadministrationsportal der E-POSTBRIEF Plattform hinterlegen. Sie können E-POSTIDENT mit mehreren Domains verwenden. Voraussetzung Sie befinden sich im Selbstadministrationsbereich von E-POSTIDENT. E-POSTIDENT ist freigeschaltet. Vorgehen 1. Wählen Sie das Symbol Domain hinzufügen. Sie gelangen auf die Registerkarte Domain anlegen. Abb. 4 Domain anlegen Handbuch für Diensteanbieter 13
E-POSTIDENT beauftragen und konfigurieren 2. Erfassen Sie die erforderlichen Informationen. Weitere Informationen finden Sie in Tabelle 2. Achtung! Identitätsdiebstahl Um Missbrauch mit Ihrem Dienst E-POSTIDENT vorzubeugen, stellen Sie Folgendes sicher: - Das Passwort (ClientSecret) ist geheimgehalten, es ist nur Ihnen als Diensteanbieter persönlich bekannt. - Sie erfassen ein neues Passwort, wenn das Passwort unautorisierten Personen bekannt geworden ist. Empfehlung: Erfassen Sie alle 3 Monate ein neues Passwort. Feldname System- Parameter Beispiel Beschreibung Domain domain_uri Mit ssl-proxy: https://ssl.webpa ck.de/myshop.co m Ohne ssl-proxy: https://www.mys hop.com Die domain_uri wird verwendet, um sicherzustellen, dass der Kunde zu einer korrekten URL (Uniform Resource Locator) zurückgeleitet wird. Daher muss die später bei jedem Request mitgesendete redirect_uri die domain_uri enthalten, z. B. (HTTPS only) -domain_uri: https://ssl.webpack.de/example.c om -redirect_uri: https://ssl.webpack.de/example.c om/back Wenn Sie mehrere Domains anlegen, beachten Sie, dass die Domains eindeutig sein müssen, d.h. jede Domain darf nur genau einmal verwendet werden. Alias alias Shop 1 Der Alias-Name wird während des Logins und der Datenfreigabe und in der Transaktionsübersicht angezeigt. Der Alias hat maximal 16 Zeichen und ist in UTF-8 kodiert. Leerzeichen sind erlaubt. Handbuch für Diensteanbieter 14
E-POSTIDENT beauftragen und konfigurieren Feldname ClientSecret, Bestätigung ClientSecret System- Parameter client_secret Beispiel Client ID client_id 123example456 Beispiel: 93bc22b4-efeb- 4e84-b7cec169c29ea79f a5d0f05d-9835-4681-8c47-2c03fb0defaa Beschreibung Erfassen Sie ein Passwort nach folgenden Regeln: -Zeichenlänge 10-20 Zeichen, -Erlaubte Zeichen: a-z, A-Z, 0-9, -Keine Sonderzeichen. Gemäß OAuth 2.0 wird das client_secret vom Diensteanbieter gemeinsam mit dem authorization code gegen das Access ticket eingetauscht. Die Client ID ist die Identifikationsnummer jeder Domain eines Diensteanbieters und wird bei der Anlage einer Domain automatisch erzeugt. Die Client ID lässt sich nicht ändern. Hinweis: Die im Selbstadministrationsportal angezeigte Client ID hat das Format: xxxxxxxx-xxxx-4xxx-yxxxxxxxxxxxxxxx Dabei wird für jedes x ein hexadezimales Zeichen und für y eines der folgenden Zeichen verwendet: 0-9, a-b. Kostenstelle cost_center Kostenstelle0815 Optional: Erfassen Sie den Namen Ihrer (internen) Kostenstelle. Die Kostenstelle wird später in Ihrer Rechnung angezeigt und ermöglicht Ihnen so die Zuordnung von E-POSTIDENT Vorgängen in Ihrer Buchhaltung. Die Bezeichnung der Kostenstelle hat maximal 256 Zeichen. Er ist in UTF-8 kodiert, Leerzeichen sind erlaubt. Serverstandort innerhalb der Ja/Nein Geben Sie an, ob sich der Standort der Server, auf denen die Identitätsdaten gespeichert Handbuch für Diensteanbieter 15
E-POSTIDENT beauftragen und konfigurieren Feldname System- Parameter Beispiel Beschreibung EU und verarbeitet werden, innerhalb oder außerhalb der EU/EWG befindet. Aus rechtlichen Gründen erhält jeder Kunde vor seiner Zustimmung zur Übertragung der Daten einen Hinweis, wenn sich der Standort Ihrer Server außerhalb der EU/EWG befindet. Tabelle 2. Konfigurationsparameter Selbstadministration Diensteanbieter 3. Um die Domain und damit den Dienst E-POSTIDENT zu aktivieren, markieren Sie unter E-POSTIDENT Status den Auswahlknopf Aktiv. 4. Die Domain wird auf der Registerkarte E-POSTIDENT angezeigt. 5. Um die Parameter einer Domain zu ändern, wählen Sie das Symbol Bearbeiten. Die automatisch generierte Client ID lässt sich nicht ändern. Hinweis Löschen einer Domain Um eine Domain zu löschen, deaktivieren Sie die Domain zunächst. Sie können eine Domain löschen, wenn mindestens 60 Tage seit der letzten Transaktion vergangen sind. 3.4 Logo hochladen Um die Kunden-Ansicht auf E-POSTIDENT zu personalisieren, können Sie Kunden Ihr eigenes Logo im rechten, oberen Bildbereich präsentieren. Das Hochladen eines Logos ersetzt ein evtl. schon vorhandenes Logo. Hinweis Das Bild wird hochkant im Format 3:4 angezeigt. Voraussetzungen: Die Bild-Datei für das Logo ist maximal 2 MB groß. Die Bild-Datei hat das Dateiformat jpg, gif oder png. Sie sind am E-POSTBRIEF Portal angemeldet. Vorgehen 1. Wählen Sie im linken, oberen Bildschirmbereich Administration. Sie erhalten eine TAN auf Ihre hinterlegte Mobilfunknummer, geben Sie diese im dafür vorgesehenen Feld ein. Je nach Portal-Konfiguration haben Sie bereits nach Handbuch für Diensteanbieter 16
E-POSTIDENT beauftragen und konfigurieren der Anmeldung eine TAN erhalten und eingegeben. In dem Fall überspringen Sie diesen Schritt. 2. Wählen Sie im Auswahlmenü auf der linken Seite Firmenstammdaten. 3. Klicken Sie im oberen Bildschirmbereich auf die Schaltfläche Bearbeiten. 4. Laden Sie auf der rechten Seite die Bilddatei für Ihr Logo hoch. 3.5 Firmenstammdaten im öffentlichen Adressverzeichnis freigeben Ihre Kunden können Sie nur dann im öffentlichen E-POSTBRIEF Adressverzeichnis finden, wenn Sie Ihre Einträge dafür freigegeben haben. Voraussetzungen: Sie sind am E-POSTBRIEF Portal angemeldet. Vorgehen 1. Wählen Sie im linken, oberen Bildschirmbereich Administration. Sie erhalten eine Handy-TAN auf Ihre hinterlegte Mobilfunknummer. 2. Geben Sie die Handy-TAN im dafür vorgesehenen Feld ein. Je nach Portal- Konfiguration haben Sie bereits nach der Anmeldung eine TAN erhalten und eingegeben. In dem Fall überspringen Sie diesen Schritt. 3. Im Auswahlmenü auf der linken Seite wählen Sie Firmenstammdaten. 4. Wählen Sie im oberen Bildschirmbereich die Schaltfläche Freigabe Adressverzeichnis. 5. Nehmen Sie Ihre individuellen Freigabeeinstellungen vor. Handbuch für Diensteanbieter 17
E-POSTIDENT implementieren (für Diensteanbieter) 4. E-POSTIDENT IMPLEMENTIEREN (FÜR DIENSTEANBIETER) Als Diensteanbieter müssen Sie folgende Vorgänge implementieren: 1. E-POSTIDENT Links konfigurieren, siehe Kapitel 4.1 2. authorization code auslesen, siehe Kapitel 4.2 3. access ticket anfordern, siehe Kapitel 4.3 4. access ticket entgegennehmen, siehe Kapitel 4.4 5. Identitätsdaten anfordern, siehe Kapitel 4.5 6. Identitätsdaten entgegennehmen, siehe Kapitel 4.6 7. Fehlercodes auslesen, siehe Kapitel 4.7 Voraussetzungen Folgende Voraussetzungen müssen vor Implementierung der E-POSTIDENT Vorgänge erfüllt sein: Damit Sie sich beim fachlichen Test Ihrer Implementierung über E-POSTIDENT authentifizieren können, besitzen Sie ein aktives E-POSTBRIEF Konto besitzen (siehe auch AGB E-POSTIDENT). Sie haben im Selbstadministrationsportal eine Domain für Ihre Website angelegt, alle erforderlichen Parameter zu dieser Domain mit zulässigen Werten gefüllt und die Domain aktiviert (siehe Kapitel 3). Alle vertraglichen Voraussetzungen, die in den AGB E-POSTIDENT aufgeführt sind, sind erfüllt (siehe AGB E-POSTIDENT). Sie finden die AGB unter www.epost.de/epostident -> Einbindung -> Zum Download- Center. 4.1 E-POSTIDENT Link konfigurieren Erläuterung Der Kunde wird auf Ihrer Website aufgefordert, sich über die E-POSTIDENT Schaltfläche zu authentifizieren. Klickt der Kunde auf die E-POSTIDENT Schaltfläche, wird er durch den hier beschriebenen Link auf das E-POSTIDENT System geleitet. Der Link enthält unter anderem die Callback URI (redirect_uri mit https- Schema), auf die der Kunde nach Abschluss der Datenfreigabe im E-POSTIDENT System zurück auf Ihre Diensteanbieter Portalseite geleitet wird. Hinweis Verwenden Sie ausschließlich die von der DPAG im Web-Integrations- Package zur Verfügung gestellten E-POSTIDENT Schaltflächen. Alle Informationen zur Integration der E-POSTIDENT Schaltflächen sind im Web-Integrations-Package beschrieben. Sie finden das Web- Integrations-Package unter www.epost.de/epostident -> Einbindung -> Zum Download-Center. Handbuch für Diensteanbieter 18
E-POSTIDENT implementieren (für Diensteanbieter) Voraussetzung Sie haben eine Domain konfiguriert und aktiviert (siehe Kapitel 3.3). Vorgehensweise Programmieren Sie einen Link auf die E-POSTIDENT Seite mit folgenden Parametern: Parameter Wert Beschreibung Pflicht/ Optional redirect https://ident.epost.de/ oauth2/login Weiterleitung auf E-POSTIDENT Seite client_id 123example456 Identifikationsnummer Ihrer Domain, die Sie vom E-POSTIDENT System bekommen haben und die im Selbstadministrationsportal angezeigt wird. Hinweis: Ersetzen Sie 123example456 durch Ihre jeweilige Client ID. redirect_uri https://ssl.webpack.de /example.com/back Zurückleitung vom E-POSTIDENT Server auf die Diensteanbieterportalseite. Hinweis: Die redirect_uri (Uniform Resource Identifier) muss die Domain-URI enthalten. Hinweis: Die redirect_uri muss URL encoded sein und darf aus Sicherheitsgründen eine max. Länge von 155 Zeichen nicht überschreiten. Hinweis: Ersetzen Sie example.com durch Ihre Domain und ggf. /back durch Ihre eigene Erweiterung. Pflicht Pflicht Pflicht Handbuch für Diensteanbieter 19
E-POSTIDENT implementieren (für Diensteanbieter) Parameter Wert Beschreibung Pflicht/ Optional scope 10 Im scope Parameter wird die ID der ID-Card mitgegeben, deren Datensätze übermittelt werden sollen. Die Auswahl einer bestimmten ID-Card bestimmt den Umfang der zurück gelieferten Daten. Die ID-Card definiert die vom Diensteanbieter angeforderten Identitätsdatenfelder eines Kunden, die übermittelt werden sollen (siehe Kapitel 5). Eine Übersicht über alle derzeit verfügbaren ID-Cards und die jeweils zur Abfrage zu verwendenden Werte finden Sie im Dokument Datenpakete unter www.epost.de/epostident -> Einbindung -> Zum Download- Center. reason Verifikation z.b.: Der Verkauf Ihres Mobiltelefons Der hier übermittelte Freitext wird dem Kunden angezeigt: - Bei der Anmeldung an den E-POSTIDENT Server - In der SMS-Nachricht - Während der Datenfreigabe Hinweis: Der Text darf eine max. Länge von 66 Zeichen nicht überschreiten. Die Zeichen müssen URL-encoded sein. Pflicht Pflicht Hinweis: Enthält der Parameter zu viele oder unerlaubte Zeichen, kann die Darstellung des Textes in der SMS-Nachricht unvollständig sein. response_type code Muss immer den Wert code enthalten. Pflicht Handbuch für Diensteanbieter 20
E-POSTIDENT implementieren (für Diensteanbieter) Parameter Wert Beschreibung Pflicht/ Optional state Kunden-Bezeichner In diesem Parameter übermitteln Sie den von Ihnen zugeordneten dedizierten Kunden Bezeichner. Der Wert wird vom E-POSTIDENT System unverändert zurück gegeben. Damit können Sie diesen Kunden im weiteren Prozess eindeutig zuordnen (z.b. Warenkorb). Pflicht Tabelle 3. Parameterliste Aufbau Redirect URL (Uniform Resource Locator) Beispiel https://ident.epost.de/oauth2/login? client_id=123example456& redirect_uri=https://ssl.webpack.de/example.com/back& scope=10& reason= Der%20Verkauf%20Ihres%20Mobiltelefons & response_type=code& state=meinkunde_4711 Hinweis Nach Aufbau des Redirect findet eine E-POSTIDENT interne Prüfung statt, bei der alle notwendigen Voraussetzungen geprüft werden. Falls die Prüfung fehlt schlägt oder ein negatives Ergebnis geliefert wird, wird der Kunde entsprechend der in Kapitel 7 beschriebenen Fehlermeldungen zurückgeleitet, ohne dass ihm seitens E-POSTIDENT eine Login-Maske oder Fehlermeldung angezeigt wird. 4.2 Authorization Code auslesen Hat der Kunde der Datenfreigabe zugestimmt, wird der authorization code im Redirect an die Diensteanbieter-Portalseite mitgeliefert. Vorgehen 1. Identifizieren Sie den Kunden anhand des Wertes im Parameter state und lesen Sie den beim Redirect mitgelieferten der authorization code im Parameter code aus. Der authorization code hat eine Größe von 4096 Byte. 2. Ersetzen Sie den Wert example.com durch Ihre Domain und ggf. /back durch Ihre eigene Erweiterung. Handbuch für Diensteanbieter 21
E-POSTIDENT implementieren (für Diensteanbieter) Beispiel https://ssl.webpack.de/example.com/back? code=<123code456>& state=meinkunde_4711 Mit dem authorization code können Sie im nächsten Schritt das access ticket anfordern, um die Daten abzurufen. 4.3 Access Ticket anfordern 1. Programmieren Sie mit folgenden Parametern einen POST Request, um das access ticket anzufordern: Parameter token endpoint Host: content-type: code client_id client_secret redirect_uri grant_type Wert POST /oauth2/token HTTP/1.1 https://ident.epost.de application/x-www-form-urlencoded Fügen Sie den ausgelesener Authorisierungscode ein. Im Beispiel in Kap. 4.2: Authorization Code auslesen: 123authorization_code456. Fügen Sie die von Ihnen konfigurierte Client ID ein. Im Beispiel in Kap. 3.3: Domain konfigurieren und aktivieren: 123example456. Fügen Sie das von Ihnen konfigurierte Passwort für Sie als Diensteanbieter ein. Im Beispiel in Kap. 3.3: Domain konfigurieren und aktivieren: example_s_e_c_r_e_t. https://ssl.webpack.de/example.com/back Ersetzen Sie die example.com durch Ihre Domain und ggf. /back durch Ihre eigene Erweiterung. authorization_code Tabelle 4. Parameterliste access ticket anfordern 2. Schicken Sie den folgenden POST Request an den E-POSTIDENT token endpoint: https://ident.epost.de/oauth2/token wie im folgenden Beispiel dargestellt. Handbuch für Diensteanbieter 22
E-POSTIDENT implementieren (für Diensteanbieter) Beispiel POST /oauth2/token HTTP/1.1 Host: https://ident.epost.de Content-Type: application/x-www-form-urlencoded ; charset=utf-8 code=123authorization_code456& client_id=123example456& client_secret=example_s_e_c_r_e_t& redirect_uri=https://ssl.webpack.de/example.com/back& grant_type=authorization_code 4.4 Access Ticket entgegennehmen Lesen Sie das access ticket aus: Das kurzlebige access ticket wird ohne refresh token base64 codiert im JSON Format zurückgeliefert. Hinweis Das access ticket hat eine Gültigkeit von 5 Minuten (300 sec.) Beispiel HTTP/1.1 200 OK Content-Type: text/plain;charset=utf-8 Cache-Control: no-store Pragma: no-cache 123access_token456 Mit dem access ticket können Sie im nächsten Schritt die Identitätsdaten abrufen. Hinweis Mit erfolgreicher Übertragung des access tickets von der DPAG an den Diensteanbieter erfolgt die Berechnung des Transaktionsentgelds für die angeforderte ID-Card entsprechend dem vertraglich vereinbarten Tarif, siehe auch AGB E-POSTIDENT. Handbuch für Diensteanbieter 23
E-POSTIDENT implementieren (für Diensteanbieter) 4.5 Identitätsdaten abrufen Mit dem access ticket können die freigegebenen Identitätsdaten des Kunden über einen GET request Befehl abgeholt werden. Das access ticket wird im Authorization header des Requests übergeben. Verwenden Sie dazu das unveränderte base64-codierte access ticket, dessen Entgegennahme in Kapitel 4.4 beschrieben ist. Programmieren Sie einen GET request zur Datenabholung mit folgenden Parametern: Parameter Host: Authorization: Wert https://ident.epost.de Bearer 123access_token456 Tabelle 5. Parameterliste Identitätsdaten abrufen Beispiel GET /oauth2/identdata Host: https://ident.epost.de Authorization: Bearer 123access_token456 Accept: application/xml Accept-Charset:utf-8 4.6 Daten entgegennehmen Die http-rückgabe an den Diensteanbieter enthält ein Dokument im XML Format. Nehmen Sie die XML-Datei mit den Daten entgegen. Beispiel HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <identdata> <epostaddress>hans.schmidt@epost.de</epostaddress> <givenname>hans</givenname> <familyname>schmidt</surname> <zipcode>50937</zipcode> <city>köln</city> <dateofbirth>1966-08-26 00:00:00.0</dateofbirth> </identdata> Enthält die ID-Card ein optionales Datenfeld, das nicht ausgefüllt ist, wird ein leeres XML-Tag für dieses Datenfeld zurückgeliefert. Handbuch für Diensteanbieter 24
E-POSTIDENT implementieren (für Diensteanbieter) Beispiel HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <identdata> <epostaddress>hans.schmidt@epost.de</epostaddress> <givenname>hans</givenname> <familyname>schmidt</surname> <birthname/> <zipcode>50937</zipcode> <city>köln</city> <dateofbirth>1966-08-26 00:00:00.0</dateofbirth> </identdata> Hinweis Die XML Datei genügt dem in Kapitel 6 beschriebenen XML Schema. 4.7 Fehlercodes auslesen Im Fehlerfall wird der Kunde per Redirect (via http 302) samt Fehlercode auf die konfigurierte callback_uri (redirect_uri) geleitet, z.b. wenn der Kunde seine Identitätsdaten NICHT freigibt oder schon vorher die Verbindung zum E-POSTIDENT Service abbricht. Zeigen Sie dem Kunden, die im Kapitel 8 Textbausteine zur Moderation im Fehlerfall angegebenen Textbausteine an. Anhand des Werts im Parameter state identifizieren Sie den Kunden und leiten ihn durch Ihren Folgeprozess. Beispiel https://ssl.webpack.de/example.com/back? error=<errorcode>& state=meinkunde_4711 Hinweis Ersetzen Sie example.com durch Ihre Domain und ggf. /back durch Ihre eigene Erweiterung. Implementieren Sie die dem Kunden angezeigte Folgeseite in Abhängigkeit von der übermittelten Fehlersituation und Fehlernachricht. Berücksichtigen Sie dabei die Moderationsempfehlungen aus dem Web-Integration-Package und die in Kapitel 8 angegebenen Textbausteine für die Moderation im Fehlerfall. Eine Liste der gültigen Fehlercodes finden Sie in Kapitel 7. Handbuch für Diensteanbieter 25
E-POSTIDENT ID-Cards 5. E-POSTIDENT ID-CARDS ID-Cards sind Identitätsdatensätze von Kunden innerhalb von E-POSTIDENT. Jede ID- Card stellt eine Teilmenge der innerhalb von E-POSTIDENT vorliegenden beziehungsweise abgeleiteten Kundenstammdaten dar. Bei jeder Nutzung von E-POSTIDENT muss die Anwendung des Diensteanbieters (client) die ID der jeweils angeforderten ID-Card im Parameter scope beim initialen Link mitgegeben werden. ID-Cards setzen sich derzeit aus folgenden Datenfeldern zusammen; alle Werte sind UTF-8 kodiert: Technischer Bezeichner Attribut Format Gültigkeitsregeln givenname Vorname String(29) additionalgivennames Weitere Vornamen String(50) familyname Nachname String(29) birthname Geburtsname String(40) dateofbirth Geburtsdatum Date yyyy-mm-dd HH:mm:ss.S placeofbirth Geburtsort String(80) nationality Staatsangehörigkeit String(2) 2-buchstabiges Länderkennzeichen, (nach ISO 3166), z.b. DE street Straße String(50) housenumber Hausnummer String(10) addressaddon Adresszusatz String(40) zipcode Postleitzahl String(5) city Ort String(80) country Staat String(2) 2-buchstabiges Länderkennzeichen, (nach ISO 3166), z.b. DE mobilephone Mobilfunknummer String(20) Mobilfunknummer inklusive Länderkennung epostaddress E-POSTBRIEF Adresse String(128) over18 Ü18 {true false} salutation Anrede {mr mrs} oder {Herr Frau} Bemerkung: Prüfen Sie auf Gleichheit mit mr oder Herr bzw. auf mrs oder Frau Tabelle 6. ID-Card-Parameter Handbuch für Diensteanbieter 26
E-POSTIDENT ID-Cards Nachstehende Tabelle zeigt beispielhaft eine E-POSTBRIEF ID-Card, Ergänzungen sind jederzeit möglich. ID-Card-Nummer 90/XL ID-Card-Name Produkt-Bezeichnung Ident-Check Plus Anrede Vorname Nachnahme Geburtsname Enthaltene Attribute (Kunden-Identitätsdaten) Weitere Vornamen Geburtsdatum Geburtsort Straße Hausnummer Adresszusatz Postleitzahl Ort Länderkennzeichen E-POSTBRIEF Adresse Mobiltelefon-Nr. Ü18 Staatsangehörigkeit Tabelle 7. Ident-Check Plus Hinweis Eine Übersicht über alle derzeit verfügbaren ID-Cards und die jeweils zur Abfrage zu verwendenden Werte finden Sie im Dokument Datenpakete unter www.epost.de/epostident -> Einbindung -> Zum Download-Center. Handbuch für Diensteanbieter 27
E-POSTIDENT Schema (XML) 6. E-POSTIDENT SCHEMA (XML) Hinweis Das nachstehende XML Schema ist als Referenz-Information zu sehen. Dieses Schema, ist nicht für Validierungszwecke zu verwenden. Zusätzliche Elemente können jederzeit hinzugefügt werden. <?xml version="1.0" encoding="utf-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:tns="http://www.epost.de/schema/e-postident" targetnamespace=" www.epost.de/schema/e-postident" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:annotation> <xsd:documentation xml:lang="en"> ID-Card schema for E-POSTIDENT. Copyright 2011-2012 Deutsche Post AG. All rights reserved. </xsd:documentation> </xsd:annotation> <xsd:element name="identdata" type="tns:idcardtype" /> <xsd:complextype name="idcardtype"> <xsd:all> <xsd:element name="salutation" type="xsd:string" minoccurs="0" maxoccurs="1" /> <xsd:element name="familyname" type="xsd:string" minoccurs="0" maxoccurs="1" /> <xsd:element name="givenname" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="birthname" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="additionalgivennames" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="dateofbirth" type="xsd:date" minoccurs="0" maxoccurs="1"/> <xsd:element name="placeofbirth" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="nationality" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="street" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="housenumber" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="addressaddon" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="zipcode" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="city" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="country" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="mobilephone" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="epostaddress" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="over18" type="xsd:boolean" minoccurs="0" maxoccurs="1"/> <xsd:element name="over21" type="xsd:boolean" minoccurs="0" maxoccurs="1"/> <xsd:all/> </xsd:complextype> </xsd:schema> Handbuch für Diensteanbieter 28
Fehlercodes 7. FEHLERCODES Während eines E-POSTIDENT Prozesses können Fehler auftreten. Mögliche Fehlerszenarien sind: Fehler, die vor einem Kunden-Login auftreten können Fehler, die zu einem unspezifizierten Zeitpunkt auftreten können Fehler, die vor dem Abrufen der Identitätsdaten des Kunden auftreten können, also vor Abholung der Daten durch den Diensteanbieter. Hinweis Beachten Sie, dass bei den in Abschnitt 7.1 aufgeführten möglichen Fehlern weder eine Fehlermeldung noch eine Login-Seite angezeigt wird. Textbausteine zur Moderation im Fehlerfall finden Sie in Kapitel 8. 7.1 Mögliche Fehler vor Anmeldung Fehlerfälle E-POSTIDENT nicht verfügbar E-POSTIDENT global deaktiviert E-POSTIDENT Technische Störung Diensteanbieter gesperrt Fehlernachricht im E-POSTIDENT Redirect temporarily_unavailable (falls Portal noch verfügbar) temporarily_unavailable (falls Portal noch verfügbar) temporarily_unavailable (falls Portal noch verfügbar) unauthorized_client E-POSTIDENT ist derzeit für Sie deaktiviert unauthorized_client E-POSTIDENT ist derzeit für Sie nicht freigeschaltet ID-Card nicht bekannt Bonitätsprüfung negativ Preis der ID-Card konnte nicht ermittelt werden Nicht alle Parameter vorhanden Response_type lautet nicht "code" Fehlerhafte client_id und/oder redirect_uri: Redirect konnte nicht ausgelöst werden. invalid_request invalid_scope unauthorized_client unauthorized_client invalid_request unsupported_response_type Tabelle 8. E-POSTIDENT Fehlercodes vor Anmeldung Hinweis Die hier definierten Fehlerwerte werden dem Kunden im Parameter error mit dem Redirect mitgegeben, siehe Kapitel 4.7. Handbuch für Diensteanbieter 29
Fehlercodes 7.2 Fehler, die zu einem unspezifizierten Zeitpunkt auftreten können Fehlerfälle Kunde bricht Freigabeprozess an beliebiger Stelle ab Kunde widerspricht der Freigabe seiner Identitätsdaten Kunde schließt Browser Verbindung zwischen Kunde und E-POSTIDENT bricht ab Browser des Kunden stürzt ab Unerwarteter Fehler im E-POSTIDENT Service Fehlernachricht im E-POSTIDENT Redirect access_denied access_denied server_error Tabelle 9. E-POSTIDENT Fehlercodes, zu einem unspezifizierten Zeitpunkt 7.3 Mögliche Fehler vor Datenübergabe Fehlerfälle Beim Tausch des authorization code gegen das Access ticket: Für die übergebene client_id existiert kein Kunde Beim Tausch des authorization code gegen das access ticket: Redirect-URI entspricht nicht der im initialen Request übergebenen Redirect- URI Beim Tausch des authorization code gegen das access ticket: Fehlerhafter authorization code Fehlerhaftes access ticket beim Abholen der Identitätsdaten Fehlernachricht im E-POSTIDENT Redirect invalid_client, HTTP-Statuscode 400 (Bad Request) invalid_client, HTTP-Statuscode 400 (Bad Request) invalid_grant, HTTP-Statuscode 400 (Bad Request) keine Fehlerklasse, HTTP-Statuscode 404 (Not Found) Tabelle 10. Fehlercodes E-POSTIDENT vor Daten-Übergabe Handbuch für Diensteanbieter 30
Fehlercodes 7.4 Hinweise zum Umgang mit Fehlern Im Falle des Auftretens von Fehlern beachten Sie folgende Hinweise: Implementieren Sie die dem Kunden angezeigte Folgeseite in Abhängigkeit von der übermittelten Fehlersituation und Fehlernachricht. Berücksichtigen Sie dabei die Designrichtlinien aus dem Web-Integration-Package, siehe auch Kapitel 8 Textbausteine zur Moderation im Fehlerfall. Sollten in der Produktionsumgebung Fehler auftreten, tun Sie Folgendes: a) Notieren Sie die minutengenaue Fehlerzeit sowie den Fehlerreferenzcode auf der Fehlermaske (im Browser). b) Erstellen Sie einen Screenshot des Fehlers. c) Kopieren Sie den kompletten Inhalt des URL (Uniform Resource Locator) als Text in eine Datei. d) Notieren Sie, welche Aktionen durchgeführt wurden unmittelbar bevor der Fehler auftrat. e) Senden Sie die gesammelten Informationen an den Kundenservice der DPAG. 7.5 Bekannte Fehlerquellen In diesem Abschnitt möchten wir Sie auf Fehler hinweisen, die bei der fehlerhaften Implementierung von E-POSTIDENT auftreten können. Erhält der Nutzer nach Betätigen der E-POSTIDENT Schaltfläche auf Ihrer Website die hier abgebildete Fehlermeldung, so notieren Sie die angezeigte Referenznummer und die minutengenaue Fehlerzeit. Abb. 5 Fehlermeldung Mögliche Ursachen könnten sein Die Client ID enthält einen Tippfehler Sie verwenden die Client ID aus der Test-Umgebung für die Produktion oder umgekehrt Handbuch für Diensteanbieter 31
Fehlercodes Der Parameter redirect_uri enthält einen Tippfehler Sie verwenden die redirect_uri aus der Test-Umgebung für die Produktion oder umgekehrt Sie verwenden eine fehlerhafte Parameterbezeichnung, etwa redirect_url anstelle von redirect_uri Handbuch für Diensteanbieter 32
Textbausteine zur Moderation im Fehlerfall 8. TEXTBAUSTEINE ZUR MODERATION IM FEHLERFALL Verwenden Sie nachstehende Textbausteine zur Moderation im Fehlerfall. 8.1 Textbausteine für mögliche Fehler vor Anmeldung Fehlerfall temporarily_unavailable zu verwendende Textbausteine Leider steht der Service momentan nicht zur Verfügung. Wichtig: In diesem Fall darf der Name des E-POSTIDENT Service nicht namentlich genannt werden! Fehlerfall unauthorized_client invalid_request invalid_scope unauthorized_client invalid_request unsupported_response_type zu verwendende Textbausteine Leider ist uns ist ein Fehler unterlaufen. Wir arbeiten bereits an der Fehlerbehebung. Bitte versuchen Sie es später noch einmal. Wichtig: In diesem Fall darf der Name des E-POSTIDENT Service nicht namentlich genannt werden! 8.2 Textbausteine für mögliche Fehler zu einem unspezifiziertem Zeitpunkt Fehlerfall access_denied, server_error zu verwendende Textbausteine Leider konnten Sie nicht erfolgreich identifiziert werden. Wichtig: In diesem Fall darf der Name des E-POSTIDENT Service nicht namentlich genannt werden! 8.3 Textbausteine für mögliche Fehler vor Datenübergabe Fehlerfall invalid_client (HTTP-Statuscode 400) invalid_grant (HTTP-Statuscode 400) HTTP-Statuscode 404 zu verwendende Textbausteine Leider uns ist ein Fehler unterlaufen. Wir arbeiten bereits an der Fehlerbehebung. Bitte versuchen Sie es später noch einmal. Wichtig: In diesem Fall darf der Name des E-POSTIDENT Service nicht namentlich genannt werden! Handbuch für Diensteanbieter 33
Textbausteine zur Moderation im Fehlerfall Hinweis Im Fehlerfall sollten Sie, falls möglich, Ihrem Kunden alternative Möglichkeiten aufzeigen, den entsprechenden Business Prozess weiterzuführen. Bieten Sie Ihrem Kunden z.b. ein alternatives Zahlungsverfahren an. Handbuch für Diensteanbieter 34
Transaktionshistorie 9. TRANSAKTIONSHISTORIE E-POSTIDENT Transaktionen werden im E-POSTBRIEF Portal sowohl dem Diensteanbieter als auch dem Kunden in der Historie angezeigt. Transaktionen sind für 60 Tage sichtbar und werden danach automatisch gelöscht. 9.1 Transaktionshistorie Kunde Der Kunde sieht in der Historie für jede erfolgreich durchgeführte Transaktion: Datum und Uhrzeit der Transaktion Alias des Diensteanbieters, der die Identitätsdaten abgerufen hat Wert des Parameters reason (Anlass) Domain-URI, für welche der Kunde seine Daten freigegeben hat Der Kunde hat die Möglichkeit, sich in einer Detailansicht die freigegebenen Identitätsdaten zu jeder Transaktion anzusehen (z. B. Name, Geburtsdatum, Adresse). 9.2 Transaktionshistorie Diensteanbieter Der Diensteanbieter sieht in der Historie für jede erfolgreich durchgeführte Transaktion: Transaktionsnummer Datum und Uhrzeit der Transaktion Wert des Parameters reason (Anlass) Produktbezeichnung der ID-Card (inkl. der enthaltenen Attribute ohne Werte) Ergebnis (Status) jeder angelegten Transaktion Domain-URI, für welche der Kunde seine Daten freigegeben hat Der Diensteanbieter kann eine Auswahl von Transaktionen als CSV-Datei herunterladen. Handbuch für Diensteanbieter 35
E-POSTIDENT testen 10. E-POSTIDENT TESTEN Dieses Kapitel beschreibt, wie Sie ihren E-POSTIDENT Service testen können. Sie haben folgende Möglichkeiten: Mit Check Connect die Anbindung an E-POSTIDENT prüfen. Als Administrator die Implementierung aus der Sicht eines Privatkunden kostenlos in der Produktionsumgebung testen. Grundsätzliches Vorgehen: 1. Um die Anbindung an E-POSTIDENT zu prüfen, rufen Sie den Service Check- Connect in der Produktionsumgebung auf. Verwenden Sie den Host https://ident.epost.de. Weitere Informationen finden Sie in Kap. 10.1.1: Parameter für den Aufruf von Check Connect. 2. Testen Sie Ihre Implementierung solange kostenlos in der Produktionsumgebung, bis die Implementierung technisch erfolgreich ist. Ihr Administrator-Konto fungiert dabei als Test-Benutzer (siehe Kap. 10.2). 3. Um Ihre Implementierung fachlich zu testen, führen Sie mit einem Privatkunden- Account Ihrer Wahl mindestens eine Identifizierung aus 4. Um den Dienst E-POSTIDENT Ihren Kunden zugänglich zu machen, laden Sie Ihre Implementierung z. B. aus Ihrem Entwicklungs- oder Testsystem in Ihr Produktionssystem hoch. 10.1 Check-Connect E-POSTIDENT stellt Ihnen den Service Check-Connect zur Verfügung. Gegen diese Schnittstelle können Sie Ihre grundsätzliche Anbindung an E-POSTIDENT sowie die korrekte Zusammensetzung aus Client ID und Domain-URI überprüfen. Check-Connect liefert im Fehlerfall Details, die Ihnen Hinweise auf anzupassende Einstellungen geben können. Handbuch für Diensteanbieter 36
E-POSTIDENT testen 10.1.1 Parameter für den Aufruf von Check Connect Sie rufen den Service Check-Connect auf, indem Sie einen GET request mit folgenden Parametern erstellen: Parameter Wert Beschreibung Pflicht/ Optional clientid 123example456 Identifikationsnummer Ihrer Domain, die Sie vom E-POSTIDENT System bekommen haben und die im Selbstadministrationsportal angezeigt wird. Hinweis: Ersetzen Sie 123example456 durch Ihre jeweilige Client ID. Pflicht domainuri https://ssl. webpack.de/e xample.com Die Domain-URI (Uniform Resource Identifier) des Diensteanbieters wird in der Selbstadministration gepflegt. Pflicht Hinweis: Ersetzen Sie example.com durch Ihre eigene Domain. Achtung: Der Parameter enthält an dieser Stelle keinen Unterstrich! 10.1.2 Beispiele für Check-Connect Aufrufe Nachfolgend finden Sie Konfigurationsbeispiele für Aufruf und Response von Check- Connect. Hinweis Die nachfolgenden Code-Beispiele enthalten Leerzeichen, die ausschließlich aus optischen Gründen verwendet wurden. Beispiel für den URL-Aufruf https://ident.epost.de/oauth2/clientverification? clientid=123example456& domainuri=https://ssl.webpack.de/example.com Als Antwort liefert der Service Check-Connect ein JSON-Objekt mit den Attributen status und message. Die möglichen Antworten sind in der folgenden Tabelle dargestellt. Handbuch für Diensteanbieter 37
E-POSTIDENT testen 10.1.3 Mögliche Antworten des Services Check-Connect status message 200 clientid and domainuri matched 400 clientid matched but domainuri mismatched 403 clientservice activation state is false Bedeutung Die angegebene Client ID existiert und die Domain-URI ist zu dieser Client ID hinterlegt. Die Client ID existiert, aber der Domain-URI passt nicht zur Client ID. Prüfen Sie die in der Selbstadministration hinterlegte Domain-URI. Die angegebene Client ID existiert, die Client Konfiguration wurde aber nicht aktiviert. Aktivieren Sie E-POSTIDENT in diesem Fall in der Selbstadministration des Portals. 404 clientid mismatched Die angegebene Client ID existiert nicht. Antwort-Beispiel HTTP/1.1 200 OK Content-Type: text/plain;charset=utf-8 { "status": "200", "message": "clientid and domainuri matched" } 10.2 E-POSTIDENT-Implementierung kostenlos im Produktionssystem testen Sie können als Administrator Ihre Implementierung von E-POSTIDENT in der Rolle als Privatkunde kostenlos im Produktionssystem testen. Dazu steht die kostenlose ID-Card 1304 zur Verfügung. Diese ID-Card für gewerbliche Nutzer erlaubt den Zugriff auf folgende Informationen: Vorname Nachname Geburtsdatum E-POSTBRIEF-Adresse Mobil-Tel.-Nummer Voraussetzung Sie haben E-POSTIDENT in der Selbstadministration des Portals aktiviert. Handbuch für Diensteanbieter 38
E-POSTIDENT testen Vorgehen 1. Stellen Sie beim Programmieren des E-POSTIDENT-Links sicher, dass der Parameter scope den Wert 1304 hat. Weitere Informationen finden Sie in Kap. 4.1: E-POSTIDENT Link konfigurieren, S. 18. Die Anmeldemaske zeigt Eingabefelder für den localpart und die Subdomain für eine Anmeldung als Geschäftskunde an (Abb. 6). Abb. 6 Anmeldebildschirm für Diensteanbieter-Administrator 2. Melden Sie sich mit Ihrer E-POSTBRIEF Adresse als Administrator an. 3. Erfassen Sie Ihre Handy-TAN. Auf der Seite Zustimmung zur Übermittlung Ihrer Angaben werden folgende Angaben zu Ihrer Identität angezeigt: Vorname Nachname Geburtsdatum E-POSTBRIEF-Adresse Mobil-Tel.-Nummer Handbuch für Diensteanbieter 39