HelseID protects the most sensitive health APIs in Norway. We therefore have a relatively strict list of requirements that software must fulfill before the software can be accepted as HelseID clients in our production environment. This document lists those requirements and describes the documentation we require from the software supplier.
Normally, NHN performs a code review as part of its acceptance process for software that calls national health APIs protected by HelseID. NHN also performs code reviews of APIs that protect sensitive health information. For other software NHN performs code reviews on a case-to-case basis. In cases where the software supplier cannot share their source code an interview can be an acceptable replacement for a code review.
Software that only does user logon via HelseID | A code review is optional, and the requirement is decided by NHN |
Software that only calls machine-to-machine APIs | A code review is optional, and the requirement is decided by NHN |
Software that combines user logon with API access | A code review or interview is mandatory |
APIs protected by HelseID | A code review or interview is recommended |
Our goal is to ensure that all HelseID clients adhere to a common set of requirements. Most requirements are mandatory, if for some reason these cannot be fulfilled the reason must be presented in the code review or interview. This reason will be evaluated, and the risk assessed by NHN.
1. Protocol Implementation
The following requirements are meant to ensure that the software offers a solid implementation of the OAuth2 and OpenID Connect protocols.
1.1 The software should use a certified OAuth2 or OpenID Connect client library
Implementing protocol support correctly is very challenging. To make this easier, several client libraries are available for most development platforms. For OpenID Connect there is a self-certification checklist that library suppliers can follow. There is also a list of certified client libraries (https://openid.net/developers/certified/). We recommend that all HelseID client are built using one of these libraries.
If no library is available for the development platform the following instructions describe the requirements for a certified OpenID Connect implementation: https://openid.net/certification/instructions/ We recommend that clients adhere to the FAPI 2.0 specification.
Required Documentation
The software supplier describes which client library has been used in the software. If the software supplier has implemented their own protocol support a more thorough review is required.
1.2 The software must implement all requirements of the HelseID security profile
The security profile is available at the following webpage: https://helseid.atlassian.net/wiki/spaces/HELSEID/pages/296583194/Security+profile+for+HelseID+Clients
By following the FAPI 2.0 security profile the software also fulfills all requirements of the HelseID security profile.
Required Documentation
The software supplier describes how the security profile is implemented. A reason must be given for any requirements the software doesn’t implement.
1.3 Access tokens and refresh tokens must not be available outside the application
Access Tokens and Refresh Tokens are considered sensitive information. They must be protected and must not be available outside the boundaries of the software.
Required Documentation
The software supplier describes the software architecture and defines its boundaries. Based on this definition the software supplier describes how they ensure that Access Tokens and Refresh Tokens are properly protected.
2. Handling of secrets
Every HelseID client defines one or more secrets that are used to authenticate the client when accessing the HelseID APIs. A secret is typically a private key. Proper protection of these secrets is an essential part of the trust model that HelseID builds upon.
2.1 Secrets used for client authentication must not be available outside the application
This requirement is similar to #1.3 but considers protecting secrets instead of Access Tokens and Refresh Tokens.
Required Documentation
The software supplier describes the software architecture and defines its boundaries. Based on this definition the software supplier describes how they ensure that secrets are properly protected.
3. Software architecture
HelseID has some architectural requirements for our clients. These requirements are meant to ensure that HelseID clients follow basic security principles and that they use HelseID following the recommended patterns.
3.1 The client software must follow the OWASP best security practices
We recommend that the software supplier studies the OWASP Application Security Verification Standard (https://owasp.org/www-project-application-security-verification-standard/) and the OWASP Container Security Verification Standard (https://owasp.org/www-project-container-security-verification-standard/) if the application is based on container technologies.
All HelseID client suppliers must verify that the software is not at risk for the weaknesses in the OWASP Top 10 Web Application Security Risks (https://owasp.org/www-project-top-ten/).
Required Documentation
The software supplier verifies that their software development process is in line with the OWASP recommendations and follows the requirements in Normen (The Code of Conduct for information security and data protection in the healthcare and care services).
3.2 Calls to the HelseID metadata endpoint must be cached
The HelseID metadata (https://helseid-sts.nhn.no/.well-known/openid-configuration) seldom changes so these must be cached and not downloaded before every request to HelseID.
Required Documentation
The software supplier describes how the software caches the HelseID metadata and how often this cache is updated.
3.3 Calls to the HelseID token endpoint must not be performed unnecessary
Access Tokens have a validity period which is always known by the HelseID client. The client software must not request new Access Tokens if they already possess one that is still valid. At some time before the Access Token expires the client software may request a new one to ensure that they always possess a valid Access Token. Normal lifetime for an Access Token in HelseID is 10 minutes.
Required Documentation
The software supplier describes how they cache access tokens and how they decide to request a new Access Token.
3.4 The HelseID metadata and configuration data must not be hardcoded
The HelseID metadata must be downloaded regularly and cached in the application, see also #3.2. In addition, any HelseID configuration value (scope names, endpoint addresses and so on) must not be stored in the application source code but instead must be contained in configuration files so that they can easily be changed if needed.
Required Documentation
The software supplier describes how they handle metadata from HelseID and how they handle other HelseID related configuration variables.
4. Validation of tokens and claims
These requirements describe how a HelseID client should validate Identity Tokens and how claims in these tokens should be validated and used to perform access control.
4.1 The HelseID guidelines for token validation must be followed
HelseID has published guidelines for token validation at https://helseid.atlassian.net/wiki/spaces/HELSEID/pages/284229708/Guidelines+for+using+JSON+Web+Tokens+JWTs. Every application that uses an Identity Token must follow these guidelines to ensure that it validates tokens according to the industry best practice.
There is normally no need for client application to verify the integrity or contents of an Access Token.
Required Documentation
The software supplier describes how identity tokens are validated.
4.2 Relevant claims from the Identity Token must be validated
Before an Identity Token can be used in an application several claims must be validated. Specifically, the issuer, the audience and the nonce (number used once, https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes) must have the expected values and the current time must be inside the lifetime of the Identity Token.
Required Documentation
The software supplier describes which claims are used for validation of the Identity Token.
4.3 Relevant claims from the Identity Token must be used for access control
All HelseID client applications must validate that the security_level and/or assurance_level claims are at the expected level. They must also validate that the pid, pid_pseudonym or hpr number claims indicate a person that is allowed access to the application.
Applications that only use HelseID to access APIs must also validate that the identity of the person logging on using HelseID is that same as the identity of the locally logged on user.
All claims that HelseID offers can be found here: https://helseid.atlassian.net/wiki/spaces/HELSEID/pages/5570914/Claims.
Required Documentation
The software supplier describes which claims are used for access control and how they are used. Applications that only uses HelseID to access APIs must describe how they ensure that the user logging on using HelseID is the same as the one already logged on to the application.