Bruk av organisasjonsnumre

Hvis en klient-programvare bruker et API som trenger organisasjonsnummer i Access-tokenet, enten som overenhet eller som underenhet, må programvaren sende inn en JSON-struktur (beskrevet under) til HelseID som inneholder disse organisasjonsnumrene.

ℹ️  Unntak for single-tenant-klienter

Unntaket til dette er single-tenant-klienter som konsumerer ett eller flere API som kun trenger organisasjonsnummer for overenhet. I dette tilfellet vil organisasjonsnummeret bli satt i Access-tokenet uten at programvaren trenger å sende inn en JSON-struktur. Hvis API-et også trenger organisasjonsnummer for en underenhet, må derimot programvaren sende inn en JSON-struktur som beskrevet under.

Mønstre for innsending av organisasjonsnumre

Det finnes forskjellige mønstre for å sende inn en JSON-struktur (som vist nedenfor) med organisasjonsnummer til HelseID.

Maskin-til-maskin

Hvis en innlogget bruker ikke er påkrevd, kan du bruke maskin-til-maskin-flyten (Client Credentials). I dette tilfellet må programvaren gjøre et kall mot Token-endepunktet der verdien for grant_type i kallet er client_credentials, og JSON-strukturen må være inneholdt i client assertion-objektet.

Med innlogget bruker

Hvis klient-programvaren trenger en innlogget bruker, kan du gjøre et kall til Token-endepunktet, ved å sende inn JSON-strukturen i client assertion-objektet. Verdien for grant_type vil i dette tilfellet være refresh_token. Dette er det anbefalte mønsteret, ettersom brukeren kan representere flere orgnaisasjonsenheter uten å måtte logge inn på nytt.

Det finnes også et annet mønster, der klienten kan bruke PAR-endepunktet ved å sende inn JSON-strukturen i et Request-object. Dette kan brukes hvis din klient ikke har mulighet til å legge til organisasjonsnumre i client assertion-objektet. Hvis du bruker dette mønsteret, må brukeren reautentiseres hver gang de representerer en ny organisasjonsenhet.

JSON-Struktur for innsending av organisasjonsnumre

Uansett hvilket mønster du bruker for innsending av organisasjonsnumre, må du bruke en JSON-struktur for formålet. Denne strukturen har forskjellig innhold, avhengig av om klienten som sender inn informasjonen om organisasjonsnummer er single-tenant eller multi-tenant.

JSON-Struktur for innsending av organisasjonsnumre for single-tenant-klienter

Single-tenant-klienter sender ikke inn organisasjonsnummeret for hovedenheten; denne informasjonen har HelseID allerede i sin database.

Den følgende strukturen må brukes for å sende inn et organisasjonsnummer for en underenhet:

{
    "type":"helseid_authorization",
    "practitioner_role": {
        "organization": {
            "identifier": {
                "system":"urn:oid:2.16.578.1.12.4.1.4.101",
                "type":"ENH",
                "value":"974589605"
            }
        }
    }
}

Legg merke til at det er kun organisasjonsnummeret til underenheten (974589605) som sendes inn i denne strukturen. Merk også at system-verdien i dette tilfellet må være urn:oid:2.16.578.1.12.4.1.4.101.

JSON-Struktur for innsending av organisasjonsnumre for multi-tenant-klienter

Multi-tenant-klienter sender inn organisasjonsnummeret for hovedenheten, og kan også sende inn et organisasjonsnummer for en underenhet.

Den følgende strukturen må brukes for å sende inn et organisasjonsnummer for en overenhet og eventuelt en underenhet:

{
    "type":"helseid_authorization",
    "practitioner_role": {
        "organization": {
            "identifier": {
                "system":"urn:oid:1.0.6523",
                "type":"ENH",
                "value":"NO:ORGNR:972418013:974042436"
            }
        }
    }
}

I dette tilfellet sendes både nummeret for hovedenheten (972418013) og nummeret for underenheten (974042436?) inn i strukturen. Merk at system-verdien i dette tilfellet må være urn:oid:1.0.6523.

Hvis klienten bare vil sende inn nummeret for en hovedenhet, må parameteren value ha en struktur som dette:

"value":"NO:ORGNR:972418013",

Et eksempel på en full struktur

Token-endepunktet

Eksempelet under viser en struktur for organisasjonsnumre som bruker authorization_details-claimet, sendt inn som et client_assertion-objekt i et kall til Token-endepunktet. I dette tilfellet er klienten satt opp som en multi-tenant-klient.

{
  "alg": "RS256",
  "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]

PAR-endepunktet

Du kan bruke et Request-object på PAR-endpunktet for dette, men i de aller fleste tilfellene vil det være mest praktisk å sende inn organisasjonsnumre i Token-endepunktet.

Eksempelet under viser en struktur for organisasjonsnumre som bruker authorization_details-claimet, sendt inn som et Request-objekt i et kall til Par-endepunktet. I dette tilfellet er klienten satt opp som en multi-tenant-klient.

"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",
       }
    }
  }
}]