Denne siden på norsk

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.

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. The code_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 also 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. If this mechanism is utilized, the API must use separate scopes per endpoint in order to avoid a mixup of DPoP and Bearer Tokens.

• 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.