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 med organisasjonsnummer til HelseID.

Med innlogget bruker

Hvis din klient-programvare, eller et API den skal konsumere, trenger en innlogget bruker, kan du kan bruke to forskjellige mønstre for å overføre organisasjonsnumre til HelseID:

  1. Enten, i et kall til PAR-endepunktet, ved å sende inn JSON-strukturen i et Request-objekt/Authorization Details.

  2. Eller, i et kall til Token-endepunktet, ved å sende inn JSON-strukturen i client assertion-objektet.

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.

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.

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.

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å parameteret value ha en struktur som dette:

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

Et eksempel på en full struktur

Dette eksempelet viser en struktur for organisasjonsnumre som bruker authorization_details-claimet, sendt inn som et Request-objekt i et kall til Par-endepunktet:

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

Bruk av Token-endepunktet

Som nevnt ovenfor, støtter HelseID at klienten legger ved organisasjonsinformasjon både mot Par-endepunktet og mot Token-endepunktet. Informasjonsinnholdet struktureres på samme måte i begge tilfeller, men ved bruk av Token-endepunktet bruker man claimet assertion_details i stedet for authorization_details.

I dette tilfellet vil en client assertion inneholde følgende claim:

{
  ...
  "assertion_details": [{
     ... innhold som ovenfor ...
   }]
}