Enhancing Security and Accountability in HCX Gateway API Access

[maheshkumargangula]

The HCX Protocol defines multi-level mechanisms to ensure security and privacy of claims data being exchanged – transport level, message level and API level. For API security, an API-key based security for authentication and authorization of the API calls between the participating systems and the HCX Gateway. HCX instances have to generate the API keys in the form of JWT tokens (RFC7519) and shall mandatorily set an expiry time for all the generated tokens.

Securing HCX Gateway APIs & Challenges

To secure the HCX APIs, the current version of the protocol (v0.8) requires participant’s username and password to be used in the token generation API to obtain the API key.

However, as observed in on ground implementations, there could be multiple people responsible for managing participant’s registry configuration in HCX on behalf of a participant (payer or provider). This could be because of the following key reasons:

• Participants may want to have a quorum of users managing its HCX integration for the purpose of redundancy and business continuity.
• Participants may employ services from one or more Technology Service Providers to handle their claims exchange processes.

In such cases, generating the API key solely through the participant's credentials raises security concerns for the participant organization, as in the current scheme of things, it entails sharing the participant’s credentials with multiple users. Furthermore, it also affects accountability as there is no way to trace which user has handled the HCX Protocol requests.

The diagram below depicts the current API token generation workflow:

Proposed approach

To effectively deal with this practical reality, wherein a participating system may need to involve multiple users to manage its HCX integration. The participating system will onboard the users to the HCX User registry. The verification of the users will be done as below.

• The participating system will identify and onboard only a valid and verified user.
• The participating system will choose to request the HCX to validate and verify the user.

Considering this, we propose following an AWS like approach in creating and managing the API tokens:

Per participant, per user API key

We propose that instead of using a single client key and secret per participant to generate the API tokens, the protocol recommends using the username and password of each eligible user for the participant in generating the API token. To achieve this, while onboarding a new user to a participant, the HCX Gateway would be required to generate a secret for each user of a participant. This secret, along with username and participant code, is then used to generate the API key for the users to access Protocol APIs. Following would be the key elements for generating the API token:

• participant code: The participant systems' code in HCX Gateway participant registry.
• username: The primary email address in the HCX Gateway user registry.
• secret: The secret or password generated when the user linked with participant along with a role.

The diagram below depicts the process of user Onboarding to a Participant:

The diagram below depicts the process of generating and using the API token:

The participant system can call /participant/auth/token/generate along with username, participant code and secret to obtain the API key.

POST /participant/auth/token/generate
Content-Type: application/x-www-form-urlencoded

Request-Body:

 {
   "participant_code": "", // The code in HCX Gateway participant registry.
   "username": "", // This is the primary email of the user who is attempting to authenticate.
   "secret": "" // This is the secret of the user for the above participant.
 }

HCX instance would respond with the API token upon successful validation of the participant code, username and secret values:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

Response-Body:

 {
   "access_token": "", // This is the token that the client can use to access protected resources on the server. The token is a JSON Web Token (JWT) that contains claims about the user and the client
   "expires_in": 6000, // The number of seconds until the access token expires. After this time, the client must obtain a new access token.
   "refresh_expires_in": 300, // The number of seconds until the refresh token expires. After this time, the client must obtain a new refresh token. 
   "refresh_token": "", // A token that the client can use to obtain a new access token after the current access token expires. The refresh token is also a JWT that contains claims about the user and the client. 
   "token_type": "Bearer", // The type of token, which is usually "bearer".
   "not-before-policy": 1607576887, // The time before which the token is not valid.
   "session_state": "a1415249-c4eb-49e1-97ea-42c7c91db874", // A unique identifier for the user's session.
   "scope": "profile email" // The scopes that the client has requested access to.
 }