SFM-id for multi-tenant clients

Context: Sentral forskrivningsmodul (SFM) uses the mechanism SFM-id for single-tenant clients using HelseID.

The functionality described in this document shows how a multi-tenant client can use this mechanism.

Submission of SFM-id

To submit an SFM ID, you must use a JSON structure for the purpose.

The structured claim is composed as follows:

{
  "type": "nhn:sfm:journal-id",
  "value": {
     "journal_id": "1231231234-34213412-432423-4233"
  }
}

The value for type must always be nhn:sfm:journal-id, and the value for $.value.journal_id must be a UUID.

Note that the type nhn:sfm:journal-id uses a syntax with hyphens, while the claim journal_id uses a syntax with underscore.

The Token Endpoint

You can make a call to the Token Endpoint, by passing the JSON structure in the client assertion object. This is the recommended pattern.

There is also another pattern (see below), where the client can use the PAR endpoint by sending the JSON structure in a Request-object. This can be used if your client does not have the option to add the SFM-id to the client assertion object. As mentioned, this is not recommended.

The value for grant_type in this case will be refresh_token.

{
  "alg": "PS256",
  "kid": "B2C61A07EE0661237D19BEE1E0A1463C",
  "typ": "client-authentication+jwt"
}.{
  "authorization_details":
  [{
    "type": "nhn:sfm:journal-id",
    "value": {
     "journal_id": "1231231234-34213412-432423-4233"
   },
   {
    "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

If your client does not have the option to use authorization_details in the Token endpoint, you can use a Request-object on the PAR Endpoint for this, if your client does not have the option to use authorization_details in the Token endpoint. In most cases, it will be more practical to send an SFM-id in the Token endpoint as seen above.

The example below shows a structure for an SFM-id that uses the authorization_details claim, sent as a Request object in a call to the PAR Endpoint.

"authorization_details":
[{
    "type": "nhn:sfm:journal-id",
    "value": {
      "journal_id": "ed30a6a5-4834-40be-a32b-1e4f5217e378"
    }
 }]

Claim in token

The claim from HelseID (in the Access token) looks like this:

{
  ...
  "nhn:sfm:journal-id" : "ed30a6a5-4834-40be-a32b-1e4f5217e378",
  ...
}

Error Messages

HelseID validates the values in the call to either the Token endpoint or the PAR endpoint, and will return HTTP code 400 (Bad Request) with the error message invalid_request if the content is incorrect.

If the client does not have access to the scope nhn:sfm:journal-id, HelseID will return HTTP code 400 (Bad Request) with the error message invalid_scope.

See the document Error Messages for descriptions of typical error messages from HelseID.