E POSTBUSINESS API Login-API Reference. Version 1.1

E POSTBUSINESS API Login-API Reference

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

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 Reference

1 Introduction 1 Introduction The Login API is part of the E POSTBUSINESS API, the REST interface of the E POST system for software suppliers. With the Login API you allow E POST users to log to the E POST system from your software application. The login is required to directly use the integrated E POST functions from within your application. Integration of E POST functions Functioning Audience Partner portal 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 OAuth 2.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 standard Refreshing an Access Token. The Login API is a REST API, whose entire communication 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 the E POST partner website (http://partner.epost.de/). Login-API Reference 1

2 Basic concepts 2 Basic concepts This section details the basic concepts of the Login API, as well as the implemented OAuth 2.0 features in the E POSTBUSINESS API. Request and response Request and response invocations have been implemented according to the HTTP standard. In addition, note the following requirements: UTF-8 For the processing of strings UTF-8 encoding is required. Dates and Times All dates and times are in ISO 8601 format (e.g. 2014-07 -16T17:05:39+02:00). HTTPS encryption The Login API only uses HTTPS connections. Therefore the identification data of the participants are protected throughout the whole communication process. Verify the correctness of the certificate on the other side with every call. JSON data format REST API endpoint HTTP status codes For the exchange of data between your application and the E POST system the JSON data format 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 returned in the body of the response and formatted as JSON document. In addition to the resource specific response codes the following general response codes are returned 405 Method Not Allowed The HTTP method is not supported. 415 Unsupported Media Type The submitted Content-Type does not correspond to the expected value. 500 Internal Server Error Internal processing error Login-API Reference 2

2 Basic concepts 503 Service Unavailable Internal processing error Login-API Reference 3

3 Identity Levels and E POST Functions 3 Identity Levels and E POST Functions E POST user can choose between different E POST identity levels, each one with different E 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 with E POST by completing the online form, without the need for the POSTIDENT procedure. By this way, a customer has direct access to the E POST Portal without further actions. There are four different identity levels, to which a private customer is assigned to, depending on the verification level of his identity and his postal address. Comparison between identity level and level of authentication Identity level The identity level defines what kind of knowledge the E POST system has about a customer (the user's identity) and to what extent it has been verified in the course of the registration process. Authentication level (see 4. Authentication) The level of authentication defines the way in which a customer's identity has been verified during the use of E POST products. or Simple authentication: through user name and password Extended authentication: by a second factor (HandyTAN). The second factor provides the system with a higher level of certainty that the expected identity, is the authenticated one. Identity levels and Registration A private customer gets a specific identity level, depending on the verification of his identity and his postal address during the registration process. Basic By completing the registration form, private customers are directly registered, without the need for an POSTIDENT procedure. By this way, customers get the identity level basic. Premium Customers with the identity level basic upgrade to the identity level premium, when verifying via POSTIDENT after registration. In addition, a basic customer as well as a premium customer can verify their address and change 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 level premium+. Login-API Reference 4

3 Identity Levels and E POST Functions The AdressTAN is sent to the specified address in a physical letter. E POST Functions depending on the identity level A private customer can ( ) or cannot ( ) use certain E POST functions depending on his identity level: Function Basic Basic+ Premium Premium+ Physically send E POST letters Use E POSTSAFE Send and receive faxes Receive electronic E POST letters Send electronic E POST letters Use E POSTZAHLUNG Use IdentPLUS Use E POSTSCAN Table 3-1 E POST Functions depending on the identity level Procedure: Implementation with the Send API Your application receives the identity level of a user, after he has successfully logged into the E POST system, via the parameter id_level, which is included in the response of the Login-API (see 4.1.2 Request access token). In the implementation of the send process, ensure that only the functions are made available to a user which are approved for his identity level. In addition, you have to process error messages if a non-permitted function was called. Example: Your application can either proactively prevent that a basic user sends an electronic E POST letter, or permits this process in general, handling the corresponding error message, and displaying a message to the user. Business customers do not have an identity level. No identity level restrictions apply to them. Login-API Reference 5

4 Authentication 4 Authentication With the Login API your application authenticates itself for the E POST system. OAuth 2.0 Registration Use the OAuth 2.0 procedures to register your application on the E-POST Sytem. OAuth 2.0 uses the resources of HTTP, so that the login functionality through a browser is enabled. Alternatively, you can login without a browser. To registration, contact our support on the following URL (http://partner.epost.de/registrieren/). 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. Take the following naming conventions into account, when defining the DevID and the AppID 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. CompanynameLTD ). 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 platform from Deutsche Post AG. License-file (LIF file) Along with the registration data, a License-File (LIF file) is created and sent to you. The LIF file is a encrypted key that is required in the authentication process. The LIF file ensures that your application has the necessary authorization for the E POST system. Login-API Reference 6

4 Authentication ǀ Authorization Code Grant Next, you find the instructions required to authenticate with the Login-API. The OAuth 2.0 specific steps that take place between a browser, the Send API, the Mailbox API or the Safe API and your application are not described here, as no implementation in this context is required. Choice of authentication specification You have the choice between using the procedures specified in one of the following OAuth 2.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). 4.1 Authorization Code Grant When your application implements a login with user action, the authentication process has to comply 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 process sequentially. 1. Implement one of the following actions, to access a ressource with a specific user purpose (characterized by scope, e.g. Sending an E POST letter or receiving an E POST letter) 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 transferring 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. Login-API Reference 7

4 Authentication ǀ Authorization Code Grant 4.1.1 Request login page By requesting the login page, your application allows a user to authenticate for the E POST system. With the authentication, a user grants rights to your application. The authentication of your application is only successful when the authorization code is changed to an access token. 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 Access to login URL Your application must have access to the login URL: https://login.epost.de (Production) https://login.epost-gka.de (Test and integration environment) URL structure GET /oauth2/auth Path parameter response_type (required) A string that specifies which permissions your application needs for authorization. Currently, you can only pass the value code. client_id (required) A string that identifies your application. The client_id is derived from Devid and AppId. You specify these values when you register 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 of your 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 forgery, even if the parameter is not expected as a mandatory value. For more information, 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 be passed. scope (required) The scope determines the extent to which your client can access one or several resource(s) of the user. Login-API Reference 8

4 Authentication ǀ Authorization Code Grant 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 device) Requires a normal level of authentication The level of authentication specifies whether the user of the E POST system must authenticate with a HandyTAN (high) or not (normal). It is possible to specify multiple scopes simultaneously. Several scopes are separated with a space. Examples: scope=send_letter create_letter scope=safe read_letter scope=delete_letter read_letter Login-API Reference 9

4 Authentication ǀ Authorization Code Grant redirect_uri (required) A URI to which the Login result is redirected. The redirect_uri must be known to the E POST system. The final system-generated redirect_uri must not be longer than 2083 characters, including protocol specification and other parameters. Otherwise display problems occur both in the browser and the server. Example GET /oauth2/auth? response_type=code& client_id=testclientid& state=teststate& scope=send_letter& redirect_uri=https://localhost:8888/briefkasten HTTP/1.1 Host: login.epost.de Response 302 Found (if successful) In the case of success, a redirect URL with authorization code is returned. The server submits the following parameters to your application as query string of the redirect URL. The response contains the following parameters: code The returned authorization code. state The value that is passed by the request is forwarded unchanged. 302 Found (error) In the event of an error your application receives a redirect URL with the appropriate error message. In this case, an error code (error), an optional description (error_description), an optional note, under which URL a detailed description can be retrieved (error_uri), as well as the value passed in the request (state) is returned. error access_denied Invalid TAN or incorrect redirect_uri invalid_niveau The login is only allowed with a high level of authentication (to be set by the user in the E POST portal) invalid_request Missing or incorrect parameters or referer invalid_scope Wrong list format or the list includes one or more unknown, or invalid scope(s) server_error Unexpected server-side error Login-API Reference 10

4 Authentication ǀ Authorization Code Grant temporarily_unavailable temporary server-side error unauthorized_client client_id is incorrect unsupported_response_type Response type does not correspond to code error_description For human readable text with additional information to support the developer to understand the error that occurred. error_uri state A URI that delivers a human readable web page with information about the error. The value that is passed by the request is forwarded unchanged. 500 503 Internal Server Error Internal processing error Service Unavailable Internal processing error Example: Response in the case of success HTTP/1.1 302 Found Location: https://localhost:8888/briefkasten?code=dghpcybpcybhbibiyxn &state=teststate Example: Response in the event of an error 4.1.2 HTTP/1.1 302 Found Location: 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 token If the request for the authorization code was answered successfully in the previous step and your application has received it, the second step is the request of the access token via the Login API. This process is performed by replacing the authorization code with an access token by a further request from your application. Login-API Reference 11

4 Authentication ǀ Authorization Code Grant Request Access to login URL Your application must have access to the login URL: https://login.epost.de (Production) https://login.epost-gka.de (Test and integration environment) URL structure POST /oauth2/tokens/ HTTP header 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 AppId with a comma. The resulting string is coded with the application/x-www-formurlencoded algorithm (http://tools.ietf.org/html/rfc6749#appendix-b). This coded value is used as the user name, the contents of the LIF-file is encoded with the same algorithm and used as a password. After combining the user name together with a : character and the password, the value is to be encoded in base 64. The resulting string is preceded by the word Basic with a blank 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> HTTP body The client application sends the following parameters in the format application/x-wwwform-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 authentication with authorization code only the type authorization_code is permitted. code (required) The authorization code that is received by the authenticating user. Login-API Reference 12

4 Authentication ǀ Authorization Code Grant scope (required) The scope that is requested through authorization. It must correspond to the scope that was 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_uri has to be transferred to verify the consistency of the request. Example POST /oauth2/tokens/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=utf-8 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== grant_type=authorization_code& code=dghpcybpcybhbibiyxn& scope=send_letter%20create_letter& redirect_uri=https://localhost:8888/briefkasten/ Response 200 OK In the event of success, your application receives a ticket in form of a JSON object, which contains an access token. Depending on the given scope you can use the Send API or the Mailbox API resources for the delivery or access to E POST letters. Furthermore you can access or change documents or directories through the Safe API. In contrast to the OAuth2.0 specification, the response does not contain a refresh token for the update on its own. To implement this, the already existing access token is renewed. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the ticket. The ticket is structured as follows: access_token The access token in the form of a string. expires_in Validity of the access token in seconds. The access token has a limited validity period, which is determined by the Login API. token_type The parameter is required by the OAuth2.0 specification and you always have to set it to Bearer in the E POSTBUSINESS API. Login-API Reference 13

4 Authentication ǀ Authorization Code Grant id_level The identity level of the logged-in E POST user (see 3. Identity Levels and E POST Functions). Possible values are basic, basicplus, premium, premiumplus and null. In case of a business customer the value is null. When the access token has exceeded its validity period, the request is rejected with the corresponding note invalid_token. After that, your application can renew the token for an extended period of time through the Login API. To do this, your application 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 unauthorized access is possible. 400 Bad Request The request is încorrect. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_request parameter error unsupported_grant_type grant_type is not equal to authorization_code invalid_grant Invalid authorization_code unauthorized_client The grant_type is not allowed for the authenticated client invalid_scope The wrong list format has been used, or the specified list contains one or more unknown or invalid scopes, or the submitted list is not equal to the list that was used at the time of the request for the authorization code. Login-API Reference 14

4 Authentication ǀ Authorization Code Grant 401 Unauthorized HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_client Credentials are missing, Client-ID is invalid or credentials are not valid. 403 Forbidden There is no authorization to access the resource. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_niveau The login is only allowed with a high level of authentication (to be set by the user in the E POST portal) 415 Unsupported Media Type The media type of the file is not permitted. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: unsupported_media_type The Content-Type of the request is not supported. 500 503 Internal Server Error Internal processing error Service Unavailable Internal processing error Login-API Reference 15

4 Authentication ǀ Authorization Code Grant Example: Response in the case of success HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { } "access_token": "V0aG9yaXphdGlvbiBjb2Rl", "token_type": "Bearer", "expires_in": 3600, "id_level": "basicplus" Example: Response in the event of an error 4.1.3 HTTP/1.1 400 Bad Request Content-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 tokens An access token has the following parameters that define how long it can be renewed. For more information, see 4.1.4 Renew access token. Parameters Value (h:min) Description validity 0:10 Time period within which an access token (regardless of level of authentication) is valid, and can be used. After this time period the access token can no longer be used for operations on the API. But it can be renewed. available 1:00 Time period within which an access token on a normal level of authentication must be renewed latest. If it is not replaced within this time 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 authentication must be renewed. If it is not renewed within this time period, it switches to the normal level of authentication. Since the validity time has already expired, it must be renewed, so that it can be used once again (now at a normal level of authentication). The available time has already partially passed at this time as well. Therefore there are only 45 minutes left until the access token becomes invalid. max.validity 24:00 Maximum period of validity of an access token despite continuous renewal. After the expiry a renewal is no longer possible. Table 4.1-1 Parameters of access tokens Login-API Reference 16

4 Authentication ǀ Authorization Code Grant 4.1.4 Renew access token When the access token is no longer valid, your application can renew it with the provided registration 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 (see http://tools.ietf.org/html/rfc6749#section-3) and the chapter The WWW-Authenticate Response Header Field from RFC 6750 (see http://tools.ietf.org/html/rfc6750#section-3). For the 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 error invalid_token and the 401 status code. The application can now try to update the access token. The update is done by a POST request to the authorization server together with the LIF file and the current access token as request parameter. If the access token could be updated successfully, the authorization server responds with 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 the access token. The update is done by a POST request to the authorization server together with the LIF file and the current access token as request parameter. When the access token could not be updated, the authorization server responds with the error invalid_grant and the 400 status code. The application can now try to generate a new access token. The application requests a new login through the Login API. After the user has logged in again, the application can change the authorization code to an access token and continue to use the resource. Request Access to login URL Your application must have access to the login URL: https://login.epost.de (Production) https://login.epost-gka.de (Test and integration environment) URL structure POST /oauth2/tokens/ Content-Type (required) application/x-www-form-urlencoded;charset=utf-8 Authorization (required) Authorization header in accordance with HTTP Basic authentication scheme Login-API Reference 17

4 Authentication ǀ Authorization Code Grant HTTP body The client application sends the following parameters in the format application/x-wwwform-urlencoded in UTF-8 encoding in the entity-body of the HTTP request. 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. Example POST /oauth2/tokens/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=utf-8 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== grant_type=refresh_token&refresh_token=dghpcybpcybhbibiyxn Response 200 OK In the event of success, your application receives a ticket in form of a JSON object, which contains an access token. Depending on the given scope you can use the Send API or the Mailbox API resources for the delivery or access to E POST letters. Furthermore you can access or change documents or directories through the Safe API. In contrast to the OAuth2.0 specification, the response does not contain a refresh token for the update on its own. To implement this, the already existing access token is renewed. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the ticket. The ticket is structured as follows: access_token The access token in the form of a string. expires_in Validity of the access token in seconds. The access token has a limited validity period, which is determined by the Login API. token_type The parameter is required by the OAuth2.0 specification and you always have to set it to Bearer in the E POSTBUSINESS API. Login-API Reference 18

4 Authentication ǀ Authorization Code Grant id_level The identity level of the logged-in E POST user (see 3. Identity Levels and E POST Functions). Possible values are basic, basicplus, premium, premiumplus and null. In case of a business customer the value is null. When the access token has exceeded its validity period, the request is rejected with the corresponding note invalid_token. After that, your application can renew the token for an extended period of time through the Login API. To do this, your application 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 unauthorized access is possible. 400 Bad Request The request is incorrect. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_request parameter error unsupported_grant_type grant_type is not equal to authorization_code invalid_grant The submitted refresh_token is invalid or has expired. unauthorized_client The grant_type is not allowed for the authenticated client invalid_scope The wrong list format has been used or the specified list contains one or more unknown or invalid scopes, or the submitted list is not equal to the list that was used at the time of the request for the authorization code. Login-API Reference 19

4 Authentication ǀ Resource Owner Password Credentials Grant Example: Response in the case of success HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { } "access_token": "V0aG9yaXphdGlvbiBjb2Rl", "token_type": "Bearer", "expires_in": 3600, "id_level": "basicplus" Example: Response in the event of an error HTTP/1.1 400 Bad Request Content-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" } 4.2 Resource Owner Password Credentials Grant The authorization process according to the Resource Owner Password Credentials Grant is applied, if there is a trustworthy connection between a user and your application. This trustworthy connection is necessary since access data (user name and password) are stored in your application. Prerequisites: Submission of a safety concept Implementation For the implementation of this procedure, presenting a safety concept is mandatory: Contact epost-partner@deutschepost.de 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 present a safety concept. The expected credentials are the E POST address and the corresponding password. By authenticating according to the Resource Owner Password Credentials Grant, it is possible that your 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 authentication. 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 the following way: Increase the level of authentication You implement a process to increase the level of authentication (see 4.3 Increase the level of authentication). Authorization with a trusted device If you set the optional parameters device_id and integrity_token the process of increasing the level of authorization is bypassed. that the device_id has to specify a registered and unlocked device (see 4.4 Register trusted device). Login-API Reference 20

4 Authentication ǀ Resource Owner Password Credentials Grant When requesting the resource, and a correct combination of the parameters device_id and integrity_token is given, the access token has automatically the high level of authentication. This is also the case if the requested scope(s) do not require such a high level of authentication. Result: If the device is unlocked, no HandyTAN is needed and an access token is immediately issued. If the transmitted device_id and integritiy_token are incorrect or the device is not unlocked the response is an error message. If you already have implemented a Resource Owner Password Credentials Grant authentication process and want to allow an authentication with a trusted device, you additionally need to implement a process to increase the level of authentication (see 4.3 Increase the level of authentication). The use of a trusted device ist only possible for user with the user role business customer. Furthermore your application has to be activated for the functionality trusted device. Attention If you save user-specific data, such as user name and password, locally or remotely, you must encrypt the saved data. If you allow an authentication with a trusted device, the use of the device_id requires as well a secure, encrypted storage of the user-specific integrity_token. Request Access to login URL Target of the request Your application must have access to the login URL: https://login.epost.de (Production) https://login.epost-gka.de (Test and integration environment) 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/. URL structure POST /oauth2/tokens/ HTTP header 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 AppId with a comma. The resulting string is coded with the application/x-www-formurlencoded algorithm (http://tools.ietf.org/html/rfc6749#appendix-b). This coded value is used as the user name, the contents of the LIF-file is encoded with the same algorithm and used as a password. Login-API Reference 21

4 Authentication ǀ Resource Owner Password Credentials Grant After combining the user name together with a : character and the password, the value is to be encoded in base 64. The resulting string is preceded by the word Basic with a blank 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> HTTP body The client application sends the following parameters in the format application/x-wwwform-urlencoded in UTF-8 encoding in the entity-body of the HTTP request. 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 transmitted incorrectly, and an authentication is not possible. Well chosen passwords usually contain a number of special characters, e.g. %. Since % has a special meaning, the character must be encoded with %25. Thus, e.g., the password G$eHeImNi%S is the URLencoded 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 submit the 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 Login-API Reference 22

4 Authentication ǀ Resource Owner Password Credentials Grant This scope is only applicable in this login process when using the authorization with a trusted device or increasing the level of authentication. send_hybrid read_letter Allows a user to send physical E POST letters Requires a normal level of authentication For more information, see Send-API Reference 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 in 4.4 Register trusted device. If the parameter is used it is also required to specify the parameter integrity_token. This parameter is only applicable if you use Resource Owner Password Credentials Grant. 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. Login-API Reference 23

4 Authentication ǀ Resource Owner Password Credentials Grant This parameter is only applicable if you use Resource Owner Password Credentials Grant. Example (one scope) POST /oauth2/tokens/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=utf-8 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== grant_type=password&username=john.doe@testingepost.de&password=********&sco pe=send_hybrid Example (multiple scopes) POST /oauth2/tokens/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=utf-8 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== grant_type=password&username=john.doe@testingepost.de&password=********&sco pe=send_hybrid+delete_letter Response 200 OK In the event of success, your application receives a ticket in form of a JSON object, which contains an access token. Depending on the given scope you can use the Send API or the Mailbox API resources for the delivery or access to E POST letters. Furthermore you can access or change documents or directories through the Safe API. In contrast to the OAuth2.0 specification, the response does not contain a refresh token for the update on its own. To implement this, the already existing access token is renewed. HTTP header Content-Type: application/json; charset=utf-8 HTTP body The body contains a JSON object with the ticket. The ticket is structured as follows: access_token The access token in the form of a string. expires_in Validity of the access token in seconds. The access token has a limited validity period, which is determined by the Login API. Login-API Reference 24

4 Authentication ǀ Resource Owner Password Credentials Grant token_type The parameter is required by the OAuth2.0 specification and you always have to set it to Bearer in the E POSTBUSINESS API. id_level The identity level of the logged-in E POST user (see 3. Identity Levels and E POST Functions). Possible values are basic, basicplus, premium, premiumplus and null. In case of a business customer the value is null. When the access token has exceeded its validity period, the request is rejected with the corresponding note invalid_token. After that, your application can renew the token for an extended period of time through the Login API. To do this, your application 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 unauthorized access is possible. 400 Bad Request The request is incorrect. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_request parameter error unsupported_grant_type grant_type is not equal to password invalid_grant The submitted user data is invalid. unauthorized_client The grant_type is not allowed for the authenticated client invalid_scope The wrong list format has been used or the specified list contains one or more unknown or invalid scopes, or the submitted list is not equal to the list that was used at the time of the request for the authorization code. Login-API Reference 25

4 Authentication ǀ Increase the level of authentication Example: Response in the event of an error HTTP/1.1 400 Bad Request Content-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" } 4.3 Increase the level of authentication Request Access to login URL Your application must have access to the login URL: https://login.epost.de (Production) https://login.epost-gka.de (Test and integration environment) URL structure POST /oauth2/auth/extension HTTP header Content-Type (required) application/x-www-form-urlencoded;charset=utf-8 HTTP body The client application sends the following parameters in the format application/x-wwwform-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. Currently, you can only pass the value code. client_id (required) A string that identifies your application. The client_id is derived from Devid and AppId. You specify these values when you register 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 of your application. The value is returned to your application in the login result. Login-API Reference 26

4 Authentication ǀ Increase the level of authentication Attention Your application must specify this parameter in order to prevent cross-site request forgery, even if the parameter is not expected as a mandatory value. For more information, 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 be passed. scope (optional) A string that is used to indicate the extension of the scope with the default value send_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 in 4.4 Register trusted device. If the parameter is used it is also required to specify the parameter integrity_token. This parameter is only applicable if you use Resource Owner Password Credentials Grant. 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. This parameter is only applicable if you use Resource Owner Password Credentials Grant. Example (Handy- TAN input) POST /oauth2/auth/extension HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=utf-8 Content-Length: 999 response_type=code &client_id=testclientid &state=teststate &scope=send_letter &redirect_uri=https://localhost:8888/briefkasten &access_token=dghpcybpcybhbibiyxn Login-API Reference 27

4 Authentication ǀ Increase the level of authentication Example (authorization with a trusted device) POST /oauth2/auth/extension HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=utf-8 Content-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 302 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_id state The returned authorization code. The value that is passed by the request is forwarded unchanged. scope The scope of the access token in the normal level of authentication, as well as the extension send_letter. redirect_uri Redirect 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. 302 Found (error) In the event of an error your application receives a redirect URL with the appropriate error message. In this case, an error code (error), an optional description (error_description), an optional note, under which URL a detailed description can be retrieved (error_uri), as well as the value passed in the request (state) is returned. error invalid_scope None of the specified scopes requires a high level of authentication. Login-API Reference 28

4 Authentication ǀ Register trusted device access_denied The access token has expired. error_description For human readable text with additional information to support the developer to understand the error that occurred. error_uri state A URI that delivers a human readable web page with information about the error. The value that is passed by the request is forwarded unchanged. 500 503 Internal Server Error Internal processing error Service Unavailable Internal processing error Beispiel: Response in the case of success (authorization with a trusted device) Example: Response in the case of success (HandyTAN input) HTTP/1.1 302 Found Set-Cookie: code=sdfgsdhtzjw45ggw Location: https://localhost:8888/briefkasten? code=dghpcybpcybhbibiyxn&state=teststate HTTP/1.1 302 Found Set-Cookie: code=sdfgsdhtzjw45ggw Location: 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 Example: Response in the event of an error HTTP/1.1 302 Found Location: 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 4.4 Register trusted device A trusted device is a device that is registered at the E POST system. With a trusted device it is possible to send electronic E POST letters without the input of a HandyTAN. A trusted device can not only be a mobile device but also a tablet, notebook, desktop computer etc. Via your application the registration of a device is carried out. A registration has to take a clear characteristic of a device into account, e.g. a MAC address. Your application registers a trusted device with the transmission of a device ID to the E POST system.after a registration via Login-API Reference 29

4 Authentication ǀ Register trusted device your application it is required that the device gets unlocked. The unlock mechanism is carried out through an stand-alone online portal that is provided by E POST. Your customers use 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 immediately to the high level of authentication (4.2 Resource Owner Password Credentials Grant oder 4.3 Increase the level of authentication). The use of a trusted device ist only possible for user with the user role business customer. 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 input of a HandyTAN. The functionality is not part of RFC 6749 - The OAuth 2.0 Authorization Framework. Scope For the use of the resource you need the scope register_device. Request Access to login URL Your application must have access to the login URL: https://login.epost.de (Production) https://login.epost-gka.de (Test and integration environment) URL structure POST /device/register HTTP header x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. Content-Type (required) application/json HTTP body In the body you pass a JSON object that includes the ID, name and model type of the device that 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 device during run time. After the process of registration and unlocking you pass that value during login with the parameter device_id (see 4.2 Resource Owner Password Credentials Grant or 4.3 Increase the level of authentication). Maximum character length: 100 Login-API Reference 30

4 Authentication ǀ Register trusted device Allowed characters: upper and lower-case letters and numbers 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 Galaxy 5, DELL latitude e6420 ) Maximum character length: 100 Allowed characters: upper and lower-case letters, spaces and numbers Example POST /device/register HTTP/1.1 Content-Type: application/json x-epost-access-token: eyjjb250zw50ijoie1widw5p.. { } "id": "1234-ABCD-5678-EFGH", "name": "Mein Laptop", "model": "lenovo thinkpad t123" Response 201 Created The device was registered and can now be unlocked. HTTP header application/json;charset=utf-8 HTTP body The body of the response contains a JSON object with an integrity token: integrity_token The integrity token is a unique string that you pass over in the parameter integrity_token for a login with a trusted device (see 4.2 Resource Owner Password Credentials Grant oder 4.3 Increase the level of authentication). 400 Bad Request The request is incorrect. HTTP header Content-Type: application/json; charset=utf-8 Login-API Reference 31