GIL

GIL är INCA:s integrationsproxy för REST-baserade integrationer.

Skaffa ett SITHS-funktionscert

Integrationer måste autentisera mot INCA med SITHS-funktionscert. Regionerna har olika sätt att tillhandahålla SITHS-cert.

VGR

Beställning av SITHS-funktionscertifikat under VGR:

https://www.vgregion.se/ov/etjanstekort/boka-och-bestall/funktionscertifikat/

Region Västerbotten

Beställning av SITHS-funktionscertifikat under Region Västerbotten:

• Fyll i blanketten Blankett: Beställning av SITHS Funktionscertifikat (Word).
  • Ansvarig beställare = Chef på RCC (2025-12-08 Katarina Örnkloo), personligt HSA-id anges.
  • Ansvarig mottagare = Beställande utvecklare, personligt HSA-id anges.
  • Ange gamla HSA ID:et som certet hade och exakt namn.
  • Underskrift av någon annan, ditt och denne annan skall stå på lappen. Det går att använda https://signera.regionvasterbotten.se/ för digital signering.
  • Lämpligen kan systemförvaltare användas för QA och systemägare för PROD.
  • Blanketten lämnas/mejlas till Jan Dahlin (angivit 2024-11-14)
• Vid ansökan, skapa och bifoga ett CSR (Certificate Signing Request)
  • Under Linux:
    • openssl kan användas för att generera en .pem fil (privat nyckel) och en .csr fil.
      • Kör kommandot openssl req -new -newkey rsa:2048 -keyout <namn-på-nyckel>.pem -out <namn-på-cert>.csr -nodes -keyform PEM
      • Spara och administrera er genererade .pem fil säkert.
      • Bifoga er genererade .csr med ansökningsblanketten.
  • Under Windows:
    • openssl kan användas enligt ovan.
    • Alternativt:
      • Gör motsvarande Linux-instruktioner med "Internet Information Services (IIS) Manager" (inetmgr i cmd.exe eller Powershell).
      • Är inte inetmgr aktiverad på er Windows-maskin kan ni behöva aktivera detta via:
        • "Windows Features" -> "Internet Information Services" -> "Web Management Tools" -> "IIS Management Console"
  • Vid generering av CSR (och nyckel)
    • Ange: Common Name = certets namn
    • Ange: Organization = Region Vasterbotten
    • Ange: Organisation Unit = CIMT
    • Ange: City/Locality = Umea
    • Ange: State = Vasterbotten
    • Ange: Country/Region = SE
    • Ange: Bit length - 2048
    • "Challenge password" kan anges blankt
    • "Optional company name" kan anges blankt
• Vid skapande av en helt ny integrationsfunktion (för utvecklingssyfte eller produktion) måste en systemanvändare skapas på INCA som associeras med samma HSA-id som certifikatet.
• Vid skapande av ett SITHS-funktionscertifikat för utvecklingssyfte, koordinera med ditt utvecklingsteam och dokumentera vilket HSA-objekt (id) du har ansökt om och/eller mottagit.
• Vid förnyelse av cert: Ange gamla HSA ID:et som certet hade tidigare och exakt namn.

Systemkonto

Integrationer använder sig av systemkonton. Systemkonton prefixas med EXT_kontonamn och ska försöka vara så förklarande som möjligt. Exempelvis EXT_LAKEMEDEL, EXT_SVF osv.

Se till att systemkontot har nödvändiga behörigheter till roller, placeringar, register etc. Associera också SITHS-certets HSA-id.

Utveckla integrationen

• Skapa en egen repo på bitbucket för din integration, kalla den ext-[namn].
• En GET-endpoint v1/health måste finnas som åtminstone returnerar: name, version.
• 0..n övriga endpoints som kan mappas upp i Gil, exempelvis för att hämta data.
• Gil skickar med headern X-GIL-SENDER med värdet på avsändarsystemet.
• Gil skickar 1..2 headers X-GIL-ROLE med roller det sändande systemet har. Kan vara User och Admin.
• Gil skickar vidare alla headers som börjar med X-INCA-*.
• Om integrationen skickar response-headern X-GIL-LOG-META loggas innehållet av GIL för analys. Innehållet måste vara en json-sträng.
• Integrationen bör, om möjligt, exponera en swagger-endpoint.
• Prefixa inte URL:er med api, det är överflödigt.
• Autobygg och pusha image m.h.a. Bitbucket Pipelines.

Skapa GIL-integration med ASPNET Core

Skapa GIL-integration med Node

Publicera ny integration i GIL

När en ny integration är skapad och testad lokalt är nästa steg att publicera den i GIL:s QA-miljö.

Adressen till QA är https://api.qa-incanet.se/gil/v1/integrations/:namn/...

Förbered en docker-compose.yml och skicka den till tommy.larsson@umu.se på Teams. Han återkopplar med vilken port containern startades på, ex 5020.

Be sedan en GIL-admin att konfigurera integrationen i GIL. För det behövs:

• önskat namn på integrationen i URL:en (:namn ovan), exempelvis lakemedel
• port, exempelvis 5001
• vilka routes som ska vara exponerade och om de kräver autentisering, exempelvis: /v1/health, /v1/data, /swagger (publik)

Uppdatera befintlig GIL-integration

Kontakta tommy.larsson@umu.se på Teams och be honom uppdatera och starta om integrationscontainern.

Kontakta en GIL-admin om någon ny route tillkommit eller något annat konfigurationsrelaterat behöver ändras.

GIL-admins

Befintliga GIL-admins är:

• Martin Landälv
• Robert Åhs
• Martin Bodin

En GIL-admin kan bland annat

• konfigurera integrationer
• konfigerera användare
• söka i historikloggen.

En up-to-date-lista med endpoints finns på GIL-repon.

Målet är att ha minst en GIL-admin per utvecklingsteam.

PGP-Krypterade requests och responses

GIL loggar request och response body för att underlätta felsökning men eftersom dessa i princip alltid innehåller patientrelaterad data så kryperas de med PGP.

För att du som GIL-admin ska komma åt loggarna behövs:

• Exportera din publika nyckel till fornamn-efternamn.asc. Exempelvis gpg --armor --export mittnamn@epost.com > fornamn-efternamn.asc.
• Skicka filen till Martin Landälv och skriv till honom på Teams så ber han serveradminen att lägga in den.

Det går endast att komma åt loggar som krypterats efter det att nyckeln lagts in.