Requirements for all HelseID clients

• 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. TLS 1.3 is recommended by NHN.

• 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. Clients must always authenticate using this secret.

• 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

Instead of using a private/public key pair for client authentication, an enterprise certificate (virksomhetssertifikat) may be used, but only for authenticating one client. The use of enterprise certificates is legacy functionality, and will not be accepted for new clients.

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

• Clients should pass request parameters as JWT as described by OIDF in OpenID Connect, and as detailed by HelseID (link her til dokument i utviklerportalen).

• Clients must use the HelseID metadata instead of hardcoding endpoint urls and other HelseID metadata.

• Clients shall send Access Tokens in http authorization headers, as described by RFC 6750. 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. Pure front-end web applications are not supported by HelseID.

• Clients must use a certified OAuth2 or OpenID Connect client library if one is available. A list of certified Open ID libraries can be found here.

• Communication between components inside a client must follow the same requirements as communication between the client and HelseID. For instance this means that an internal api cannot be secured by a shared secret.

Future requirements

• Clients shall support sender-constrained tokens using “Demonstrating Proof-of-Possession at the Application Layer” (DPoP) as described by draft-ietf-oauth-dpop.

• Clients shall pass request parameters as JWT as described by OIDF in OpenID Connect (link her), and as detailed by HelseID (https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests).

Requirements for machine-to-machine clients

• Clients shall use the Client Credentials flow as described in RFC 6749.

• If the client needs to pass fine grained authorization information to HelseID, that information must be included in the client assertion as specified in the HelseID documentation (link her til dokument i utviklerportalen).

Requirements for clients that supports user logon

• Clients shall use authorization code grant, as described by IETF in OAuth 2.0 and by OIDF in OpenID Connect for interactive sessions (https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).

• Clients shall use PKCE, as defined by IETF in RFC 7636 - Proof Key for Code Exchange, to mitigate against code interception and other attacks. Clients must use the S256 `code_challenge_method.

• Clients may use the nonce parameter in addition to PKCE

• Clients shall either use the “authorization_details” structure, as defined by IETF in the specification Rich Authorization Requests, or similar claims in the client assertion if it needs to pass fine grained authorization requirements to HelseID. Be aware that only authorization details is accepted for use against the Dokumentdeling APIs.

• Clients shall check the the validity of the “iss” parameter in the authorization response to prevent mix-up attacks.

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

• The client must validate the ID-Token according to the guidelines given in the HelseID documentation (link til dokument i utviklerportalen her).

• The client must not use the Access Token for access control.

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

Future requirements

• The client must use the Pushed Authorization Requests (PAR) mechanism to avoid passing unnecessary information via the user agent as described in RFC 9126.

Requirements for APIs protected by HelseID

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

• The API must validate the signature of the Access Token against the public key exposed in the HelseID metadata.

• An API that requires information about a logged on user must validate both the users identity (PID or HPR number) and the security level of the identity.

• An API endpoint that accepts a DPoP token must not accept Bearer tokens as well

• The API must use a certified client library for token validation if one is available

• The API should validate that it is the only audience in the Access Token. Access Tokens with multiple audiences are not recommended but may be acceptable in some cases.

• An API that supports DPoP must not accept bearer tokens at the same endpoint. The API may expose separate endpoints for each authentication scheme.