Security profile for HelseID clients and APIs
This document contains the standards to be met for any software that needs to make use of the HelseID service.
Definitions | |
---|---|
HelseID | An authorization server as defined in RFC 6749. Used to secure national e-health APIs in Norway. |
Client | A Client as defined in RFC 6749. In context of HelseID a client is an installation of a software that follows this security profile. |
Confidential Client | Confidential clients are clients which have the ability to maintain the confidentiality of the client_secret. Clients authentication using this secret is mandatory in HelseID. All clients that use HelseID must be confidential clients. |
Client Authentication | The process where an application proves its identity to the Authorization Server. In HelseID this is always done by signing a JWT with a private key that corresponds to a public key that HelseID already has registered. |
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. This information can be verified and trusted because it is digitally signed. |
External API | An open API that is secured by HelseID. |
Internal API | An API that is only available for components inside the client software. |
Keywords | The keywords must, must not, shall, shall not, should, and may in this document are to be interpreted as described in RFC2119. |
The HelseID security profile is aligned with the FAPI 2.0 profile, but there are a few notable differences. These differences are allowed to accomodate the profile to the Norwegian health sector. The differences are as follows:
- HelseID allows a locally installed desktop client to be considered a confidential client
- MTLS for Client Authentication is not supported
- Requests without PAR will not be rejected for clients already in use
- Consent is not required
General requirements for all HelseID clients
Clients must use a certified OAuth2 or OpenID Connect client library if one is available. The HelseID team can help with recommandations for a suitable library.
Clients shall only establish connections to servers, including HelseID, using TLS. All TLS connections shall be set up using TLS version 1.2 or later, and follow RFC 7525. Clients should use TLS 1.3.
Clients shall perform client authentication using "private_key_jwt”, as described by OpenID Connect for interactive sessions. See this link for allowed algorithms.
Clients shall be confidential clients, the public key of the secret must be known to HelseID prior to the client authentication. Pure front-end web applications are not supported by HelseID.
The secret used for client authentication shall only be used for
- authenticating this one client, and
- for creating a DPoP proof to the HelseID server and APIs protected by HelseID that require DPoP
The client must protect the secret used for client authentication from being accessed by the user or any other party except the client software. As long as proper protection is in place, HelseID considers a desktop software a confidential client.
- The secret may be shared among several components inside the boundaries of the client software. See Håndtering av hemmeligheter i distribuerte systemer for an in depth discussion.
Clients must use the HelseID metadata instead of hardcoding endpoint urls and other configuration values. The metadata is always available at https://helseid-sts.nhn.no/.well-known/openid-configuration.
As long as a DPoP enabled endpoint is available for a requested API, Clients must support sender-constrained tokens using “Demonstrating Proof-of-Possession at the Application Layer” (DPoP) as described by RFC9449. DPoP proofs must be formatted as described in the appendix Formatting DPoP proofs. This document provides more information about the subject.
Clients shall send Access Tokens in http authorization headers, as described by RFC 6750, Bearer Token Usage or by RFC 9449, DPoP. Access Tokens must never be exposed in a url.
The client shall never expose tokens to the end user in any way. This means that web clients must implement the HelseID integration in a backend.
Any internal APIs that needs to consume external APIs secured by HelseID must follow this security profile. For instance this means that an internal API cannot be secured by a shared secret if that API allows access to a national API secured by HelseID.
Requirements for machine-to-machine clients
These requirements expand upon the general requirements for all clients.
Clients shall use the Client Credentials flow as described in RFC 6749.
Requirements for clients that supports user logon
These requirements expand upon the general requirements for all clients.
Clients shall use authorization code grant as described in the OpenID Connect specification.
Clients shall use "Proof Key for Code Exchange" (PKCE), as described in RFC 7636, to mitigate against code interception and other attacks. Clients must use the
S256
code_challenge_method. Thecode_challenge
value must be unique for each request as described in RFC 7636, section 7.1.All new clients must use the Pushed Authorization Requests (PAR) mechanism to avoid passing unnecessary information via the user agent as described in RFC 9126.
Clients shall use the
authorization_details
structure, as defined by IETF in the specification Rich Authorization Requests if it needs to pass fine graind authorization requirements to the/authorize
endpoint.Clients shall use the
assertion_details
structure if it needs to pass fine graind authorization requirements to the Token endpoint.Clients shall check the the validity of the
iss
parameter in the authorization response to prevent mix-up attacks.The client must validate the ID-Token according to these rules.
The client must not use the Access Token for access control. The Access Token should be considered opaque by the client.
A client that performs a local logon in addition to a HelseID logon must validate that both user identities belong to the same person. This is done by either comparing the Pid-claim or the HPR Number-claim against the corresponding claim on the local user identity.
Clients shall implement protection against XSS and CSRF attacks. Please refer to external sources like OWASP for details about how to test and secure a client.
Clients shall not expose open redirectors where the client is vulnerable to malicious redirections.
The client shall protect against attacks via HTTP Header
The client shall protect against attacks via Javascript (e.g. XSS attacks)
Requirements for APIs protected by HelseID
The API must use a certified client library for token validation if one is available. The HelseID team can help with recommandations for a suitable library.
The API endpoint must only accept Access Tokens, alternative mechanisms like API keys can only be allowed in separate endpoints.
The API must validate Access Tokens as specified in the appendix Validating Access Tokens.
The API must offer an endpoint that supports DPoP. The API may offer a separate endpoint that uses Bearer tokens to be backwards compatible with older clients. An API must not accept both DPoP and Bearer tokens at the same endpoint.
The API must validate DPoP proofs as specified in the appendix Validating DPoP proofs.
Further information for APIs
See this checklist for how to secure your API.