Passing organization identifier from a client application to HelseID
Background
To use Kjernejournal (the norwegian Core Journal -“KJ”from now on), information about the place of treatment (in addition to“juridisk person”- in most cases the organization number of the municipality) is required to be included in access tokens issued by HelseID. This is information which only the system accessing KJ knows at the time of treatment. Therefore, mechanisms have been implemented to transmit this information to HelseID when the user authenticates.
HelseID supports two methods of passing organization numbers from the client. The most commonly used mechanism allows the client to specify the place of treatment (child unit) the user represents while the parent unit is set as a fixed value on the client configuration. The other mechanism allows the client to specify both the parent and child units in the same request. HelseID only allows this for selected clients, it is not meant to be used by most clients.
Terms
Kjernejournal (“KJ”)
Pleie- og omsorgssektoren (“PLO”)
Subunit
Unit - Municipality / Place of treatment
Underlying technical mechanisms
In order to be able to pass information to HelseID in a secure way, support has been implemented for a mechanism in OpenID Connect called Request Objects.
This allows you to use a signed JWT to send parameters to the authorization endpoint in HelseID. Note that HelseID does not support the «Passing a Request Object by Reference» mechanism.
The actual information is included in the signed JWT is wrapped in a structure based on the Rich Authorization Requests specification and the FHIR format. This results in a somewhat complex structure, but this is the basis for sending other information from a client to HelseID (role, «tjenestlig behov», technical information about the client application etc.) in a secure, standardized way.
Prerequisites
The following must be in place for HelseID to approve submitted organization information.
POST must be used
Signed JWTs can be large, and there are size restrictions in browsers and web servers on GET requests. POST must be used when passing requests to the authorization endpoint in HelseID. This causes some complexity in native applications (“tykke klienter”) that use an integrated browser for authentication to HelseID. See our sample code for how this can be handled.
Valid parent units or sub units must be pre-registered in HelseID
When HelseID receives organization information from the subject system, it is validated. The units that are valid for a professional system must therefore be pre-registered in HelseID. This is currently done in the HelseID portal.
For clients that should specify both parent and child units the list of parent units must be setup manually by the HelseID operations team. The process for setting this up must be agreed upon before using the mechanism. At the time of writing HelseID only validates the parent unit, the child unit is still represented in tokens but it is not validated by HelseID.
Public key for validating the signed Request Object JWT must be pre-registered in HelseID
When HelseID receives a unit from the subject system, the signature on the JWT in which it is located is validated. The public key to be used for this must be pre-registered in HelseID. This is currently done in the HelseID portal.
Note that this is not necessarily the same key used against the token endpoint in HelseID.
Description of Request Objects
A Request Object is sent as follows to the authorization endpoint:
request: signed_jwt_base64_code
Rules for signed_jwt_base_64
JWT MUST be signed with minimum RS256.
JWT MUST include the claim
nbf(which indicates when JWT is valid from).JWT MUST include claim
exp(which indicates when JWT is no longer valid). Max life of JWT is 60 seconds.JWT MUST include the claim
isswith value set to the current client_id.that ensures that there is a negligible probability that the same value will be accidentally assigned to a different JWT” (link) for the same issuer.
JWT MUST include the claim
audwhich is set to url to the HelseID for the relevant environment. This value can be found in the «issuer» claim in our metadata, for our test environment the value is «https://helseid-sts.test.nhn.no, see https://helseid-sts.test.nhn.no/.well-known / openid-configuration .The JWT MAY contain other parameters to the authorization endpoint in accordance with the specification
EDIT 07.Dec.2020: JWT SHOULD include the claim
client_idwith value set to current client_idEDIT 07.Dec.2020: JWT SHOULD include the claim
jtiwith a value which “MUST be assigned in a manner Note that the last two rules will be transitioned from “SHOULD” to “MUST”.
Example of signed Request Object JWT
JWK
}.
{
"nbf":1575463285,
"exp":1575463345,
"iss": "some_client_id",
"client_id": "some_client_id",
"jti": "some_unique_value",
"aud":"https://helseid-sts.nhn.no",
"authorization_details": {LOOK BELOW FOR FORMAT}
}.
{
SIGNATURE
}Authorization Details for specifying child units
The following structure must be used to provide the organization number for the place of treatment. This structure expresses the following:
[org number] is an identifier from the unit registry that represents the place of treatment that a health professional currently has a role in. In the future, more context will be given in this structure, eg the role of the health care professional or more detailed location.
"authorization_details":
{
"type":"helseid_authorization",
"practitioner_role":
{
"organization":
{
"identifier":
{
"system":"urn:oid:2.16.578.1.12.4.1.4.101",
"type":"ENH",
"value":"[org number]",
}
}
}
}Authorization Details for specifying both parent and child units
The following structure must be used to provide the organization numbers for the parent and child units. Ths structure is similar to the one described above, but with the following changes:
“system” must be “urn:oid:1.0.6523” instead of "urn:oid:2.16.578.1.12.4.1.4.101".
“value” must be of the form "NO:ORGNR:[parent orgnumber]:[child orgnumber]"
|
| Explanation of Authorization Details Items |
Name | Defined By | Description |
|---|---|---|
authorization_details | The Rich Authorization Requests specification | Rich Authorization Requests Parameter Name |
type | Type of authorization request. Only valid value is | FHIR links organization and health professionals through the role of health care professionals. |
practitioner_role | FHIR | FHIR links organization and health professionals through the role of health care professionals. |
organization | FHIR | The organization health personnel has a role in. |
identifier | FHIR | Unique identification for an organization. |
system | FHIR | Organization.system contains a uri (in this case an OID) that uniquely identifies the registry in which the organization is registered. Must have the value |
type | FHIR | Description of the register in which the organization is registered. Must have value |
value | FHIR | If specifying a child unit this value should be the identifier of the treatment site / sub-unit, ie a Norwegian organization number. Nine digits. If specifying a parent and child unit this value should include the identifiers of the parent organization followed by the identifier of the child organization, setup as follows:
|
Example of full request
Below is an example of an http request to the authorization endpoint which includes a claim for a place of treatment.
The decoded version of the base64-encoded request parameter looks like this
Sample Code
An example of Request Objects implementation can be found at https://github.com/HelseID/HelseID.Samples/tree/master/HelseId.Samples.RequestObjectsDemo .
References
This is a list of specifications and codes we have based on.
| References |
Name | Link |
|---|---|
Request Objects | https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests |
Rich Authorization Objects (RAR) | |
FHIR PractionerRole | |
FHIR Organization | |
FHIR Identifier | |
Coding for Identifier |