The api is secured with OAuth2.0. In order to access the api the client needs to be in possession of a bearer token. This means he needs to be able to retrieve an access token. To be able to retrieve an access token the client needs to be registered in the authorisation server first. The authorisation server uses openID connect (which is built on top of the Auth2.0 protocol) to identify the users.
Depending on the kind of client that would like to use the api, the following openID connect flows are advised:
- client side applications : implicit flow ( security wise not advised even in acceptance)
- web applications: authorisation code flow
Registering a new client
Please fill in the table below and send it to filoretta.velica@abrumet.be :
| Name of the client ID: | |
|---|---|
| Acceptance or Production ? | |
| Callback URI | |
| Is it a Mobile app or a web app? |
Registering a new client is something that can only be performed by the administration user of the the authorisation server.
Retrieving the access token
After registration the client will be able to retrieve an access token by implementing the flow that was configured for the client. More about the flows and endpoints.
- QA: configuration of the endpoint: https://auth.qa.brusafe.be/auth/realms/abrumet/.well-known/openid-configuration(specified according to openid connect discovery spec)
The most important urls are:
- authorization_endpoint : https://{domain}/auth/realms/abrumet/protocol/openid-connect/auth
- token_endpoint : https://{domain}/auth/realms/abrumet/protocol/openid-connect/token
Their usage is explained in the openID connect spec. https://www.keycloak.org/docs/2.5/server_admin/topics/sso-protocols/oidc.html
Implementation guides:
- implicit flows: https://openid.net/specs/openid-connect-implicit-1_0.html
- authorisation code flow: https://openid.net/specs/openid-connect-basic-1_0.html
For debugging purposes it's also possible to retrieve an access token using the portal: https://auth.qa.brusafe.be/portal/patient/test/api/bearer.xhtml
Note that the api is currently only useful for therapeutist, so if you are registered as a patient you won't be able access the api with your token. This token has only a limited lifetime (5 min) to retrieve a new one, simply refresh the page. Expiration of the token will result in "unauthorized" responses returned from the server.
Using the access token
Once the access token is retrieved it needs to be added as Authorization HTTP with the requests made to the api as bearer token. The header looks like:
Authorization: Bearer <access_token>
Troubleshooting
Login errors can be checked in an event log in keycloak: events → login events.
Next filter (+Fiilter) on LOGIN_ERROR and update the list. A list of all login errors is shown.
For more info about events: https://keycloak.gitbooks.io/server-adminstration-guide/content/v/2.3/topics/events/login.html