The usage of organization numbers
If a client software needs to consume an API that wants organization numbers in the Access token, either as a parent unit, or as a child unit, the software must send a JSON structure (described below) to HelseID. This structure will then contain one or two organization numbers.
It is only organization which have signed membership terms for Helsenettet which can get access to health data in Helsenettet. For that reason the Access Tokens issued by HelseID have information about which organization the authorization is done in context of. HelseID has three claism that point to organization numbers.
orgnr_parent
This organizationnumber says who is data responsible in the exchange of health records. This organization must be a member of Helsenettet by signing the membership terms. For services that require a signed service offer it is this organization that has to sign the service offer.
It is the parent unit in Brønnøysundregistrene that has to be a member of helsenettet (not org ledd or sub units). There are some exceptions, see more information on this page:https://www.nhn.no/medlemskap-i-helsenettet/nye-medlemsvilkar
Hvor data kommer fra
HelseID has two mechanisms to know the context of an authentication:
- Single tenant clients are owned by an organization and it is this organizations organizationnumber which is set in orgnr_parent. All authentications with this client will get the same organizationnumber and it will be static for this client.
- Multi-tenant clients are owned by the supplier. The organizationnumber for the member is sent in dynamically during runtime when the client authenticates with HelseID. The supplier is responsible for having control over which context their users are in then they log in. The supplier is responsible for their implementation always fulfilling HelseIDs securityprofile.
There will always be an orgnr_parent set in the access token.
orgnr_child
This organizationnumber often represent where the treatment took place. Note: orgnr_child does not need to be a direct descendant of orgnr_parent in Brønnøysundregistrene. Examples of organizationnumbers in orgnr_child:
- The organizationnumber for an nursing home where nursing staff performed a treatment
- The organizationnumber for a clinic where imaging diagnostics took place
Hvor data kommer fra
The data is sent in during runtime from the journaling system, for both single tenant and multi tenant. It is the suppliers responsiblity to make sure this information is correct when it is sent to HelseID. HelseID has no way to validate this information on their end. It is not obligatory to send in orgnr_child, so orgnr_child will not always be set in the access token.
orgnr_supplier
This claim only applies to authentications done by multi tenant clients. This value is the organizationnumber of the organization that represents the member in the authentication with HelseID. The member has given orgnr_supplier an authorization (norwegian: fullmakt) for them to represent the member in HelseID.
ℹ️ Note: single-tenant clients
For single-tenant clients that needs to consume one or more APIs which only need orgnr_parent the organization number will be automatically set in the Access token, without the need for the software to send in a JSON structure to HelseID. If the API also needs orgnr_child, the software needs to send in a JSON structure as described below.
Patterns for transfering organization numbers
Various patters for sending in a JSON structure (as shown below) with organization numbers to HelseID can be used.
Machine to Machine (M2M)
If a logged-in user is not required, you can use the Machine to Machine flow (Client Credentials). In this case, the client software must create a request to the Token endpoint, where the value for grant_type is client_credentials, and the JSON structure is located in the client assertion.
Having a logged-in user
If the client software needs a logged-in user, you can make a call to the Token endpoint, by passing the JSON structure in the client assertion object. The value for grant_type in this case will be refresh_token. This is the recommended pattern, as the user can represent multiple organizational units without having to log in again.
There is also another pattern, where the client can use the PAR endpoint by submitting the JSON structure in a Request object. This can be used if your client does not have the ability to add organization numbers to the client assertion object. If you use this pattern, the user must reauthenticate every time they represent a new organizational unit.
The JSON structure for including organization numbers in requests to HelseID
Disregarding what kind of pattern you use for the transfer of organization numbers to HelseID, you must use a JSON structure for this purpose. This structure will have a different content, dependent on whether the client software that transfers the organization number information is either single-tenant or multi-tenant.
The JSON structure for including organization numbers for single-tenant clients
Single-tenant clients do not include the organization number for any parent unit: this information is already in HelseID's database.
The following structure must be used for transmitting an organization number for a child unit:
{
"type":"helseid_authorization",
"practitioner_role": {
"organization": {
"identifier": {
"system":"urn:oid:2.16.578.1.12.4.1.4.101",
"type":"ENH",
"value":"974589605"
}
}
}
}
Notice that only the organization number for the child unit (974589605) is transmitted in this structure. Also not that the system value needs to have the value urn:oid:2.16.578.1.12.4.1.4.101.
The JSON structure for including organization numbers for multi-tenant clients
Multi-tenant clients include the organization number for a parent unit, and may also include the organization number for a child unit.
The following structure must be used for transmitting a organization numbers for a parent unit, and possibly, a child unit:
{
"type":"helseid_authorization",
"practitioner_role": {
"organization": {
"identifier": {
"system":"urn:oid:1.0.6523",
"type":"ENH",
"value":"NO:ORGNR:972418013:974042436"
}
}
}
}
In this case, organization numbers for both the parent unit (972418013), and for the child unit (974042436?) are set in this structure. Also not that the system value needs to have the value urn:oid:1.0.6523.
If the clients only want to send the organization number for a parent unit, the parameter value must be set as this:
"value":"NO:ORGNR:972418013",
An example of a complete structure
The Token Endpoint
The example below shows a structure for organization numbers using the authorization_details claim, passed as a client_assertion object in a call to the Token Endpoint. In this case, the client is set up as a multi-tenant client.
{
"alg": "PS256",
"kid": "B2C61A07EE0661237D19BEE1E0A1463C",
"typ": "client-authentication+jwt"
}.{
"authorization_details":
[{
"type":"helseid_authorization",
"practitioner_role": {
"organization": {
"identifier": {
"system":"urn:oid:1.0.6523",
"type":"ENH",
"value":"NO:ORGNR:972418013:974042436"
}
}
}
}],
"sub": "f7cd1256-0526-4b5a-b4c3-f054c984ace8",
"iat": "1716644273",
"jti": "cf6a320674cf44cba9177ac6f84103a3",
"nbf": 1716644273,
"exp": 1716644333,
"iss": "f7cd1256-0526-4b5a-b4c3-f054c984ace8",
"aud": "https://helseid-sts.test.nhn.no"
}.[Signature]
The PAR endpoint
You can use a Request object on the PAR endpoint for this, but in most cases it will be most convenient to pass organization numbers in the Token endpoint.
The example below shows a structure for organization numbers using the authorization_details claim, passed as a Request object in a call to the Par endpoint. In this case, the client is set up as a multi-tenant client.
"authorization_details":
[{
"type": "nhn:sfm:journal-id",
"value": {
"journal_id": "ed30a6a5-4834-40be-a32b-1e4f5217e378"
}
},
{
"type":"helseid_authorization",
"practitioner_role":
{
"organization":
{
"identifier":
{
"system":"urn:oid:1.0.6523",
"type":"ENH",
"value":"NO:ORGNR:972418013:974042436",
}
}
}
}]