Anslutning till API-tjänst

Granskad: ‎den ‎22‎ ‎augusti‎ ‎2024

Om du är en förtagare och verksamhetsutövare med ett rapporteringsansvar för ett miljöområde så kan det finnas en möjlighet att ansluta ett IT-system direkt till ett av Naturvårdsverkets API:er.

För underlätta processen för anslutning har Naturvårdsverket tagit fram en E-tjänst (självservicetjänst), där man enkelt som företag kan ansöka om att ansluta till olika API:er. 

Varje API har en testmiljö och en produktionsmiljö och man kan ansöka till dem var för sig. Anslutningen till ett API:s testmiljö är till för att använda vid framtagning och vidareutveckling av IT-system. IT-systemet kan vara ett som ni själva utvecklat, köpt in eller använder som en tjänst.

Anslutningen till ett API:s produktionsmiljö behövs alltid om man har ett rapporteringsansvar, i vissa fall även om man har ett IT-system som ska anslutas och som bara någon annan ska använda. Detta kan låta krångligt men det beror på att det är flera kombinationer av hur API:er, IT-system och rapporteringsansvar fungerar som måste kunna hanteras.

Vad som gäller för anslutning till produktionsmiljö framgår i beskrivningen för respektive miljöområde.

Ansöka i e-tjänsten

En ansökan om anslutning till ett API är kostnadsfri och tar endast ett par minuter i anspråk. E-tjänsten kan användas av firmatecknare eller ett ombud som enbart gäller för denna E-tjänst, en person som firmatecknaren kan utse i Bolagsverkets tjänst Mina Ombud (länk). 

I e-tjänsten identifierar man sig med e-legitimation (t.ex. BankID eller FrejaID) och väljer sedan eventuellt ett företag om det skulle vara så att man står på flera. Därefter så väljer man det API man vill ansluta till och fyller i ett antal uppgifter, bland annat kontaktuppgifter. Sedan granskar och godkänner man villkoren och avslutar med att skicka in ansökan. Efter ett par minuter ska det komma en bekräftelse på att ett konto skapat och det går då att hämta anslutningsuppgifterna i e-tjänsten.

Naturvårdsverkets e-tjänst för API-anslutning

En anslutning till ett API består av två delar. Dels är det den fysiska kopplingen av ett IT-system till Naturvårdsverkets API och dels är det en logisk koppling som utgörs av ett konto, en identitet, som representeras av en åtkomstnyckel (OAuth2 Bearer Token).

Den fysiska kopplingen består av en webbadress för datakommunikation mellan två datorer över nätverk, i detta fall Internet. För att den ska vara säker och skydda uppgifterna som skickas till Naturvårdsverket så långt det är möjligt är kommunikationen krypterad.

Den som ansluter till ett av Naturvårdsverkets API:er bör därför regelmässigt verifiera API:ets servercertifikat (naturvardsverket.se) i sitt IT-system. På motsvarande sätt så kräver Naturvårdsverket ömsesidigt att det anslutande IT-systemet har ett klientcertifikat som antingen är av typen QWAC (se nedan) med 1 års giltighet eller ExpiTrust EID CA v4 (PROD) och ExpiTrust Test CA v8u (TEST) utfärdat av CA Expisoft med två års giltighet. (Expisoft är även återförsäljare för “Entrust QWAC eIDAS”.)

Expisoft – beställningstjänst för e-legitimationer och certifikat (expisoft.se)

  • QWAC med ett års giltighet (se nedan).
  • ExpiTrust EID CA v4 (PROD) och ExpiTrust Test CA v8u (TEST) utfärdat av CA Expisoft med två års giltighet

Åtkomstnyckeln består av ett digitalt signerat textdokument (JWT) med en 1 timmes giltighetstid och skickas med i varje anrop till API:et. Om giltighetstiden har gått ut så finns det uppgifter i E-tjänsten (key och secret) hur den kan förnyas maskinellt.

Exempelvis görs förnyelsen med “curl” enligt följande i produktion:

curl -X POST https://api.naturvardsverket.se/oauth2/token -d "grant_type=client_credentials" -H "Authorization: Basic Base64(key:secret)"

Observera att -d i curl lägger till en extra header "Content-Type: application/x-www-form-urlencoded" som man behöver ta med i en egen lösning.

Om du ska utveckla ett IT-system:

  1. Skaffa ett klientcertifikat från EU:s lista med QWAC-leverantörer eller Expisoft (Serverlegitimation/organisationslegitimation).

    Expisoft – beställningstjänst för e-legitimationer och certifikat (expisoft.se)
  2. Ansök om anslutning till API:ets testmiljö.
  3. Hämta anslutningsuppgifterna (URL, key, secret, token).
  4. Implementera klientcertifikat, URL, key, secret och token.
    1. Klientcertifikatet och token ska skickas med i varje anrop, token ska förnyas med key/secret vid behov. Giltighetstiden är normalt 1 timme. Förnyelse görs lämpligen först om ett anrop ger statuskod 401 tillbaka varpå token förnyas och cachas i 1 timme.
    2. Se till att API:ets servercertifikat verifieras mot en lokal kopia eller mot betrodda utgivare (rot-certifikat).

Om du ska ansluta ett IT-system som du förfogar över själv (utvecklat, köpt, hyrt) till en produktionsmiljö och ska rapportera själv:

  1. Se till att det är testat (se ovan).
  2. Ansök om anslutning till API:ets produktionsmiljö.
  3. Hämta anslutningsuppgifterna (URL, key, secret, token).
    1. Uppdatera IT-systemet med anslutningsuppgifterna.

Om du ska ansluta ett IT-system (typ kommersiell tjänst/molntjänst) som du äger till en produktionsmiljö som en eller flera andra företag ska rapportera i:

  1. Se till att det är testat (se ovan).
  2. Hämta URL för API:ets produktionsmiljö.
  3. Se till att de andra företagen (kunderna) ansöker om en anslutning och egna unika anslutningsuppgifter (key, secret och token),
  4. Lägg in deras anslutningsuppgifter (key, secret, token) så att de kopplas till respektive företag och används i anropen till API:et. 

Om du ska använda någon annans IT-system (tjänst) att rapportera i:

  1. Ansök om anslutning till API:ets produktionsmiljö.
  2. Hämta anslutningsuppgifterna (URL, key, secret, token).
  3. Meddela leverantören på ett säkert sätt dina anslutningsuppgifter (key, secret, token), Använd krypterat meddelande.

Observera att token och framför allt key och secret är en värdehandling som kan missbrukas om den kommer i fel händer. Förvara dem i ett krypterat format, vid överlämning använd krypterade meddelandetjänster i stället för vanlig e-post.

I verkliga livet använder vi ofta pass och nationellt id-kort för att identifiera oss i Sverige och utomlands. Det beror på att det finns en överenskommelse att lite på att den som utfärdar identitetshandlingen, respektive myndighet, är pålitliga. På liknande sätt använder vi oss av vanligtvis av BankID och FrejaID+ för att identifiera oss i olika tjänster för att de båda anses pålitliga genom dem som har kontrollerat vår identitet vid utfärdandet. BankID och FrejaID+ är två exempel på en elektronisk identitetshandling som i kommunikationen med tjänsterna representeras av ett certifikat, en signerad (låst) textfil som bl.a. innehåller personnummer och namn.

På liknande sätt finns det andra typer av certifikat som enbart används för kommunikation mellan IT-system, så att de kan “lita” på varandra, att meddelanden skickas och tas emot av “rätt” system. I en webbläsare så syns detta som ett “hänglås” till vänster i adressfältet, då vet man att överföringen är krypterad. Därefter krävs numera expertkunskaper för att avgöra certifikatets “pålitlighet”, vem som står bakom webbplatsen, vem som intygar detta, hur det är gjort och hur pålitligt allt detta är sammantaget.

QWAC står för Qualified Web Authentication Certificate och är ett kvalificerat digitalt certifikat som främst används för intyga en webbplats äkthet. Det är en standard för detta användningsområde som är framtaget av EU med syfte att främja och underlätta pålitlig elektronisk kommunikation inom mellan företag och myndigheter inom EU. Standarden regleras av flera direktiv som alla går under benämningen eIDAS. Tanken är att certifikatet ska vara absolut pålitligt genom att leverantörerna måste leva upp till vissa krav och genomgår kontroller av efterlevnad. Därmed blir leverantörerna kvalificerade, Qualified Trust Service Providers. Det innebär att leverantörerna måste göra en noggrann bakgrundskontroll av de företag som de utfärdar QWAC för, vilket tar tid, en del olägenhet och medför vissa kostnader. 

I ett QWAC-certifikat ingår bl.a. företagets namn, organisationsnummer och hemvist. Det kan användas både för att säkra en webbplats med krypterad trafik (HTTP/TLS) och identifiera ett system som anropar ett annat system, s.k. klientcertifikat. Det finns också ett tillägg som heter PSD2 och används av banker inom EU.

EV-certifikat (Extended Validation) är den närmaste klassiska typen av certifikat som liknar QWAC. På grund av att marknaden är oreglerad för EV-certifikat med ett ett stort antal leverantörer så indikeras inte webbplatser “som extra pålitliga” (grönt hänglås) längre i de flesta moderna webbläsare. 

Nackdelen med QWAC (och de flesta liknande certifikat) är att de har en giltighetstid på 1 år och måste förnyas efter det, vilket dock är relativt enkelt.

Man kan söka fram leverantörer på eIDAS webbplats. Sök på typ genom att kryssa för “Qualified certificate for website authentication”. Det finns tyvärr ingen leverantör i Sverige men väl flera återförsäljare. Ett enklare alternativ kan vara att Googla på “QWAC Sweden”. Notera att det är viktigt att ”client” finns med i en eventuell beställning, leverantörerna har inte alltid detta som standard. Certifikatet ska användas för server- till serverkommunikation. PSD2 behöver inte ingå.

 eIDAS Dashboard (europa.eu)