Security Requirements for Clients and APIs Integrating with HelseID
This document outlines the standards required for any software intending to utilize the HelseID service.
| Terms | |
|---|---|
| HelseID | An authorization server, as described in RFC 6749. Used to secure national APIs within the healthcare sector. |
| Client | A client as defined in RFC 6749. In the context of HelseID, a client is a software installation that adheres to this security profile. |
| Confidential Client | Confidential clients are capable of maintaining the confidentiality of a client secret. All clients utilizing HelseID must authenticate using such a secret. Any client using HelseID must be a confidential client. |
| JWT | JSON Web Token is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. The information can be verified as valid because it is digitally signed. |
| Client Authentication | The process by which a client proves its identity to the authorization server. In HelseID, this is always performed by signing a JWT with a private key, such that the corresponding public key is registered with HelseID. |
| External API | An API secured with HelseID. |
| Internal API | An API accessible only to components within the client’s software. |
| Keywords | The keywords must, must not, shall, shall not, should, and may in this document are to be interpreted as defined in RFC2119. |
Security Requirements for All HelseID Clients
SK1: All clients shall establish connections to servers, including HelseID, using TLS. All TLS connections shall be configured using TLS 1.2 or higher, and shall comply with RFC 7525. Clients should use TLS 1.3. Internal traffic within the client’s network should also be secured with TLS.
SK2: All clients shall perform client authentication using private_key_jwt, as described in Use of client assertion for client authentication in HelseID. See Cryptographic Requirements for approved algorithms.
- The expiration time (
exp-claim) for the client_assertion shall not be set to more than 10 seconds in the future.
SK3: All clients must be confidential clients, and the public key of the client secret must be known to HelseID prior to authentication. Web applications without a backend (frontend-only code) are not accepted for use with HelseID.
SK4: A client must protect the confidentiality and integrity of the secret used for client authentication; only the software shall have access to the secret. Provided the secret is sufficiently protected, HelseID will also accept thick-client software as a confidential client.
- The client secret may be shared among multiple components within the software boundary. See Handling Secrets in Distributed Systems for further information.
SK5: The secret used for client authentication shall only be used for:
- authenticating a single client to HelseID, and
- generating a DPoP proof to the HelseID server and any API secured with HelseID that requires DPoP.
SK6: If a client consumes an API, it must support sender-constrained tokens using "Demonstrating Proof-of-Possession at the Application Layer" (DPoP), as described here. DPoP proofs must be formatted as described in the appendix Formatting DPoP Proofs. This requirement applies even if the API has not yet implemented DPoP support.
SK7: All clients shall transmit access tokens in HTTP authorization headers, as described in RFC 6750 or RFC 9449. Access tokens shall not be exposed in URLs and shall not be made available to end users.
SK8: Clients shall not expose the contents of tokens to end users in any way. This means web clients must implement integration with HelseID in the backend.
SK9: Any internal API that needs to consume an external API secured with HelseID must also comply with this security profile. This means an internal API cannot be secured using authentication mechanisms not permitted by HelseID. For example, use of a shared secret (client_secret) is not acceptable if the API requires access to a national API secured with HelseID.
SK10: Clients shall be up to date with measures to address the most well-known security risks according to OWASP Top Ten.
Security Requirements for Clients Requiring User Login
These requirements extend the general requirements for all HelseID clients.
SB1: Clients shall use the "Authorization Code Flow" as described in the OpenID Connect specification.
The response_type parameter must have the value code, other values will be rejected.
SB2: Clients shall use "Proof Key for Code Exchange" (PKCE), as described in RFC 7636, to mitigate risks such as code interception and other known attacks. Clients must use the value S256 for the code_challenge_method parameter. The value of the code_challenge parameter must be unique for each request, as described in RFC 7636.
SB3: Clients must use the "Pushed Authorization Requests" (PAR) mechanism to avoid transmitting unnecessary information through the browser. This is described in RFC 9126.
SB4: Clients shall validate the ID token from HelseID according to these rules.
SB5: A client that performs local user login in addition to login (e.g. username/password using a local user database og login to a local domain) via HelseID shall validate that both user identities belong to the same individual. This is done by comparing either the pid claim (national identity number) or the HPR number claim with corresponding information in the local user identity.
Security Requirements for Clients Not Requiring User Login
These requirements extend the general requirements for all HelseID clients.
SC1: Clients must use the “Client Credentials Grant” as described in RFC 6749.
Security Requirements for APIs Secured with HelseID
SA1: An API endpoint shall only accept access tokens. Other security mechanisms, such as API keys, may only be used on separate endpoints.
SA2: The API must validate access tokens as specified in the appendix Access Token Validation.
SA3: The API must provide an endpoint that supports DPoP.
SA4: The API must validate DPoP proofs as specified in the appendix DPoP Proof Validation.
SA5: Existing APIs may also offer a separate endpoint using Bearer tokens to maintain backward compatibility with legacy clients.
- The API shall not accept both Bearer tokens and DPoP tokens on the same endpoint.
- The API must use distinct scopes per endpoint to ensure that DPoP and Bearer tokens cannot be used interchangeably.
SA6: New APIs shall not support Bearer tokens.
SA7: APIs shall be up to date with measures to address the most well-known security risks according to the OWASP API Security Top Ten.