API Security*
Details of API security to ensure authenticated and authorised access to APIs
The protocol defines 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.
In future versions, HCX instances may support JWTs issued by other system identity providers, e.g. Health Facility Registry’s IDP.
Securing HCX Gateway APIs
To secure the HCX APIs, the previous 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, there could be multiple people responsible for managing participant’s registry and claims exchanges 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, it is required to use user specific API tokens per participant to ensure security and traceability of actions executed on behalf of a participant.
Per Participant, Per User API key
The protocol recommends using the username and participant specific secret of each eligible user for the participant in generating the API token. To achieve this, participants should onboard users to a participant with a specific role. The below diagram depicts the process of user Onboarding to a Participant:
Participant either creates a new user or selects an existing user from the HCX user registry to initiate onboarding.
Participant assigns one or more roles (ex: admin) to the user. This updates the "tenant_roles" attribute in the User Registry.
HCX generates a participant-specific secret for the newly onboarded user and sends it to registered email address of the user.
Steps to obtain the API key:
After a successful onboarding of user to a participant, use the following details to generate a API key:
participant code: The participant systems' code in HCX Gateway participant registry.
username: The primary email address of the user in the HCX Gateway user registry.
secret: The secret or password generated when the user linked with participant along with a role.
The participant system can call ‘/participant/auth/token/generate’ API along with the participant code, username and secret to obtain the API key.
{realm-name} is the security realm name used by the HCX Gateway insteance. Recommended name for the realm is "hcx", but gateway instances are free to use a different name.
HCX Gateway would respond with the API token upon successful validation of the username and secret values for the provided participant code:
The generated API token can be used to execute HCX protocol API requests on behalf of the participant, provided that the user possesses the requisite roles for making such protocol API calls. The below diagram depicts the process of generating and using the API token:
JWT Token Structure:
API keys are expected to be in JWT format and signed as per JSON web signature (RFC7515). The API key should have three elements separated by periods (.): BASE64URL(UTF8(JOSE Header)), BASE64URL(JWS Payload), and BASE64URL(JWS Signature).
JOSE Header should be a JSON with the following values:
JWS Payload should be a claim set containing the following claims:
participant_code: participant code of the participant from the HCX Participant Registry
user_id: identifier of the user from the HCX User Registry
realm_access.participant_roles: roles assigned to this participant
realm_access.user_roles: roles assigned to the user in this participant
iat - unix timestamp at which the JWT is issued
exp - the expiration time after which the JWT must not be accepted for processing
JWS Signature must be computed in the manner defined for RS256 algorithm over the input ASCII(BASE64URL(UTF8(JOSE Header)) || '.' || BASE64URL(JWS Payload)) using the private key of the authentication provider.
Securing Participant System APIs
HCX instances while making the calls to the participant system will use a self-generated JWT token with the following elements:
JOSE Header should be a JSON with the following values:
JWS Payload should be a claim set containing the mandatory claims jti, iss, sub, iat and exp.
jti - unique identifier for the JWT
iss - HCX instance identifier
sub - same as iss claim, HCX instance identifier
iat - unix timestamp at which the JWT is issued
exp - the expiration time after which the JWT must not be accepted for processing
JWS Signature must be computed in the manner defined for RS256 algorithm over the input ASCII(BASE64URL(UTF8(JOSE Header)) || '.' || BASE64URL(JWS Payload)) using the private key of the HCX instance.
Participant systems should validate the API key signature using the public key of the HCX instance.
Last updated