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 (“PLL”)

Subunit

Unit - Municiplaity / 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 iss with 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 aud which 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_id with value set to current client_id

• EDIT 07.Dec.2020: JWT SHOULD include the claim jti with 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.2.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.2.101".

• “value” must be of the form "NO:ORGNR:[parent orgnumber]:[child orgnumber]"

"authorization_details":
{
    "type":"helseid_authorization",
    "practitioner_role":
    {
        "organization":
        {
            "identifier":
            {
                "system":"urn:oid:1.0.6523",
                "type":"ENH",
                "value":"NO:ORGNR:[parent orgnumber]:[child orgnumber]",
            }
        }
    }
}

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.

POST connect/authorize

client_id: request_object_demo_client_id
redirect_uri: https:// min_url / return
response_type: code
scope: [scopes]
response_mode: form_post
nonce: [nonce]
request: eyJhbGci .... (abbreviated, see below)
state: [state]

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.