Date post: | 27-Apr-2023 |
Category: |
Documents |
Upload: | khangminh22 |
View: | 0 times |
Download: | 0 times |
Technical specifications Identity amp Authorization Management (IAM)
Mobile integration Version 10
This document is provided to you free of charge by the
eHealth platform Willebroekkaai 38
38 Quai de Willebroek
1000 BRUSSELS
All are free to circulate this document with reference to the URL source
IAM Mobile integration v100 dd 08062017 240
Table of contents
TABLE OF CONTENTS 2
1 DOCUMENT MANAGEMENT 4
11 DOCUMENT HISTORY 4
2 INTRODUCTION 5
21 GOAL OF THE SERVICE 5
22 GOAL OF THE DOCUMENT 5
23 EHEALTH DOCUMENT REFERENCES 5
24 EXTERNAL DOCUMENT REFERENCES 5
3 SUPPORT 7
31 SUPPORT IN GENERAL 7
4 GLOBAL OVERVIEW 8
41 AUTHORIZATION CODE 8
42 IMPLICIT FLOW 9
43 CLIENT CREDENTIALS 9
5 STEP-BY-STEP 10
51 TECHNICAL REQUIREMENTS 10
511 Application-level protocol 10
512 Transport Layer Security 10
52 PROCESS OVERVIEW 10
521 Registering clients with the authorization server 10
522 Environments 10
53 OPENID CONNECT FLOWS 11
531 Authorization code flow 11
532 Implicit flow 22
533 Client credentials flow 25
54 VALIDATE ACCESS TOKEN 26
55 CONSENT 28
56 TOKEN SPECIFICATION 28
561 IDToken 28
562 AccessToken 32
57 USERINFO ENDPOINT 33
58 LOGOUT 33
59 TIMEOUT AND LIFESPAN 33
IAM Mobile integration v100 dd 08062017 340
6 RISKS AND SECURITY 35
61 SECURITY 35
611 Business security 35
612 Recommendations for mobile clients 35
7 TEST AND RELEASE PROCEDURE 36
71 PROCEDURE 36
711 Initiation 36
712 Development and test procedure 36
713 Release procedure 36
714 Operational follow-up 36
8 ERROR AND FAILURE MESSAGES 37
To the attention of ldquoIT expertrdquo willing to integrate this web service
IAM Mobile integration v100 dd 08062017 440
1 Document management
11 Document history
Version Date Author Description of changes remarks
100 08062017 eHealth First version
IAM Mobile integration v100 dd 08062017 540
2 Introduction
21 Goal of the service
eHealth IAM Connect is an identity and access management solution for web applications and RESTful web services
It allows clients to request and receive information about authenticated sessions and end-users Clients of all types are supported web application clients JavaScript clients native appmobile clients
IAM Connect also allows clients to verify the identity of the end user based on the authentication performed by an authorization server
22 Goal of the document
This document is not a development or programming guide for internal applications Instead it provides functional and technical information and allows an organization to integrate and use eHealth IAM Connect
But in order to interact in a smooth homogeneous and risk controlled way with a maximum of partners eHealth partners must commit to comply with the requirements of specifications data format and release processes described in this document
Technical and business requirements must be met in order to allow the integration and validation of the eHealth service in the client application
23 eHealth document references
All the document references can be found in the technical library on the eHealth portal1 These versions or any following versions can be used for the eHealth service
ID Title Version Date
1 Glossarypdf 10 DDMMYYYY
24 External document references
All documents can be found on the internet They are available to the public but not supported by eHealth
ID Title Source Date Author
1 The OAuth 20 Authorization Framework
httpstoolsietforghtmlrfc6749
October 2012 D Hardt Ed (Microsoft)
2 JSON Web Token (JWT) httpstoolsietforghtmlrfc7519
May 2015 M Jones (Microsoft)
J Bradley (Ping Identity)
N Sakimura (NRI)
1 wwwehealthfgovbe
IAM Mobile integration v100 dd 08062017 640
3 OAuth 20 Token Introspection
httpstoolsietforghtmlrfc7662
October 2015 J Richer Ed
4 Date and Time on the Internet Timestamps
httpstoolsietforghtmlrfc3339
July 2002 G Klyne (Clearswift Corporation)
C Newman (Sun Microsystems)
5 An IANA Registry for Level of Assurance (LoA) Profiles
httpstoolsietforghtmlrfc6711
August 2012 L Johansson (NORDUNet)
6 OpenID Connect Core 10 incorporating errata set 1
httpopenidnetspecsopenid-connect-core-1_0html
8th November 2014 N Sakimura (NRI)
J Bradley (Ping Identity)
M Jones (Microsoft)
B de Medeiros (Google)
C Mortimore (Salesforce)
7 JSON Web Token (JWT) Profile for OAuth 20 Client Authentication and Authorization Grants
httpstoolsietforghtmlrfc7523
May 2015 M Jones (Microsoft)
B Campbell (Ping Identity)
C Mortimore (Salesforece)
8 Proof Key for Code Exchange by OAuth Public Clients
httpstoolsietforghtmlrfc7636
September 2015 N Sakimura (NRI)
J Bradley (Ping Identity)
N Agarwal (Google)
9 JSON Web Key (JWK) httpstoolsietforghtmlrfc7517
May 2015 N Jones (Microsoft)
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 240
Table of contents
TABLE OF CONTENTS 2
1 DOCUMENT MANAGEMENT 4
11 DOCUMENT HISTORY 4
2 INTRODUCTION 5
21 GOAL OF THE SERVICE 5
22 GOAL OF THE DOCUMENT 5
23 EHEALTH DOCUMENT REFERENCES 5
24 EXTERNAL DOCUMENT REFERENCES 5
3 SUPPORT 7
31 SUPPORT IN GENERAL 7
4 GLOBAL OVERVIEW 8
41 AUTHORIZATION CODE 8
42 IMPLICIT FLOW 9
43 CLIENT CREDENTIALS 9
5 STEP-BY-STEP 10
51 TECHNICAL REQUIREMENTS 10
511 Application-level protocol 10
512 Transport Layer Security 10
52 PROCESS OVERVIEW 10
521 Registering clients with the authorization server 10
522 Environments 10
53 OPENID CONNECT FLOWS 11
531 Authorization code flow 11
532 Implicit flow 22
533 Client credentials flow 25
54 VALIDATE ACCESS TOKEN 26
55 CONSENT 28
56 TOKEN SPECIFICATION 28
561 IDToken 28
562 AccessToken 32
57 USERINFO ENDPOINT 33
58 LOGOUT 33
59 TIMEOUT AND LIFESPAN 33
IAM Mobile integration v100 dd 08062017 340
6 RISKS AND SECURITY 35
61 SECURITY 35
611 Business security 35
612 Recommendations for mobile clients 35
7 TEST AND RELEASE PROCEDURE 36
71 PROCEDURE 36
711 Initiation 36
712 Development and test procedure 36
713 Release procedure 36
714 Operational follow-up 36
8 ERROR AND FAILURE MESSAGES 37
To the attention of ldquoIT expertrdquo willing to integrate this web service
IAM Mobile integration v100 dd 08062017 440
1 Document management
11 Document history
Version Date Author Description of changes remarks
100 08062017 eHealth First version
IAM Mobile integration v100 dd 08062017 540
2 Introduction
21 Goal of the service
eHealth IAM Connect is an identity and access management solution for web applications and RESTful web services
It allows clients to request and receive information about authenticated sessions and end-users Clients of all types are supported web application clients JavaScript clients native appmobile clients
IAM Connect also allows clients to verify the identity of the end user based on the authentication performed by an authorization server
22 Goal of the document
This document is not a development or programming guide for internal applications Instead it provides functional and technical information and allows an organization to integrate and use eHealth IAM Connect
But in order to interact in a smooth homogeneous and risk controlled way with a maximum of partners eHealth partners must commit to comply with the requirements of specifications data format and release processes described in this document
Technical and business requirements must be met in order to allow the integration and validation of the eHealth service in the client application
23 eHealth document references
All the document references can be found in the technical library on the eHealth portal1 These versions or any following versions can be used for the eHealth service
ID Title Version Date
1 Glossarypdf 10 DDMMYYYY
24 External document references
All documents can be found on the internet They are available to the public but not supported by eHealth
ID Title Source Date Author
1 The OAuth 20 Authorization Framework
httpstoolsietforghtmlrfc6749
October 2012 D Hardt Ed (Microsoft)
2 JSON Web Token (JWT) httpstoolsietforghtmlrfc7519
May 2015 M Jones (Microsoft)
J Bradley (Ping Identity)
N Sakimura (NRI)
1 wwwehealthfgovbe
IAM Mobile integration v100 dd 08062017 640
3 OAuth 20 Token Introspection
httpstoolsietforghtmlrfc7662
October 2015 J Richer Ed
4 Date and Time on the Internet Timestamps
httpstoolsietforghtmlrfc3339
July 2002 G Klyne (Clearswift Corporation)
C Newman (Sun Microsystems)
5 An IANA Registry for Level of Assurance (LoA) Profiles
httpstoolsietforghtmlrfc6711
August 2012 L Johansson (NORDUNet)
6 OpenID Connect Core 10 incorporating errata set 1
httpopenidnetspecsopenid-connect-core-1_0html
8th November 2014 N Sakimura (NRI)
J Bradley (Ping Identity)
M Jones (Microsoft)
B de Medeiros (Google)
C Mortimore (Salesforce)
7 JSON Web Token (JWT) Profile for OAuth 20 Client Authentication and Authorization Grants
httpstoolsietforghtmlrfc7523
May 2015 M Jones (Microsoft)
B Campbell (Ping Identity)
C Mortimore (Salesforece)
8 Proof Key for Code Exchange by OAuth Public Clients
httpstoolsietforghtmlrfc7636
September 2015 N Sakimura (NRI)
J Bradley (Ping Identity)
N Agarwal (Google)
9 JSON Web Key (JWK) httpstoolsietforghtmlrfc7517
May 2015 N Jones (Microsoft)
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 340
6 RISKS AND SECURITY 35
61 SECURITY 35
611 Business security 35
612 Recommendations for mobile clients 35
7 TEST AND RELEASE PROCEDURE 36
71 PROCEDURE 36
711 Initiation 36
712 Development and test procedure 36
713 Release procedure 36
714 Operational follow-up 36
8 ERROR AND FAILURE MESSAGES 37
To the attention of ldquoIT expertrdquo willing to integrate this web service
IAM Mobile integration v100 dd 08062017 440
1 Document management
11 Document history
Version Date Author Description of changes remarks
100 08062017 eHealth First version
IAM Mobile integration v100 dd 08062017 540
2 Introduction
21 Goal of the service
eHealth IAM Connect is an identity and access management solution for web applications and RESTful web services
It allows clients to request and receive information about authenticated sessions and end-users Clients of all types are supported web application clients JavaScript clients native appmobile clients
IAM Connect also allows clients to verify the identity of the end user based on the authentication performed by an authorization server
22 Goal of the document
This document is not a development or programming guide for internal applications Instead it provides functional and technical information and allows an organization to integrate and use eHealth IAM Connect
But in order to interact in a smooth homogeneous and risk controlled way with a maximum of partners eHealth partners must commit to comply with the requirements of specifications data format and release processes described in this document
Technical and business requirements must be met in order to allow the integration and validation of the eHealth service in the client application
23 eHealth document references
All the document references can be found in the technical library on the eHealth portal1 These versions or any following versions can be used for the eHealth service
ID Title Version Date
1 Glossarypdf 10 DDMMYYYY
24 External document references
All documents can be found on the internet They are available to the public but not supported by eHealth
ID Title Source Date Author
1 The OAuth 20 Authorization Framework
httpstoolsietforghtmlrfc6749
October 2012 D Hardt Ed (Microsoft)
2 JSON Web Token (JWT) httpstoolsietforghtmlrfc7519
May 2015 M Jones (Microsoft)
J Bradley (Ping Identity)
N Sakimura (NRI)
1 wwwehealthfgovbe
IAM Mobile integration v100 dd 08062017 640
3 OAuth 20 Token Introspection
httpstoolsietforghtmlrfc7662
October 2015 J Richer Ed
4 Date and Time on the Internet Timestamps
httpstoolsietforghtmlrfc3339
July 2002 G Klyne (Clearswift Corporation)
C Newman (Sun Microsystems)
5 An IANA Registry for Level of Assurance (LoA) Profiles
httpstoolsietforghtmlrfc6711
August 2012 L Johansson (NORDUNet)
6 OpenID Connect Core 10 incorporating errata set 1
httpopenidnetspecsopenid-connect-core-1_0html
8th November 2014 N Sakimura (NRI)
J Bradley (Ping Identity)
M Jones (Microsoft)
B de Medeiros (Google)
C Mortimore (Salesforce)
7 JSON Web Token (JWT) Profile for OAuth 20 Client Authentication and Authorization Grants
httpstoolsietforghtmlrfc7523
May 2015 M Jones (Microsoft)
B Campbell (Ping Identity)
C Mortimore (Salesforece)
8 Proof Key for Code Exchange by OAuth Public Clients
httpstoolsietforghtmlrfc7636
September 2015 N Sakimura (NRI)
J Bradley (Ping Identity)
N Agarwal (Google)
9 JSON Web Key (JWK) httpstoolsietforghtmlrfc7517
May 2015 N Jones (Microsoft)
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 440
1 Document management
11 Document history
Version Date Author Description of changes remarks
100 08062017 eHealth First version
IAM Mobile integration v100 dd 08062017 540
2 Introduction
21 Goal of the service
eHealth IAM Connect is an identity and access management solution for web applications and RESTful web services
It allows clients to request and receive information about authenticated sessions and end-users Clients of all types are supported web application clients JavaScript clients native appmobile clients
IAM Connect also allows clients to verify the identity of the end user based on the authentication performed by an authorization server
22 Goal of the document
This document is not a development or programming guide for internal applications Instead it provides functional and technical information and allows an organization to integrate and use eHealth IAM Connect
But in order to interact in a smooth homogeneous and risk controlled way with a maximum of partners eHealth partners must commit to comply with the requirements of specifications data format and release processes described in this document
Technical and business requirements must be met in order to allow the integration and validation of the eHealth service in the client application
23 eHealth document references
All the document references can be found in the technical library on the eHealth portal1 These versions or any following versions can be used for the eHealth service
ID Title Version Date
1 Glossarypdf 10 DDMMYYYY
24 External document references
All documents can be found on the internet They are available to the public but not supported by eHealth
ID Title Source Date Author
1 The OAuth 20 Authorization Framework
httpstoolsietforghtmlrfc6749
October 2012 D Hardt Ed (Microsoft)
2 JSON Web Token (JWT) httpstoolsietforghtmlrfc7519
May 2015 M Jones (Microsoft)
J Bradley (Ping Identity)
N Sakimura (NRI)
1 wwwehealthfgovbe
IAM Mobile integration v100 dd 08062017 640
3 OAuth 20 Token Introspection
httpstoolsietforghtmlrfc7662
October 2015 J Richer Ed
4 Date and Time on the Internet Timestamps
httpstoolsietforghtmlrfc3339
July 2002 G Klyne (Clearswift Corporation)
C Newman (Sun Microsystems)
5 An IANA Registry for Level of Assurance (LoA) Profiles
httpstoolsietforghtmlrfc6711
August 2012 L Johansson (NORDUNet)
6 OpenID Connect Core 10 incorporating errata set 1
httpopenidnetspecsopenid-connect-core-1_0html
8th November 2014 N Sakimura (NRI)
J Bradley (Ping Identity)
M Jones (Microsoft)
B de Medeiros (Google)
C Mortimore (Salesforce)
7 JSON Web Token (JWT) Profile for OAuth 20 Client Authentication and Authorization Grants
httpstoolsietforghtmlrfc7523
May 2015 M Jones (Microsoft)
B Campbell (Ping Identity)
C Mortimore (Salesforece)
8 Proof Key for Code Exchange by OAuth Public Clients
httpstoolsietforghtmlrfc7636
September 2015 N Sakimura (NRI)
J Bradley (Ping Identity)
N Agarwal (Google)
9 JSON Web Key (JWK) httpstoolsietforghtmlrfc7517
May 2015 N Jones (Microsoft)
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 540
2 Introduction
21 Goal of the service
eHealth IAM Connect is an identity and access management solution for web applications and RESTful web services
It allows clients to request and receive information about authenticated sessions and end-users Clients of all types are supported web application clients JavaScript clients native appmobile clients
IAM Connect also allows clients to verify the identity of the end user based on the authentication performed by an authorization server
22 Goal of the document
This document is not a development or programming guide for internal applications Instead it provides functional and technical information and allows an organization to integrate and use eHealth IAM Connect
But in order to interact in a smooth homogeneous and risk controlled way with a maximum of partners eHealth partners must commit to comply with the requirements of specifications data format and release processes described in this document
Technical and business requirements must be met in order to allow the integration and validation of the eHealth service in the client application
23 eHealth document references
All the document references can be found in the technical library on the eHealth portal1 These versions or any following versions can be used for the eHealth service
ID Title Version Date
1 Glossarypdf 10 DDMMYYYY
24 External document references
All documents can be found on the internet They are available to the public but not supported by eHealth
ID Title Source Date Author
1 The OAuth 20 Authorization Framework
httpstoolsietforghtmlrfc6749
October 2012 D Hardt Ed (Microsoft)
2 JSON Web Token (JWT) httpstoolsietforghtmlrfc7519
May 2015 M Jones (Microsoft)
J Bradley (Ping Identity)
N Sakimura (NRI)
1 wwwehealthfgovbe
IAM Mobile integration v100 dd 08062017 640
3 OAuth 20 Token Introspection
httpstoolsietforghtmlrfc7662
October 2015 J Richer Ed
4 Date and Time on the Internet Timestamps
httpstoolsietforghtmlrfc3339
July 2002 G Klyne (Clearswift Corporation)
C Newman (Sun Microsystems)
5 An IANA Registry for Level of Assurance (LoA) Profiles
httpstoolsietforghtmlrfc6711
August 2012 L Johansson (NORDUNet)
6 OpenID Connect Core 10 incorporating errata set 1
httpopenidnetspecsopenid-connect-core-1_0html
8th November 2014 N Sakimura (NRI)
J Bradley (Ping Identity)
M Jones (Microsoft)
B de Medeiros (Google)
C Mortimore (Salesforce)
7 JSON Web Token (JWT) Profile for OAuth 20 Client Authentication and Authorization Grants
httpstoolsietforghtmlrfc7523
May 2015 M Jones (Microsoft)
B Campbell (Ping Identity)
C Mortimore (Salesforece)
8 Proof Key for Code Exchange by OAuth Public Clients
httpstoolsietforghtmlrfc7636
September 2015 N Sakimura (NRI)
J Bradley (Ping Identity)
N Agarwal (Google)
9 JSON Web Key (JWK) httpstoolsietforghtmlrfc7517
May 2015 N Jones (Microsoft)
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 640
3 OAuth 20 Token Introspection
httpstoolsietforghtmlrfc7662
October 2015 J Richer Ed
4 Date and Time on the Internet Timestamps
httpstoolsietforghtmlrfc3339
July 2002 G Klyne (Clearswift Corporation)
C Newman (Sun Microsystems)
5 An IANA Registry for Level of Assurance (LoA) Profiles
httpstoolsietforghtmlrfc6711
August 2012 L Johansson (NORDUNet)
6 OpenID Connect Core 10 incorporating errata set 1
httpopenidnetspecsopenid-connect-core-1_0html
8th November 2014 N Sakimura (NRI)
J Bradley (Ping Identity)
M Jones (Microsoft)
B de Medeiros (Google)
C Mortimore (Salesforce)
7 JSON Web Token (JWT) Profile for OAuth 20 Client Authentication and Authorization Grants
httpstoolsietforghtmlrfc7523
May 2015 M Jones (Microsoft)
B Campbell (Ping Identity)
C Mortimore (Salesforece)
8 Proof Key for Code Exchange by OAuth Public Clients
httpstoolsietforghtmlrfc7636
September 2015 N Sakimura (NRI)
J Bradley (Ping Identity)
N Agarwal (Google)
9 JSON Web Key (JWK) httpstoolsietforghtmlrfc7517
May 2015 N Jones (Microsoft)
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 740
3 Support
31 Support in general
For issues in production only
eHealth ContactCenter
Phone 02788 51 55
Mail supportehealthfgovbe
Contact Form
o httpswwwehealthfgovbenlneem-contact-op-met-de-openbare-instelling-eHealth-platform (Dutch)
o httpswwwehealthfgovbefrcontactez-institution-publique-plate-forme-eHealth (French)
FOR PARTNERS AND SOFTWARE DEVELOPERS ONLY
For business issues please contact infoehealthfgovbe
For technical issues in production please contact supportehealthfgovbe or call 02788 51 55
For technical issues in acceptance please contact Integration-supportehealthfgovbe
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 840
4 Global overview
IAM Connect provides authorization flows for various needs You can find a graphic description of the supported flows below You can find technical information about these flows in section 53
41 Authorization code
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 940
42 Implicit flow
Flow designed for client-side application The client is in many cases the web browser Used with mobile apps or web applications (running on userrsquos device)
43 Client credentials
Flow designed for client requesting access to protected resources under the control of the client (the client is also the resource owner)
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1040
5 Step-by-step
51 Technical requirements
511 Application-level protocol
The endpoints and methods described hereafter all use HTTP as application-level protocol
512 Transport Layer Security
Client applications MUST use TLS (ie HTTPS) communication with the authorization and resource endpoints to ensure protection of credentials and access tokens
52 Process overview
This process describes how to use eHealth IAM Connect to access REST services for the eHealth domain eHealth divides clients and services into security realms Each client or service needs to be registered in a realm Clients and services that need to connect with one another need to be defined in the same realm
521 Registering clients with the authorization server
The registration procedure can be divided in two steps
Register the realm
Register the clients within the realm
If the client must be added into an existing realm use the client registration form If the realm does not exist use the realm registration form
522 Environments
The following table describes the base URLs of the endpoints in each environment The URLs described in later sections are relative to these base URLs
Environment Endpoint base URL
Integration httpsapi-intehealthfgovbeauth
Acceptance httpsapi-acptehealthfgovbeauth
Production httpsapiehealthfgovbeauth
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1140
53 OpenID Connect flows
531 Authorization code flow
The authorization code flow offers more security than the implicit flow as tokens are not directly sent to the client application
The OpenID Connect protocol in abstract follows steps below
1 The client sends (GET) a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends the end-user back to the client with an authorization code 5 The client requests (POST) a response using the authorization code at the token endpoint 6 The client receives a response (POST) that contains an IDToken and AccessToken in the response body
53111 The client validates the IDToken
The URL depends on the realm for which the token is requested
The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Token endpoint token_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttoken
Authentication request
531211 Input arguments
Endpoint Authentication endpoint
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client Identifier valid at the Authorization Server
response_type MANDATORY Value MUST contain ldquocoderdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider (Simple String Comparison) When using this flow the redirection URI SHOULD use the https scheme however
it MAY use the http scheme provided that the Client Type is confidential as defined in
Section 21 of OAuth 20 and provided the AuthorizationServer allows the use of http Redirection URIs in this case The redirection URI MAY use an alternate scheme such as one that is intended to identify a callback into a native application The redirection URI MAY use an alternate scheme such as one that is intended to identify a call back into a native application
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1240
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification2)
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53122 Output arguments (success)
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Code REQUIRED The authorization code generated by the authorization server The client MUST NOT use the authorization code more than once The authorization code is bound to the client identifier and redirection URI
State REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
531221 Authentication response validation
When using the Authorization Code Flow the Client MUST validate the response according to RFC 6749 especially Sections 412 and 1012
53123 Output arguments (error)
HTTP status code 302 Found
If the resource owner does not grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
Error An error code
error_description Human-readable description of the error
State The exact value initially received from the client
The list of error can be found in section 8
2 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1340
Token endpoint
The token endpoint is used to obtain tokens Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used The token endpoint may also be used to obtain new access tokens when they expire
To obtain an access token an ID Token and optionally a refresh token the client sends a token request to the token endpoint to obtain a token response as described in Section 32 of OAuth 20 (RFC6749)
The refresh token can be used just once
A new refresh token will be delivered upon successful renewal of the accessToken
53131 Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant (in the form of an authorization code) to the Token Endpoint using the grant_type value authorization_code as described in Section 413 of OAuth 20 (RFC6749)
If the client is a confidential client then it MUST authenticate to the token endpoint using the authentication method registered for its client_id as described in Section 9 of OpenID Connect Core 103
Field name Description
grant_type MANDATORY Value MUST be set to ldquoauthorization_coderdquo
code MANDATORY The authorization code received from the authorization server
redirect_uri MANDATORY if the redirect_uri parameter was included in the authorization request Their values MUST be identical
client_id MANDATORY if the client is not authenticating with the authorization_server
53132 Input arguments for Refresh Token request
Endpoint Token endpoint
HTTP method POST
Field name Description
grant_type MANDATORY Value MUST be set to ldquorefresh_tokenrdquo
refresh_token MANDATORY The refresh token issued to the client
scope OPTIONAL The scope of the access request The requested scope MUST NOT include any scope not originally granted by the resource owner If the scope is omitted it is treated as equal to the scope originally granted by the resource owner
53133 Output arguments for AccessRefresh Token (success)
HTTP status code 200 OK
3 httpopenidnetspecsopenid-connect-core-1_0htmlClientAuthentication
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1440
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY The access token issued by the authorization server
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
scope The scope of the access token
OPTIONAL if identical to the scope requested by the client REQUIRED otherwise
531331 ID Token validation
See Sections 31374 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
531332 Access Token validation
If the ID Token contains an at_hash Claim the client MUST use it to validate the access token as described in section 31385 of the OpenID Connect Core 10 specification
53134 Output arguments for AccessRefresh Token (error)
HTTP status code 400 (Bad Request) (unless specified otherwise)
Field name Description
error MANDATORY An error code
error_description OPTIONAL Human-readable description of the error
error_uri OPTIONAL A URI identifying a human-readable web page with information about the error used to provide the client developer with additional information about the error
The list of errors can be found in section 8
Example
GET authrealms[realm id]protocolopenid-connectauth
Request Headers
Host localhost8080
Referer httplocalhost8000
Request DATA
4 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
5 httpopenidnetspecsopenid-connect-core-1_0htmlCodeFlowTokenValidation
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1540
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=2c988c4b-0fb9-4678-89b0-4de60ba44dbbamp
nonce=51ccca50-2e08-4fb9-8374-beb09df2eba3amp
response_mode=fragmentamp
response_type=codeamp
scope=openid
Response Headers
HTTP11 302 Found
---------------------------------------------------------
GET redirect_fragment=2Fmain
Request Headers
Host localhost8000
User-Agent Mozilla50 (Windows NT 61 WOW64 rv510) Gecko20100101 Firefox510
Accept texthtmlapplicationxhtml+xmlapplicationxmlq=09q=08
Accept-Language nlen-USq=07enq=03
Accept-Encoding gzip deflate
Connection keep-alive
Upgrade-Insecure-Requests 1
Request DATA
state=234a37a1-9cb3-42b6-868c-c6b13d351c96amp
code=OTlZYsQ9bTZrdR78O3ijXSsHJV9agZ3dG4hqz2Jgu4c9ff864ad-145d-459f-8d42-bc7c1c16b48a
Response Headers
HTTP11 200 OK
---------------------------------------------------------
POST authrealms[realm id]protocolopenid-connecttoken
Request Headers
Host localhost8080
Referer httplocalhost8000
origin httplocalhost8000
Request DATA
code=uFy-rrFCc8b4InD7TSu9vfZfsrSQ6EBKdds8bmEVBgY3c13b729-d889-4392-8bea-af7839bdf5bb
grant_type=authorization_code
client_id=tutorial-frontend
redirect_uri=httplocalhost8000
Response Headers
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1640
HTTP11 200 OK
Content-Type applicationjson
Content-Length 4105
Response DATA
access_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI2NDAxZGM3Mi02MDkwLTQ1MDgtYjEwYy0zOWMyYTJkMjY4NTAiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjIxYzgwNWFjLTJmYTctNGQxMC1hNDYwLTFmNWVlYzA3YTFlNiIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQTotVCIyxwF3ef1G85Vr_8vZvTp4tE1rrr_2GaamLmODsIIYukuIEPKHmJlkgXvkQUo8AdkUnbr9iLsm1JrmFBPbahyhMJeyvK0pPFqNZxTBxBRQAWjn0oDu7PHFz23Rnur9__kCdlnEZhUFf71EQD8_31mGlEL5FLTtOPf6oThykiBCnTEbp4oPmRPvz06TpI0_iw2mbRnV2nmvQmvq7HXNdO_mrM9THd5gGv1zXmGzRrB1Vpu895mZBbYANg5La6NU0-ymijWhksB_i0jrLqkb0lcJqbsf3n4GQx-q5S9TbdDT9F7PIU53SyBmYutB8F9ZcE3bLQthBlaivR0Ky2Q
expires_in300
refresh_expires_in1800
refresh_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIyYWIwNGU5My03MGI1LTRjZmItOTA3Yy03YzcyZDMyZWZiZTUiLCJleHAiOjE0ODYxMzAyOTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InR1dG9yaWFsLWZyb250ZW5kIiwibm9uY2UiOiIyMWM4MDVhYy0yZmE3LTRkMTAtYTQ2MC0xZjVlZWMwN2ExZTYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiOWZlODlkNS1mMDVjLTRiMDQtOTczYS00OTk0MTc1MWMwN2MiLCJjbGllbnRfc2Vzc2lvbiI6IjYxOTIyMTVhLTNmMWEtNGU3My1hNmNjLWEzY2E5NjQzMzY5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJtYW5hZ2VyIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19fUy6-m0nEWsc-VyS-MbNZMsFQfx0VgOCvOvA3PI3Et8qYAYgcy1zz_Uk6ygVByxVt9AMGyZ3JvlZxl01IelKrCjQGkSbJx6RbMjnhqVgaQLVFWXFo6z2LFZRAow71_-r9T3DXqWV1g6gOoZ0Pyhj6j_0N7Vc6MloERhq5VnXlZHGNyDrEZrTTExa4lHjQ556hMzYhjkb-3m9C0NFKrrvCssxMizC7r2MqHTZ-SEqji3KAbW19koSbHeGoeTfccfi8XDGTBH0vt3Bn0Ep8RUc4fbwjgZh9qmD1ycnsu8qb2TPy3X068Xk0ZDtowYSArp4CpGxVyROB1Wn5PuK8wbfFw
token_typebearer
id_tokeneyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiI5OTY1ZDg0NS0wOGZjLTQ2M2EtODc3My1kOTBkZDhkNmIyMDYiLCJleHAiOjE0ODYxMjg3OTksIm5iZiI6MCwiaWF0IjoxNDg2MTI4NDk5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiMjFjODA1YWMtMmZhNy00ZDEwLWE0NjAtMWY1ZWVjMDdhMWU2IiwiYXV0aF90aW1lIjoxNDg2MTI4NDk5LCJzZXNzaW9uX3N0YXRlIjoiYjlmZTg5ZDUtZjA1Yy00YjA0LTk3M2EtNDk5NDE3NTFjMDdjIiwiYWNyIjoiMSIsInBlcnNvbiI6eyJzc2luIjoiNzYxMjA5MDI1MjcifSwibmFtZSI6IkZyZWRlcmlrIExpYmVydCIsInByZWZlcnJlZF91c2VybmFtZSI6IjZmZTg4MmJhLTNlMDItNDczOS05MWRhLTU4YjZiN2QwYTQ4NSIsImdpdmVuX25hbWUiOiJGcmVkZXJpayIsImZhbWlseV9uYW1lIjoiTGliZXJ0In0Q2hj5L5vyau7ztgSMnbA9E65rSg1bs3E1sqEtRQumLKOqD3FoYvSXvARK5kvZN4wCUWEarYO82boosUS7P89rPQNDIq-l9Mx7wCOqh3c0q8c_1Lb5IJ5o2MwQUhG0soFOpx3qD92siG9gKD_vHjHifZoJGG7t9YLkvf2vI3P5IjdvxrA3tZUlNtHuWwnH0FzovSS8Xi_wYyZV8nwZ09vyoFgSapNZQoqFPiJPiXO2Jhy-larI0hu3-tGbT35pXTfz8UxILeJDNuElq6_Cv6Uyn8qPmHE1dnpkxNESbeSq5zU-ZicVWzQ5C_neMSzM6REntExv9ud_tWB-IdylMhtig
not-before-policy1486050488
session_stateb9fe89d5-f05c-4b04-973a-49941751c07c
---------------------------------------------------------
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1740
GET authrealms[realm id]account
Request Headers
Host localhost8080
Accept applicationjson
Authorization bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiIwNWQ2YmNmNC0zNmI1LTQ4YzgtOTQ5MC0yNThjZjFkMzc0ZjgiLCJleHAiOjE0ODYxMzAxNDYsIm5iZiI6MCwiaWF0IjoxNDg2MTI5ODQ2LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6IjUxY2NjYTUwLTJlMDgtNGZiOS04Mzc0LWJlYjA5ZGYyZWJhMyIsImF1dGhfdGltZSI6MTQ4NjEyODQ5OSwic2Vzc2lvbl9zdGF0ZSI6ImI5ZmU4OWQ1LWYwNWMtNGIwNC05NzNhLTQ5OTQxNzUxYzA3YyIsImFjciI6IjAiLCJjbGllbnRfc2Vzc2lvbiI6IjNjMTNiNzI5LWQ4ODktNDM5Mi04YmVhLWFmNzgzOWJkZjViYiIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQhK_PKfMpHnst_ADn251xkCN3P0JwwVim5kOJMV4waOdwKd2-cfN4NAG9i9h-KHoCnJP3ofMa5NEN-s7_HoSioBSa2X3wt-kUiDGuiZ3pQrMKv20J_en66FztJvYbcAoTFJUFucqnPzdJ-q9mVCfI-X-bLqZGtMSbVA1rxdAPS4Wx_dRu_xcmdL20Ma3RpW36v2iO-XiekjHdbTFeFDG4aayyYxrkllotxRYdy8clay61MNSHVKm0avM2JWsJTWe-5Az-tufEr2BOZIr9dgKLWozpVb7iLscZBEJWV7B1wWzhrbhygsHa6iSVHk1WbcUWaymceJqSKMaj1w5MgHu59Q
Referer httplocalhost8000
origin httplocalhost8000
Response Headers
HTTP11 200 OK
Content-Type applicationjson
Content-Length 792
Response DATA
idee51caaf-9680-42e7-bbe4-bdcb145711b9
createdTimestamp1486127148882
username6fe882ba-3e02-4739-91da-58b6b7d0a485
enabledtrue
totpfalse
emailVerifiedfalse
firstNameJohn
lastNameDoe
attributes
organizationId[0809394427]
ssin[12345678901]
role[user]
organizationName[PLATE-FORME EHEALTH]
email[do_not_replyehealthfgovbe]
disableableCredentialTypes[]
requiredActions[]
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1840
JWT
PAYLOAD access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD refresh_token
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 1940
jti 2ab04e93-70b5-4cfb-907c-7c72d32efbe5
exp 1486130299
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Refresh
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 0
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
view-profile
]
PAYLOAD id_token
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2040
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
PAYLOAD bearer token
jti 05d6bcf4-36b5-48c8-9490-258cf1d374f8
exp 1486130146
nbf 0
iat 1486129846
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 51ccca50-2e08-4fb9-8374-beb09df2eba3
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 0
client_session 3c13b729-d889-4392-8bea-af7839bdf5bb
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
]
resource_access
account
roles [
manage-account
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2140
view-profile
]
person
ssin 12345678901
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2240
532 Implicit flow
The implicit flow is used to obtain access tokens (it does not provide refresh tokens) and is optimized for public clients known to operate a particular redirection URI These clients are typically implemented in a browser using a scripting language (JavaScript for example)
Unlike the authorization code flow in which the client makes separate requests for authorization and for an access token the client receives the access token as the result of the authorization request
OpenID Connect 10 is a simple identity layer on top of the OAuth 20 protocol It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner
The OpenID Connect protocol in abstract follows steps below
1 The client sends a request to the authorization server 2 The authorization server authenticates the end-user (if he doesnrsquot have an active session yet) 3 The authorization server obtains end-user consentauthorization (if he hasnrsquot given his consent yet) 4 The authorization server sends an ID token and usually an access token to the client 5 The client validates the IDToken 6 The client can send a request with the access token to the UserInfo endpoint
The URL depends on the realm for which the token is requested The URL can be retrieved using the well-known endpoints
Authentication endpoint authorization_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectauth
Authentication request
53211 Input arguments
HTTP method GET
The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the applicationx-www-form-urlencoded format
Field name Description
client_id MANDATORY Client identifier valid at the authorization server
response_type MANDATORY Value MUST contain ldquoid_tokenrdquo
If response should have an id_token and an access token the value MUST be ldquotoken id_tokenrdquo
scope MANDATORY Space-delimited list of scopes of the access request MUST contain ldquoopenidrdquo scope
redirect_uri MANDATORY Redirection URI to which the response will be sent This URI MUST exactly match one of the redirection URI values for the client pre-registered at the OpenID Provider When using this flow the redirection URI MUST NOT use the http scheme unless the client is a native application in which case it MAY use the ldquohttprdquo scheme with ldquolocalhostrdquo as the hostname
nonce MANDATORY String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through unmodified from the authentication request to the ID Token Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values (for more information see OpenID Connect Core 10 specification6)
6 httpopenidnetspecsopenid-connect-core-1_0htmlNonceNotes
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2340
state RECOMMENDED Opaque value used to maintain state between the request and the call back Typically Cross-Site Request Forgery (CSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
53212 Output arguments
HTTP status code 302 Found
If the resource owner grants the access request the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
access_token Access Token This is returned unless the response_type value used is id_token
token_type MANDATORY Will always be ldquobearerrdquo
id_token MANDATORY ID Token
expires_in MANDATORY The lifetime in seconds of the access token
scope MANDATORY Access token scope
state OAuth 20 state value REQUIRED if the state parameter is present in the authorization request Clients MUST verify that the state value is equal to the value of state parameter in the authorization request
The ID Token is represented by an RFC 7519 JSON Web Token (JWT) whose payload is described in section 56
532121 ID Token Validation
See Sections 3137 7and 322118 of the OpenID Connect Core 10 specification for requirements regarding client-side validation of ID Tokens Clients MUST validate ID Tokens
532122 Access Token validation
See Sections 32299 of the OpenIDConnect Core 10 specification for requirements regarding client-side validation of Access Tokens Clients MUST validate Access Tokens
53213 Output arguments (error)
HTTP status code 302 Found
If the resource owner doesnrsquot grant the access request the authorization server issues an error and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the applicationx-www-form-urlencoded format
Field name Description
error An error code See section Error and failure message
error_description Human-readable description of the error
7 httpsopenidnetspecsopenid-connect-core-1_0htmlIDTokenValidation
8 httpsopenidnetspecsopenid-connect-core-1_0htmlImplicitIDTValidation
9 httpopenidnetspecsopenid-connect-core-1_0htmlImplicitTokenValidation
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2440
state The exact value initially received from the client
The list of error can be found in section 8
53214 Example GET authrealms[realm id]protocolopenid-connectauth
client_id=tutorial-frontendamp
redirect_uri=http3A2F2Flocalhost3A80002Famp
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
nonce=d7205b86-106c-4051-af2b-1456ccb93422amp
response_mode=fragmentamp
response_type=id_token20tokenamp
scope=openid
---------------------------------------------------------
httplocalhost8000
state=8157b796-90bc-43d0-8c53-21eebacbaa3aamp
id_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkYTJhYzA2MS03MDAzLTRhNjctYWQ2ZS03ZTg2YTVlMDg4YzciLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiSUQiLCJhenAiOiJ0dXRvcmlhbC1mcm9udGVuZCIsIm5vbmNlIjoiZDcyMDViODYtMTA2Yy00MDUxLWFmMmItMTQ1NmNjYjkzNDIyIiwiYXV0aF90aW1lIjoxNDg2MTM0MTk4LCJzZXNzaW9uX3N0YXRlIjoiZDk3NTVkYTUtNzU0OS00MGQyLTkwYjMtOWUwMjA4MTNmNGFjIiwiYXRfaGFzaCI6ImYtbVRPX1pSUk9oWWRSYkxhaEgxdlEiLCJhY3IiOiIxIiwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQXpizfMXCEmOyreGQeFBMpysSzPYUpr-csDkJSEVhlHFUMO5yfLFKvp-NpL8PR5izOug9xtRkjV0brqfNqZSNisVtYGDh2Pnbs-XW5Y1f4HKojRSutvHK3TDIRx5NHlKTtoMIx7-HC_8iuP_ezoLPDVUoYpsP9wu5J9Nr70zCHgotCPpnIXWDdVPjT1p_kumVF_IEBoq1c-veTdjviPnc0VqT4UXI6prq-FUT4zM0v9bvOWSFujVF5M7buZKpwn1rvxCCCKS0P1F6Ticx69x6w2v2mduBKMOxhTZqUyp0JgweR7J8ByQSpek8Irbb06RoRAEeXz3IS-OTmZcE_8n5ogamp
access_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKVUNoTEVnZkYzNjBXRWg0dzJ4OVFneEhqamhYUzN6Y0gyLW5helQ1clNnIn0eyJqdGkiOiJkMWI5OWJiNS1kMTBlLTRlZjMtYTQzNy05ZmYyZWE1MzQyNjkiLCJleHAiOjE0ODYxMzUwOTgsIm5iZiI6MCwiaWF0IjoxNDg2MTM0MTk4LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvRGVtby1SZWFsbSIsImF1ZCI6InR1dG9yaWFsLWZyb250ZW5kIiwic3ViIjoiZWU1MWNhYWYtOTY4MC00MmU3LWJiZTQtYmRjYjE0NTcxMWI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidHV0b3JpYWwtZnJvbnRlbmQiLCJub25jZSI6ImQ3MjA1Yjg2LTEwNmMtNDA1MS1hZjJiLTE0NTZjY2I5MzQyMiIsImF1dGhfdGltZSI6MTQ4NjEzNDE5OCwic2Vzc2lvbl9zdGF0ZSI6ImQ5NzU1ZGE1LTc1NDktNDBkMi05MGIzLTllMDIwODEzZjRhYyIsImFjciI6IjEiLCJjbGllbnRfc2Vzc2lvbiI6IjdjZWZiNDVkLTZmNmQtNGMwMC1iZGRlLTBiZDRhMTRlNmJmZCIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwMDAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm1hbmFnZXIiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50Iiwidmlldy1wcm9maWxlIl19fSwicGVyc29uIjp7InNzaW4iOiI3NjEyMDkwMjUyNyJ9LCJuYW1lIjoiRnJlZGVyaWsgTGliZXJ0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNmZlODgyYmEtM2UwMi00NzM5LTkxZGEtNThiNmI3ZDBhNDg1IiwiZ2l2ZW5fbmFtZSI6IkZyZWRlcmlrIiwiZmFtaWx5X25hbWUiOiJMaWJlcnQifQW_DUfimwbNeW8dTceBjXOv_J3CgGFINNOT44YIrKOn0Y1iZI6dsInwW4fGISf39QXf5lVbkqPzj5JBvRos_j5uDC9ypow9smHBIRxQX17Ac0D5C_6dbB7JPCwnlhywu2txwSWOOZGTTfblU3psR24AYM3czZwoLkdq1DZDxfH4MLDjjYFVv_UlDfBi8N-Jaj9ESNohnj1ywRQJDEEiQvSfQ5imdkWYMarP1UGX9z79gG3KoLX29L3QxFptu2kW7W1ntt2G7xgbaWfHf5eSEGsCnfPkALY1yYT1h1KGMOibE8deuPm2ET5A0wwd2AlaH9qH53l4_57VvPhm6w_OFtXAamp
token_type=beareramp
session_state=d9755da5-7549-40d2-90b3-9e020813f4acamp
expires_in=900amp
not-before-policy=1486050488
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2540
533 Client credentials flow
ldquoClient credentialsrdquo is used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user
The client credentials flow in abstract contains the following steps
1 The client authenticates with the authorization server and requests an access token from the token endpoint
2 The authorization server authenticates the client and if valid issues an access token
The client credentials grant type can only be used by confidential (server-side) clients
Input arguments for Access Token request
Endpoint Token endpoint
HTTP method POST
A client makes a token request by presenting its authorization grant to the token endpoint using the grant_type value client_credentials
Field name Description
grant_type MANDATORY Value MUST be set to ldquoclient_credentialsrdquo
client_assertion_type MANDATORY Value must be set to ldquournietfparamsoauthclient-assertion-typejwt-bearerrdquo
client_assertion MANDATORY JWT token signed with the certificate of the partnerrsquos client
The JWT token must contain some elements as defined in httpstoolsietforghtmlrfc7523section-3
iss and sub correspond to the client_id aud contains the identification of the authorization server (example ldquohttps[IAMConnectRoot]authrealms[realm id]rdquo)
Output arguments for Access Token (success)
HTTP status code 200 OK
The parameters are included in the entity-body of the HTTP response using the applicationjson media type The parameters are serialized into a JSON structure by adding each parameter at the highest structure level The order of parameters does not matter and can vary
Field name Description
access_token MANDATORY Access token
token_type MANDATORY The type of the token issued Always ldquobearerrdquo
expires_in MANDATORY The lifetime in seconds of the access token
refresh_token OPTIONAL The refresh token which can be used to obtain new access tokens using the same authorization grant
refresh_expires_in OPTIONAL The lifetime in seconds of the refresh token
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2640
Output arguments for Access Token (error)
See section 531331
54 Validate access token
Once an access token has been obtained by the client and passed to the target resource server the latter must check whether the access token received is valid
The keys used to sign tokens (all tokens are signed by the Realm key) and all endpoints can be consulted online for each Realm https[IAMConnectRoot]authrealms[realm id] well-knownopenid-configuration
Access tokens are JSON Web Token (JWT) General validation Access Token
JWT tokens can be validated offline The signing key may be retrieved using the well-known endpoints (see above) jwks_uri https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectcerts
In addition clients can send the token to IAM Connect for validation We use the following standard OAuth 20 token Introspection (based on RFC 7662) This allows the client to verify if a token has not been revoked With offline validation only you obviously cannot perform this verification Clients who want to check revocation must use the following endpoint
https[IAMConnectRoot]authrealms[realm id]protocolopenid-connecttokenintrospect URL therefor can also be retrieved via the well-known endpoints token_introspection_endpoint
Input arguments
Endpoint token_introspection_endpoint
HTTP method POST
The access token is passed using the applicationx-www-form-urlencoded format
Field name Description
token MANDATORY The string value of the token For access tokens this is the access_token value returned from the token endpoint defined in OAuth 20 (RFC6749) Section 51
Output arguments (success)
HTTP status code 200 OK
The server responds with a JSON object in ldquoapplicationjsonrdquo format with the following top-level members
Field name Description
active MANDATORY Boolean indicator of whether or not the presented token is currently active
sub OPTIONAL Subject Identifier A locally unique and never reassigned identifier within the Issuer for the End-User which is intended to be consumed by the Client eg 24400320
or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255
ASCII characters in length The sub value is a case sensitive string
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2740
aud OPTIONAL Audience(s) that this access token is intended for It MUST be the OAuth 20 client_id of the Client
iss OPTIONAL Issuer Identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
exp OPTIONAL The lifetime in seconds of the access token For example the value 3600 denotes that the access token will expire in one hour from the time the response was generated
scope OPTIONAL The scope of the access token (space-separated)
client_id OPTIONAL Client identifier for the OAuth 20 client that requested this token
token_type OPTIONAL Type of the token
iat OPTIONAL Integer timestamp indicating when this token was originally issued
nbf OPTIONAL Integer timestamp indicating when this token is not to be used before
jti OPTIONAL Provides a unique identifier for the JWT
Output arguments (error)
HTTP status code 401 Unauthorized
If the protected resource uses OAuth 20 client credentials to authenticate to the introspection endpoint and these credentials are invalid the authorization server responds with an HTTP 401 (Unauthorized)
If the protected resource uses an OAuth 20 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request the authorization server responds with an HTTP 401 code
Example
HTTP11 200 OK
Content-Type applicationjson
active true
client_id l238j323ds-23ij4
username jdoe
scope read write dolphin
sub Z5O3upPC88QrAjx00dis
aud httpsprotectedexamplenetresource
iss httpsserverexamplecom
exp 1419356238
iat 1419350238
extension_field twenty-seven
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2840
HTTP11 200 OK
Content-Type applicationjson
active false
55 Consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process After a user provides their credentials authorization server will pop up a screen identifying the client requesting a login and what identity information is requested of the user User can decide whether or not to grant the request
Consent is optional and can be configured by client
56 Token specification
561 IDToken
An ID Token is a JSON Web Token (JWT) that contains claims about the authentication event It MAY contain other claims
The IDTokens generated will contain the default info any idToken should have according to the specs You can find a description of the default info in
Table 1 IDToken default claims
Field name Description
iss Issuer identifier for the issuer of the response The iss value is a case sensitive URL using the https scheme that contains scheme host and optionally port number and path components and no query or fragment components
sub Subject identifier A locally unique and never reassigned identifier within the issuer for the end-user which is intended to be consumed by the client eg 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4 It MUST NOT exceed 255 ASCII characters in length The sub value is a case sensitive string
aud Audience(s) that this ID Token is intended for It MUST contain the OAuth 20 client_id of the relying party as an audience value It MAY also contain identifiers for other audiences In the general case the aud value is an array of case sensitive strings In the common special case when there is one audience the aud value MAY be a single case sensitive string
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 2940
exp Expiration time on or after which the ID Token MUST NOT be accepted for processing The processing of this parameter requires that the current datetime MUST be before the expiration datetime listed in the value Implementers MAY provide for a small margin usually not more than a few minutes to account for clock skew Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime See RFC 3339 for details regarding datetimes in general and UTC in particular
iat Time at which the JWT was issued Its value is a JSON number representing the number of seconds from 1970-01-01T000Z as measured in UTC until the datetime
nonce String value used to associate a client session with an ID Token and to mitigate replay attacks The value is passed through in unmodified way from the authentication request to the ID Token If present in the ID Token clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request If present in the authentication request authorization servers MUST include a nonce claim in the ID Token with the claim value being the nonce value sent in the authentication request Authorization servers SHOULD perform no other processing on nonce values used The nonce value is a case sensitive string
acr Authentication Context Class Reference String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied The value 0 indicates the end-user authentication did not meet the requirements of ISOIEC 29115 [ISO29115] level 1 Authentication using a long-lived browser cookie for instance is one example where the use of level 0 is appropriate Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value (This corresponds to the OpenID 20 PAPE [OpenIDPAPE] nist_auth_level 0) An absolute URI or an RFC 6711 registered name SHOULD be used
as the acr value registered names MUST NOT be used with a different meaning than registered Parties using this claim will need to agree upon the meanings of the values used which may be context-specific The acr value is a case sensitive string
azp Authorized party - the party to which the ID Token was issued If present it MUST contain the client ID of this party This claim is only needed when the ID Token has a single audience value and that audience differs from the authorized party It MAY be included even when the authorized party is the same as the sole audience The azp value is a case sensitive string containing a StringOrURI value
nbf The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing The processing of the nbf claim requires that the current datetime MUST be after or equal to the not-before datetime listed in the nbf claim Implementers MAY provide for some small margin usually no more than a few minutes to account for clock skew Its value MUST be a number containing a NumericDate value
jti The jti (JWT ID) claim provides a unique identifier for the JWT The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object if the application uses multiple issuers collisions MUST be prevented among values produced by different issuers as well The jti claim can be used to prevent the JWT from being replayed The jti value is a case-sensitive string
name End-users full name in displayable form including all name parts possibly including titles and suffixes ordered according to the end-users locale and preferences
given_name Given name(s) or first name(s) of the end-user Note that in some cultures people can have multiple given names all can be present with the names being separated by space characters
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3040
family_name Surname(s) or last name(s) of the end-user Note that in some cultures people can have multiple family names or no family name all can be present with the names being separated by space characters
Table 1 IDToken default claims
IDToken example
jti 9965d845-08fc-463a-8773-d90dd8d6b206
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ ID
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
person
id 96120902527
id_typeCITIZEN
name John Doe
preferred_username 6fe882ba-3e02-4739-91da-58b6b7d0a485
given_name John
family_name Doe
For client involving IDP the ID Token may contain other claim depending on the userrsquos chosen profile (within eHealth IDP)
Claim IAM Attribute
All profile profile_opt urnbefgovehealth10profileOptionType
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3140
Individual profile personid urnbefgovpersonssin
personid_type urnbefgovpersonprofessionaltype-code
Healthcare professional profile
personnihdi_id urnbefgovpersonehealth10nihii11
Organization profile
orgid urnbefgovorganizationid
orgid_type urnbefgovorganizationid-type
orgname urnbefgovorganizationname
orgid_code urnbefgovorganizationid-code
orgtype_code urnbefgovorganizationtype-code
Mandate profile mandatorid_type urnbefgovmandatorid
mandatortype_code urnbefgovmandatortype-code
mandatorid_code urnbefgovmandatorid-code
mandatorname urnbefgovmandatorname
Parent profile childid urnbefgovchildssin
childgiven_name urnbefgovchildfirstName
childfamily_name urnbefgovchildlastName
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3240
562 AccessToken
An access token is a JSON Web Token (JWT) that contains credentials used to access protected resources This token is issued to the client
Tokens represent specific scopes and durations of access granted by the resource owner and enforced by the resource server and authorization server
As for ID Token it contains registered claim names (iss sub aud exp nbf iat jti) Other claims may be provided
Access token may contain realm_access and resource_access realm_access contains realm roles (global roles applicable for all clients in the realm) resource_access contains specific client roles Client roles are grouped by client
AccessToken example
access_token
jti 6401dc72-6090-4508-b10c-39c2a2d26850
exp 1486128799
nbf 0
iat 1486128499
iss httplocalhost8080authrealms[realm id]
aud tutorial-frontend
sub ee51caaf-9680-42e7-bbe4-bdcb145711b9
typ Bearer
azp tutorial-frontend
nonce 21c805ac-2fa7-4d10-a460-1f5eec07a1e6
auth_time 1486128499
session_state b9fe89d5-f05c-4b04-973a-49941751c07c
acr 1
client_session 6192215a-3f1a-4e73-a6cc-a3ca9643369d
allowed-origins [
httplocalhost8000
]
realm_access
roles [
manager
uma_authorization
user
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3340
]
resource_access
account
roles [
manage-account
view-profile
]
57 UserInfo endpoint
The userinfo endpoint returns standard claims about the authenticated user and is protected by a bearer token The endpoint can be found in the well-known endpoints userinfo_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectuserinfo
For more details refer to Userinfo Endpoint10 section in the OpenID Connect specification
58 Logout
The logout endpoint logs out the authenticated user The user agent can be redirected to the endpoint in which case the active user session is logged out Afterwards the user agent is redirected back to the application
The endpoint can also be invoked directly by the application To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client
The endpoint can be found in the well-known endpoints end_session_endpoint https[IAMConnectRoot]authrealms[realm id]protocolopenid-connectlogout
59 Timeout and lifespan
SSO Session Idle
If the user is not active for longer than this timeout the user session will be invalidated
Maximum time before a session is invalidated 15 minutes
A client requesting authentication will bump the idle timeout Refresh token requests will also bump the idle timeout
SSO Session Max
Maximum time before a user session is expired and invalidated 12 hours
10 httpopenidnetspecsopenid-connect-core-1_0htmlUserInfo
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3440
Access Token Lifespan
Maximum time before an access token expires 5 minutes
Access Token Lifespan For Implicit Flow
Maximum time before an access token issued during OpenID Connect Implicit Flow expires 15 minutes
Client login timeout
Maximum time a client has to finish the access token protocol 1 minute
Login timeout
Maximum time a user has to complete login related actions like update password or configure totp 30 minutes
Login action timeout
Maximum time a user can spend on any one page in the authentication process 5 minutes
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3540
6 Risks and security
61 Security
611 Business security
In case the development adds an additional use case based on an existing integration eHealth must be informed at least one month in advance with a detailed estimate of the expected load This will ensure an effective capacity management
In case of technical issues on the web service the partner may obtain support from the contact center
In case eHealth finds a bug or vulnerability in its software the partner is advised to update his application with the newest version of the software within 10 business days
In case the partner finds a bug or vulnerability in the software or web service that eHealth delivered he is obliged to contact and inform eHealth immediately and he is not allowed to publish this bug or vulnerability in any case
612 Recommendations for mobile clients
For native app you can refer to httpstoolsietforghtmldraft-ietf-oauth-native-apps-10
For clients utilizing the Authorization Code Grant you should consider using PKCE11
11 httpstoolsietforghtmlrfc7636
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3640
7 Test and release procedure
71 Procedure
This chapter explains the procedures for testing and releasing an application in acceptation or production
711 Initiation
If you intend to use the eHealth service please contact infoehealthfgovbe The Project department will provide you with the necessary information and mandatory documents
712 Development and test procedure
You have to develop a client in order to connect to our service Most of the required integration info to integrate is published in the technical library on the eHealth portal
In some cases eHealth provides you with a mock-up service or test cases in order for you to test your client before releasing it in the acceptance environment
713 Release procedure
When development tests are successful you can request to access the eHealth acceptance environment
From this moment you start integration and acceptance tests eHealth suggests testing during minimum one month
After successful acceptance tests the partner sends his test results and performance results (with a sample of ldquoeHealth requestrdquo and ldquoeHealth answerrdquo) to the eHealth point of contact by email
Then eHealth and the partner agree on a release date eHealth prepares the configuration for the production environment and provides the partner with the necessary information During the release day the partner provides eHealth with feedback on the test and performance tests
For further information and instructions please contact integration-supportehealthfgovbe
714 Operational follow-up
Once in production the partner using the eHealth service for one of its applications will always test first in the acceptance environment before releasing any adaptations of its application in production In addition he will inform eHealth on the progress and test period
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3740
8 Error and failure messages
Authorization code flow (authorization endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorizd_client The client is not authorized to request an authorization code using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an authorization code using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3840
Authorization code flow (token endpoint) error and client credentials flow (token endpoint) error
Error Error description
invalid_request The request is missing a required parameter includes an unsupported parameter value (other than grant type) repeats a parameter includes multiple credentials utilizes more than one mechanism for authenticating the client or is otherwise malformed
invalid_client Client authentication failed (eg unknown client no client authentication included or unsupported authentication method) The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported If the client attempted to authenticate via the Authorization request header field the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client
invalid_grant The provided authorization grant (eg authorization code resource owner credentials) or refresh token is invalid expired revoked does not match the redirection URI used in the authorization request or was issued to another client
unauthorized_client The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type The authorization grant type is not supported by the authorization server
invalid_scope The requested scope is invalid unknown malformed or exceeds the scope granted by the resource owner
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 3940
Implicit flow errors
Error Error description
invalid_request The request is missing a required parameter includes an invalid parameter value includes a parameter more than once or is otherwise malformed
unauthorized_client The client is not authorized to request an access token using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type The authorization server does not support obtaining an access token using this method
invalid_scope The requested scope is invalid unknown or malformed
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect)
interaction_required The authorization server requires end-user interaction of some form to proceed This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user interaction
login_required The authorization server requires end-user authentication This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user authentication
account_selection_required The end-user is REQUIRED to select a session at the authorization server The end-user MAY be authenticated at the authorization server with different associated accounts but the end-user did not select a session This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface to prompt for a session to use
consent_required The authorization server requires end-user consent This error MAY be returned when the prompt parameter value in the authentication request is none but the authentication request cannot be completed without displaying a user interface for end-user consent
invalid_request_uri The request_uri in the authorization request returns an error or contains invalid data
invalid_request_object The request parameter contains an invalid request object
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter
IAM Mobile integration v100 dd 08062017 4040
request_not_supported The authorization server does not support use of the request parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
request_uri_not_supported The authorization server does not support use of the request_uri parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlJWTRequests
registration_not_supported The authorization server does not support use of the registration parameter defined in httpopenidnetspecsopenid-connect-core-1_0htmlRegistrationParameter