+ All Categories
Home > Documents > eHealth platform

eHealth platform

Date post: 27-Apr-2023
Category:
Upload: khangminh22
View: 0 times
Download: 0 times
Share this document with a friend
40
Technical specifications Identity & Authorization Management (I.AM) Mobile integration Version 1.0 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.
Transcript

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


Recommended