Functional Requirements for Clients and APIs Integrating with HelseID
| Terms | |
|---|---|
| HelseID | An authorization server, as described in https://www.rfc-editor.org/rfc/rfc6749#section-1.1. Used to secure national APIs within the healthcare sector. |
| Client | A client as defined in https://www.rfc-editor.org/rfc/rfc6749#section-1.1. In the context of HelseID, a client is a software installation that adheres to this security profile. |
| Keywords | The keywords must, must not, shall, shall not, should, and may in this document are to be interpreted as defined in https://www.rfc-editor.org/rfc/rfc2119. |
Functional Requirements for All HelseID Clients
FK1: All clients must use a certified OAuth2 or OpenID Connect client library if one is available for the programming language in use. Our list of recommended client libraries can be found here.
FK2: All clients must utilize information from HelseID’s metadata endpoint rather than hardcoding endpoint URLs and other configuration values. The metadata endpoint will always be available at https://helseid-sts.nhn.no/.well-known/openid-configuration (in production). Metadata should be cached to prevent unnecessary calls to HelseID, we recommend caching for 24 hours.
FK3: Clients shall not request new access tokens if an already issued token remains valid for the intended resource. This implies that the client must implement a caching mechanism where the expires-in parameter defines the token's storage duration.
FK4: Clients must synchronize the local system clock with HelseID. Clients that can access the Health Network may use ntp.nhn.no for this purpose.
FK5: If the client needs to send fine-grained authorization content (e.g., organization number, healthcare professional credentials, or similar) to HelseID’s /token endpoint, it shall use the assertion_details structure as described here.
Functional Requirements for Clients Requiring User Login
These requirements extend the functional Requirements for All HelseID Clients.
FB1: The client shall not use the access token for access control. The access token shall not be inspected by the client and must be treated as opaque.
FB2: The client shall not allow log in for patient, HelseID should only be used to log in employees of the health sector in work-related systems.
Functional Requirements for APIs Secured with HelseID
FA1: The API must use a certified OAuth2 library for token validation if one is available for the programming language in use. Our list of recommended client libraries can be found here.
FA2: The API shall use information from HelseID’s metadata endpoint rather than storing signing keys and other configuration values. The metadata endpoint will always be available at https://helseid-sts.nhn.no/.well-known/openid-configuration (in production). Metadata should be cached to prevent unnecessary calls to HelseID, we recommend caching for 24 hours.
FA3: The API must synchronize the local system clock with HelseID. APIs that can access the Health Network may use ntp.nhn.no for this purpose.
FA4: The FAPI 2.0 profile and the HelseID security profile assumes that all network trafic is done using HTTP. Other protocols and mechanisms may be used, but separate security assessments must be done. Please contact the HelseID team if this is required.