How to submit organizational information to HelseID, machine-to-machine
Target Audience
This specification is intended for developers who will integrate Kjernejournal Portal (and HelseID) into a professional system used in the nursing and care sector.
Background
Kjernejournal Portal (aka the Health Personnel Portal - HPP) for the nursing and care sector requires to know which health institution (or subunit) the user is working for at the time of the request. In addition Kjernejournal Portal needs to know the municipality that owns the health institution. This information must be included in access tokens issued by HelseID.
In many cases, the EHR system is the only party that knows this information, and because HelseID allready establishes a trust relationship with the EHRs on behalf of Kjernejournal we have implemented mechanisms that enables the EHR systems to send the neccessary contextual information to HelseID.
This document describes how this is done in in the context of machine-to-machine communication with the “Helseindikator”-service in Kjernejournal.
Underlying technical mechanisms
In order to send information to HelseID in a secure way, we support sending claims from the client in a JWT-based client_assertion . This allows you to use a signed JWT to send parameters to the token endpoint in HelseID in a client credentials flow (machine-to-machine).
The information included in the JWT is formatted as a JSON-structure. The structure and content are based on open standards such as Rich Authorization Requests and the FHIR format. In the future, this structure can also be used to submit other information from the client system to HelseID (role, service needs, technical information about the subject system, etc.).
Prerequisites
The following must be in place for HelseID to approve a treatment site / subunit.
POST must be used
Signed JWTs can be large, and there are size restrictions in web servers on GET requests. POST must therefore be used when sending requests to the token endpoint in HelseID.
Valid sub-units must be pre-registered in HelseID
HelseID validates all claims about subunits that come from a client. The sub-units that are valid for a client must therefore be pre-registered in HelseID. A self-service system is currently being worked on to deal with this. Until this is in production valid sub-units must be registered manually by personnel in HelseID until further notice.
Public key for validation of Client Assertion JWT must be pre-registered in HelseID
When HelseID receives a claim for a subunit from a subject system, the signature on the containing JWT is validated. The public key to be used for this must be pre-registered in HelseID as a secret for the client configuration. A self-service system is currently being worked on for issuing keys. Until this is in production, public keys must be registered manually by personnel in HelseID.
Specification
Client Assertion
A client assertion is sent as the following parameters in the authorization request to the token endpoint:
client_assertion: signed_jwt_base64_coded
client_assertion_type: "urn: ietf: params: oauth: client-assertion-type: jwt-bearer"
Rules for signed_jwt_base_64
JWT MUST be signed with a minimum of RS256.
JWT MUST include the claim nbf (which indicates when JWT is valid from). .
JWT MUST include the claim exp (which indicates when JWT is no longer valid). Maximum life of JWT is 60 seconds.
JWT MUST include the claim iss which is set to client_id for the subject system.
JWT MUST include the claim sub which is set to client_id for the subject system.
JWT MUST include the claimed aud which is set to url to the token endpoint in HelseID for relevant environment. This value can be found in the "issues" claim in our metadata, for our test environment the value is " https://helseid-sts.test.nhn.no/connect/token ", see https: //helseid-sts.test. nhn.no/.well-known/openid-configuration
Example of signed client assertion
HEADER_JWK.
{
"nbf" : 1575463285 ,
"exp" : 1575463345 ,
"iss" : "your_client_id_here",
"sub" : "your_client_id_here",
"aud" : "https://helseid-sts.nhn.no/connect/token",
"authorization_details" : {SEE BELOW FOR FORMAT}
}.
SIGNATUREAuthorization Details
To enter the organization number of the treatment site, the following structure must be used. This structure expresses the following:
"[orgnummer] is an identifier from the “enhetsregister” that represents the business in which a healthcare professional currently has a role". In the future, more context will be provided in this structure, such as the role of health personnel or a more detailed location.
"authorization_details" : {
"type" : "helseid_authorization" ,
"practitioner_role" : {
"organization" : {
"identify" : {
"system" : "urn: oid: 2.16.578.1.12.4.1.2.101" ,
"type" : "ENH" ,
"value" : "[orgnummer]"
}
}
}
}Explanation of the elements in the Authorization Details structure
Name | Defined by | Description |
authorization_details | The Rich Authorization Requests specification | Parameter Name for Rich Authorization Requests. |
authorization_details.type | HelseID | Type of authorization request. The only valid value is "helseid_authorization". |
practitioner_role | FHIR | FHIR connects organization and health personnel through the role of the health personnel. |
organization | FHIR | The organization health personnel have a role in. |
identifier | FHIR | Unique identification of organization. |
system | FHIR / e-health | Organization.system contains a uri (in this case an OID) that uniquely identifies the register in which the organization is registered. Must have value " urn: oid: 2.16.578.1.12.4.1.2.10 " which indicates the register of legal entities in Norway - “Enhetsregisteret”. |
identifier.type | FHIR / e-health | Description of the register in which the organization is registered. Must have value " ENH " which indicates the register of legal rntities in Norway - “Enhetsregisteret” |
value | FHIR | The identifier of the treatment center / subunit, ie a Norwegian organization number from the “Enhetsregister”. Nine digits. |
Example of full request
Below is an example of an http request to the authorization endpoint that includes a claim for a treatment site.
request
https://helseid-sts.nhn.no/connect/token
Body (POST)
client_id: request_object_demo_client_id
grant_type: client_credentials
scope: [scopes]
client_assertion: eyJhbGci .... (abbreviated, see below)
client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearerDecoded version of client_assertion looks like this
Sample Code
Runnable sample code is here:
https://github.com/NorskHelsenett/HelseID.Samples/tree/master/ClientCredentials
8 References
This is a list of the specifications and coding systems we have relied on.
Description | link |
Client Assertion JWT | |
Rich Authorization Objects | |
FHIR PractionerRole | |
FHIR Organization | |
FHIR Identifier | |
Encoding for Identifier |