OAuth (RFC-040)
A period when the community can review the RFC (comment Docs)
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.
Abstract
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. |
Contributors
-
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.
-
PharmaLedger Project: Review, feedback, observations, new content, and corrections MIT licensed accordingly with the consortium agreements.
- PrivateSky Research Project: MIT licensed content accordingly with the contracts. https://profs.info.uaic.ro/~ads/PrivateSky/
Annex 1. Contributors
| Current Editors | |
|---|---|
| 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 | |
| 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 | |
| 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 | |
| Ana Balan | bam@rms.ro (RMS) |
| Bogdan Mastahac | mab@rms.ro (RMS) |
| Cosmin Ursache | cos@rms.ro (RMS) |
| Rafael Mastaleru | raf@rms.ro (RMS) |