This document is an appendix to the HelseID security profile. Its purpose is to explain the rationale behind the various requirements so that vendors can better adapt their solutions.
General Requirements for All HelseID Clients
Requirement for Use of TLS (SK1)
TLS is now the industry standard for all internet communication. Implementation cost is low, and the overhead is minimal.
The OAuth2 threat model assumes confidentiality is guaranteed through TLS. If this assumption fails, the use of OAuth2 and OpenID Connect must be reconsidered.
Therefore, we require TLS for all traffic over open networks and recommend its use internally as well.
Requirement for Client Authentication Using private_key_jwt (SK2)
HelseID does not allow any client authentication mechanisms other than private_key_jwt. This mechanism uses asymmetric cryptography with key pairs. The client holds a private key, and HelseID only knows the public key, which can be used to verify digital signatures.
This mechanism offers two advantages over the more common client_secret method, where client authentication is performed using a shared password known to both the client and HelseID. The first advantage is that HelseID never has access to the private key; only the client retains possession of it.
The second advantage is that, in practice, securing a key pair is generally easier than securing a password. Many operating systems provide robust mechanisms for storing signing keys such that only designated users or processes can access them.
Requirement for Confidential Clients and Use of Key Pairs (SK3, SK4, SK5)
Most APIs protected by HelseID provide access to sensitive health information concerning large populations. The consequences of unauthorized access to such data are sufficiently severe that HelseID does not permit clients incapable of adequately protecting a secret. Furthermore, in HelseID, the client secret is bound to an organization; this binding mechanism enables the inclusion of organizational information in the access token.
While numerous mechanisms exist for protecting secrets in pure web applications, none offer a sufficient level of security for HelseID’s use case. HelseID does, however, permit locally installed thick clients to be treated as confidential clients. This exception is made to maintain compatibility with the many legacy journal systems currently in use, a significant portion of which are locally installed thick clients. HelseID requires that the client secret be protected with the same rigor as the health data managed by the client.
A commonly accepted principle in key pair management is that a key pair should be used for a single purpose. This practice serves both to prevent unauthorized use and to avoid operational ambiguity.
HelseID imposes no requirements on how key pairs are issued; it is the responsibility of the client vendor to establish an appropriate issuance procedure. Consequently, there should be minimal or no need to reuse a key pair for multiple purposes. A list of supported algorithms and key lengths is available here.
HelseID’s self-service solution provides an API for automatic key rotation. By utilizing this API, client vendors can easily replace keys generated by the client as needed.
Requirement for Use of DPoP (SK6)
The threat and attacker models for OAuth2 identify the leakage of access tokens as a significant security risk. Fundamentally, there is no inherent guarantee that the entity presenting an access token is the legitimate client. Consequently, the API must rely on the assumption that the client is sufficiently secured. There are numerous vectors through which an access token may be compromised—for example, it may be exposed in the client’s user interface, logged inadvertently, or intercepted by network monitoring tools.
To mitigate the risk of access token misuse, HelseID mandates that all clients and APIs implement the Demonstrating Proof of Possession at the Application Layer (DPoP) mechanism. When properly implemented, DPoP enables the API to confidently verify that the client presenting the token is its rightful owner.
DPoP requires adaptations in both the client and the API. This has led to a situation where client vendors await DPoP support from APIs, while API providers await sufficient client adoption. To accelerate this transition, HelseID requires that all new APIs support DPoP and that all clients implement DPoP support. Because DPoP is backward-compatible with traditional Bearer tokens, clients may adopt the mechanism even if the APIs they interact with do not yet support it.
Requirement for Access Token Protection (SK7, SK8)
Both of these requirements are intended to mitigate the risk of access token misuse. Although the likelihood of misuse is reduced when using DPoP, HelseID maintains these requirements to further minimize the probability of such incidents.
Requirement for Internal Security Compliance (SK9)
HelseID is a large ecosystem that safeguards highly sensitive health information. The level of trust between the API providing the health data and the owner of the client retrieving it is high, and therefore, an attack against such a client would have significant consequences.
If an internal API acts as an intermediary to an external API secured by HelseID, the internal API MUST implement the same security requirements. This ensures that the internal API does not become a weak link capable of compromising the trust chain.
Requirement for General Web Security (SK10)
Most clients integrating with HelseID are web applications. Therefore, HelseID imposes specific requirements to ensure their security. These requirements are based on known vulnerabilities and implementation flaws that could expose the APIs protected by HelseID. Such requirements are less relevant for thick clients, as attacks against them typically require access to the local machine on which the client is running.
Requirement for Use of a Certified Client Library (FK1)
OAuth2 and OpenID Connect have evolved into complex protocols that are challenging to implement correctly. The consequences of incorrect implementation are significant, both for the client and for the APIs with which the client integrates. Therefore, it is REQUIRED that vendors employ pre-existing libraries wherever such libraries are available for the programming language in question. In cases where no library fully satisfies all requirements, it is MANDATORY to use an available library to the greatest extent possible.
HelseID has published a list of recommended client libraries here.
Requirement for Use of the HelseID Metadata Endpoint (FK2)
A large number of clients and APIs integrate with HelseID. Changes to the service may necessitate updates across many systems; therefore, systems must be designed to be as flexible as possible.
By consuming metadata from HelseID rather than hardcoding values, changes can be made without requiring modifications to dependent systems. This is particularly relevant for clients performing user authentication and APIs, as these require access to HelseID’s signing keys to validate Identity or Access tokens.
It is recommended that metadata be cached for a duration of one day. If a client or API receives a token that cannot be validated, it may attempt to re-fetch the metadata in case updates have occurred.
Requirement for Caching of Access Tokens (FK3)
HelseID has become a critical component in the Norwegian healthcare sector; therefore, it is essential to protect the service from unnecessary or improper usage. An Access Token always has a defined lifetime, and within this period, the token must be reused rather than requesting a new token for each API call.
Reusing Access Tokens yields several benefits. It reduces traffic to HelseID, improves client response times by avoiding HTTP requests to HelseID, and enhances client availability by allowing continued operation even if HelseID is temporarily unavailable.
Requirements that the system clock must be synchronized (FK4)
NHN has observed multiple failures caused by discrepancies between the system clocks of the client and HelseID, or the API being called. These issues are particularly evident during validation of DPoP proofs, but may also result in authentication failures and other errors.
Such failures are difficult to troubleshoot due to their transient nature. To prevent these issues, all clients must ensure that their system clocks are synchronized with HelseID and NHN, minimizing any time drift.
Requirement for Mechanisms to Transmit Information from Client to HelseID (FK5)
HelseID provides mechanisms for receiving information from the client that is to be exposed as claims in the Access Token. This mechanism is primarily used for transmitting organizational information, but it may also be used to submit the healthcare professional attestation (trust framework) or journal-id for SFM.
The application should transmit this information via the Token endpoint. The mechanism used is a HelseID-specific extension of the standards. HelseID does not recommend submitting this information via a Request Object to the PAR endpoint. The rationale is that implementation is simpler using the Token endpoint and, in most cases, the user experience is improved.
Requirements for Machine-to-Machine Clients (SC1)
Although OAuth2 defines mechanisms other than Client Credentials Grant for obtaining Access Tokens without active user involvement, HelseID has chosen to support only this mechanism. The rationale is that it is relatively straightforward to implement, widely supported by existing libraries, and aligns well with other parts of HelseID’s security profile.
Requirements for Clients Requiring User Authentication
Requirement to Use Authorization Code Flow and Associated Mechanisms (SB1, SB2, SB3)
These requirements define the foundational approach to user authentication in HelseID. Alternative flows that support user authentication are no longer considered secure. Even the Authorization Code Flow must be secured with PKCE to mitigate known attack vectors. PAR further reduces the risk of exploitation by protecting a range of sensitive parameters that would otherwise be transmitted via the browser.
Requirement for Validation of ID Tokens (SB4)
Several known attacks against the OpenID Connect protocol involve deceiving an application into accepting a forged token. If the application does not adequately validate the ID Token, an attacker may succeed in gaining access despite lacking proper authorization.
Clients can control which claims are included in the ID Token by requesting the HelseID-specific scopes, as described here (scopes) and here (claims corrresponding to scopes).
Requirement for Linking Local and External User Identity (SB5)
This requirement applies only to applications where the user initially authenticates using mechanisms other than HelseID and subsequently authenticates via HelseID to access national APIs. In such applications, there exists a risk that the two authentications are performed by different individuals, potentially resulting in unauthorized disclosure of health information. For example, a user may log in locally using a username and password, and then borrow another person’s BankID to authenticate with national shared services.
To mitigate this risk, the application must verify the national identity number or HPR number of the authenticated user against the corresponding values in the ID Token. It is not sufficient to verify the user's name, and HelseID does not provide alternative claims suitable for confirming user identity.
Systems that utilize HelseID for initial authentication are NOT subject to this requirement.
Requirement That Clients Do Not Inspect the Contents of the Access Token (FB1)
This requirement serves both to protect the client from implementation errors and to facilitate future changes by HelseID.
The contents of an Access Token are not controlled by the client; they are tailored to the needs of the target API. As API requirements may evolve over time, applications risk encountering failures that are difficult to manage. For example, an API that initially requires a user's national identity number may later switch to using the HPR number. If the client extracts the identity number from the Access Token, it will fail once the API changes its expectations.
Clients can control which claims are included in the ID Token by requesting the HelseID-specific scopes, as described here (scopes) and here (claims corrresponding to scopes).
Currently, HelseID issues JSON Web Tokens with digital signatures in JWS format. These tokens can be read and verified by any party with access to the token. In the future, HelseID may transition to encrypted tokens using the JWE format or to reference tokens, which require a call to HelseID to retrieve token contents. Applications that rely on reading Access Token contents will fail under these conditions.
Instead of inspecting the Access Token, applications should use the ID Token and the response from the Token endpoint. The response includes an expires_in parameter indicating the token’s validity duration, which should be used to determine token reuse. Additionally, the response includes a scope parameter indicating the scopes granted by the Access Token.
Requirement That Citizens or Patients Cannot Use HelseID for Authentication (FB2)
HelseID is designed for authentication in a professional context. The purpose of the service is to make it as simple and secure as possible for healthcare sector employees to access the various services secured by HelseID. One of the measures implemented by HelseID to achieve this is to avoid requesting consent from the individual logging in for the client to access their data and call APIs on their behalf. In HelseID, this consent is assumed to be granted as part of the employee’s contract with their employer.
For citizens, this assumption cannot be made. If citizens are to log in, HelseID must be extended with functionality to provide consent when authentication is performed as a citizen rather than as a healthcare sector employee.
Requirements for APIs Secured by HelseID
Requirement to Use a Certified OAuth2 Library (FA1)
The rationale for this requirement is identical to that for clients.
Requirement for Use of the HelseID Metadata Endpoint (FA2)
The rationale for this requirement is identical to that for clients.
Requirements that the system clock must be synchronized (FA3)
The rationale for this requirement is identical to that for clients.
Requirement for use of HTTP for APIs (FA4)
The HelseID security profile is based on the FAPI 2.0 profile, which in turn builds upon a highly detailed threat and attacker model developed for the OAuth2 protocol. A fundamental assumption in these models is reliance on the existing security mechanisms provided by the HTTP protocol.
It is possible to use tokens issued by HelseID in other contexts, and there are several examples of such usage in production today. However, this usage is based on thorough prior risk assessments.
Please contact the HelseID team if you have such a requirement, and we will assist in analyzing your case.
Requirement to Avoid Mixing Access Tokens with Other Access Control Mechanisms in the Same Endpoint (SA1)
The purpose of HelseID’s security profile is to establish a shared understanding of adequate technical security for the exchange of health information between entities in the Norwegian healthcare sector. The profile is based on assumptions regarding attacker capabilities and the countermeasures implemented to mitigate those threats. (link to BCP here)
Mixing OAuth2 with other security mechanisms invalidates these assumptions and requires a full reassessment from first principles. The scope of such an effort is prohibitively large, and therefore such mixing is not permitted. It is assumed that providing multiple endpoints will not impose significant additional effort for API providers. Furthermore, this approach improves clarity for clients regarding supported authentication mechanisms and simplifies maintenance of access control logic.
Requirement for Access Token Validation (SA2)
There are numerous details that must be verified for an API to make correct access control decisions. A certified library will validate all standard claims and thereby ensure trust in the token itself. However, the API must implement its own checks for organization number or user identity if such validation is required.
Requirement That the API Supports DPoP (SA3, SA4, SA6)
The rationale for these requirements is identical to that for clients. The HelseID team is available to assist API providers with the implementation of DPoP if needed. Proper validation of DPoP proofs is complex; therefore, it is required to use a certified library for this purpose whenever possible.
Note that in a redundant environment where multiple instances of the API are running concurrently, all instances must share state (typically via a distributed cache) to protect against replay attacks involving DPoP proofs.
Requirement That DPoP and Bearer Tokens Are Not Accepted on the Same Endpoint (SA5)
The purpose of DPoP is to protect the API from misuse of stolen Access Tokens. A Bearer Token (i.e., an Access Token not protected by DPoP) can be used by any party that obtains it, and the API has no inherent means to verify the identity of the token holder. DPoP enables the API to verify that the token is being used by the legitimate client and not by an attacker.
Since the introduction of DPoP constitutes a breaking change for the API, the mechanism is designed to be backward compatible with traditional Bearer Tokens. This means a client may use a DPoP Token against an API that only supports Bearer Tokens without requiring changes to the API. Most APIs adopting DPoP will continue to support Bearer Tokens on a separate endpoint to avoid breaking existing clients during a transition period.
On one hand, these two measures offer significant advantages: they allow clients to adopt DPoP selectively across APIs and enable APIs to gradually enforce DPoP. On the other hand, this introduces risk, as a stolen DPoP Token may be misused against endpoints that still accept Bearer Tokens. Thus, the introduction of DPoP provides no security benefit if the API supports both token types on the same endpoint.
By requiring separate endpoints and distinct scopes, we ensure that DPoP delivers its intended security benefits even when Bearer Token support is retained. These two measures are partially overlapping, but the general recommendation is to implement both.
Requirement for General Web Security for APIs (SA7)
APIs secured by HelseID are accessible either via the Internet or through the Helsenett. Therefore, it is essential that these APIs adhere to best practices for securing web services.