OAuth (RFC-040)

Document Maintainers: Andi Gabriel Tan 2024. List of other contributors in Annex. 1.

Copyright: MIT license

Copyright © 2018-2024 Axiologic Research and Contributors.

This document is licensed under MIT license.


This RFC introduces general information related to the OAuth protocol, how it is used within the application, and configurations of the OAuth component.

1. Overwiew

1.1 Authorization code flow with PKCE

Figure 1: Authorization Code Flow + PKCE

The OAuth protocol is the standard model for accessing a resource that is protected by password and username using SSO. OAuth protocol presumes a three-component model: the server on which the resource is located (APIHub), the SSO server and the Client. The flow used is Authorization code flow with PKCE (Proof Key for Code Exchange).

Figure 1 shows the flow mentioned above for accessing an APIHub resource, but by logging in first, through the SSO server.

In the first step (the arrow that returns to the Client), it just generates the PKCE code verifier and code challenge, which are some random strings. They are sent to the SSO server to verify that they are indeed the one who generated the PKCE code.

In the second step, a request is made to an endpoint in the SSO server. This endpoint is called authorization endpoint. For most providers, the termination is /authorize. The authorization request must include the code request and the code challenge from step 1. After the SSO server receives this request, it will automatically redirect (step 3) to a login page (step 4), where the user must enter their credentials (username and password).

After completing the login stage (step 5), the SSO server redirects to a client page (usually called “login callback”); when redirecting to the “login callback” page, the SSO server adds the authorization code in the query parameters.

In step 6, a getToken request is sent. The SSO server evaluates the PKCE code (step 7). If all is well and those are the same as the ones sent in step 2, then everything is okay. We get access to the token (step 8), and then, in step 9, we can use this Access Token to have direct access to APIHub, meaning the resource. The Token is usually placed in the Authorization Header. In step 10, the server responds with what we asked for.

2. The OAuthMiddleware component

Figure 2: The flow of EPI requests when SSO is enabled

When an ePI wallet is accessed, the OAuthMiddleware component in APIHub checks whether the user is logged into SSO. If the user is not logged into SSO, they are redirected to the SSO provider login page. After the login, the OAuthMiddleware component gets the access and refresh tokens from the SSO provider and puts them in the response cookies in an encrypted form. The encryption is done with AES (256-GCM) using a randomly generated 32-byte encryption key which is rotated after a specified time interval (by default, this interval is 1 hour). The encryption keys are stored on disk. Tokens are obtained by following the steps (see Figure 1) using the Authorization code flow with PKCE (Proof Key for Code Exchange).

The OAuthMiddleware also implements an SSO session that ends after a specified time interval (30 minutes, by default) of user inactivity.

Every request sent to APIHub goes through OAuthMiddleware, which decrypts the access token from the request cookie and checks whether the token is still valid and the session has not expired. If the access token is valid and the session has not expired, the request is forwarded to the other APIHub components. If the session has expired, the user is automatically logged out of SSO. If the token is invalid, the user is redirected to the SSO login page.

3. Configuration

The OAuthMiddleware component is configurable via the apihub.json file. Below are the fields that need to be configured in order to enable SSO for an application previously registered with an SSO provider. The table describes each field in more detail.

"enableOAuth": true,
"oauthJWKSEndpoint": "",
"oauthConfig": {
"issuer": {
  "issuer": "",
  "authorizationEndpoint": "",
  "tokenEndpoint": ""
"client": {
  "clientId": "",
  "scope": "email offline_access profile openid",
  "redirectPath": "",
  "clientSecret": "",
  "logoutUrl": "",
  "postLogoutRedirectUrl": ""
"sessionTimeout": 1800000,
"keyTTL": 3600000,
"debugLogEnabled": false
"serverAuthentication": true

Field Description
enableOAuth Flag for enabling the OAuth component on the client side.
oauthJWKSEndpoint The endpoint for retrieving the public key in order to verify the token’s signature.
issuer The issuer endpoint.
authorizationEndpoint The endpoint for retrieving the authorization code.
tokenEndpoint The endpoint for retrieving the access and refresh tokens.
clientId The id assigned to the application after being registered with the SSO provider.
scope The claims to be included in the access token payload.
redirectPath The endpoint the user is redirected to after the SSO login.
clientSecret The client secret was created when registering the application.
logoutUrl The endpoint called in order for the user to be signed out by the SSO provider
postLogoutRedirectUrl The endpoint the user is redirected to after being logged out by the SSO provider.
sessionTimeout The number of milliseconds of idle time before the user is logged out from the application.
keyTTL The time (in milliseconds) between encryption key rotations. The encryption key is used to encrypt the access token and is kept on disk.
debugLogEnabled A flag for enabling or disabling the OAuthMiddleware logs.
serverAuthentication A flag for enabling/disabling the OAuthMiddleware component.


  1. Axiologic Research: New content and improvements. Original texts under PharmaLedger Association and Novartis funding. MIT licensed content accordingly with the contracts. Publish and maintain the www.opendsu.org site.

  2. PharmaLedger Project: Review, feedback, observations, new content, and corrections MIT licensed accordingly with the consortium agreements.

  3. PrivateSky Research Project: MIT licensed content accordingly with the contracts. https://profs.info.uaic.ro/~ads/PrivateSky/

Annex 1. Contributors

Current Editors Email
Sînică Alboaie sinica.alboaie@axiologic.net
Cosmin Ursache cosmin@axiologic.net
Teodor Lupu teodor@axiologic.net
Andi-Gabriel Țan andi@axiologic.net
Contributors Axiologic Research Email
Adrian Ganga adrian@axiologic.net
Andi-Gabriel Țan andi@axiologic.net
Cosmin Ursache cosmin@axiologic.net
Daniel Sava daniel@axiologic.net
Nicoleta Mihalache nicoleta@axiologic.net
Valentin Gérard valentin@axiologic.net
PrivateSky Contributors Email
Alex Sofronie alsofronie@gmail.com (DPO)
Cosmin Ursache cos.ursache@gmail.com (UAIC)
Daniel Sava sava.dumitru.daniel@gmail.com (HVS, AQS)
Daniel Visoiu visoiu.daniel.g@gmail.com (SGiant)
Lenuța Alboaie lalboaie@gmail.com (UAIC)
Rafael Mastaleru rafael@rms.ro (RMS)
Sînică Alboaie salboaie@gmail.com (UAIC)
Vlad Balmos vlad.balmos@gmail.com (Code932)
PharmaLedger Contributors Email
Ana Balan bam@rms.ro (RMS)
Bogdan Mastahac mab@rms.ro (RMS)
Cosmin Ursache cos@rms.ro (RMS)
Rafael Mastaleru raf@rms.ro (RMS)