Security Controls

Status

Ready for review

Depending on the classification of the information that is presented in the APIs and the Risk Framework applied, different access controls will need to be applied. This section provides a summary of the controls that SHOULD be implemented when protecting Health APIs. The five areas that MUST be considered are:

• Confidentiality

• Integrity

• Availability

• Threat Protection

• Monitoring, Logging and Auditing

Using the Resource Type definition detailed in FHIR, the controls above will be mapped to the different resources:

Resource Type	Data Type	Classification
Anonymous Read Access	Does not contain any individual data, or business sensitive data Contains important information that must be authenticated back to the source publishing them Examples: Capability Statement Clinical User Definition	PUBLIC
Business Sensitive	Does not contain any individual data Contains data that describe business or service sensitive data Contains data related to organisation, location, or other group that is not identifiable as individuals Examples: Location Medication	IN-CONFIDENCE
Individual Sensitive	Does NOT contain Patient data Contains individual information about other participants i.e. Practitioners and Practitioner Role. Examples; Practitioner Practitioner Role	IN-CONFIDENCE
Patient Sensitive	Contain highly sensitive health information Closely linked to highly sensitive health information Examples: Procedure Invoices	SENSITIVE

The following controls are recommended by the FHIR specification and MUST be implemented by the API provider:

Resource Type	Control Required
Anonymous Read Access	No access control based on the user or system requesting are required MUST use TLS (HTTPS) to provide authentication of the server and integrity protection in transit
Business Sensitive	Client authentication is required to assure that only authorized access is given The Client can be a person or a System Client authentication methods SHOULD use at least one of: mutual-authenticated-TLS APIKey App signed JWT App OAuth client-id JWT Business protected Provider Directory can be used to provide information that can be used for ABAC / RBAC controls
Individual Sensitive	Apply RBAC or ABAC access polices
Patient Sensitive	Often requires a declared Purpose Of Use Controlled by a Privacy Consent Security labels to differentiate various confidentiality levels within this broad group of Patient Sensitive data

Confidentiality and Integrity

Confidentiality and integrity cover the handling of request and response data, both in transit and at rest. The aim is to protect the payload content from unauthorised access (eavesdropping), manipulation or faking of content. An API request needs to be received intact by the API, with validation as to the source of the request. Untampered API responses need to be received by the consuming application, with confirmation that they are legitimately from the API.

Data Classification	Control
Public	TLS 1.3 MUST be applied between client, authorisation server and resource server MAY encrypt the payload Authentication MAY be applied Coarse grained Authorisation MAY be applied
In-Confidence	TLS 1.3 MUST be applied, MTLS MAY be applied, between client, authorisation server and resource server Encryption of the payload SHOULD be considered Strong Authentication SHOULD be applied Fine grained Authorisation SHOULD be applied using ABAC or RBAC
Sensitive	TLS 1.3 MTLS MUST applied between client, authorisation server and resource server The Payload MUST be encrypted Security Tags (labels) MUST be used for FHIR APIs to apply the masking or removal sensitive data in the response Strong Authentication MUST be applied Coarse grained Authorisation MUST be applied Fine grained Authorisation MUST be applied

The following table details the data classification application for API Security using OAuth 2 and OpenID Connect:

Data Classification	API Security Control (Grant Flows)
Public	Client Credentials with Scopes MAY be applied Implicit Grant flow with PKCE MAY be applied Authorisation Code grant with PKCE MAY be applied
In-confidence	Client Credentials with Scopes MUST NOT be applied Implicit Grant flow MUST NOT be applied Authorisation Code grant with PKCE SHOULD be applied
Sensitive	Client Credentials with Scopes MUST NOT be applied Implicit Grant flow MUST NOT be applied Authorisation Code grant with PKCE MUST be applied

Grant Type	Control Required
Client Credentials with Scopes	OAuth 2 SHOULD be applied, MAY use OpenID Connect Client_secret_post token endpoint authorisation SHOULD be applied Access Tokens MAY be signed to validate integrity The authorisation server MUST validate the scopes
Implicit grant with PKCE	OpenID Connect SHOULD be applied using an openid scope in the authentication request Client_secret_post or client_secret_jwt or private_key_jwt token endpoint authorisation SHOULD be applied Access Tokens MUST be signed to validate integrity The authorisation server MUST validate the scopes PKCE SHOULD be allied to mitigate stolen authorisation codes The response_type SHOULD be id_token token The state parameter MUST be used in the authorisation request and the API consumer MUST validate it in the response If OpenID Connect is used the nonce parameter MUST be used in the authorisation request and the API consumer MUST validate it in the id_token
Authorisation Code grant with PKCE	OpenID Connect MUST be applied using an openid scope in the authentication request private_key_jwt token endpoint authorisation MUST be applied Access Tokens MUST be signed to validate integrity The authorisation server MUST validate the scopes PKCE MUST be applied to mitigate stolen authorisation codes The response_type MUST be code id_token The state parameter MUST be used in the authorisation request and the API consumer MUST validate it in the response The nonce parameter MUST be used in the authorisation request and the API consumer MUST validate it in the id_token Client secrets MUST be securely stored id_token SHOULD be used as a detached signature The flow SHOULD contain c_hash,at_hash and c_hash values Encryption of the id_token MAY be used Demonstration of Proof-of-Possession SHOULD be applied to tie an Access Token to a client

Hash Values

In OpenID Connect, the c_hash, at_hash, and s_hash values are used to enhance the security and integrity of the authorisation process.

c_hash (Code Hash)

• Used in the authorisation code flow when using response_type=code id_token
• The response to the client is a code and the first id_token
• The id_token signature is validates by obtaining the JWKS from the the Authorisation Server JWK endpoint
• Parsing the id_token the c_hash is found and using SHA-256 (defined in the header of the id_token "alg") compares the code with the c_hash

at_hash (Access Token Hash)

• Used in the authorisation code flow when using response_type=code id_token
• The response to the client when the code is presented to the token endpoint is a JWT access token and and id_token
• The id_token signature is validated by obtaining the JWKS from the the Authorisation Server JWK endpoint
• Parsing the id_token the at_hash is found and using SHA-256 (defined in the header of the id_token "alg") compares the access token with the at_hash
• Provides Access token integrity

s_hash (State Hash)

• Used in the authorisation code flow and implicit flow when using response_type=code id_token the authorisation request includes a state value created by the client
• The response to the client is a code and and the first id_token
• The id_token signature is validated by obtaining the JWKS from the the Authorisation Server JWK endpoint
• Parsing the id_token the s_hash is found and using SHA-256 (defined in the header of the id_token "alg") compares the state with the s_hash

State (Integrity)

State is also a parameter that MUST be used during the authorisation grant stage to provide a level of security to address possible man-in-the-middle attacks. The state parameter is a string of random letters and numbers that is sent to the Authorisation Server by the client when requesting an authorisation code. It is sent back to the client with the Authorisation Code and MUST be verified by the API consumer application to confirm the authenticity of the response i.e. it came from the authorisation server to which the request was sent.

Content Encryption (Confidentiality)

If content needs only to be visible to specific consumer endpoints, use encryption. However, if content only needs to be guaranteed untampered and/or from a specific source (e.g. provider) then use content signing. Content encryption enables all or part of an API payload to be readable only by the target consumer(s). This is useful where the content being carried by the API is sensitive, and the API request or response transits multiple stopping points. Whilst TLS protects the payload in transit, it only applies to each point to point connection between components (e.g. mobile app to API gateway). If transit components are not totally under the provider’s control, it can be worthwhile performing payload encryption. E.g. it may be sensible to encrypt credit card details passed between consumer and provider backend systems.

It is also worth considering how much protection the information needs whilst at rest. Data at rest encryption is generally considered good practice and may cloud service providers offer this as standard. See NZISM for details.

Encryption is only worthwhile implementing when data sensitivity or data protection requirements drive it, as encryption can be computationally intensive. It also makes it more difficult for protection mechanisms, such as API gateways, to validate and transform API content. When only the integrity of the content passed needs to be ensured, consider using Content Signing instead.

There are many existing ways of encrypting message content, built into code libraries and development tools. It is required that any content encryption adheres to the standard algorithms laid out in NZISM (HMAC Algorithms).

Content Signing (Integrity)

Content signing is used to assure content integrity and proof of authorship. It can apply to the entire payload of the API request/response or specific elements of that content e.g. credit card details. There are many approaches to content signing and the most appropriate approach is requirements dependent. Standard signing algorithms exist within coding libraries, and JWT has a payload that can contain verifiable (signed) JSON fields.

Signing has less of a computational overhead than encryption, but can still affect performance, so it is advisable that it be used only when and where needed. This is covered under:

• RFC 7800 Proof of Possession - OAuth 2.0 Proof-of-Possession (PoP) Security Architecture (draft)

Where Bearer Tokens are used, they MUST be JSON Web Tokens (JWT) signed using JSON Web Signature as defined in:

• JSON Web Token (JWT) RFC 7519

• JSON Web Signature (JWS) RFC 7515

• JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants RFC 7523

Non-Repudiation (Integrity)

Non-repudiation covers the means to ensure that a consumer cannot deny making a request and, similarly, a provider cannot claim they did not send a response. To aid non-repudiation for APIs, it is important to ensure credentials are not shared between consumers and to perform comprehensive logging of API request/responses.

Digital signatures are useful for not just guaranteeing authenticity and integrity, but also supporting non-repudiation.

Organisation controls for all APIs

The following is a list of controls:

• MUST enforce access controls at the API provider edge
  • Throttling to address DoS
  • Message analysis to block HTTP attacks; parameter attacks such as cross-site scripting, SQL injection, command injection and cross site request forgery
• MUST use short lived Access Tokens
• SHOULD use JWT Access and Refresh Tokens
• The Authorisation Server MUST provide a Token Revocation endpoint
• The Authorisation Server MUST provide a Token Introspection endpoint
• Token Signing MUST use EdDSA or ECDA when protecting sensitive information
• Token Encryption MUST use RSA-OAEP
• Hashing algorithms that MUST be applied or SHA-256 or SHA-384
• All communications to or from an API MUST be over TLS 1.3 or higher. Other versions of TLS and SSL should be disabled. This provides a recognised level of confidentiality that covers all communications between all components.
• API consumer applications MUST validate TLS certificate chains when making requests to protected resources, including checking the Certificate Revocation List (CRL).

Availability and Threat Protection

Availability in this context covers threat protection to minimise API downtime, looks at how threats against exposed APIs can be mitigated using basic design principles and how to apply protection against specific risks and threats.

Availability also covers scaling to meet demand and ensuring hosting environments are stable etc. These levels of availability are addressed across hardware and software stacks that support the delivery of APIs. There are no specific standards for availability, but availability is normally addressed under business continuity and disaster recovery standards. These standards recommend a risk assessment approach to define API availability requirements. Further information on business continuity and risks can be found at Standards New Zealand website

For cloud services, the New Zealand Government ICT website provides an assessment capability that includes a risk assessment tool which covers availability, business continuity and disaster recovery related questions.

TODO

As mentioned in section xxx, there are various types of risk which impact APIs. This includes threats to availability as well as confidentiality and integrity. Many threats can be mitigated through good secure coding practices, using OWASP guidelines, as indicated in section xxx.

Where the resources being exposed by an API are sensitive i.e. not public data, the following rules apply:

• Threat assessment MUST be assessed on in the API development lifecycle

• Penetration testing MUST be performed once an API is developed and published (testable) and on a regular schedule post publication

• Automated vulnerability testing tools MUST be used to give an indication of vulnerabilities in API implementations.

Below is a table of risk types and some approaches that SHOULD be used to help mitigate these threats:

Threat	Mitigation (OWASP)
Exposure of inappropriate API methods to access services	Protect and Limit (whitelist) the HTTP Methods (GET, PUT etc) exposed Validate Method(s) for session token / API key.
Denial of Service attacks	Throttle access to all exposed APIs. Monitor use to indicate possible DoS attacks
Malicious Input, Injection attacks and Fuzzing	Validate input: Secure parsing and strong typing Validate incoming content-type application/json Validate JSON content Validate XML (schema and format) Scan attachments Produce valid HTTP Return Code Validate response
Cross-Site Request Forgery	Use tokens with state and nonce parameters
Cross-Site Scripting Attacks	Validate Input

Token Threat Mitigation

Securing OAuth flows relies on the exchange of tokens between consuming applications and API provider servers. There is always the threat of these tokens being obtained illicitly, losing confidentiality and integrity of message content or the integrity of the sender of the token. This risk also applies to the transferring of API keys.

The table below captures the main Token threats and mitigation strategies that SHOULD be applied:

Threat	Mitigation
Token Manufacture or modification (fake tokens and man in the middle attacks)	Digital signing of tokens (e.g. JWS with JWT) or attaching a Message Authentication Code (MAC)
Token disclosure – man in the middle attack. The Access Token is passed in clear text with no hashing, signing or encryption.	Communication Security: Use TLS 1.3 with a cipher suite that includes DHE or ECDHE The client application must validate: The TLS certificate chain Check the certificate revocation list Stored locally in a file or LDAP server
Token Redirects. Ensure the Authentication and Resource Servers are "paired”, and the access token can only be used in this between the specified servers	Using the "audience” header (defined currently in a draft RFC) the client application, resource server and authorisation server can help ensure that the token can only be used on the resource servers requested by the client and recognised by the authorisation server Also addressed with "state” parameter in the header Signing of tokens is also applicable to address token redirects
Token replay – where the threat actor copies an existing token (e.g. refresh token or authorisation code) and reuses it on their own request	Limit lifetime of the token (e.g. 10 minutes) – turning it into a short-lived issue Use signed requests along with nonce and timestamps Validate TLS certificate chain when accessing Resource

Monitoring, Logging and Alerting

Appropriate controls:

• All API interactions MUST be logged

• The request or response payload SHOULD NOT be logged

• PII information MUST NOT be logged

• Sensitive information in headers MUST NOT be logged (e.g. tokens, API Keys etc.)

• Full Content logging MUST NOT be applied

• The use and issuance of Access Tokens MUST be monitored

• Monitoring the Oauth flow SHOULD be performed for suspicious activity and regularly auditing logs can help detect and prevent potential security breaches. This includes monitoring for anomalous requests, access attempts to unauthorized resources, and unusual client behavior.

• Traditional logging, alerting and incident management practices also apply to APIs, along with additional considerations that SHOULD be applied:

  • Correlating API requests with specific back-end system activity and the resulting API responses to support end-to-end tracing - capture timestamps, user/consumer information and actions performed

  • Logging of user actions (login, logout) SHOULD be monitored

  • Identifying specific API requests from consumers to help resolve API consumer problems

  • Detecting events that may indicate a malicious attempt to access an API

  • Logs MUST be stored in a tamper-proof and secure location

• Regular security audits and vulnerability scanning MUST be planned and actioned to help identify and address potential security vulnerabilities in APIs.