E POSTIDENT Handbuch für Diensteanbieter. Version Release 2.6

Transkript

1 E POSTIDENT Handbuch für Diensteanbieter

2 Impressum 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 Warenund Produktnamen sind Warenzeichen oder eingetragene Warenzeichen der jeweiligen Eigentümer Deutsche Post AG E POSTIDENT Handbuch für Diensteanbieter

3 Inhalt 1 Einführung Zweck des Dokuments Zielgruppe Leistungsbeschreibung und AGB 1 2 E POSTIDENT: Überblick Prozessübersicht Fachliche Beschreibung Auslöser Authentisierung Authentisierung mit hohem Identitätsnachweis Autorisierung der Datenfreigabe Übermittlung der Daten, Datenabruf Technischer Überblick OAuth HTTPS-Verschlüsselung Browserkompatibilität 6 3 E POSTIDENT beauftragen und konfigurieren Selbstadministrationsbereich im E POSTBRIEF Portal aufrufen E POSTIDENT beauftragen Domain konfigurieren und aktivieren Logo hochladen Firmenstammdaten im öffentlichen Adressverzeichnis freigeben 12 4 E POSTIDENT implementieren E POSTIDENT Link konfigurieren Authorization Code auslesen Access Ticket anfordern Access Ticket entgegennehmen Identitätsdaten abrufen Daten entgegennehmen Fehlercodes auslesen 19 5 E POSTIDENT ID-CARDS 20 6 E POSTIDENT schema (XML) 22 7 Fehlercodes Mögliche Fehler vor Anmeldung Fehler, die zu einem unspezifizierten Zeitpunkt auftreten können 25 E POSTIDENT Handbuch für Diensteanbieter

4 7.3 Mögliche Fehler vor Datenübergabe Umgang mit Fehlern Bekannte Fehlerquellen 26 8 Textbausteine zur Moderation im Fehlerfall Textbausteine für mögliche Fehler vor Anmeldung Textbausteine für mögliche Fehler zu einem unspezifiziertem Zeitpunkt Textbausteine für mögliche Fehler vor Datenübergabe 29 9 Transaktionshistorie Transaktionshistorie Kunde Transaktionshistorie Diensteanbieter E POSTIDENT testen Check-Connect Parameter für den Aufruf von Check Connect Beispiele für Check-Connect Aufrufe Mögliche Antworten des Services Check-Connect E POSTIDENT-Implementierung kostenlos im Produktionssystem testen Änderungen der Schnittstelle sowie dieses Nutzerhandbuchs Glossar 36 Glossar 38 E POSTIDENT Handbuch für Diensteanbieter

5 1 Einführung 1 Einführung Der E POSTIDENT Service der Deutschen Post AG ermöglicht es Ihnen als Diensteanbieter im Internet (z. B. Webshop-Betreiber), die Identität und das Alter Ihrer Kunden online zu prüfen. Ihre Kunden identifizieren sich Ihnen gegenüber mit Daten, die im Rahmen der E POST- BRIEF Registrierung von der Deutschen Post AG erhoben und verifiziert wurden. Sie können den E POSTIDENT Service beispielsweise für folgende Zwecke nutzen: 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 Dokuments Das Nutzerhandbuch E POSTIDENT versetzt Sie in die Lage, gegen die E POSTIDENT Schnittstelle zu programmieren, und 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 im Download-Center unter > Hilfe > Für Unternehmen > Download-Center > E POSTIDENT.. E POSTIDENT Handbuch für Diensteanbieter 1

6 2 E POSTIDENT: Überblick 2 E POSTIDENT: Überblick E POSTIDENT ist Teil der E POST Internetplattform der Deutschen Post AG. E POSTBRIEF Kunden werden im Rahmen der Registrierung durch die Deutsche Post AG über verschiedene Verifizierungsverfahren identifiziert. Die erhobenen Daten stellen die Datenbasis von E POSTIDENT dar. Die Grafik Abbildung 2-1 zeigt die Einbettung von E POSTIDENT im Kontext der E POST Plattform und die Anbindung Ihrer Infrastruktur an das E POST System: Abbildung 2-1 E POSTIDENT im Kontext von E POST 2.1 Prozessübersicht Nachdem der E POSTIDENT Prozess auf der Website des Diensteanbieters aufgerufen wurde, wird der Kunde auf die E POST 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 POST 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 (Abbildung 2.1-1) veranschaulicht die Anfrage/Antwort (Request/Response) Beziehungen während der Authentisierungsund Autorisierungsphasen von E POSTIDENT : E POSTIDENT Handbuch für Diensteanbieter 2

7 2 E POSTIDENT: Überblick Abbildung 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 POST- IDENT Schaltfläche, um sich für einen bestimmten Geschäftsvorfall zu authentisieren; dabei wird er auf die Seite des E POSTIDENT Systems geleitet. E POSTIDENT Handbuch für Diensteanbieter 3

8 2 E POSTIDENT: Überblick HINWEIS Verwenden Sie ausschließlich die von der Deutsche Post AGim 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. Sie finden das Web-Integrations-Package im Download-Center unter > Hilfe > Für Unternehmen > Download-Center > E POSTIDENT. 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. Weitere Informationen finden Sie unter 4.1 E POSTIDENT Link konfigurieren. 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 E POSTIDENT Link konfigurieren) auf die mitgelieferte Callback URI (Uniform Resource Identifier) zurückgeleitet. Wenn Sie einen SSL-Proxy nutzen, kann die Callback URI z. B. dem Schema ssl.webpack.de/example.com/back). folgen. Dabei ersetzen Sie example.com durch Ihre jeweilige Domain und ggf. /back durch Ihre eigene Erweiterung. Im Redirect wird ein Authorization Code mitgeliefert, den Sie als Diensteanbieter zum anschließenden Datenabruf benötigen. 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. 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. E POSTIDENT Handbuch für Diensteanbieter 4

9 2 E POSTIDENT: Überblick 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 Textbeispiele zur Moderation sowie detaillierte Integrationsanweisungen. Sie finden das Web-Integrations-Package im Download-Center unter > Hilfe > Für Unternehmen > Download-Center > E POSTIDENT. 2.8 Technischer Überblick Im Folgenden werden die im E POSTIDENT System verwendeten Standards beschrieben 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 oder 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 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. E POSTIDENT Handbuch für Diensteanbieter 5

10 2 E POSTIDENT: Überblick 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. Weitere Informationen finden Sie unter 4.2 Authorization Code auslesen. Weitere Informationen zum OAuth 2.0-Standard finden Sie unter draft-ietf-oauth-v 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. 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 E POSTIDENT Handbuch für Diensteanbieter 6

11 3 E POSTIDENT beauftragen und konfigurieren 3 E POSTIDENT beauftragen und konfigurieren Im Selbstadministrationsbereich des E POST Portals können Sie die Nutzung von E POST- IDENT beauftragen, sowie verschiedene Einstellungen zum Produkt E POSTIDENT vornehmen. Der Selbstadministrationsbereich steht Ihnen nach Anmeldung am E POST Portal zur Verfügung. 3.1 Selbstadministrationsbereich im E POSTBRIEF Portal aufrufen Um den Selbstadministrationsbereich aufzurufen, gehen Sie wie folgt vor: Vorgehen Vorgehen 1. Melden Sie sich im E POST Portal mit der E POSTBRIEF Adresse des Adminstrators an. 2. Wählen Sie im linken, oberen Bildschirmbereich "Administration". Sie erhalten eine HandyTAN auf Ihre hinterlegte Mobilfunknummer. 3. Geben Sie die HandyTAN im dafür vorgesehenen Feld ein. Je nach Portalkonfiguration haben Sie bereits nach der Anmeldung eine TAN erhalten und mitgegeben; in dem Fall überspringen Sie diesen Schritt. 3.2 E POSTIDENT beauftragen Voraussetzung ü Sie befinden sich im Selbstadministrationsbereich des E POST Portals. Vorgehen 1. Wählen Sie im Auswahlmenü auf der linken Seite E POSTIDENT (siehe Abbildung 3.2-1, Position 1). Abbildung E POSTIDENT im Selbstadministrationsbereich beauftragen E POSTIDENT Handbuch für Diensteanbieter 7

12 3 E POSTIDENT beauftragen und konfigurieren 2. Klicken Sie im oberen Bildschirmbereich auf das Symbol E POSTIDENT beauftragen (siehe Abbildung 3.2-1, Position 2). Ein Dialogfenster erscheint. 3. Markieren Sie das Kontrollkästchen zum Bestätigen der AGB, und wählen Sie die Schaltfläche E POSTIDENT beauftragen. Ein kostenfreier E POSTBRIEF wird an den Kundenservice der Deutschen Post AG versendet, in dem die Beauftragung von E POSTIDENT enthalten ist. Diesen E POST- BRIEF finden Sie in Ihrem Gesendet -Ordner. Der Kundenservice der Deutschen Post AG schaltet Sie innerhalb von 3 Werktagen für den Dienst E POSTIDENT frei. Sie erhalten einen E POSTBRIEF, sobald der Dienst freigeschaltet ist. Den aktuellen Status Ihres Auftrags können Sie jederzeit unter Administration > E POSTIDENT anzeigen (siehe Abbildung 3.2-1, Position 3). 4. Konfigurieren Sie nach Ihrer Freischaltung für den Dienst E POSTIDENT Service die Parameter wie in den folgenden Abschnitten beschrieben. HINWEIS Sie können E POSTIDENT jederzeit im Selbstadministrationsbereich des E POST Portals kündigen. Der Vertrag wird innerhalb von drei Werktagen beendet. 3.3 Domain konfigurieren und aktivieren Bevor Sie den E POSTIDENT Service nutzen, müssen Sie als Diensteanbieter (Webshop- Betreiber) die folgenden Parameter im Selbstadministrationsbereich des E POST Portals hinterlegen. Sie können den E POSTIDENT Service für mehrere Domains verwenden. Voraussetzung Vorgehen ü Sie befinden sich im Selbstadministrationsbereich von E POSTIDENT. ü E POSTIDENT ist freigeschaltet. 1. Wählen Sie das Symbol Domain hinzufügen. Sie gelangen auf die Registerkarte Domain anlegen (siehe Abbildung 3.3-1). E POSTIDENT Handbuch für Diensteanbieter 8

13 3 E POSTIDENT beauftragen und konfigurieren Abbildung Domain anlegen 2. Erfassen Sie die erforderlichen Informationen wie in Tabelle Konfigurationsparameter Selbstadministration Diensteanbieter dargestellt. ACHTUNG Identitätsdiebstahl Um Missbrauch mit Ihrem Dienst E POSTIDENT vorzubeugen, stellen Sie Folgendes sicher: Das Passwort (ClientSecret) ist geheim, es ist nur Ihnen als Diensteanbieter persönlich bekannt. Sie ändern das Passwort, wenn das Passwort unautorisierten Personen bekannt geworden ist. Empfehlung: Erfassen Sie alle 3 Monate ein neues Passwort. 3. Um die Domain und damit den E POSTIDENT Service zu aktivieren, markieren Sie unter E POSTIDENT Status den Auswahlknopf Aktiv. Die Domain wird auf der Registerkarte E POSTIDENT (Abbildung 3.3-2) angezeigt. E POSTIDENT Handbuch für Diensteanbieter 9

14 3 E POSTIDENT beauftragen und konfigurieren Abbildung Registerkarte E POSTIDENT 4. Um die Parameter einer Domain zu ändern, wählen Sie auf der Registerkarte E POST- IDENT das Symbol Bearbeiten (Abbildung 3.3-2, Position 1). HINWEIS Die automatisch generierte Client ID lässt sich nicht ändern. Feldname System-Parameter Beispiel-Eingaben Beschreibung Domain domain_uri Typisch ist die Konfiguration ohne ssl-proxy: Hinweis: Sie können auch einen SSL-Proxy verwenden, etwa nach folgendem Schema: ssl.web- pack.de/exam- ple.com. Mit der domain_uri wird der Kunde vom Server der Deutschen Post AG zu einer korrekten URL (Uniform Resource Locator) zurückgeleitet. Dazu muss sichergestellt sein, dass die später bei jedem Request mitgesendete redirect_uri die domain_uri enthält, z. B. (HTTPS): domain_uri: redirect_uri: 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. E POSTIDENT Handbuch für Diensteanbieter 10

15 3 E POSTIDENT beauftragen und konfigurieren Feldname System-Parameter Beispiel-Eingaben Beschreibung Der Alias hat maximal 16 Zeichen und ist in UTF-8 kodiert. Leerzeichen sind erlaubt. ClientSecret, Bestätigung Client- Secret client_secret Erfassen Sie ein Passwort nach folgenden Regeln: Zeichenlänge Zeichen Erlaubte Zeichen: a z, A Z, 0 9 Keine Sonderzeichen Hintergrund: Gemäß OAuth 2.0 wird das client_secret vom Diensteanbieter gemeinsam mit dem Authorization Code gegen das Access Ticket eingetauscht. Client ID client_id 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 Selbstadministrationsbereich des E POST Portals angezeigte Client-ID hat das Format: xxxxxxxx-xxxx-4xxx-yxxxxxxxxxxxxxxx, z. B.: 93bc22b4- efeb-4e84-b7ce-c169c29ea79f. 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 Kostenstelle 0815 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. Leer- und Sonderzeichen sind erlaubt. Serverstandort innerhalb der EU Ja/Nein Geben Sie an, ob sich der Standort der Server, auf denen die Identitätsdaten gespeichert 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 E POSTIDENT Handbuch für Diensteanbieter 11

16 3 E POSTIDENT beauftragen und konfigurieren Feldname System-Parameter Beispiel-Eingaben Beschreibung der Standort der Server außerhalb der EU/EWG befindet. Tabelle Konfigurationsparameter Selbstadministration Diensteanbieter HINWEIS Löschen einer Domain Um eine Domain zu löschen, deaktivieren Sie die Domain zunächst. Sie können eine Domain erst 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. Voraussetzung ü ü Die Bild-Datei für das Logo ü ü ist maximal 2 MB groß hat das Dateiformat jpg, gif oder png Sie sind im E POSTBRIEF Portal angemeldet. Um die Kunden-Ansicht auf E POSTIDENT zu personalisieren, können Sie Ihr eigenes Logo im rechten, oberen Bildbereich präsentieren. Das Hochladen eines Logos ersetzt ein evtl. bereits vorhandenes Logo. HINWEIS Das Bild wird hochkant im Format 3:4 angezeigt. Vorgehen 1. Wählen Sie im linken, oberen Bildschirmbereich Administration. Sie erhalten eine TAN auf Ihre hinterlegte Mobilfunknummer. Geben Sie diese 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. 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. Voraussetzung ü Sie sind am E POST Portal angemeldet. E POSTIDENT Handbuch für Diensteanbieter 12

17 3 E POSTIDENT beauftragen und konfigurieren Vorgehen 1. Wählen Sie im linken, oberen Bildschirmbereich Administration. Sie erhalten eine HandyTAN auf Ihre hinterlegte Mobilfunknummer. 2. Geben Sie die HandyTAN 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. Wählen Sie im Auswahlmenü auf der linken Seite Firmenstammdaten. 4. Klicken Sie im oberen Bildschirmbereich auf die Schaltfläche Freigabe Adressverzeichnis. 5. Nehmen Sie Ihre individuellen Freigabe-Einstellungen vor. E POSTIDENT Handbuch für Diensteanbieter 13

18 4 E POSTIDENT implementieren 4 E POSTIDENT implementieren Als Diensteanbieter müssen Sie folgende Vorgänge implementieren: 4.1 E POSTIDENT Link konfigurieren 4.2 Authorization Code auslesen 4.3 Access Ticket anfordern 4.4 Access Ticket entgegennehmen 4.5 Identitätsdaten abrufen 4.6 Daten entgegennehmen 4.7 Fehlercodes auslesen 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 (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.3 Domain konfigurieren und aktivieren). Alle vertraglichen Voraussetzungen, die in den AGB E POSTIDENT aufgeführt sind, sind erfüllt. Sie findne die E-POSTIDENT AGBs im Download-Center unter > Hilfe > Für Unternehmen > Download-Center > E POSTIDENT 4.1 E POSTIDENT Link konfigurieren 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 Deutschen Post AG 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 im E POSTBRIEF PORTAL unter Einbindung > Zum Download-Center. Voraussetzung ü Sie haben eine Domain konfiguriert und aktiviert (siehe Kapitel 3.3 Domain konfigurieren und aktivieren). E POSTIDENT Handbuch für Diensteanbieter 14

19 4 E POSTIDENT implementieren Vorgehen Programmieren Sie einen Link auf die E POSTIDENT Seite mit folgenden Parametern: Parameter Wert Beschreibung Pflicht/ Optional redirect ident.epost.de/ oauth2/login Weiterleitung auf E POSTIDENT Seite Pflicht 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. Pflicht redirect_uri Zurückleitung vom E POSTIDENT Server auf die Diensteanbieterportalseite.Hinweis: Die redirect_uri (Uniform Resource Identifier) muss die Domain-URI enthalten. Pflicht 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. in der Redirect-URI /back durch Ihre eigene Erweiterung. 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. E POSTIDENT ID-CARDS). Eine Übersicht über alle derzeit verfügbaren ID-Cards und die jeweils zur Abfrage zu verwendenden Werte finden Sie im Dokument Datenpakete im Download-Center unter > Hilfe > Für Unternehmen > Download-Center > E POSTI- DENT. Pflicht reason Verifikation, z. B.: Der Verkauf Ihres Mobiltelefons Der hier übermittelte Freitext wird dem Kunden angezeigt: bei der Anmeldung an den E POSTI- DENT Server Pflicht in der SMS-Nachricht während der Datenfreigabe E POSTIDENT Handbuch für Diensteanbieter 15

20 4 E POSTIDENT implementieren Parameter Wert Beschreibung Pflicht/ Optional Hinweis: Der Text darf eine max. Länge von 66 Zeichen nicht überschreiten. Die Zeichen müssen URL-encoded sein. Hinweis: Enthält der Parameter zu viele oder unerlaubte Zeichen, kann die Darstellung des Texts in der SMS-Nachricht unvollständig sein. response_type code Muss immer den Wert code enthalten. Pflicht 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 Parameterliste Aufbau Redirect URL (Uniform Resource Locator) Beispiel: client_id=123example456& redirect_uri= 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. Fehlercodes 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 Werts 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 den Namen Ihrer Domain und ggf. /back durch Ihre eigene Erweiterung. E POSTIDENT Handbuch für Diensteanbieter 16

21 4 E POSTIDENT implementieren code=<123code456>& state=meinkunde_4711 Ergebnis Mit dem Authorization Code können Sie im nächsten Schritt das Access Ticket anfordern, um die Daten abzurufen. 4.3 Vorgehen 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 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 Kapitel 3.3 Domain konfigurieren und aktivieren: 123authorization_code456: 123example456. Fügen Sie das von Ihnen konfigurierte Passwort für Sie als Diensteanbieter ein. Im Beispiel in Kapitel 3.3 Domain konfigurieren und aktivieren: example_s_e_c_r_e_t. Ersetzen Sie example.com durch Ihre Domain und ggf. /back durch Ihre eigene Erweiterung. authorization_code Tabelle Parameterliste Access Ticket anfordern 2. Schicken Sie den folgenden POST Request an den E POSTIDENT Token Endpoint: wie im folgenden Beispiel dargestellt. POST /oauth2/token HTTP/1.1 Host: 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= grant_type=authorization_code E POSTIDENT Handbuch für Diensteanbieter 17

22 4 E POSTIDENT implementieren 4.4 Vorgehen 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.) HTTP/ ok Content-Type: application/json;charset=utf-8cache-control: no-storepragma:no-cache { "access_token": "123access_token456", "token_type":"bearer", "expires_in":300 } Ergebnis Mit dem Access Ticket können Sie im nächsten Schritt die Identitätsdaten abrufen. Mit erfolgreicher Übertragung des Access Tickets von der Deutsche Post AG an den Diensteanbieter erfolgt die Berechnung des Transaktionsentgelts für die angeforderte ID-Card entsprechend dem vertraglich vereinbarten Tarif (siehe AGB E POSTIDENT ). 4.5 Identitätsdaten abrufen Mit dem Access Ticket rufen Sie die vom Kunden freigegebenen Identitätsdaten über einen GET Request Befehl ab. 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 Access Ticket entgegennehmen beschrieben ist. Vorgehen Programmieren Sie einen GET request zur Datenabholung mit folgenden Parametern: Parameter Host Authorization Wert Bearer 123access_token456 Tabelle Parameterliste Identitätsdaten abrufen Beispiel GET /oauth2/identdata Host: Authorization: Bearer 123access_token456 Accept: application/xml Accept-Charset:utf-8 E POSTIDENT Handbuch für Diensteanbieter 18

23 4 E POSTIDENT implementieren 4.6 Daten entgegennehmen Die http-rückgabe an Sie als Diensteanbieter enthält ein Dokument im XML Format. Vorgehen Nehmen Sie die XML-Datei mit den Daten entgegen. HTTP/ 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> :00:00.0</dateofbirth> </identdata> HINWEIS Die XML-Datei genügt dem in Kapitel 6. E POSTIDENT schema (XML) 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. Vorgehen 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. error=<errorcode>& state=meinkunde_4711 HINWEIS Ersetzen Sie example.com durch Ihre Domain und ggf. /back durch Ihre eigene Erweiterung. HINWEIS 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. Textbausteine zur Moderation im Fehlerfall angegebenen Textbausteine für die Moderation im Fehlerfall. Eine Liste der gültigen Fehlercodes finden Sie im Kapitel 7. Fehlercodes. E POSTIDENT Handbuch für Diensteanbieter 19

24 5 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 ALPHA 2), z. B. DE mobilephone Mobilfunknummer String(20) Mobilfunknummer inklusive Länderkennung epostaddress E POSTBRIEF Adresse String(128) over18 Ü18 {true false} salutation Anrede String(10) {mr mrs} oder {Herr Frau} Bemerkung: Prüfen Sie auf Gleichheit mit mr oder Herr bzw. auf mrs oder Frau Tabelle 5-1 ID-Card-Parameter Tabelle 5-2 Ident-Check Plus zeigt beispielhaft eine E POSTBRIEF-Card. E POSTIDENT Handbuch für Diensteanbieter 20

25 5 E POSTIDENT ID-CARDS HINWEIS Ergänzungen sind jederzeit möglich. ID-Card-Nummer ID-Card Name Produktbezeichnung Enthaltene Attribute (Kunden-Identitätsdaten) 90/XL Ident-Check Plus Anrede Vorname Nachnahme Geburtsname Weitere Vornamen Geburtsdatum Geburtsort Straße Hausnummer Adresszusatz Postleitzahl Ort Länderkennzeichen E POSTBRIEF Adresse Mobiltelefon-Nr. Ü18 Staatsangehörigkeit Tabelle 5-2 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 im Download-Center unter > Hilfe > Für Unternehmen > Download-Center > E POSTIDENT. E POSTIDENT Handbuch für Diensteanbieter 21

26 6 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=" xmlns:tns=" targetnamespace=" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:annotation> <xsd:documentation xml:lang="en"> ID-Card schema for E-POSTIDENT. Copyright 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"/> E POSTIDENT Handbuch für Diensteanbieter 22

27 6 E POSTIDENT schema (XML) <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> E POSTIDENT Handbuch für Diensteanbieter 23

28 7 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 Kapitel 7.1 Mögliche Fehler vor Anmeldung aufgeführten möglichen Fehlern weder eine Fehlermeldung noch eine Login-Seite angezeigt wird. Textbausteine zur Moderation im Fehlerfall finden Sie in Kapitel 8. Textbausteine zur Moderation im Fehlerfall. 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 E POSTIDENT ist derzeit für Sie deaktiviert 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. 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 unauthorized_client invalid_request invalid_scope unauthorized_client unauthorized_client invalid_request unsupported_response_type Tabelle E POSTIDENT Fehlercodes vor Anmeldung E POSTIDENT Handbuch für Diensteanbieter 24

29 7 Fehlercodes HINWEIS Die hier definierten Fehlerwerte werden dem Kunden im Parameter error mit dem Redirect mitgegeben. Weitere Informationen finden Sie unter 4.7 Fehlercodes auslesen. 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. Fehlernachricht im E POSTIDENT Redirect access_denied access_denied Kunde schließt Browser. Verbindung zwischen Kunde und E POST- IDENT bricht ab. Browser des Kunden stürzt ab. Unerwarteter Fehler im E POSTIDENT Service server_error Tabelle 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 Fehlercodes E POSTIDENT vor Daten-Übergabe 7.4 Umgang mit Fehlern Im Falle des Auftretens von Fehlern beachten Sie folgende Hinweise: E POSTIDENT Handbuch für Diensteanbieter 25

30 7 Fehlercodes 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: 1. Notieren Sie die minutengenaue Fehlerzeit sowie den Fehlerreferenzcode auf der Fehlermaske (im Browser). 2. Erstellen Sie einen Screenshot des Fehlers. 3. Kopieren Sie den kompletten Inhalt des URL (Uniform Resource Locator) als Text in eine Datei. 4. Notieren Sie, welche Aktionen durchgeführt wurden unmittelbar bevor der Fehler auftrat. 5. Senden Sie die gesammelten Informationen an den Kundenservice der Deutschen Post AG. 7.5 Bekannte Fehlerquellen In diesem Kapitel erhalten Sie Hinweise auf Fehler, die bei einer 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. Abbildung 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. Der Parameter redirect_uri enthält einen Tippfehler. E POSTIDENT Handbuch für Diensteanbieter 26

31 7 Fehlercodes 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. E POSTIDENT Handbuch für Diensteanbieter 27

32 8 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. ACHTUNG 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. ACHTUNG 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. ACHTUNG In diesem Fall darf der Name des E POSTIDENT Service nicht namentlich genannt werden! E POSTIDENT Handbuch für Diensteanbieter 28

33 8 Textbausteine zur Moderation im Fehlerfall 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. ACHTUNG In diesem Fall darf der Name des E POST- IDENT Service nicht namentlich genannt werden! TIPP Zeigen Sie Ihrem Kunden alternative Möglichkeiten auf, den entsprechenden Geschäftsprozess im Fehlerfall weiterzuführen. Bieten Sie Ihrem Kunden z. B. ein alternatives Zahlungsverfahren an. E POSTIDENT Handbuch für Diensteanbieter 29

34 9 Transaktionshistorie 9 Transaktionshistorie E POSTIDENT Transaktionen werden im E POST 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. E POSTIDENT Handbuch für Diensteanbieter 30

35 10 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 zu testen. Um die Anbindung an E POSTIDENT zu prüfen: Vorgehen 1. Rufen Sie den Service Check-Connect in der Produktionsumgebung auf. Verwenden Sie den Host Weitere Informationen finden Sie in Kapitel 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 Kapitel Beispiele für Check-Connect Aufrufe). Um Ihre Implementierung fachlich zu testen, führen Sie mit einem Privatkunden-Account Ihrer Wahl mindestens eine Identifizierung aus. 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 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 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. Ersetzen Sie 123example456 durch Ihre jeweilige Client ID. Pflicht domainuri ssl.webpack.de/ example.com Die Domain-URI (Uniform Resource Identifier) des Diensteanbieters wird in der Selbstadministration gepflegt. Ersetzen Sie example.com durch Ihre eigene Domain. Pflicht Achtung: Der Parameter enthält an dieser Stelle keinen Unterstrich! Tabelle Parameter für den Aufruf von Check Connect E POSTIDENT Handbuch für Diensteanbieter 31

36 10 E POSTIDENT testen Beispiele für Check-Connect Aufrufe Nachfolgend finden Sie Konfigurationsbeispiele für Aufruf und Response von Check-Connect. clientid=123example456& domainuri= Als Antwort liefert der Service Check-Connect ein JSON-Objekt mit den Attributen status und message. Die möglichen Antworten sind in der Tabelle Tabelle Mögliche Antworten des Services Check-Connect dargestellt Mögliche Antworten des Services Check-Connect status message Bedeutung 200 clientid and domainuri matched 400 clientid matched but domainuri mismatched 403 clientservice activation state is false 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. Tabelle Mögliche Antworten des Services Check-Connect Antwort HTTP/ 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: E POSTIDENT Handbuch für Diensteanbieter 32

37 10 E POSTIDENT testen Vorname Nachname Geburtsdatum E POSTBRIEF-Adresse Mobil-Tel.-Nummer Voraussetzung Vorgehen Sie haben E POSTIDENT in der Selbstadministration des Portals aktiviert. 1. Stellen Sie beim Programmieren des E POSTIDENT-Links sicher, dass der Parameter scope den Wert 1304 hat. Weitere Informationen finden Sie unter 4.1 E POSTIDENT Link konfigurieren. Die Anmeldemaske zeigt Eingabefelder für den localpart und die Subdomain für eine Anmeldung als Geschäftskunde an (Abbildung ). Abbildung Anmeldebildschirm für Diensteanbieter-Administrator 2. Melden Sie sich mit Ihrer E POSTIDENT Adresse als Administrator an. 3. Erfassen Sie Ihre HandyTAN. 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 4. Stimmen Sie der Übermittlung zu. E POSTIDENT Handbuch für Diensteanbieter 33