Version 2016-01-15
1

About this Document .............................................................................................................................. 3
Audience ............................................................................................................................................. 3
Definitions ........................................................................................................................................... 3
Preconditions ...................................................................................................................................... 3
General Flow ....................................................................................................................................... 5
Details...................................................................................................................................................... 6
Protocol ............................................................................................................................................... 6
Host ..................................................................................................................................................... 6
Trigger Point: User starts ID-Card retrieval ......................................................................................... 6
Authentication Request ...................................................................................................................... 7
Redirect, path and request .............................................................................................................. 7
Release by the use and redirect to the RP ...................................................................................... 8
Authentication successful ............................................................................................................. 10
Authentication Error ..................................................................................................................... 11
Token Request ................................................................................................................................... 12
Path ............................................................................................................................................... 13
Header/Body ................................................................................................................................. 13
Sample Request ............................................................................................................................. 13
Token Result .................................................................................................................................. 14
Token Error .................................................................................................................................... 14
Using the Nimbus Library .................................................................................................................. 16
For Authentication Requests ......................................................................................................... 16
For Token Requests ....................................................................................................................... 18
ID-Card as Result Object ........................................................................................................................ 20
Overview of the ID-Cards currently available .................................................................................... 20
ID-Card data structure ....................................................................................................................... 20
Standards and Protocols ....................................................................................................................... 23
2

POSTID is a service of Deutsche Post that allows the personal identification of customers with only a few clicks and minimal technical requirements (web browser, mobile phone). Data of the identified person will be provided in form of ID-Cards. In cases where the required information are available in the POSTID account of the customer, the identification process diminishes to a simple data transmission process. Customers simply need to approve data transmission.
The POSTID ID-Card API enables business costumers to retrieve identity data of registered users from the POSTID-System. The API is based on the OpenID Connect-Standard.
1 ID-Cards will be provided in
JSON Web Token-Format (JWT) 2 .
This document is intended for software developers on side of business customer that want to connect their service to the POSTID-System.
Term
Relying Party (RP), synonym: client user
POSTID idcard
Open ID-Provider
Data transmission
Definition
Business customer which is the principal for the identification process
End user providing identity data.
Container for identity data of an end user.
POSTID-System of DPAG
Technical procedure where the ID-Card is transmitted to the IT-System of the business customer. End users have an transaction history in their
POSTID account which details all data transmission procedures.
The following table specifies parameters provided by the Deutsche Post that you will require to build the authentication request and to successfully connect your IT-System to the POSTID-System:
Parameter Description client_id User name of the service provider (RP). The client_id is required for the authentification request and the token request. client_secret Password of the technical user. The
Example
1001
Kdemr&§!!"2466
1 See http://openid.net/connect/
2 See http://openid.net/specs/openid-connect-core-1_0.html#JWTRequests and https://tools.ietf.org/html/rfc7519
3

Parameter Description client_secret is required to implement the token request. The client_secret is saved within the POSTID-System as encrypted and oneway encoded data package.
Note
The OpenID Connect specification requires that the RedirectURI is stored on the OpenID provider's side - in this case the POSTID-System. sign_keyid
The authentication request also contains the
RedirectURI of the client. The request will be responded only in case both URIs match.
Name of the used signature key. Used to build the token request. sign_secret Secret used to sign the encrypted SignedJWT via
HS256. The sign_secret parameter is required to generate the token request.
Format: numeric character string of HEX-digits.
Note
The string has to be transformed into a byte array where 2 characters result in a single byte before it is used by a crypto-provider.
In Java:
DatatypeConverter.parseHexBinary(<SampleHe xString>);
Example keyid001
1234567890abcdef1234567890a bcdef1234567890abcdef1234567
890abcdef
The following parameters have to be provided to the DPAG by the business costumer:
Parameter
RP Alias
Callback-URL
(=redirect_uri)
Beschreibung
Name of the client or relying party system
(RP) that will be shown to the user during data transmission. callback_URL as HTTP return path to the client after successful data transmission.
Beispiel
Demomovie https://demomovie.de/cb/
RedirectHandler.jsp
4

Retrieving an ID-Card follows the Authorization Code Flow 3 given by OpenID Connect. It encompasses the following steps:
1.
Trigger point : A user has a browser session within a client’s application (RP), from where he/she initializes the identification with POSTID by clicking a button.
2.
The RP sends an Authentication Request 4 with the required ID-Card to the authorization endpoint of the POSTID system. The browser of the user is directed per HTTP-redirect to the
POSTID system.
3.
The POSTID Authentication Endpoint authenticates the user ( login ).
4.
The POSTID system shows the user all requested data ( ID-Card ).
5.
The user allows access to the requested ID-Card ( release ).
6.
The POSTID Authentication Endpoint redirects user's browser per HTTP-redirect back to the
RP ( Redirect ). The POSTID system appends a code parameter to the HTTP-redirect.
5
7.
Continuation of 6.
8.
The RP sends a token request containing the code parameter directly to the POSTID system.
6
9.
The response of the POSTID system contains the data of the ID-Card within an ID-Token.
7
10.
The RP verifies the ID-Token obtained.
8
Figure 1: Flow of retrieving an ID-Card
3 See http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
4 See http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
5 See http://openid.net/specs/openid-connect-core-1_0.html#AuthResponse
6 See http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest
7 See http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse
8 See http://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
5

POSTID uses the Nimbus-Library to analyze the OpenID requests and to generate the OpenID responses.
9 You can use the open Nimbus-Java-Library or any other library that complies with the
OpenID Connect specification.
10
POSTID uses HTTPs to ensure that the communication between all parties is encrypted.
Host
Demo- & Test-Server
(under construction)
Live Server
URL up to release 3.0 URL planned for later releases postident-demo.deutschepost.de postid-demo.deutschepost.de
postident.deutschepost.de
postid.deutschepost.de
Trigger point for retrieving an ID-Card is a user having a HTTP browser session on a client’s website where he/she is asked to identify him-/herself by prompting a HTTP-request. This request is client specific and does not yet belong to the Authorization Code Flow.
Example
Video-on-demand provider Demomovie uses POSTID as an age verification service. For this,
Demomovie includes a button on its webpage. If the user clicks on this button, he will be directed to the POSTID system for the purpose of age verification.
9 See http://connect2id.com/products/nimbus-oauth-openid-connect-sdk
10 See http://openid.net/developers/libraries/
6

Figure 2: Start of an ID-Card retrieval by the user
The authentication request must be built according to the OpenID Connect standard http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest . Request and answer of the
POSTID system will each be served via HTTP-redirects of the user’s browser.
Redirect, path and request
Send a 302 redirect response to the user’s browser. The browser will send an authentication GET request to the POSTID authorization endpoint.
Path
Use the following path to the POSTID authorization endpoint:
/api/v2/authorize
Header
The following parameters must be used to build the 302 redirect:
Parameter client_id
Description response_type POSTID implements the authorization code flow.
Hence, always use “code”.
Will be provided by DPAG. For more information see section Preconditions in this document. redirect_uri scope
Return-URI to the client’s site (RP) after successful data transfer (see Preconditions ).
Note
The redirect-URI must be the same as the one specified in the POSTID-System.
Requested ID-Card. Use the following structure to state build the request: “openid <idcard>” e.g. <idcard> := idcard2 | idcard3 | …
Note
The OpenID Connect-/OAuth standard requires the prefix “openid”. Separate prefix and ID-Card number with a space.
Character string to be generated by the client (RP) according to the OpenID Connect specification.
Example code
1001 https://demomovie.de/cb/R edirectHandler.jsp openid idcard2 cbWAQe-
PdCmmmiPz0s3PUkp72_JhR ngd0yCz-Otqv_g
7

Example
For their use case Demomovie builds the following authentication request, which is returned to the browser session as 302 HTTP redirect:
HTTP/1.1 302 Found
Location: https://<host>/api/v2/authorize?
&response_type=code
&client_id=1001
&redirect_uri=https://demomovie.de /cb/RedirectHandler.jsp
&scope=openid+idcard2
&state=cbWAQe-PdCmmmiPz0s3PUkp72_JhRngd0yCz-Otqv_g
Content-Type: text/html;charset=ISO-8859-1
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 20
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
The user's browser transforms the 302 HTTP redirect into an authentication GET request to the
POSTID authorization endpoint:
GET https://<host>/api/v2/authorize? response_type=code
&client_id=1001
&redirect_uri=http://demomovie.de/cb/RedirectHandler.jsp
&scope=openid+idcard2
&state=cbWAQe-PdCmmmiPz0s3PUkp72_JhRngd0yCz-Otqv_g
HTTP/1.1
Host: <host>
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:39.0) Gecko/20100101 Firefox/39.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Referer: https://demomovie.de /cb/RedirectHandler.jsp
Connection: keep-alive
Release by the use and redirect to the RP
The POSTID system authenticates the user and authorizes the transmission of the requested ID-Card to the relying party. The POSTID system notifies the response of the requested action, and sends the user's browser session back to the relying party.
The POSTID-Authorization-Server authenticates the User (login)
The user must login to the POSTID system using his/her POSTID credentials.
8

Figure 3: Login-Page of the POSTID-System
Display and Release of ID-Card
The POSTID system displays the requested data. The user releases the ID-Card to be transmitted to the client.
Figure 4: ID-Card-Release-Page of the POSTID-Systems
9

Redirect to the RP
The POSTID authorization server sends the user’s browser back to the relying party via HTTP redirect.
The resulting GET request contains the code parameter, which the relying party later needs to include in the token request to retrieve the ID-Card from the POSTID token endpoint.
Authentication successful
Parse and process the data according to http://openid.net/specs/openid-connect-core-
1_0.html#AuthResponse .
The POSTID system returns the following HTTP status code after successful authorization:
HTTP-Status Code
302
Notification
Found
Reason
Successful authorization
The location property in the header area contains the following parameters:
Parameter redirect_uri code state
Description
Redirect URI of the relying party after successful transmission.
Parameter to retrieve the ID-Card in the token request.
Note
The parameter code is valid for 30 days.
Character string generated by the client (RP).
Example https:// demomovie.de/cb/Redirect
Handler.jsp postid_ac_cIzWY8H%2BCVF
14LMP13EnhKmZYZ5gd%2B
8OKpDT5JeqliNsryieTHONZB
3xgDRAbzi3hdVmVnrO5Qzk
Vf7wpQYzEA%3D%3D cbWAQe-
PdCmmmiPz0s3PUkp72_JhR ngd0yCz-Otqv_g
Example:
HTTP/1.1 302 Found
Location: https:// demomovie.de/cb/RedirectHandler.jsp? code=postid_ac_cIzWY8H%2BCVF14LMP13EnhKmZYZ5gd%2B8OKpDT5JeqliNsryieTHONZB3x gDRAbzi3hdVmVnrO5QzkVf7wpQYzEA%3D%3D
&state= cbWAQe-PdCmmmiPz0s3PUkp72_JhRngd0yCz-Otqv_g
The user's web browser session is routed to the relying party via HTTP GET redirect.
Example:
GET https://demomovie.de/cb/RedirectHandler.jsp? code=postid_ac_cIzWY8H%2BCVF14LMP13EnhKmZYZ5gd%2B8OKpDT5JeqliNsryieTHONZB3x gDRAbzi3hdVmVnrO5QzkVf7wpQYzEA%3D%3D
&state=cbWAQe-PdCmmmiPz0s3PUkp72_JhRngd0yCz-Otqv_g
HTTP/1.1
Host: serernity:8080
10

User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:39.0) Gecko/20100101 Firefox/39.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Cookie: JSESSIONID=1A31529708958FAAB1F5975C4827DCC2
Connection: keep-alive
Authentication Error
A description of error handling can be find here: http://openid.net/specs/openid-connect-core-
1_0.html#AuthError .
HTTP Status Code
In case of an authentication error, the POSTID-System returns the following HTTP status code:
HTTP Status Code
302
Notification
Found
Note
Due to the redirect mechanism, there is no other status code possible.
Reason
See error list bellow
Erroneous authentication
In case the user denies the request, or the authentication procedure fails, the POSTID-System informs the client (RP) of the error by using the error code response parameters defined in section
4.1.2.1 of the OAuth 2.0 standard (see Hardt, D., “ The OAuth 2.0 Authorization Framework ,” RFC
6749, Oktober 2012).
List of possible error messages:
Error
TEMPORARILY_UNAVAILABLE
REDIRECT_URL_INVALID
REDIRECT_URL_FALSCH
Error Description
Internal error of the
POSTID system;
(database or any other service layer not available).
Authentication request without redirect URI redirect_URI of the authentication request is not compliant with the redirect_URI stored in the configuration of the relying party.
RP Handling
None, as a redirect to the relying party is not possible.
None, as a redirect to the relying party is not possible.
None, as a redirect to the relying party is not possible.
Remark
User portal shows
HTML error page.
User portal shows
HTML error page.
User portal shows
HTML error page.
11

Error
INVALID_REQUEST
INVALID_SCOPE
INVALID_SCOPE
Error Description
Invalid OpenID
Connect
Authentication
Request
The scope parameter send by the relying party is not allowed.
The requested ID-
Card is unknown or the ID-Card has been set to not available.
RP Handling
Error message according to DPAG, see next section.
Error message according to DPAG, see next section.
Error message according to DPAG, see next section.
Error message to be displayed by the relying party according to DPAG guidelines:
Remark
The request cannot be parsed by the
Nimbus library accordingly.
The request cannot be parsed by the
Nimbus library accordingly.
The request cannot be parsed by the
Nimbus library accordingly.
German: „Leider ist uns ist ein Fehler unterlaufen. Wir arbeiten bereits an der Fehlerbehebung. Bitte versuchen Sie es später noch einmal.“
English: “Unfortunately, an error has occurred. We are working to resolve this issue. Please, try it again later.“
ATTENTION: In this case the POSTID service is not to be mentioned by name!
Error parameters
According to the OpenID Connect standard (see http://openid.net/specs/openid-connect-core-
1_0.html#AuthError ) the POSTID-System uses the following error parameters in the query element of the redirection URI:
Parameter error state
Mandatory Description
Yes Error code. error_description No error_uri No
Human-readable ASCII encoded text description of the error.
URI of a web page that includes additional information about the error.
Note
Currently not supported by the POSTID-System.
Set to the value received from the client. Yes (if included in authorization request)
After the requested identity data are successfully released by the user and user’s browser are redirected to the RP, the client can build the token request.
12

Therefore a REST request to the POSTID system according to the OpenID standard (see http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest) must be executed.
Path
Obtain the required ID-Card with a HTTP POST request using the following URI:
/api/v2/token
Header/Body
Parameter
Host
Content-Type
Authorization grant_type
Description
POSTID host; see section Host
Contains: “application/x-www-formurlencoded”
Contains client_id and client_secret, both encrypted with base64: Basic BASE64
(<client_id>:< client_secret >)
Note
Client_id and client_secre are provided by the
DPAG; see section Preconditions
Contains code and redirect_uri in the following format:
“authorization_code&code=<code>&redirect_ uri=<redirect_uri>”
Note
Code is received from the POSTID system and redirect_uri is the callback URL of the relying party deposited at the POSTID system; see section Preconditions
Example postid.deutschepost.de
Basic cnAwMDE6Z2VoZWlt
See sample request below
Sample Request
POST /api/v2/token HTTP/1.1
Host: postid-deutschepost.de
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cnAwMDE6Z2VoZWlt
grant_type=authorization_code&code= postid_ac_cIzWY8H%2BCVF14LMP13EnhKmZYZ5gd%2B8OKpDT5JeqliNsryieTHONZB3xgDRAbzi3hdV mVnrO5QzkVf7wpQYzEA%3D%3D
&redirect_uri= https://demomovie.de/cb/RedirectHandler.jsp
13

Token Result
In case of success, POSTID responds with an ID Token with the following claims:
Claim iss sub aud exp iat postidcard idcard
Description
Issuer Identifier
Here: https://<host>
Subject Identifier
Here: postid_id (POSTID number)
Principal/Client
Here: client_id
Expiration time of the ID-Token
Here: iat plus 5 minutes
Time the ID-Token was created
Result data of the ID-Card 3.0/3.1
For details see corresponding section below.
Note
Will be replaced by the claim idcard
Result data of the ID-Card as of 3.11
For details see corresponding chapter below.
Example Version
„https://postident.deutschepost.de“ v0
„12345678“
„1001“
1311282330
1311281970 v1 v1 v1 v1 v0 / v1 v2
For more details regarding the ID token claims, refer to http://openid.net/specs/openid-connectcore-1_0.html#IDToken .
The received ID token must be validated according to the OpenID Connect specifications. More detailed information about validation can be found here: http://openid.net/specs/openid-connectcore-1_0.html#IDTokenValidation .
Token Error
Error cases are detailed in the OpenID standard, for more information see http://openid.net/specs/openid-connect-core-1_0.html#TokenErrorResponse .
HTTP Status Codes
HTTP status codes in case of error:
HTTP Status Code
400
Error Code
Bad Request
404
500
Not found
Internal server error
Reason
See list with possible error causes below
Wrong Path
Something unexpected went wrong in the POSTID system
14

List of possible error codes
Error
INVALID_REQUEST
INVALID_REQUEST
INVALID_REQUEST
INVALID_REQUEST
INVALID_REQUEST
Error Description Action at the RP
Side client_id not available Use the error
Erroneous client_id messages provided and/or client_secret
Authentication code not available
Data transmission expired
Data transmission does not match to client_id by DPAG, see text message below
Note
Error message to be displayed by the relying party according to DPAG guidelines:
In case of error, the token endpoint always answers with
INVALID_REQUEST, to prevent targeted spying actions to access valid client_id or their passwords. This is valid for both parameters, error and error request.
German: „Leider ist uns ein Fehler unterlaufen. Wir arbeiten bereits an der Fehlerbehebung. Bitte versuchen Sie es zu einem späteren Zeitpunkt noch einmal.“
English: “Unfortunately, an error has occurred. We are working to resolve this issue. Please, try it again later.“
ATTENTION: In this case the POSTID service is not to be mentioned by name!
Error parameters
The POSTID-System uses the following error parameters, according to the OpenID Connect standard, for more information see http://openid.net/specs/openid-connect-core-
1_0.html#TokenErrorResponse and http://tools.ietf.org/html/rfc6749 :
Parameter error
Mandatory
Yes error_description No error_uri No
Description
Error code.
Human-readable ASCII encoded text description of the error.
URI of a web page that includes additional information about the error.
Note
Not supported by POSTID.
Sample response for error “Bad Request”:
HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1 cache-control: no-store
15

pragma: no-cache
Content-Type: application/json;charset=UTF-8
Content-Length: 65
Date: Mon, 26 Oct 2015 09:44:45 GMT
Connection: close
{"error_description":"Invalid request","error":"invalid_request"}
Sample response for error “Not Found” (not specific to OpenID):
HTTP/1.1 404 Not Found
Date: Mon, 26 Oct 2015 10:02:42 GMT
Server: Apache-Coyote/1.1
Content-Type: text/html;charset=utf-8
Content-Language: en
Content-Length: 990
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
<html><head><title>Apache Tomcat/7.0.53 - Error report</title></head><body><h1>HTTP Status
404 - /oidcprovider/token</h1><hr><p><b>type</b> Status report</p><p><b>message</b>
<u>/oidcprovider/token</u></p><p><b>description</b> <u>The requested resource is not available.</u></p><hr><h3>Apache Tomcat/7.0.53</h3></body></html>
Sample response for error “Internal Server Error“ (not specific to OpenID):
HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1 cache-control: no-store pragma: no-cache
Content-Type: application/json;charset=UTF-8
Content-Length: 70
Date: Mon, 26 Oct 2015 10:00:24 GMT
Connection: close
{"error_description":"Unexpected server error","error":"server_error"}
For Authentication Requests
Generating the Request
Build the authentication request with the Nimbus classes:
/**
* Generates an OpenID Connect authentication request.
*
* @param pIdcardName Name of the ID-Card.
16

* @param pClientID
* @param pAuthenticationEndpointUri
* @param pRedirectUri
* @return AuthenticationRequestURI.
*
*/
@throws SerializeException
ClientID.
AuthenticationEndpoint.
Redirect URI.
Path.
Error when parsing the request. public static URI buildOidAuthenticationRequest(String pIdcardName , String pClientID ,
URI pAuthenticationEndpointUri , URI pRedirectUri) throws SerializeException {
// Generating a random state for subsequently matching the response
// to this request
State state = new State();
// Specify the scope
Scope scope = Scope.
parse ( "openid " + pIdcardName );
Nonce nonce = null ;
// Compose the request
AuthenticationRequest authenticationRequest = new AuthenticationRequest( pAuthenticationEndpointUri , new ResponseType(ResponseType.Value.
CODE ), scope , new ClientID( pClientID ), pRedirectUri , state , nonce );
URI authReqURI = authenticationRequest .toURI(); return authReqURI ;
}
The URI object generated by the code snippet can be used to trigger the redirect request. For instance, in case of a servlet the redirect command to the user's browser would be built as: response.sendRedirect(<generated URI>)
Parsing the Response
Parse the authentication response with the Nimbus classes:
/**
* Handles an incoming authentication callback.
*
* @param servReq
* @return
*/
ServletRequest .
Interpreted Authentication Response.
public static AuthenticationResponse handleAuthenticationCallback(HttpServletRequest servReq ) {
AuthenticationResponse response = null ;
// Parse the authorisation response from the callback URI
String requestString = servReq .getRequestURI() + "?" + servReq .getQueryString(); response = AuthenticationResponseParser.
parse (URI.
create ( requestString )); if (!
response .indicatesSuccess()) {
// The request was denied or some error may have occurred
17

AuthenticationErrorResponse errorResponse = (AuthenticationErrorResponse) response ; return errorResponse ;
}
AuthenticationSuccessResponse successResponse = (AuthenticationSuccessResponse) response ;
LOGGER .info( "AuthenticationSuccessResponse " + successResponse .toString()); return successResponse ;
}
The code required to access the ID-Card can be retrieved from the Authentication-SuccessResponse with getAuthorizationCode().
For Token Requests
Implementing the token request
To implement the token request using the Nimbus framework:
/**
* Implements a TokenRequest and provides a TokenResponse.
*
* @param pAuthorizationCode
* @return assigned AuthorizationCode
TokenResponse
*/ public static TokenResponse handleBasicTokenRequest(String pAuthorizationCode ,
HttpServletRequest pReq ) {
TokenResponse tokResp = null ;
AuthorizationCode code = new AuthorizationCode( pAuthorizationCode );
URI callback = RelayingPartyConfig .getMyRedirectUrl();
AuthorizationGrant codeGrant = new AuthorizationCodeGrant( code , callback );
// The credentials to authenticate the client at the token endpoint
ClientID clientID = new ClientID( RelayingPartyKonfig .getClientID());
Secret tokenEndpointPassword = new
Secret( RelayingPartyConfig .getTokenEndpointPassword());
ClientAuthentication clientAuth = new ClientSecretBasic( clientID , tokenEndpointPassword );
// URI des Token Providers
URI tokenEndpoint = RelayingPartyConfig .getTokenEndpointUrl();
// Erzeuge den Token Request
TokenRequest request = new TokenRequest( tokenEndpoint , clientAuth , codeGrant );
HTTPRequest lReq = request .toHTTPRequest();
HTTPResponse resp = null ; try { resp = lReq .send();
} catch (IOException e ) {
//handle Exception
} try { tokResp = OIDCTokenResponseParser.
parse ( resp );
} catch (ParseException e ) {
// handle Exception
18

} return tokResp ;
}
The ficticious class
RelyingPartyConfig
has been used in the code sample above, to demonstrate the requirements to access the local configuration.
Accessing the JWT
To access the JWT, use the token response as in the sample below:
JWT jWT = null ;
//Recognizing and displaying the error case if (!toResp.indicatesSuccess()) {
TokenErrorResponse terr = (TokenErrorResponse)toResp;
// Implementing error treatement here
} else {
// Success case
OIDCAccessTokenResponse oiDCAccessTokenResponse =
(OIDCAccessTokenResponse) tokenResponse; jWT = oiDCAccessTokenResponse.getIDToken();
}
Decrypting the JWT
Check with the JWT header, if the JWT was encrypted, and if this is the case, which key has been used.
EncryptedJWT encjwt = (EncryptedJWT) jWT ;
DirectDecrypter directDecrypter = new DirectDecrypter( RelayingPartyConfig .getEncryptionSecret());
encjwt .decrypt( directDecrypter );
// write back the decrypted JWT to jWT
jWT = encjwt .getPayload().toSignedJWT();
Checking the JWT signature
The JWT header has to be extracted again, before checking the signature
SignedJWT sjwt = (SignedJWT) jWT ;
if (MACVerifier.
SUPPORTED_ALGORITHMS .contains( headerAlg )) { verifier = new MACVerifier( RelayingPartyConfig.
getSigningSecret());
} else{
// Error treatment
}
if ( sjwt .verify( verifier )) {
// Treat success case
} else {
19

// Error treatment
}
Extract the ClaimsSet for further processing
After succesfully checking the signature, the ClaimSet can be extracted from the JWT for further processing.
ReadOnlyJWTClaimsSet claims = jWT.getJWTClaimsSet();
POSTID Release Language
As of Rel. 3.11 english
idcard2 x idcard3 x idcard4 x idcard5 x
ID-Card data are transferred in the claim idcard of the API implementation from release 3.11 on (that is v2). The ID-Card claim has the following structure:
Figure 5: UML-Diagram of the transferred ID token (grey) and ID-Card (blue)
20

Object: idcard
Claim idcard engl. idcard userData identificationD ocument
Objekt: userData
Description
ID-Card Identifier
JSON Objekt
JSON Objekt idcard
2 x x
Claim idcard engl. salutation givenName familyName nickname
Description
Salutation as selected by the user: „Frau“, „Herr“, „Mrs“,
„Mr“
All first names as part of the name in the identification document.
Surname of the user
Casual name of the user, may not be the same as the givenName; e.g. "Mike" for
"Michael". birthName above18 Above18 flag; "true" or
"false" birthDate nationality ISO-3166-1 ALPHA-3 format; e.g. „DEU“ streetAddress Street address may contain: house number, street name, post office box appendix Extended address information, e.g. c/o Muster
GmbH postalCode city country ISO-3166-1 ALPHA-3 format; e.g. “DEU” phoneNumber Country code plus phone number. Blanks are allowed and will be ignored. email Email address, e.g. michael.doe@emailprovider.
de epost E-POSTBRIEF address, e.g. michael.doe@epost.de idcard
2 x idcard
3 x x x x x o x x x idcard
4 x x idcard
3 o idcard
4 o x x o o x x x o x x x x x o idcard
5 x x x idcard
5 o x x o x x x x x x o x o x o
21

Object: identificationDocument
Claim idcard engl.
Description type 1 = Identity card
2 = Passport
3 = Residence status
4 = Provisional identity card
5 = Provisional Passport dateOfExpiry ISO 8601 format:
YYYY-MM-DD x = Claim is always included o = Value can be left empty idcard
2 idcard
3 idcard
4 idcard
5 x x
All primitive types will be delivered as string. In case a value is empty, the field will be set to null.
Sample ID-Card 02:
}
{"iss":"https://postident.deutschepost.de",
"sub":"12345678",
"aud":"1001",
"exp":1311282330,
"iat":1311281970,
"idcard":{
"idcard":"idcard2",
"userData":{
"above18":"true"}
}
Sample ID-Card 05:
{"iss":"https://postident.deutschepost.de",
"sub":"12345678",
"aud":"1001",
"exp":1311282330,
"iat":1311281970,
"idcard":{
"idcard":"idcard5",
"userData":{
"salutation":"Herr",
"givenName":"Michael John",
"familyName":"Doe",
"nickname":"Mike",
"birthName":"Müller",
"birthDate":"1953-11-30",
"nationality":"DEU",
22

"streetAddress":"Sackgasse 12",
"appendix":"c/o Meier",
"postalCode":"11122",
"city":"Sindelfingen",
"country":"DEU",
"phoneNumber":"+491707777777",
}
"email":"michael.doe@emailprovider.de",
"epost":"michael.doe@epost.de"
},
"identificationDocument":{
"type":"1",
"dateOfExpiry":"2018-10-30"}
OpenID Connect
OpenID Connect is an authorization framework controlled by the OpenID Foundation as identity layer on top of the OAuth 2.0 protocol. For more information, see http://openid.net/connect/
OAuth 2.0
OAuth 2.0 is an authorization framework that enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner, or by allowing the third party application to obtain access on its own behalf. The OAuth 2.0 framework is controlled by the IETF.
For more information, see https://tools.ietf.org/html/rfc6749
Nimbus
Nimbus is an open Java library for developing OAuth 2.0 and OpenID Connect clients and servers. For more information, see http://connect2id.com/products/nimbus-oauth-openid-connect-sdk .
JSON Web Token (JWT)
JWT is a compact, URL-safe means of representing claims to be transferred between two parties. For more information, see https://tools.ietf.org/html/rfc7519.
23