Login-API Reference E POSTBUSINESS API · 1 Introduction 1 2 Basic concepts 2 3 Identity Levels and E‑POST Functions 4 ... Introduction The Login‑API is part of the E‑POSTBUSINESS

E‑POSTBUSINESS APILogin-API Reference

Version 1.1

ImprintSoftware and documentation are protected by copyright and may not be copied, reproduced,stored, translated, or otherwise reproduced without the written approval of the Deutsche PostAG. This also applies to excerpts All rights reserved.The Deutsche Post AG has the right, without prior notice, to make changes or to further de-velop the documents/software for the purposes of technical progress.Trade names are used without warranty of free usability All trade names and product namesare trademarks or registered trademarks of their respective owner.© 2016 Deutsche Post AG

Login-API ReferenceVersion 1.1

Content

1 Introduction 1

2 Basic concepts 2

3 Identity Levels and E‑POST Functions 4

4 Authentication 6

4.1 Authorization Code Grant 7

4.1.1 Request login page 8

4.1.2 Request access token 11

4.1.3 Validity of access tokens 16

4.1.4 Renew access token 17

4.2 Resource Owner Password Credentials Grant 20

4.3 Increase the level of authentication 26

4.4 Register trusted device 29

4.5 Logout 32

Login-API ReferenceVersion 1.1

Introduction

The Login‑API is part of the E‑POSTBUSINESS API, the REST interface of the E‑POST sys-tem for software suppliers. With the Login‑API you allow E‑POST users to log to the E‑POSTsystem from your software application. The login is required to directly use the integratedE‑POST functions from within your application.

For the integration of the E‑POST functions, you invoke the specific API calls after login, e.g.Send‑API or Mailbox‑API.

This document describes the options for your software to log into the Login‑API via OAuth2.0. For login, the following OAuth 2.0 Standards are supported. “Authorization-Code-Grant-Flow” and “Resource-Owner-Password-Credentials-Grant-Flow” of OAuth 2.0 are supported.The Login‑API provides the possibility to update access tokens in accordance with the stand-ard “Refreshing an Access Token”. The Login‑API is a REST API, whose entire communica-tion occurs via HTTPS only.

This API reference is intended for developers who have knowledge in the following subjects:▪ HTTP and HTTPS▪ REST▪ JSON▪ OAuth 2.0

Find all information on how to build the integration with the E‑POSTBUSINESS API on theE‑POST partner website (http://partner.epost.de/).

1

Integration ofE‑POST functions

Functioning

Audience

Partner portal

1 Introduction

Login-API Reference 1Version 1.1

http://tools.ietf.org/html/rfc6749#section-4.1



http://tools.ietf.org/html/rfc6749#section-6

http://partner.epost.de/

Basic concepts

This section details the basic concepts of the Login‑API, as well as the implemented OAuth2.0 features in the E‑POSTBUSINESS API.

Request and response invocations have been implemented according to the HTTP standard.In addition, note the following requirements:

UTF-8For the processing of strings UTF-8 encoding is required.

Dates and TimesAll dates and times are in ISO 8601 format (e.g. 2014-07 -16T17:05:39+02:00).

HTTPS encryptionThe Login‑API only uses HTTPS connections. Therefore the identification data of the par-ticipants are protected throughout the whole communication process.

Note

Verify the correctness of the certificate on the other side with every call.

For the exchange of data between your application and the E‑POST system the JSON dataformat is used.

The following REST endpoint is used by the Login‑API:▪ https://login.epost.de (Production)▪ https://login.epost-gka.de (Test and integration environment)

Responses are returned in HTTP status code syntax. Each additional information is returnedin the body of the response and formatted as JSON document.In addition to the resource specific response codes the following general response codes arereturned

405

Method Not AllowedThe HTTP method is not supported.

415

Unsupported Media TypeThe submitted Content-Type does not correspond to the expected value.

500

Internal Server ErrorInternal processing error

2

Request andresponse

JSON data format

REST APIendpoint

HTTP status codes

2 Basic concepts


https://login.epost.de

https://login.epost-gka.de

503

Service UnavailableInternal processing error

2 Basic concepts


Identity Levels and E‑POST Functions

E‑POST user can choose between different E‑POST identity levels, each one with differentE‑POST functions. According to the identity level for which E‑POST user register or select,determines which E‑POST functions private customers can use. Customers register withE‑POST by completing the online form, without the need for the POSTIDENT procedure. Bythis way, a customer has direct access to the E‑POST Portal without further actions. Thereare four different identity levels, to which a private customer is assigned to, depending on theverification level of his identity and his postal address.

Note

Comparison between identity level and level of authentication

Identity levelThe identity level defines what kind of knowledge the E‑POST system has about acustomer (the user's identity) and to what extent it has been verified in the course ofthe registration process.

Authentication level (see 4. Authentication)The level of authentication defines the way in which a customer's identity has beenverified during the use of E‑POST products.▪ Simple authentication: through user name and passwordor▪ Extended authentication: by a second factor (HandyTAN). The second factor pro-

vides the system with a higher level of certainty that the expected identity, is theauthenticated one.

A private customer gets a specific identity level, depending on the verification of his identityand his postal address during the registration process.

BasicBy completing the registration form, private customers are directly registered, without theneed for an POSTIDENT procedure. By this way, customers get the identity level basic.

PremiumCustomers with the identity level basic upgrade to the identity level premium, when verify-ing via POSTIDENT after registration.

In addition, a basic customer as well as a premium customer can verify their address andchange to another status:

Basic+A basic customer who additionally verifies his address by AdressTAN gets the level basic+.

Premium+A premium customer who additionally verifies his address by AdressTAN gets the levelpremium+.

3

Identity levels andRegistration

3 Identity Levels and E‑POST Functions


Note

The AdressTAN is sent to the specified address in a physical letter.

A private customer can ( ) or cannot ( ) use certain E‑POST functions depending on hisidentity level:

Function Basic Basic+ Premium Premium+

Physically sendE‑POST letters

Use E‑POSTSAFE

Send and receivefaxes

Receive electronicE‑POST letters

Send electronicE‑POST letters

UseE‑POSTZAHLUNG

Use IdentPLUS

Use E‑POSTSCAN

Table 3-1 E‑POST Functions depending on the identity level

Your application receives the identity level of a user, after he has successfully logged into theE‑POST system, via the parameter id_level, which is included in the response of theLogin-API (see 4.1.2 Request access token).In the implementation of the send process, ensure that only the functions are made availableto a user which are approved for his identity level. In addition, you have to process errormessages if a non-permitted function was called.Example:Your application can either proactively prevent that a basic user sends an electronic E‑POSTletter, or permits this process in general, handling the corresponding error message, and dis-playing a message to the user.

Note

Business customers do not have an identity level. No identity level restrictions apply tothem.

E‑POST Functionsdepending on the

identity level

Procedure: Imple-mentation with the

Send‑API

3 Identity Levels and E‑POST Functions


Authentication

With the Login‑API your application authenticates itself for the E‑POST system.

Use the OAuth 2.0 procedures to register your application on the E-POST Sytem. OAuth 2.0uses the resources of HTTP, so that the login functionality through a browser is enabled. Al-ternatively, you can login without a browser.

To registration, contact our support on the following URL (http://partner.epost.de/registrie-ren/).During the E‑POSTBUSINESS API registration process we will collect the following data:▪ a DevId that clearly identifies your company

▪ an AppId that clearly identifies your application

▪ a redirect URL that is returned within the OAuth 2.0 process.

Note

Take the following naming conventions into account, when defining the DevID and the Ap-pID for your application:

▪ Permitted are only letters (A-Z and a-z), digits (0-9) and underscore (“_”).▪ Blanks or special characters are not permitted.▪ A maximum of 80 characters is permitted.▪ Enter your full company name as a clear identification for the DevId (e.g. “Company-

nameLTD”).▪ Describe the functionality of your application for the AppId (e.g. “SendApp”).

▪ Define the Redirect URL to your website (e.g. https://yourdomain.com/epost/send).

After successful registration, you will receive test data for the test and integration platformfrom Deutsche Post AG.

Along with the registration data, a License-File (LIF file) is created and sent to you. The LIFfile is a encrypted key that is required in the authentication process. The LIF file ensures thatyour application has the necessary authorization for the E‑POST system.

4

OAuth 2.0

Registration

License-file (LIFfile)

4 Authentication


http://partner.epost.de/registrieren/

http://partner.epost.de/registrieren/

Note

Next, you find the instructions required to authenticate with the Login-API. The OAuth 2.0specific steps that take place between a browser, the Send‑API, the Mailbox‑API or theSafe‑API and your application are not described here, as no implementation in this contextis required.

You have the choice between using the procedures specified in one of the following OAuth2.0 specifications, to register your application, or both:▪ Authentication with Authorization Code Grant (with user action) (see 4.1 Authorization

Code Grant)▪ Authentication with Resource Owner Password Credentials Grant (optional user action)

(see 4.2 Resource Owner Password Credentials Grant).

Authorization Code GrantWhen your application implements a login with user action, the authentication process has tocomply with the Authorization Code Grant specification.For more information about Authorization Code Grant, see http://tools.ietf.org/html/rfc6749#section-4.1. The following steps describe the process of the authentication processsequentially.1. Implement one of the following actions, to access a ressource with a specific user pur-

pose (characterized by scope, e.g. Sending an E‑POST letter or receiving an E‑POSTletter) with your application:▪ your application opens a browser and requests to display the E‑POST login page to

the user,▪ your application passes the required parameters (e.g. scope) to the browser.

2. The browser displays the login page to the user.The browser notifies the user that the application would like to interact with his resources.

3. The user enters his user data into the login page.4. The Login‑API validates the user data.

If the scope requires a high level of authentication▪ the Login‑API requests a sending of a HandyTAN via SMS to the user,▪ the Login‑API responds with a redirect to the E‑POST TAN page.If the scope requires a normal level of authentication▪ continue with step 8 .

5. The browser displays the TAN page to the user.6. On the TAN-page the user enters the received HandyTAN and sends it off.7. The Login‑API validates the HandyTAN.8. The Browser returns control to your application by opening the Redirect URL and trans-

ferring an authorization code.9. The application extracts the authorization code and requests an access token.

The application uses the access token to access the resources of the user.

Choice of authenti-cation specifica-

tion

4.1

4 Authentication ǀ Authorization Code Grant




Request login pageBy requesting the login page, your application allows a user to authenticate for the E‑POSTsystem. With the authentication, a user grants rights to your application. The authenticationof your application is only successful when the authorization code is changed to an accesstoken.Your application requests authentication via a separate browser (login or login with Handy-TAN). The browser then handles the authentication process with the Login‑API.

Request

Your application must have access to the login URL:▪ https://login.epost.de (Production)▪ https://login.epost-gka.de (Test and integration environment)

GET /oauth2/auth

response_type (required)A string that specifies which permissions your application needs for authorization. Cur-rently, you can only pass the value code.

client_id (required)A string that identifies your application.

Note

The client_id is derived from Devid and AppId. You specify these values when youregister for the E‑POSTBUSINESS API. Build the client_id the following way:

▪ clientid = devid "," appid

state (optional)A random string of a maximum of 512 characters in length, that describes the status ofyour application. The value is returned to your application in the login result.

Attention

Your application must specify this parameter in order to prevent cross-site request for-gery, even if the parameter is not expected as a mandatory value. For more informa-tion, see http://tools.ietf.org/html/draft-ietf-oauth-v2-30#section-10.12.

Tip

With this parameter, e.g. a hashed session ID or a randomly generated value can bepassed.

scope (required)The scope determines the extent to which your client can access one or several re-source(s) of the user.

4.1.1

Access to loginURL

URL structure

Path parameter





http://tools.ietf.org/html/draft-ietf-oauth-v2-30#section-10.12

▪ The following scopes are possible:

send_letter▪ Allows a user to send electronic E‑POST letters▪ Requires a high level of authentication▪ For more information, see Send-API Reference

send_hybrid▪ Allows a user to send physical E‑POST letters▪ Requires a normal level of authentication▪ For more information, see Send-API Reference

read_letter▪ Allows a user to read E‑POST letters▪ Requires a normal level of authentication▪ For more information, see Mailbox-API Reference

create_letter▪ Allows a user to create E‑POST letter drafts▪ Requires a normal level of authentication▪ For more information, see Mailbox-API Reference

delete_letter▪ Allows a user to delete E‑POST letter drafts.▪ Requires a normal level of authentication▪ For more information, see Mailbox-API Reference

safe▪ Allows access to the E‑POSTSAFE▪ Requires a normal level of authentication▪ For more information, see Safe-API Reference

register_device▪ Allows your application to register a trusted device (see 4.4 Register trusted de-

vice)▪ Requires a normal level of authentication

Note

The level of authentication specifies whether the user of the E‑POST system mustauthenticate with a HandyTAN (high) or not (normal).

▪ It is possible to specify multiple scopes simultaneously. Several scopes are separatedwith a space.Examples:▪ scope=send_letter create_letter▪ scope=safe read_letter▪ scope=delete_letter read_letter



redirect_uri (required)A URI to which the Login result is redirected. The redirect_uri must be known to theE‑POST system. The final system-generated redirect_uri must not be longer than2083 characters, including protocol specification and other parameters. Otherwise displayproblems occur both in the browser and the server.

GET /oauth2/auth? response_type=code& client_id=TestClientId& state=TestState& scope=send_letter& redirect_uri=https://localhost:8888/briefkasten HTTP/1.1Host: login.epost.de

Response

Found (if successful)In the case of success, a redirect URL with authorization code is returned. The serversubmits the following parameters to your application as query string of the redirect URL.The response contains the following parameters:

codeThe returned authorization code.

stateThe value that is passed by the request is forwarded unchanged.

Found (error)In the event of an error your application receives a redirect URL with the appropriate errormessage. In this case, an error code (error), an optional description (error_descrip-tion), an optional note, under which URL a detailed description can be retrieved (er-ror_uri), as well as the value passed in the request (state) is returned.

error

access_deniedInvalid TAN or incorrect redirect_uri

invalid_niveauThe login is only allowed with a high level of authentication (to be set by the user inthe E‑POST portal)

invalid_requestMissing or incorrect parameters or referer

invalid_scopeWrong list format or the list includes one or more unknown, or invalid scope(s)

server_errorUnexpected server-side error

Example

302

302



temporarily_unavailabletemporary server-side error

unauthorized_clientclient_id is incorrect

unsupported_response_typeResponse type does not correspond to code

error_descriptionFor human readable text with additional information to support the developer to under-stand the error that occurred.

error_uriA URI that delivers a human readable web page with information about the error.




HTTP/1.1 302 FoundLocation: https://localhost:8888/briefkasten ?code=dGhpcyBpcyBhbiBiYXN &state=TestState

HTTP/1.1 302 FoundLocation: https://localhost:8888/briefkasten? error=access_denied& error_description="The resource owner or authorization server denied the request."& error_uri="http://tools.ietf.org/html/rfc6749#section-4.1.2"& state=TestState

Request access tokenIf the request for the authorization code was answered successfully in the previous step andyour application has received it, the second step is the request of the access token via theLogin‑API.This process is performed by replacing the authorization code with an access token by a fur-ther request from your application.

500

503

Example:Response in thecase of success

Example:Response in theevent of an error

4.1.2



Request


POST /oauth2/tokens/

Content-Type (required)application/x-www-form-urlencoded

Authorization (required)Authorization header according to HTTP Basic authentication scheme (see http://tools.ietf.org/html/rfc6749#section-2.3.1 and http://www.ietf.org/rfc/rfc2617.txt chapter 2).The values to be used are taken from the data of the E‑POSTBUSINESS API registration.The identification of the user is constituted by combining the JSON fields DevId and Ap-pId with a comma. The resulting string is coded with the application/x-www-form-urlencoded algorithm (http://tools.ietf.org/html/rfc6749#appendix-B). This coded value isused as the user name, the contents of the LIF-file is encoded with the same algorithmand used as a password.After combining the user name together with a “:” character and the password, the valueis to be encoded in base 64. The resulting string is preceded by the word Basic with ablank and is used as the value for the HTTP-header Authorization.

Forming:▪ Basic = basic-credentials▪ basic-credentials = base64-client-pass▪ base64-client-pass = <base64 encoding of client-pass>▪ client-pass = encoded-clientid ":" encoded-password▪ encoded-clientid = <x-www-form-urlencoding converts of clientid>▪ encoded-password = <x-www-form-urlencoding converts of password>▪ clientid = devid "," appid▪ devid = <Devid from LIF file>▪ appid = <AppId from LIF file>▪ password = <contents of the LIF file>

The client application sends the following parameters in the format application/x-www-form-urlencoded in UTF-8 encoding in the entity-body of the HTTP request.

grant_type (required)Specifies which code type the client offers for the change of the token. For authenticationwith authorization code only the type authorization_code is permitted.

code (required)The authorization code that is received by the authenticating user.

Access to loginURL

URL structure

HTTP header

HTTP body





http://tools.ietf.org/html/rfc6749#section-2.3.1


http://www.ietf.org/rfc/rfc2617.txt

http://tools.ietf.org/html/rfc6749#appendix-B

scope (required)The scope that is requested through authorization. It must correspond to the scope thatwas specified by the request of the login page.

redirect_uri (required)The redirect URL that is used for authorization (see http://tools.ietf.org/html/rfc6749#section-4.1.3). Corresponding to the OAuth2.0 specification, the redirect_urihas to be transferred to verify the consistency of the request.

POST /oauth2/tokens/ HTTP/1.1Content-Type: application/x-www-form-urlencoded;charset=UTF-8Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

grant_type=authorization_code& code=dGhpcyBpcyBhbiBiYXN& scope=send_letter%20create_letter& redirect_uri=https://localhost:8888/briefkasten/

Response

OKIn the event of success, your application receives a ticket in form of a JSON object, whichcontains an access token.▪ Depending on the given scope you can use the Send‑API or the Mailbox‑API resour-

ces for the delivery or access to E‑POST letters. Furthermore you can access orchange documents or directories through the Safe‑API.

Note

In contrast to the OAuth2.0 specification, the response does not contain a refresh tokenfor the update on its own. To implement this, the already existing access token is re-newed.

HTTP headerContent-Type: application/json; charset=UTF-8

HTTP bodyThe body contains a JSON object with the ticket.The ticket is structured as follows:

access_tokenThe access token in the form of a string.

expires_inValidity of the access token in seconds.The access token has a limited validity period, which is determined by theLogin‑API.

token_typeThe parameter is required by the OAuth2.0 specification and you always have to setit to Bearer in the E‑POSTBUSINESS API.

Example

200





id_levelThe identity level of the logged-in E‑POST user (see 3. Identity Levels and E‑POSTFunctions).Possible values are basic, basicplus, premium, premiumplus and null. In case ofa business customer the value is null.

Note

When the access token has exceeded its validity period, the request is rejected withthe corresponding note invalid_token. After that, your application can renew thetoken for an extended period of time through the Login‑API. To do this, your applica-tion has to use the existing access token. A separate refresh token is not issued.

Attention

Ensure that the access token is held securely in the application and that no unau-thorized access is possible.

Bad RequestThe request is încorrect.


HTTP bodyThe body contains a JSON object with the error information.Possible values for error:

invalid_requestparameter error

unsupported_grant_typegrant_type is not equal to authorization_code

invalid_grantInvalid authorization_code

unauthorized_clientThe grant_type is not allowed for the authenticated client

invalid_scopeThe wrong list format has been used, or the specified list contains one or more un-known or invalid scopes, or the submitted list is not equal to the list that was used atthe time of the request for the authorization code.

400



Unauthorized



invalid_clientCredentials are missing, Client-ID is invalid or credentials are not valid.

ForbiddenThere is no authorization to access the resource.



invalid_niveauThe login is only allowed with a high level of authentication (to be set by the user inthe E‑POST portal)

Unsupported Media TypeThe media type of the file is not permitted.



unsupported_media_typeThe Content-Type of the request is not supported.



401

403

415

500

503



HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8

{ "access_token": "V0aG9yaXphdGlvbiBjb2Rl", "token_type": "Bearer", "expires_in": 3600, "id_level": "basicplus"}

HTTP/1.1 400 Bad RequestContent-Type: application/json; charset=UTF-8

{ "error": "invalid_request", "error_description": "See URI below to get detailed information about the error.", "error_uri": "http://tools.ietf.org/html/rfc6749#section-5.2"}

Validity of access tokensAn access token has the following parameters that define how long it can be renewed. Formore information, see 4.1.4 Renew access token.

Parame-ters

Value(h:min)

Description

validity 0:10 Time period within which an access token (regardless of level of au-thentication) is valid, and can be used. After this time period the ac-cess token can no longer be used for operations on the API. But it canbe renewed.

available 1:00 Time period within which an access token on a normal level of au-thentication must be renewed latest. If it is not replaced within thistime period, it becomes invalid and cannot be renewed any more.

downgrade 0:15 Time period within which an access token on a high level of authenti-cation must be renewed. If it is not renewed within this time period, itswitches to the normal level of authentication.Since the validity time has already expired, it must be renewed, sothat it can be used once again (now at a normal level of authentica-tion).The available time has already partially passed at this time as well.Therefore there are only 45 minutes left until the access token be-comes invalid.

max.val-idity

24:00 Maximum period of validity of an access token despite continuous re-newal. After the expiry a renewal is no longer possible.

Table 4.1-1 Parameters of access tokens



4.1.3



Renew access tokenWhen the access token is no longer valid, your application can renew it with the providedregistration information through the authorization server.The possibility to renew the access token depends on the parameters that define its validity.For more information, see 4.1.3 Validity of access tokens.The interface corresponds to the chapter “Refreshing an Access Token” from RFC 6749 (seehttp://tools.ietf.org/html/rfc6749#section-3) and the chapter “The WWW-Authenticate Re-sponse Header Field” from RFC 6750 (see http://tools.ietf.org/html/rfc6750#section-3). Forthe refresh there is no separate refresh token used but the access token.In the following, you can see the individual cases:1. The access token is valid:

The resource can be accessed in a usual way.2. The access token is not valid:

▪ The requestor of the resource receives the response BAD REQUEST with the errorinvalid_token and the 401 status code. The application can now try to update theaccess token.

▪ The update is done by a POST request to the authorization server together with theLIF file and the current access token as request parameter.

▪ If the access token could be updated successfully, the authorization server respondswith the updated access token. This can then be used to use the original resource.

3. The access token is invalid and cannot be updated:▪ The requestor of the resource receives the response BAD REQUEST with the error

invalid_token and the 401 status code. The application can now try to update theaccess token.

▪ The update is done by a POST request to the authorization server together with theLIF file and the current access token as request parameter.

▪ When the access token could not be updated, the authorization server responds withthe error invalid_grant and the 400 status code. The application can now try togenerate a new access token.

▪ The application requests a new login through the Login‑API. After the user has log-ged in again, the application can change the authorization code to an access tokenand continue to use the resource.

Request



Content-Type (required)application/x-www-form-urlencoded;charset=UTF-8

Authorization (required)Authorization header in accordance with HTTP Basic authentication scheme

4.1.4

Access to loginURL

URL structure








grant_type (required)You have to set the value refresh_token (see http://tools.ietf.org/html/rfc6749#section-6).

refresh_token (required)The current access token.


grant_type=refresh_token&refresh_token=dGhpcyBpcyBhbiBiYXN

Response



Note







HTTP body

Example

200






Note


Attention


Bad RequestThe request is incorrect.




unsupported_grant_typegrant_type is not equal to authorization_code

invalid_grantThe submitted refresh_token is invalid or has expired.


invalid_scopeThe wrong list format has been used or the specified list contains one or more un-known or invalid scopes, or the submitted list is not equal to the list that was used atthe time of the request for the authorization code.

400



HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8

{ "access_token": "V0aG9yaXphdGlvbiBjb2Rl", "token_type": "Bearer", "expires_in": 3600, "id_level": "basicplus"}



Resource Owner Password Credentials GrantThe authorization process according to the Resource Owner Password Credentials Grant isapplied, if there is a trustworthy connection between a user and your application. This trust-worthy connection is necessary since access data (user name and password) are stored inyour application.

For the implementation of this procedure, presenting a safety concept is mandatory:▪ Contact [email protected] or use the contact form on the partner portal

(https://partner.epost.de/kontakt).Subsequently, you will receive detailed information on the requirements necessary to presenta safety concept.

The expected credentials are the E‑POST address and the corresponding password. By au-thenticating according to the Resource Owner Password Credentials Grant, it is possible thatyour application can log in on behalf of a user without his involvement, if needed.1. In general, all functions are usable with that method that require a normal level of authen-

tication.2. However, to send electronic E‑POST letters, a user has to be authenticated with a high

level of authentication. Resource Owner Password Credentials Grant allows that in thefollowing way:Increase the level of authenticationYou implement a process to increase the level of authentication (see 4.3 Increase thelevel of authentication).Authorization with a trusted device

If you set the optional parameters device_id and integrity_token the process of in-creasing the level of authorization is bypassed. Note that the device_id has to specify aregistered and unlocked device (see 4.4 Register trusted device).



4.2

Prerequisites:Submission of a

safety concept

Implementation

4 Authentication ǀ Resource Owner Password Credentials Grant


https://partner.epost.de/kontakt

When requesting the resource, and a correct combination of the parameters device_idand integrity_token is given, the access token has automatically the high level of au-thentication. This is also the case if the requested scope(s) do not require such a highlevel of authentication.Result: If the device is unlocked, no HandyTAN is needed and an access token is imme-diately issued. If the transmitted device_id and integritiy_token are incorrect or thedevice is not unlocked the response is an error message.

Note

If you already have implemented a Resource Owner Password Credentials Grant au-thentication process and want to allow an authentication with a trusted device, you ad-ditionally need to implement a process to increase the level of authentication (see4.3 Increase the level of authentication).The use of a trusted device ist only possible for user with the user role “business cus-tomer”. Furthermore your application has to be activated for the functionality “trusteddevice”.

Attention

If you save user-specific data, such as user name and password, locally or remotely, youmust encrypt the saved data. If you allow an authentication with a trusted device, the useof the device_id requires as well a secure, encrypted storage of the user-specific integ-rity_token.

Request


The target of the request is the token endpoint (see http://tools.ietf.org/html/rfc6749#section-3.2), that is accessible at the path /oauth2/tokens/.


Content-Type (required)application/x-www-form-urlencoded

Authorization (required)Authorization header according to HTTP Basic authentication scheme (see http://tools.ietf.org/html/rfc6749#section-2.3.1 and http://www.ietf.org/rfc/rfc2617.txt chapter 2).The values to be used are taken from the data of the E‑POSTBUSINESS API registration.The identification of the user is constituted by combining the JSON fields DevId and Ap-pId with a comma. The resulting string is coded with the application/x-www-form-urlencoded algorithm (http://tools.ietf.org/html/rfc6749#appendix-B). This coded value isused as the user name, the contents of the LIF-file is encoded with the same algorithmand used as a password.

Access to loginURL

Target of the re-quest

URL structure

HTTP header









http://www.ietf.org/rfc/rfc2617.txt

http://tools.ietf.org/html/rfc6749#appendix-B

After combining the user name together with a “:” character and the password, the valueis to be encoded in base 64. The resulting string is preceded by the word Basic with ablank and is used as the value for the HTTP-header Authorization.

Forming:▪ Basic = basic-credentials▪ basic-credentials = base64-client-pass▪ base64-client-pass = <base64 encoding of client-pass>▪ client-pass = encoded-clientid ":" encoded-password▪ encoded-clientid = <x-www-form-urlencoding converts of clientid>▪ encoded-password = <x-www-form-urlencoding converts of password>▪ clientid = devid "," appid▪ devid = <Devid from LIF file>▪ appid = <AppId from LIF file>▪ password = <contents of the LIF file>


Attention

The content of the body must be URL-encoded (see: http://de.wikipedia.org/wiki/URL-Encoding). This is necessary since passwords with special characters are otherwise trans-mitted incorrectly, and an authentication is not possible. Well chosen passwords usuallycontain a number of special characters, e.g. %. Since % has a special meaning, the char-acter must be encoded with %25. Thus, e.g., the password G$eHeImNi%S is the URL-encoded string G%24eHeImNi%25s.

grant_type (required)Here the fixed value password must be set as specified in RFC 6749 (see http://tools.ietf.org/html/rfc6749#section-4.3.2).

username (required)User name

password (required)The user's password

scope (required)Contrary to the RFC 6749 specification, this is a mandatory parameter. You can submitthe following values:

send_letter▪ Allows a user to send electronic E‑POST letters▪ Requires a high level of authentication▪ For more information, see Send-API Reference

HTTP body



http://de.wikipedia.org/wiki/URL-Encoding

http://de.wikipedia.org/wiki/URL-Encoding



Note

This scope is only applicable in this login process when using the authorization witha trusted device or increasing the level of authentication.

send_hybrid▪ Allows a user to send physical E‑POST letters▪ Requires a normal level of authentication▪ For more information, see Send-API Reference

read_letter▪ Allows a user to read E‑POST letters▪ Requires a normal level of authentication▪ For more information, see Mailbox-API Reference

create_letter▪ Allows a user to create E‑POST letter drafts▪ Requires a normal level of authentication▪ For more information, see Mailbox-API Reference

delete_letter▪ Allows a user to delete E‑POST letter drafts.▪ Requires a normal level of authentication▪ For more information, see Mailbox-API Reference

safe▪ Allows access to the E‑POSTSAFE▪ Requires a normal level of authentication▪ For more information, see Safe-API Reference

register_device▪ Allows your application to register a trusted device (see 4.4 Register trusted device)▪ Requires a normal level of authentication

device_id (optional)Device ID that your application reads from a device (e.g. serial number, MAC address,Windows license key). You find further information for the registration of trusted devices in4.4 Register trusted device. If the parameter is used it is also required to specify the pa-rameter integrity_token.

Note

This parameter is only applicable if you use Resource Owner Password CredentialsGrant.

integrity_token (optional)A string that was created during the registration of the device. If the parameter is used,the parameter device_id is also required.



Note



grant_type=password&[email protected]&password=********&scope=send_hybrid

POST /oauth2/tokens/ HTTP/1.1Content-Type: application/x-www-form-urlencoded;charset=UTF-8Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== grant_type=password&[email protected]&password=********&scope=send_hybrid+delete_letter

Response



Note






Example (onescope)

Example (multiple

scopes)

200





Note


Attention



HTTP headerContent-Type: application/json;charset=UTF-8



unsupported_grant_typegrant_type is not equal to password

invalid_grantThe submitted user data is invalid.


invalid_scopeThe wrong list format has been used or the specified list contains one or more un-known or invalid scopes, or the submitted list is not equal to the list that was used atthe time of the request for the authorization code.

400





Increase the level of authentication

Request


POST /oauth2/auth/extension


The client application sends the following parameters in the format application/x-www-form-urlencoded in UTF-8 encoding in the entity-body of the HTTP request:

response_type (required)A string that specifies which permissions your application needs for authorization. Cur-rently, you can only pass the value code.

client_id (required)A string that identifies your application.

Note

The client_id is derived from Devid and AppId. You specify these values when youregister for the E‑POSTBUSINESS API. Build the client_id the following way:

▪ clientid = devid "," appid

redirect_uri (required)The registered redirect URI of the partner (stored on the server).

state (optional)A random string of a maximum of 512 characters in length, that describes the status ofyour application. The value is returned to your application in the login result.


4.3

Access to loginURL

URL structure

HTTP header

HTTP body

4 Authentication ǀ Increase the level of authentication




Attention

Your application must specify this parameter in order to prevent cross-site request for-gery, even if the parameter is not expected as a mandatory value. For more informa-tion, see http://tools.ietf.org/html/draft-ietf-oauth-v2-30#section-10.12.

Tip

With this parameter, e.g. a hashed session ID or a randomly generated value can bepassed.

scope (optional)A string that is used to indicate the extension of the scope with the default valuesend_letter. The parameter does not have to be specifically indicated.

access_token (required)The access token of the normal level of authentication in the form of a string.

device_id (optional)Device ID that your application reads from a device (e.g. serial number, MAC address,Windows license key). You find further information for the registration of trusted devices in4.4 Register trusted device. If the parameter is used it is also required to specify the pa-rameter integrity_token.

Note


integrity_token (optional)A string that was created during the registration of the device. If the parameter is used,the parameter device_id is also required.

Note


POST /oauth2/auth/extension HTTP/1.1Content-Type: application/x-www-form-urlencoded;charset=UTF-8Content-Length: 999 response_type=code &client_id=TestClientId &state=TestState &scope=send_letter &redirect_uri=https://localhost:8888/briefkasten &access_token=dGhpcyBpcyBhbiBiYXN

Example (Handy-TAN input)



http://tools.ietf.org/html/draft-ietf-oauth-v2-30#section-10.12

POST /oauth2/auth/extension HTTP/1.1Content-Type: application/x-www-form-urlencoded;charset=UTF-8Content-Length: 999 response_type=code&client_id=TestClientId&state=TestState&scope=send_letter&redirect_uri=https%3A%2F%2Flocalhost%3A8888%2Fbriefkasten&access_token=dGhpcyBpcyBhbiBiYXN&device_id=06%3A76%3Aba%3A8c%3A41%3A20&integrity_token=ahZGRjjkpvcGlVuIHN5lc2FtZQ

Response

Found (if successful)In the case of success the Login‑API responds with a redirect to the E‑POST TAN page.The reply contains the following parameters:

client_idThe returned authorization code.


scopeThe scope of the access token in the normal level of authentication, as well as the ex-tension send_letter.

redirect_uriRedirect to the input window for the HandyTAN.

Return of the access token:If successful, the process continues as follows:1. Your application shows the user the E‑POST TAN page page.2. Then the user enters the HandyTAN on the form and sends it.3. The Login API validates the HandyTAN, responds to your application with a redirect

URL and assigns an authorization code.4. Your application requests the access token through the Login‑API. See 4.1.2 Request

access token.

Found (error)In the event of an error your application receives a redirect URL with the appropriate errormessage. In this case, an error code (error), an optional description (error_descrip-tion), an optional note, under which URL a detailed description can be retrieved (er-ror_uri), as well as the value passed in the request (state) is returned.

error

invalid_scopeNone of the specified scopes requires a high level of authentication.

Example (authori-zation with a trus-

ted device)

302

302



access_deniedThe access token has expired.

error_descriptionFor human readable text with additional information to support the developer to under-stand the error that occurred.

error_uriA URI that delivers a human readable web page with information about the error.




HTTP/1.1 302 FoundSet-Cookie: code=SDFGSDHTZJw45ggwLocation: https://localhost:8888/briefkasten?code=dGhpcyBpcyBhbiBiYXN&state=TestState

HTTP/1.1 302 FoundSet-Cookie: code=SDFGSDHTZJw45ggwLocation: https://login.epost.de/oauth2/auth/tan?response_type=code &client_id=TestClientId &state=TestState &scope=send_letter send_hybrid create_letter &redirect_uri=https://localhost:8888/link/zum/tan_formular

HTTP/1.1 302 FoundLocation: https://localhost:8888/briefkasten? error=access_denied& error_description="The resource owner or authorization server denied the request."& error_uri="http://tools.ietf.org/html/rfc6749#section-4.1.2"& state=TestState

Register trusted deviceA trusted device is a device that is registered at the E‑POST system. With a trusted device itis possible to send electronic E‑POST letters without the input of a HandyTAN. A trusted de-vice can not only be a mobile device but also a tablet, notebook, desktop computer etc. Viayour application the registration of a device is carried out. A registration has to take a clearcharacteristic of a device into account, e.g. a MAC address. Your application registers a trus-ted device with the transmission of a device ID to the E‑POST system.After a registration via

500

503

Beispiel:Response in thecase of success

(authorization witha trusted device)


(HandyTAN input)


4.4

4 Authentication ǀ Register trusted device


your application it is required that the device gets unlocked. The unlock mechanism is car-ried out through an stand-alone online portal that is provided by E‑POST. Your customersuse this online portal to manage all pending registrations and already unlocked devices.Trusted devices skip the input of a HandyTAN in the login process and change immediatelyto the high level of authentication (4.2 Resource Owner Password Credentials Grant oder4.3 Increase the level of authentication).

Note

The use of a trusted device ist only possible for user with the user role “business custom-er”. Furthermore your application has to be activated for the functionality “trusted device”.

After the unlocking of his device a user can send electronic E‑POST letters without the inputof a HandyTAN.

Note

The functionality is not part of RFC 6749 - The OAuth 2.0 Authorization Framework.

For the use of the resource you need the scope register_device.

Request


POST /device/register

x-epost-access-token (required)This header passes the token that authorizes your application with the permission of theowner of the specified E‑POST user account.

Content-Type (required)application/json

In the body you pass a JSON object that includes the ID, name and model type of the devicethat is to be registered. You pass the information via the following parameters:

id (string, required)▪ Device ID that your application reads from a device (e.g. serial number, MAC address,

Windows license key). It is required that your application reads the ID from the deviceduring run time.

Note

After the process of registration and unlocking you pass that value during loginwith the parameter device_id (see 4.2 Resource Owner Password CredentialsGrant or 4.3 Increase the level of authentication).

▪ Maximum character length: 100

Scope

Access to loginURL

URL structure

HTTP header

HTTP body



http://tools.ietf.org/html/rfc6749



▪ Allowed characters: upper and lower-case letters and numbers

Note

Special characters and spaces are not allowed.

name (string, required)▪ The name of the device that is to be registered (e.g. “My Laptop”, “My iPhone”)▪ Maximum character length: 200▪ Allowed characters: upper and lower-case letters, spaces and numbers

model (string, required)▪ The model type of the device that is to be registered (e.g “iPhone 5s”, “Samsung Gala-

xy 5”, “DELL latitude e6420”)▪ Maximum character length: 100▪ Allowed characters: upper and lower-case letters, spaces and numbers

POST /device/register HTTP/1.1Content-Type: application/jsonx-epost-access-token: eyJjb250ZW50Ijoie1widW5p..

{ "id": "1234-ABCD-5678-EFGH", "name": "Mein Laptop", "model": "lenovo thinkpad t123"}

Response

CreatedThe device was registered and can now be unlocked.

HTTP headerapplication/json;charset=UTF-8

HTTP bodyThe body of the response contains a JSON object with an integrity token:

integrity_tokenThe integrity token is a unique string that you pass over in the parameter integri-ty_token for a login with a trusted device (see 4.2 Resource Owner Password Cre-dentials Grant oder 4.3 Increase the level of authentication).



Example

201

400



HTTP bodyThe body contains a JSON object with error information.Possible values for error:

invalid_device_informationThe fields id, name or model are missing, have an empty string as value or do notcomply to the minimum/maximum character lengths.

ForbiddenThere is no permission to access the resource.


HTTP bodyThe body contains a JSON object with error information.Possible values for error:

insufficient_scopeThe transferred access token does not contain the scope register_device.

HTTP/1.1 201 CreatedContent-Type: application/json;charset=UTF-8X-CorrelationId: 12345678-ABCD-EFGH-87654321 { "integrity_token": "123123123123123123132..."}

LogoutTo log out, your application submits a valid access token. The submitted access token canthen no longer be used for queries against the API.

RequestThe request to log out contains the token as parameter access_token. The call is also suc-cessful for requests, that contain already expired access tokens.


403


4.5

Access to loginURL

4 Authentication ǀ Logout




POST /oauth2/tokens/logout


access_token (required)The current access token.

POST /oauth2/tokens/logout HTTP/1.1Content-Type: application/x-www-form-urlencoded;charset=UTF-8 access_token=dGhpcyBpcyBhbiBiYXN...

Response

No ContentThe response in the case of success is a HTTP message with status code 204 and anempty body. With this the logout is successful.


HTTP headerContent-Type: application/json;charset=UTF-8


invalid_inputThe submitted access token is missing or in the wrong format.



URL structure

HTTP header

Path parameter

Example

204

400

500

503

4 Authentication ǀ Logout


Deutsche Post DHL Group

If you have questions about the E‑POSTBUSINESS API you find further information on http://part-ner.epost.de.For general E‑POST questions please contact the support:

• Tel.: +49 228 76 36 76 06, Mon - Sun 09.00 - 20.00 (except on public holidays)• E‑POST letter: [email protected]• E-Mail: [email protected]

Deutsche Post AGCharles-de-Gaulle-Straße 2053113 Bonn

www.deutschepost.de

Stand 03/2016

Documents

Login-API Reference E POSTBUSINESS API · 1 Introduction 1 2 Basic concepts 2 3 Identity Levels and E‑POST Functions 4 ... Introduction The Login‑API is part of the E‑POSTBUSINESS