E-POSTIDENT Service Provider`s Guide

Transcription

E‑POSTIDENT
Service Provider's Guide
Version 2.6. Release 2.6
E‑POSTIDENT Service Provider's Guide
Content
1 Introduction
1
1.1 Purpose of the document
1
1.2 Audience
1
1.3 Service Specifications and General Terms&Conditions (GTC)
1
2 E‑POSTIDENT: An Overview
3
2.1 The E‑POSTIDENT use case
3
2.2 Functional process description
4
2.3 Trigger
4
2.4 Authentication
5
2.5 Authentication with high-level proof of identity
5
2.6 Authorizing data transmission
5
2.7 Data request and transfer of data
5
2.8 Technical outline
6
2.8.1 OAuth 2.0
6
2.8.2 HTTPS encryption
7
2.9 Browser compatibility
7
3 Ordering and Configuring E‑POSTIDENT options
8
3.1 Accessing the self-administration area at the E‑POST portal
8
3.2 Ordering E‑POSTIDENT
8
3.3 Activating and configuring the domain
9
3.4 Uploading your company logo
13
3.5 Marking your company name as public in the E‑POST address directory
13
4 Implementing E‑POSTIDENT
15
4.1 Configuring the E‑POSTIDENT link
15
4.2 Reading-out the authorization code
17
4.3 Requesting the access ticket
18
4.4 Accepting the access ticket
19
4.5 Requesting identity data
19
4.6 Accessing the data
20
4.7 Reading-out the error codes
20
5 E‑POSTIDENT ID-CARDS
22
6 E‑POSTIDENT schema (XML)
24
7 Error scenarios & codes
26
7.1 Errors that may occur before log-in
26
7.2 Errors that may occur at an unspecific process stage
27
7.3 Errors that may occur before data transmission
27
7.4 Dealing with errors
27
7.5 Known sources of error
28
8 Text messages to be displayed in the case of error
30
8.1 Text messages to be displayed in case of error before log-in
30
8.2 Text messages to be displayed in case of error at an unspecific process stage
30
8.3 Text messages to be displayed in case of error before data transmission
30
9 E‑POSTIDENT transaction history
32
9.1 Transaction history view for customers
32
9.2 Transaction history view for service providers
32
10 Testing E‑POSTIDENT
33
10.1 Check-Connect
33
10.1.1 Parameters for the check-connect request
33
10.1.2 Examples for the check-connect requests
34
10.1.3 Possible responses for the check-connect service
34
10.2 Testing the E‑POSTIDENT implementation in the production environment
35
11 Changes to the E‑POSTIDENT interface and/or to this user guide
37
12 Glossary
38
1
Introduction
1 Introduction
E‑POSTIDENT is an identification service of Deutsche Post AG that allows online service
providers to reliably identify users accessing their services on a web site. E‑POSTIDENT is a
web service of the E‑POST platform of Deutsche Post AG. Data collected and verified during
the registration process with the E‑POSTBRIEF are provided to online service providers,
with prior authorization of the end-user, the web service customer, thus enabling customers
of the E‑POSTBRIEF easy registration on the service provider’s web sites. E‑POSTIDENT
can be used for the following scenarios:
▪
Initial identification of customers yet unknown to a service provider, e.g., during registration or before an online purchase is concluded.
▪
Registration procedure on a service provider site (for new customers), i.e. before ending
an online shopping transaction
▪
Authentication of a customer as re-identification service during a business transaction.
▪
Awarding end-users with a special certified customer status, that is, E‑POSTBRIEF certified user, by using, for example, a special, dedicated symbol in the customer’s profile.
The status E‑POSTBRIEF certified customer could be used by service providers to guarantee the reliability of their users.
▪
Verification of the applicable legal minimum age for special business transactions (minimum age of 18 or 21 depending on the service location), whether a customer has the
intended minimum transaction age (Ü18 [over 18], Ü21 [over 21]).
Note
All parameters used in this guide are case-sensitive.
1.1 Purpose of the document
The E‑POSTIDENT Service Provider's Guide allows you to
▪
program against the E-POSTIDENT interface
▪
configure the self-administration portal
1.2 Audience
This document is intendet for:
▪
web developers
▪
portal administrators
▪
system architects
1.3 Service Specifications and General Terms&Conditions (GTC)
The E‑POSTIDENT General Terms & Conditions (GT&C) and the E-POSTIDENT Service
Specifications, as amended, define the use and integration of the E-POSTIDENT service.
1
1
Introduction
Note
Find all related documentation on the E‑POST download center site at http://
www.epost.de > Hilfe > Für Unternehmen > Download-Center > E‑POSTIDENT
2
2
E‑POSTIDENT: An Overview
2 E‑POSTIDENT: An Overview
E‑POSTIDENT is part of the E‑POST Internet platform of Deutsche Post AG (DPAG).
E‑POSTBRIEF customers are identified by the DPAG during registration, based on various
verification processes. The data collected during registration represent the E‑POSTIDENT
pool of identity data. The diagram below shows how E‑POSTIDENT is embedded in the context of the E‑POST platform, and how its infrastructure is linked to the E‑POSTIDENT system.
Figure 2-1 E‑POSTIDENT int the E‑POST context.
2.1 The E‑POSTIDENT use case
After invoking the E‑POSTIDENT process on the service provider’s website, the customer is
re-directed to the E‑POST website. Here, the customer logs-in with his E‑POSTBRIEF access data, that is E-POSTBRIEF address and password. The user receives an mTAN on his
cellphone, which needs to be entered in the next web page, in order to confirm the user’s
identity. After data verification, the user can see all the identity data that the service provider
requires of him, to continue with the transaction on the service provider’s site. The user can
authorize data transmission to the provider or deny data release. After the customer authorizes data transmission, the data are made available to the service provider for retrieval for a
time period of 5 minutes. Depending on the business case, and provided that the specified
requirements are met, the end-user may continue with the transaction at a later point in time,
or may be denied the transaction, if the requirements are not fulfilled, for example, if the minimum legal age requirement are not met. The following figure shows the request/response
transactions during the E‑POSTIDENT authorization procedure:
3
2
Figure 2.1-1 Sequence diagram E‑POSTIDENT overview
2.2 Functional process description
The following transactions apply during the E‑POSTIDENT process:
▪
Authentication request
▪
Authentication request with proof of identity (E‑POSTBRIEF address and password, plus
mTAN)
▪
Authorization approval of data transmission by the customer
▪
Data retrieval and data transmission
2.3 Trigger
The customer clicks on the E‑POSTIDENT button on your service provider portal page (web
application) to authenticate himself for a specific business transaction; this will direct him to
the E‑POSTIDENT system’s website.
4
2
Note
Please use only the E‑POSTIDENT buttons supplied by Deutsche Post in the web integration package. All information regarding integration of the E‑POSTIDENT buttons can be
found in the web integration package, please see also the General Terms & Conditions of
E-POSTIDENT.
Find the web integrations package on the E‑POST download center site at http://
www.epost.de > Hilfe > Für Unternehmen > Download-Center > E‑POSTIDENT.
2.4 Authentication
On the E‑POSTIDENT page, the customer logs-in with his E‑POSTBRIEF address and
E‑POSTBRIEF password. An mTAN is sent to the customer to achieve the high level proof of
authentication.
2.5 Authentication with high-level proof of identity
The customer enters the mTAN sent to him in the input field. If the mTAN is entered correctly,
a page appears which displays the identity data requested by the service provider. The customer is prompted to release the data displayed; for more information refer to 4.1 Configuring the E‑POSTIDENT link
2.6 Authorizing data transmission
After authorizing data transmission, the user is re-directed to the provider’s site. Once the
customer authorizes the transmission of the identity data, he is sent back to the service provider’s portal page. A re-direct is implemented to re-direct the customer to the callbackURI
(Uniform Resource Identifier) supplied https://www.example.com/back, where example.com is to be replaced with your domain name, and if required, /back with your own extension, for more information, refer to section 4. Implementing E‑POSTIDENT. Included in
the redirect is an authorization code, which the service provider requires, to request the
identity data afterwards. If the customer refuses to release the identity data or cancels the
operation, he will be reö-directed to the re-direct URL (Uniform Resource Locator). In case of
an error, refer to section 4.7 Reading-out the error codes
2.7 Data request and transfer of data
The service provider has to make a POST request to request the identity data of the customer from the E‑POSTIDENT server. The POST request transforms the authorization code
into an access ticket. This access ticket can be used to request the released identity
data made available on the E‑POSTIDENT server via a GET request. An XML file with the
requested identity data released by the customer is then returned.
5
2
Note
After requesting the data, the customer should receive a confirmation message explaining
that the authentication was successful, and that he can proceed with the business transaction.
The web integration package contains specific text examples for moderation, as well as
detailed integration instructions.
Find the web integrations package on the E‑POST download center site at http://
2.8 Technical outline
Below is a description of the standards used in the E‑POSTIDENT system.
2.8.1 OAuth 2.0
E‑POSTIDENT uses the OAuth 2.0 protocol to identify and release previously verified data.
OAuth 2.0 is an open protocol that allows a standardized, API authorization for desktop,
web, and mobile applications where access to or the forwarding of personal data is required.
The customer may agree to his personal identity data being accessed, or to this data being
forwarded, without having to disclose access authorizations or passwords. The following
OAuth 2.0 terms are used in the E‑POSTIDENT system:
OAuth 2.0
Bedeutung
E‑POSTIDENT
protected resource
Protected resource
Identity data of the private customer
resource owner
An entity that can allow access to a protected resource.
Private customer
resource server
The server that contains
(stores) the protected resources.
E‑POSTIDENT server
client
The client software that deThe service provider’s web applicamands protected resource da- tion
ta from the source owner.
authorization server
The server that issues access E‑POSTIDENT server
tokens to the client.
Table 2.8-1 Tabelle 1. OAuth 2.0-Terminologie
OAuth 2.0 defines the entire process, from the log-in procedure to the final data transmission. The Service provider has to necessarily implement the entire process-transactions with
all procedures, for more information, refer to section 4. Implementing E‑POSTIDENT.
6
2
Note
It is, for instance, not allowed to deduce an implicit fulfilment of legal age requirement, due
to a transmitted authorization code. The authorization code is forwarded at this
process stage through the provider’s browser and can therefore not be seen as reliable
authenticated information. To prove authentication, the authorization codes has to be
exchanged against the access ticket, only then the authorization code can be seen
as valid, for more information see 4.2 Reading-out the authorization code.
For more information on the OAuth 2.0 standard please go to http://tools.ietf.org/html/draftietf-oauth-v2-23.
2.8.2 HTTPS encryption
E‑POSTIDENT uses HTTPS connections only. The customers identity data are handled by
E‑POST as secure as current state-of-the-art technologies permit. During the entire process,
the requesting and the responding parties communicate exclusively via HTTPS. In order to
retrieve the identification data from the E‑POST platform, the client_secret parameter
must be included in the request. The client_secret parameter is stored in the E‑POSTIDENT self-administration portal.
2.9 Browser compatibility
The following browser versions are supported:
Browser
Version
Microsoft Internet Explorer
Version 8
Mozilla Firefox
from Version 3.6
Safari
from Version 5
7
3
Ordering and Configuring E‑POSTIDENT options
3 Ordering and Configuring E‑POSTIDENT options
This section explains how to order and sign-up for E‑POSTIDENT at the self-administration
area of the E‑POST portal, where, you will be able to register as E‑POSTIDENT user, and
configure all the relevant E‑POSTIDENT settings.
To access the self-administration area, you have to log-in as administrator with the E‑POSTBRIEF adress and password.
3.1 Accessing the self-administration area at the E‑POST portal
To access the self-administration area at the E‑POST portal, proceed as follows:
Prerequisites 1. Log-in to the E‑POST portal with the adminstrator's E‑POSTBRIEF address and password.
2. Select from the upper left window corner, the area Administration. You will receive a mobileTAN number to the cell phone number specified during registration.
3. Enter the mobileTAN number in the dedicated field. Depending on the portal configuration, you may already have received and entered an mobileTAN number after login, in
this case, ignore this step and proceed with the next one.
Procedure 1. Open the E‑POST website at http://www.epost.de
2. Select Einloggen.
The log-in screen for private customers opens.
3. To log-in as a business customer, select Wechseln (see Figure 3.1-1, item 1).
Figure 3.1-1 Log in as a business customer
4. Please log-in with the E‑POSTBRIEF address and password of the registered administrator.
5. Select the Administration button.
You will receive an mTAN on your cellphone.
6. Enter the mTAN.
Depending on the configuration of the E‑POST portal, you have already received and entered an mTAN after log-in. In this case, skip this step.
3.2 Ordering E‑POSTIDENT
Prerequisites ü You are in the self-administration area at the E‑POST portal.
Procedure 1. Select E‑POSTIDENT from the left-hand side menu. (see Figure 3.2-1, Position 1).
8
3
Figure 3.2-1 Ordering E‑POSTIDENT in the self-administration area
2. Click in the upper screen area at the symbol E‑POSTIDENT beauftragen (ordering EPOSTIDENT) (see Figure 3.2-1, Position 2).
A dialog box opens.
3. Mark the GT&C checkbox confirming that you accept the General Terms and Conditions,
and select the E‑POSTIDENT beauftragen button (ordering E-POSTIDENT).
An E‑POSTBRIEF containing the E‑POSTBRIEF order is sent to the customer service of
DPAG free of charge. Find this E-POSTBRIEF in your Sent folder.
Within 3 working days, the DPAG customer service activates the E‑POSTIDENT service
for you . You will receive an E‑POSTBRIEF as soon as the service has been activated.
View the current status of your order at Administration > E-POSTIDENT. After the
E‑POSTIDENT service has been activated, configure the parameters as described in the
following section.
Note
You may terminate at any time the E‑POSTIDENT service in the self-administration area
at the E‑POST portal. The agreement will be terminated within three days.
3.3 Activating and configuring the domain
Before using E‑POSTIDENT, you have to configure the following parameters in the self-administration area at the E‑POST portal. Note, that the use of several domains is possible with
E‑POSTIDENT.
Prerequisites ü You are logged-in in the self-administration area of E‑POSTIDENT.
ü E‑POSTIDENT was activated.
To create the domain:
Procedure 1. Select the icon Domain hinzufügen [Adding domain].
You get the tab Domain anlegen [creating domain], see figureFigure 3.3-1).
9
3
Figure 3.3-1 create domain
2. Enter the required information as shown in Table 3.3-1 Configuration parameter in the
self-adminstration area of the E‑POST portal .
Attention
Identity theft
To prevent any misuse of E‑POSTIDENT ensure the following:
▪
The password (ClientSecret) is kept secret and is only known to you as the service provider.
▪
As soon as the password has become known to unauthorized individuals,change
immediately the password.
Recommendation: change your password every three months.
3. To activate the domain and your E‑POSTIDENT, select from the menu E‑POSTIDENT
Status the radio button Aktiv [activ].
The domain will be shown at the E‑POSTIDENT tab. (Figure 3.3-2)
10
3
Figure 3.3-2 E‑POSTIDENT tab
4. To change the domain parameters, select from the E‑POSTIDENT tab the option
E‑POSTIDENT > Bearbeiten (see Figure 3.3-2, Position 1).
Note
The automatically generated client_id cannot be modified.
Field name
System parameter
Sample entry
Description
Domain
domain_uri
The configuration is
typically without
ssl-Proxy: https://
www.example.com.
With the domain_uri the customer
is re-directed from the server of
DPAG back to a correct URL (Uniform Resource Locator). Therefore,
it has to be ensured that the redirect_uri is contained in the domain_uri, as it will be send with
each request, e. g., HTTPS only:
Note: You might also use an SSLProxy according to
the following schema: https://
▪
ssl.webpack.de/
example.com.
domain_uri: https://
www.example.com
▪
redirect_uri:https://
www.example.com/back.
In case you create several domains,
ensure that the all domains are
unique, that means, every domain
can only be used once.
Alias
alias
Shop 1
The alias name is shown during login, and when the data sre shown
during the transaction overview.
The alias consists of a maximum of
11
3
Field name
System parameter
Sample entry
Description
16 characters and is coded in
UTF-8. Spaces are permitted.
ClientSecret,
Confirmation ClientSecret
The password you enter must comply to the following rules:
client_secret
▪
length: 10 - 20 charaktrers
▪
permitted characters: a‑z, A‑Z,
0‑9
▪ do not use special characters
According to OAuth 2.0, the client_secret and the authorization code are both exchanged for
the access ticket by the service
provider.
client_id
The client_id is the identification
number for each domain of a service provider, and is generated automatically when a domain is created.
The client_id cannot be changed.
client_id
Note
The client_id displayed in
the self-administration portal
has the following format:
xxxxxxxx-xxxx-4xxx-yxxxxxxxxxxxxxxx A hexadecimal
character is used for each x
and one of the following characters is used for y: 0-9, a-b.
Cost center
cost_center
Cost center 0815
Optional: Enter the name of your
(internal) cost center. The cost
center will later be shown on your
invoice and allows you to allocate
E‑POSTIDENT processes in your
accounting system.
The name of the cost center must
not be longer than 256 characters.
It is coded in UTF-8; spaces are
permitted.
Server location
within the EU
Applicable/N.A
Note: Specify whether the site of
the servers on which the identity data is stored and processed is located within or outside of the EU/EEC.
For legal reasons, prior to agreeing
to the data transfer, every customer
12
3
Field name
System parameter
Sample entry
Description
will be notified if the site of your
servers is outside of the EU/EEC.
Table 3.3-1 Configuration parameter in the self-adminstration area of the E‑POST portal
Note
Deleting a domain
To delete a domain, deactivate it first. You can delete a domain if the last transaction occurred at least 60 days ago.
3.4 Uploading your company logo
As service provider, you can personalize the way your customer's find you on the the
E‑POSTIDENT page, for example, by including your own company logo at the top right
screen-corner.
Prerequisites ü The image file for the company logo must have the following characteristics:
ü The maximum filesize must be 2 MB
ü The image file must have the format jpg, gif or png
ü You must be logged-in to the E‑POST portal.
Note
Uploading an image file as logo may eventually replace a logo that was there before.
Note, that the image is shown in portrait orientation in 3:4 format.
Procedure 1. SelectAdministration from the upper left screen area.
You will be sent an mTAN number to the cellphone number you specified during the
E‑POSTIDENT resgistration process. Enter the mTAN number in the corresponding field.
Depending on the portal configuration, you may already have received and entered an
mTAN number after log-in. In this case, skip this step.
2. Select Firmenstammdaten [Company master data] from the menu on the left.
3. Click on the Bearbeiten [Edit] button at the top of the screen.
4. Upload the image file for your company logo on the right menu side.
3.5 Marking your company name as public in the E‑POST address directory
In case you want your customers to find your company in the public E‑POST address directory, mark your company name as public address by marking the corresponding check box.
Your customers can only find you in the public address directory, if you mark your adress as
public.
Prerequisites ü You are logged onto the E‑POST portal.
13
3
Procedure 1. Select Administration from the upper left screen-area.
You get an mTAN number on the cellphone number you provided during registration.
2. Enter the mTAN number in the corresponding field.
Depending on the portal configuration, you may already have received and entered an
mTAN number after log-in. In this case, skip this step.
3. Select from the left screen area the option Firmenstammdaten.
4. Click on the upper screen area on the button Freigabe Adressverzeichnis [release for
public adress directory].
5. Enter your own settings for release in the public address directory.
14
4
Implementing E‑POSTIDENT
4 Implementing E‑POSTIDENT
As service provider, you have to implement the following E‑POSTIDENTprocesses:
▪
▪
▪
▪
▪
▪
▪
The following requirements must be met prior to implement any E-POSTIDENT procedures:
▪
You have an active E‑POSTBRIEF account to authenticate yourself via E‑POSTIDENT
during the functional tests of your E‑POSTIDENT implementation, see also the General
Terms & Conditions for E‑POSTIDENT on the E‑POST download center site at http://
▪
You have created a domain for your website in the self-administration area on the
E‑POST portal,
▪
You have entered all required values for all domain parameters, and activated the domain (see also section 3.3 Activating and configuring the domain).
▪
All contractual requirements listed in the GT&C E‑POSTIDENT are met.
Find the E‑POSTIDENT GT&C on the E‑POST download center site at http://
www.epost.de > Hilfe > Für Unternehmen > Download-Center > E‑POSTIDENT
Your customer is prompted on your website to authenticate himself via the E‑POSTIDENT
button. By clicking the E‑POSTIDENT button, the customer is directed to the E‑POSTIDENT
system via the link described in this section. The link includes the callback_URI (redirect_uri with https-Schema) with which the customer is redirected back to your portal after
the data have been transmitted. The link contains among other parameters the callback_URI
Note
Use only the E‑POSTIDENT buttons supplied by DPAG in the web integration package.
All information regarding integration of the E‑POSTIDENT buttons is provided in the web
integration package. Find the web integrations package at E‑POSTBRIEF www.epost.de/
epostident Einbindung > Zum Download-Center.
Prerequisites ü You have configured and activated a specifc domain (see section 3.3 Activating and configuring the domain).
15
4
Procedure
‣
You have programmed a link to the E‑POSTIDENT page with the following parameters:
Parameter
Value
Description
Mandatory
redirect
https://ident.epost.de/
Forward to the E‑POSTIDENT
page.
Mandatory
oauth2/login
client_id
123example456
Identification number of your doMandatory
main, which was generated by the
E‑POSTIDENT system and can be
verified in the self-administration
area. Note: Replace the generated
ID 123example456 with your own
client_id.
redi-
https://www.example.com
Re-direction from the E‑POSTIDENT server, back to the service
provider portal page.
rect_uri
Mandatory
Note: The redirect_uri must include the domain_URI.
Note: The redirect_uri must be
URL encoded and for security reasons it must be no longer than 155
characters.
Note: Replace example.com with
your own domain and, if required,
in the redirect_URI /back with
your own extension.
scope
10
For the scope parameter you have
to include the ID of the IDcard,
which you want to have displayed.
Choosing one IDcard or another
determines the scope of the data
to be delivered. IDcards define a
set of identity data that the service
provider requires of an end user,
for more information refer to section 5. E‑POSTIDENT ID-CARDS.
An overview of all available IDcards can be found in the document „Datenpakete“ on the
E‑POST download center site at
http://www.epost.de > Hilfe > Für
Unternehmen > Download-Center > E‑POSTIDENT.
.
Mandatory
reason
Verifikation, e. g.: Sale of
Include some descriptive text for
the parameter reason. The text
transfered will be displayed to the
customer:
Mandatory
your cell phone
▪
during log-in on the E‑POSTIDENT server
16
4
Parameter
re-
Value
Description
Mandatory
▪
in the text message itself
▪
during data release
▪
Note:The text must be no longer than 66 characters. The
characters must be URL encoded. In case the parameter
consists of too many or impermissible characters, the text
displayed in the message may
be incomplete.
code
Must always contain the value
„code“.
<Customer designator>
The parameter state contains the Mandatory
internal identifier that the service
provider assigned to his customer.
This value will not be altered by the
E‑POSTIDENT system. It allows
you to identify the user through another processes (for example,
shopping cart transactions).
sponse_typ
Mandatory
e
state
Table 4.1-1 Parameters to build the redirect_uri (Uniform Resource Locator)
Example:
https://ident.epost.de/oauth2/login?
client_id=123example456&
redirect_uri=https://www.example.com/back&
scope=10&
reason=”Der%20Verkauf%20Ihres%20Mobiltelefons“&
response_type=code&
state=meinKunde_4711
Note
After constructing the re-direct call, E‑POSTIDENT internally verifies all parameter values. once the end user approves the data transmission. In case the test is not
performed correctly, or delivers a negative result, the end user is redirected to the provider’s site according to the error codes listed in section 7. Error scenarios & codes.
Note taht the user gets no error message displayed, nor will he get to get a new log-in
site.
If the customer finally agrees to release the identity data that the E‑POSTIDENT systems
shows him asking for approval and discharge, the authorization code will be included in
the re-direct and delivered to the service provider's portal page.
17
4
Procedure 1. Identify the customer by the value in the state parameter, and read out the authorization code in the code parameter included in the re-direct. The size of the authorization code is 4096 bytes
2. Replace the example.com value with your domain name and, if required, /back with
your own extension.
https://www.example.com/back?
code=<123code456>&
Result The authorization code can be used in the next step to request the access ticket for
data transmission.
Procedure 1. Program a POST request with the following parameters to call the access ticket:
Parameter
Value
token endpoint
POST /oauth2/token HTTP/1.1
Host
https://ident.epost.de
content-type
application/x-www-form-urlencoded
code
Insert the authorization code read-out from
the re-direct call, for more information refer to
section: 4.2 Reading-out the authorization code:
123authorization_code456.
client_id
Insert the client_id you configured for your
client. As sample, refer to section 3.3 Activating
and configuring the domain: 123authorization_code456: 123example456.
client_secret
Insert the password you configured as service
provider. As sample, refer to section 3.3 Activating and configuring the domain: example_s_e_c_r_e_t.
redirect_uri
https://example.com./back
Replace example.com with your domain name
and, if required, /backwith your own extension.
grant_type
authorization_code
Table 4.3-1 List of parameters to request the access ticket
2. Send the following POST request to the E‑POSTIDENT token endpoint, as shown in the
following sample: https://ident.epost.de/oauth2/token
POST /oauth2/token HTTP/1.1
Host: https://ident.epost.de
Content-Type: application/x-www-form-urlencoded ; charset=UTF-8
18
4
code=123authorization_code456&
client_id=123example456&
client_secret=example_s_e_c_r_e_t&
redirect_uri=https://www.example.com/back&
grant_type=authorization_code
Procedure
‣
Reading out the access ticket.
The short-dated access ticket is returned base64-coded in JSON format without refresh token.
Note
The access ticket is only valid for 5 minutes (300 sec.)
HTTP/1.1 200 ok
Content-Type:
application/json;charset=UTF-8Cache-Control:
no-storePragma:no-cache
{
"access_token":
"123access_token456",
"token_type":"Bearer",
"expires_in":300
}
Result The access ticket can be used in the next step to retrieve the identity data.
Note
Upon successful transfer of the access ticket from DPAG to the service provider, the
transaction charge for the requested ID card will be calculated in accordance with the
contractually agreed rate, see also the E‑POSTIDENT General Terms & Conditions on
the E‑POST download center site at http://www.epost.de > Hilfe > Für Unternehmen > Download-Center > E‑POSTIDENT
Use the access ticket to retrieve the released identity data via a GET request command.
The access ticket is transferred in the authorization header of the request. Use the unchanged base64 coded access ticket for this operation. How to accept the access ticket is
described in Section 4.4 Accepting the access ticket.
19
4
Procedure
‣
Create a GET request to retrieve the identity data with the following parameter:
Parameter
Value
Host
https://ident.epost.de
Authorization
Bearer 123access_token456
Table 4.5-1 Parameters to request the access ticket
Sample
GET /oauth2/identdata
Host: https://ident.epost.de
Authorization: Bearer 123access_token456
Accept: application/xml
Accept-Charset:utf-8
The http response to the service provider contains a document in XML format. Accept the
XML file that contains the requested identity data.
Procedure
‣
Accept the XML file with the data.
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<identdata>
<epostaddress>[email protected]</epostaddress>
<givenname>Hans</givenname>
<familyname>Schmidt</surname>
<zipcode>50937</zipcode>
<city>Köln</city>
<dateofbirth>1966-08-26 00:00:00.0</dateofbirth>
</identdata>
Note
The XML file is compliant with the XML schema described in section 6. E‑POSTIDENT
schema (XML)
In case of error, the customer is re-directed together with the corresponding error code, via
http 302 re-direct, to the configured callback_uri (redirect_uri). This may occur for example, in case the customer denies data transmission, or disconnects from the E‑POSTIDENT
service before data release.
20
4
Procedure
‣
Display to the customer the text modules specified in section 8. Text messages to be
displayed in the case of error. The value in the parameter state allows you to identify
the customer and guides him through your further processes.
https://www.example.com/back?
error=<ErrorCode>&
Note
Replace example.com with your domain and, if required, /back with your own extension.
Note
Depending on the error case, and specific error message, implement the following pages according to the error message displayed to the customer. When doing so, consider the moderation recommendations provided in the web integration package, and
the text modules for moderation in case of error as specified in section 8. Text messages to be displayed in the case of error.
Find the list of valid error codes in section 7. Error scenarios & codes.
21
5
E‑POSTIDENT ID-CARDS
5 E‑POSTIDENT ID-CARDS
ID-cards are identity data records of E‑POST customers stored in the E‑POSTIDENT system. Each ID-card is a subset of customer data available or derived from within E‑POSTIDENT. Each time E‑POSTIDENT is used, the application of the service provider (client) must
include the ID of the requested ID card in the scope parameter during the initial link.
ID-cards consist currently of the following parameters; all parameters are UTF-8 encoded:
Technical designator Attribute
Format
givenname
First name
String(29)
additionalgivennames
Additional given
names
String(50)
familyname
Last name
String(29)
birthname
Name at birth
String(40)
dateofbirth
Date of birth
Date
placeofbirth
Place of birth
String(80)
nationality
Nationality
String(2)
street
Street
String(50)
housenumber
House number
String(10)
addressaddon
Additional address information
String(40)
zipcode
Postal code/Zip code
String(5)
city
City
String(80)
country
State
String(2)
2-letter country code (according to ISO 3166), for
example, DE
mobilephone
Cellphone number
String(20)
Cell phone number including country code
epostaddress
E‑POSTBRIEF
Adresse
String(128)
over18
Over 18 years of age
[Ü18]
{true|false}
salutation
Salutation
String(10)
{mr|mrs} oder
{Herr|Frau}
Validation rules
According to ISO 8601;
YYYY-MM-DD
2-letter country code (according to ISO 3166), for
example, DE
Comment: Check for congruence between “Mr” or
“Herr” and “Mrs” or
“Frau”.
Table 5-1 ID-card parameters
22
5
E‑POSTIDENT ID-CARDS
The table below shows an example of an E‑POSTIDENT ID card; additional information may
be added at any time.
ID-card number
90/XL
ID-card name
ID card product name
Attributes included (Customer identity
data)
Ident-Check Plus
Salutation [Anrede]
First name [Vorname]
Last name [Nachnahme]
Birth name [Geburtsname]
Additional given names [Weitere Vornamen ]
Date of birth [Geburtsdatum]
Birth place [Geburtsort]
Street [Straße]
House number [Hausnummer]
Address add-on [Adresszusatz]
Zip code [Postleitzahl]
City [Ort]
Country code [Länderkennzeichen]
E‑POSTBRIEF Adresse
Cellphone number [Mobiltelefon-Nr.]
legal age/ age of consent [Gesetzliches
Mindesalter Ü18]
Nationality [Staatsangehörigkeit]
Table 5-2 Ident-Check Plus
Note
Find a list of all currently available ID-cards with all parameters to be used in the document „Datenpakete“ on the E‑POST download center site at http://
23
6
E‑POSTIDENT schema (XML)
6 E‑POSTIDENT schema (XML)
Note
The XML schema below is to be taken as a reference. This schema is not to be used for
the purpose of validation. Additional elements may be added at any time.
<?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"
24
6
E‑POSTIDENT schema (XML)
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>
25
7
Error scenarios & codes
7 Error scenarios & codes
Possible error scenarios during E‑POSTIDENT processes arer:
▪
Errors before customer log-in
▪
Errors at an unspecific point in time
▪
Errors before the customer’s identity data are transmitted, i.e., before the service provider collects the data.
Note
Consider that in case of error before log-in (see section 7.1 Errors that may occur before
log-in) neither an error message nor a log-in page will be displayed.
Find text modules for moderation in case of error in section 8. Text messages to be displayed in the case of error.
7.1 Errors that may occur before log-in
Error cause
Error message displayed in the E‑POSTIDENT redirect message
E‑POSTIDENT not available
temporarily_unavailable (if portal still available)
E‑POSTIDENT
globally de-activated
E‑POSTIDENT
technical error
Service provider blocked
unauthorized_client
E‑POSTIDENT
unauthorized_client
is currently de-activated for you
E‑POSTIDENT
invalid_request
is currently not activated for you
ID-card not known
invalid_scope
Credit check negativ
unauthorized_client
Price for ID card could not be determined
unauthorized_client
Not all parameters existent
invalid_request
Response_type is not "code"
unsupported_response_type
Faulty client_id and/or redirect_uri: re-direct could not be initiated..
–
Table 7.1-1 E‑POSTIDENT error codes before log-in
26
7
Note
The error codes definied in this section will be issued with the parameter error in the redirect call. Find further information under 4.7 Reading-out the error codes.
7.2 Errors that may occur at an unspecific process stage
Error cause
Error message displayed in the E‑POSTIDENT
re-direct message
Customer cancels the data release process
at any time.
access_denied
Customer denies the release of his identity
data.
access_denied
Customer closes the web-browser.
–
Connection between customer and E‑POSTIDENT breaks off.
–
Customer’s browser crashes.
–
Unexpected error in the E‑POSTIDENT
service.
server_error
Table 7.2-1 E‑POSTIDENT error codes at an unspecific process stage
7.3 Errors that may occur before data transmission
Error causes
Error message in the E‑POSTIDENT redirect.
During exchange of the authorization code invalid_client, HTTP-statuscode 400 (bad
for the access ticket: there is no client for
request)
the client_id transferred.
During exchange of the authorization code invalid_client, HTTP-statuscode 400 (bad
for the access ticket: redirect URI is not request)
the same as the primary redirect URI transferred in the initial request
During exchange of the authorization code invalid_grant, HTTP-statuscode 400 (bad refor the access ticket: incorrect authoriza- quest)
tion code.
Incorrect access ticket during data access.
no error category, HTTP-statuscode 404 (not
found)
Table 7.3-1 Errors before data retrieval
7.4 Dealing with errors
In case of error, consider the following recommendations:
27
7
▪
Implement the pages dispalyed after an error occurs, in acordance with the error situation and the error message transferred. When doing so, consider the design rules provided in the web integration package, see also section 8. Text messages to be displayed in
the case of error.
▪
In case an error may occur in the production environment, proceed as follows:
1. Record the exact time of error appearance, accurate-to-the-minute, and the error
code displayed in the error message (in the browser).
2. Make a screenshot of the error.
3. Copy the entire content of the URL (Uniform Resource Locator) as text, and insert it
in an empty data file.
4. Send the entire informations to the E‑POST customer service center Deutschen Post
AG as E-POSTBRIEF to [email protected] or as E-mail to
E‑[email protected].
7.5 Known sources of error
The following section lists errors, that may occur in case E‑POSTIDENT was implemented
incorrectly.
In case the user selects the button E‑POSTIDENT on your website an gets the error message shown in the following figure, record the displayed reference number and exact timestamp of occurrence.
Figure 7.5-1 Error message
Possibel causes include:
▪
The client-id contains a typo.
▪
You are using the client-id from the test environment for the production environment
or vice versa.
▪
The redirect_uri parameter contains a typo.
28
7
▪
You are using the redirect_uri pfrom the test environment for the production environment or vice versa.
▪
You are using an incorrect parameter designator, for instance redirect_url instead of
redirect_uri.
29
8
Text messages to be displayed in the case of error
8 Text messages to be displayed in the case of error
Use the following text messages in case of error.
8.1 Text messages to be displayed in case of error before log-in
Error case
Text message to display
temporarily_unavailable
“Unfortunately, the service is currently not
available.“
Attention
In this case, do not refer to the E‑POSTIDENT service in the error message.
Error case
unauthorized_client
Unfortunately, we encountered an error. We
are currently working to resolve this issue.
Please, try again later.
invalid_request
invalid_scope
unauthorized_client
Attention
invalid_request
unsupported_response_type
8.2 Text messages to be displayed in case of error at an unspecific process stage
Error case
access_denied, server_error
"Unfortunately, you could not be identified succesfully"
Attention
8.3 Text messages to be displayed in case of error before data
transmission
Error case
invalid_client (HTTP-Statuscode 400)
Unfortunately, we encountered an error. We are
currently working to resolve this issue. Please, try
again later.
invalid_grant (HTTP-Statuscode 400)
HTTP-Statuscode 404
30
8
Text messages to be displayed in the case of error
Error case
Attention
Tip
In case of error, show your customers alternativ ways on how to proceed with the interrupted business process. For example, point out an alternativ payment method.
31
9
E‑POSTIDENT transaction history
9 E‑POSTIDENT transaction history
Every E‑POSTIDENT transaction can be retraced at the E‑POST portal. The E‑POSTIDENT
service provider, as well as the E‑POSTIDENT data owner, can equally access every single
transaction for a time period of 60 days. After that time, the data will be automatically deleted.
9.1 Transaction history view for customers
For every successful E‑POSTIDENT transaction, the service customer sees in the transactions history the following data:
▪
Date and the time of the transaction,
▪
Alias of the service provider, who requested the identity data,
▪
Value of the reason parameter, and the
▪
domain-URI for which the customer has transmitted his data.
The customer has the posibility to see in a detailed view, the transmitted identity data for
each single E‑POSTIDENT transaction, like for example, name, date of birth, or address.
9.2 Transaction history view for service providers
For every successful E‑POSTIDENT transaction, the service provider sees in the transactions history the following data:
▪
Transaction number,
▪
Date and the time of the transaction,
▪
Value of the reason parameter,
▪
domain-URI for which the customer has released his data,
▪
Product name for the ID-card that was used to retrieve the identity data, including the relevant attributes (without values), and
▪
The result of every transaction performed.
The service provider can download a selection of transactions as a CSV file.
32
10
Testing E‑POSTIDENT
10 Testing E‑POSTIDENT
This section describes how to test your E‑POSTIDENT service. The following options are
available:
▪
Checking the connection to E‑POSTIDENT with the "check-connect" test case,
▪
Testing as administrator in the role of an private customer and free of charge, the implemented E‑POSTIDENT service in the production environment.
To check the connection to E‑POSTIDENT:
Procedure 1. Request the Check-Connect service from the production environment. Use therefore the
host https://ident.epost.de. For more information, see section 10.1.1 Parameters
for the check-connect request
2. Test the E‑POSTIDENT implementation in the production environment free of charge,
until the implementation runs succesfully. In this scenario, your administrator-account
acts as test user, for more insformation refer to section 10.1.2 Examples for the checkconnect requests).
3. Perform at least a functional test of your implementation with a private customer account
of your choice and perform at least one identification scenario.
To provide the E‑POSTIDENT service to your customers, upload the implementation from
your development or test system to your dedicated production system.
10.1 Check-Connect
E‑POSTIDENT provides you the check-connect service. Test your general connection to
E‑POSTIDENT and the correct combination of the client ID and the domain URI parameters against this interface. In the case of error, check-connect provides you with error details,
indicating which settings may have to be adjusted.
10.1.1 Parameters for the check-connect request
To request the check-connect service, create a GET request with the following parameters:
Parameter
Value
Description
Mandatory
clientId
123example456
Identification number of your domain, which you received from the
E‑POSTIDENT Sytem, and which
is shown in the self-administration
area of the E‑POST portal.
Mandatory
Replace 123example456 with your
corresponding client_id.
domainUri
https://www.example.com
The Domain-URI (Uniform ReMandatory
source Identifier) of the service provider is maintained in the self-administration area of the E‑POST
portal.
33
10
Parameter
Value
Description
Mandatory
Note
Replace example.com with your
own domain. The parameter must
have no underscore.
Table 10.1-1 Parameters for he check-connect request
10.1.2 Examples for the check-connect requests
Find below a configuration sample for a check-connect request.
https://ident.epost.de/oauth2/clientverification?
clientId=123example456&
domainUri=https://www.example.com
The check-connect response is an JSON object with the attributes status and message. The
possible responses are shown in the table below. Table 10.1-2 Possible responses for the
check-connect service
10.1.3 Possible responses for the check-connect service
status
message
description
200
clientId and domainUri
The specified clientID exists
and matches with the lodged
domainURI for that clientID.
matched
400
clientID matched but domai- The clientID exists, but the
nUri mismatched
domainURI does not match the
clientID. Check the domainURI registered in the self-ad-
ministration area of the portal.
403
client service activation state
is false
The specified clientID exists
but the client configuration has
not been activated. Activate
E‑POSTIDENT in the portal’s
self-administration area in this
case.
404
clientId mismatched
The specified clientID does
not exist.
Table 10.1-2 Possible responses for the check-connect service
Antwort
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
{
"status": "200",
"message": "clientId and domainUri matched"
}
34
10
10.2 Testing the E‑POSTIDENT implementation in the production
environment
As administrator, you can test, free of charge, your E‑POSTIDENT implementation in the
production environment with the role of a private customer. The IDcard 1304 is available for
this purpose. This IDcard, usually available to commercial users, allows you to access the
following identity information:
▪
First name
▪
Last name
▪
Date of birth
▪
E‑POSTBRIEF address
▪
Cellphone number
Prerequisites E‑POSTIDENT was activated in the self-administration area of the E‑POST portal.
Procedure 1. Ensure that the parameter scope has the value 1304, when programming the E‑POSTIDENT link. Find further information under 4.1 Configuring the E‑POSTIDENT link.
The log-in screen shows the input-fields for entering the local part and the subdomain
parameters for the log-in as business customer. (Figure 10.2-1).
Figure 10.2-1 Log-in screen for administrators at the service provider site
2. Log-in as administrator with your E‑POSTIDENT address and password.
35
10
3. Enter your mTAN.
On the page where you agreed to the transmission of your identity data, the following data will be displayed:
▪
First name
▪
Last name
▪
Date of birth
▪
E‑POSTBRIEF address
▪
Cellphone number
4. Accept the transmission of data.
5. Test your E‑POSTIDENT implementation.
Prerequisites:
You have an valid private E‑POSTBRIEF customer account.
a. Ensure that the scope parameter has the value for the required IDcard, when programming the E‑POSTIDENT link. For more information, refer to section 5. E‑POSTIDENT ID-CARDS.
b. Log-in as private customer with your E‑POSTBRIEF address and agree to the identification.
c. Check whether the details accepted for identification are complete. Find further information under .
36
11
Changes to the E‑POSTIDENT interface and/or to this user guide
11 Changes to the E‑POSTIDENT interface and/or to
this user guide
The following rules apply to any changes to the interface and/or to the content of this Manual:
▪
Release-Updates: The documentation will be updated in the context of new software releases. The associated XML files to be delivered, contain the applicable software version
as part of the element version. The documentation also contains a reference to the applicable software version.
▪
Troubleshooting: Deutsche Post reserves the right to react without delay to any vulnerabilities that become known. Changes resulting from error fixing, have to be accepted by
customers of E‑POSTIDENT, see also the E‑POSTIDENT General Terms and Conditions.
▪
Software Updates: Deutsche Post provides minor as well as major releases as part of its
product maintenance. Minor releases are releases where the E‑POSTIDENT interface is
only extended by additional fields, which should normally not result in errors on the customer side, provided the customer does not validate against the XSD file, but only reads
out the fields relevant to him, for more information refer to section 6. E‑POSTIDENT
schema (XML). Major releases may comprise more profound changes and will be announced to the customer with a lead time of six months and in a suitable manner, e.g.,
via E‑POSTBRIEF.
▪
Versioning is done through the documents transmitted.
Find the General Terms&Conditions at the E‑POST portal under www.epost.de/epostident > Einbindung > Zum Download-Center.
37
12
Glossary
12 Glossary
Authentication (by user to server)
Establishment of proof of a claimed attribute of
a party's attributes.
Authentisierung
The primary objective of authentication is to
establish proof and credibility of an identity of
the entities acting in a process on the basis of
specific attributes.
Authorization
Granting of rights vis-à-vis others, for example
granting and checking of access rights to data
.
ClientSecret
Any printable byte sequence used by the service provider to identify himself to the E‑POSTIDENT system, when retrieving the data released by the end customer. In the E‑POSTIDENT system the ClientSecret is treated like a
password, see section 3. Ordering and Configuring E‑POSTIDENT options.
ClientID
The client_id is the identification number for
each domain of a service provider and is generated automatically when a domain is created.
Service provider
Service providers are business customers (BC)
or commercial customers (CC). Service providers are referred to as ‘client’ in the context of
OAuth 2.0.
mTAN
Random, alphanumeric code with a minimum
of six characters, which is sent to the customer’s cell phone after successful input of the login credentials. The (physical) possession of a
cell phone is the second factor of authentication.
Identity
In legal terms, identity means the conformity of
personal data with an individual. This identity
can be determined formally by a legally binding
confirmation of identity.
Log-in credentials
Log-in data for the E‑POST portal (E‑POSTBRIEF address plus password). These logindetails can be used by a private customer to
perform the first of the required two steps of
authentication to E‑POSTIDENT (see mTAN).
38
12
Glossary
OAuth
An open protocol in which the user of a (web)
application (here a service provider portal)
grants restricted access to some of his identity
data (authorization). This identity data is provided by the E‑POSTIDENT server. The user
does not disclose any details of his access authorization to the service provider, see also
[OAUTH-2].
SSL
Secure Socket Layer
39
Deutsche Post DHL - The Mail & Logistics Group
Deutsche Post AG
Zentrale
53250 Bonn
www.deutschepost.de
Stand 07/2014

E-POSTIDENT Service Provider`s Guide

Transcription

Similar documents

Jugendschutzbericht 1. Halbjahr 2012