Formidlingstjenesten i Altinn 3 - API-spesifikasjon til høring

[leogasnier]

Første versjon av Api for formidlingstjenesten ligger her: https://github.com/Altinn/altinn-broker/blob/main/altinn-broker-v1.json

Kom gjerne med tilbakemeldinger og spørsmål i kommentarfeltet her.

FRIST: Fredag 8. desember

[joakibj]

Innspill til høring for Formidlingstjenesten i Altinn 3 fra NAV IT

Bruk av API:

1. NAV kan motta forskjellige avtalt forretningsmeldinger fra organisasjoner i DPO. Hvordan er det tenkt at mottaker kan utføre intern adressering uten å åpne filen? Kan metadata brukes til dette?

2. Hva er det disse fileStatus betyr? Vil de forekomme etter at sender har kalt /broker/api/v1/file/upload?

   • Cancelled
   • Failed

Implementasjon/API oppførsel:

1. Hvordan vil Formidlingstjenesten forholde seg til duplikate innsendinger fra sender? Valideres det mot et sender-supplert felt (correlationId, sendersFileReference, checksum, ...). Kan det være f.eks idempotent receiver pattern eller må klient håndtere eksplisitte feil?

Produksjonsoppfølging:

1. Er det planlagt noe GUI/selvbetjening slik at de som eier filene kan se status / feilmeldinger osv uten å ringe / lage support ticket hos Altinn?

[Ceredron]

Vedrørende deduplisering: I den normale flyten vi legger opp til at filen initialiseres først. "FileId" vil dermed fungere som idempotensnøkkel. Upload-endepunktet kan terminere i forskjellige feilkoder. Det er ikke landet ennå, men det er sannsynlig at vi vil følge RFC 9457 (dvs, ProblemDetails).

Vi har også endepunktet /file/upload for å kjøre initialisering og opplasting i et synkront kall. Det er ikke standard-flyten, men har som formål å gjøre det lettere for en del legacy-kunder. Denne vil i gjeldende skisse kunne ha dupliseringsproblem. Det er sannsynlig at vi kommer til å legge på en header eller lignende med en API-konsument supplert idempotensnøkkel, men vi må kjøre noen runder internt for å sikre at de forskjellige API'ene som inngår i Altinn3 er samstemte rundt hvordan det bør gjøres.

[erik-nygren]

Innspill: • Hvordan det avgjøres om det går via dialogporten eller direkte fra Broker? • Vi forstår det slik at nedlasting av fil gjøres gjennom /download endepunktet, denne bør i så fall gi en bytestrøm i respons (ser ut som man nå har definert et «Stream» -objekt med en del egenskaper) • Content-type for JSON er (kun) application/json

[RagnarFatland-Avanade]

@joakibj Bruk av API:

1. Det er tiltenkt at feltet sendersFileReference kan brukes til dette formålet, eventuelt kan avsender legge inn et custom felt i en Key-Value-liste "PropertyList". Alle disse feltene tilgjengeligjøres i APIet (i motsetning til gammel A2-versjon der PropertyList dette ikke var tilgjengelig via API). Ser dere behov for å kunne søke/filtrere på sendersFileReference i GET-operasjonen mot APIet så tilfelle?

2. Filestatus:

   • Failed - dersom det skjer teknisk eller funksjonell feil som forhindrer løsningen i å videresende den; for eksempel at malware oppdages.
   • Cancelled - til fremtidig bruk der det blir mulig for avsender å avbryte en forsendelse, feks. på grunn av feil addressering/innhold som oppdages etter at forsendelse er gjort. Cancel-operasjonen er foreløpig ikke høyt priortiert og derfor ikke en del av spec per nå.

   Edit 23.11.2023: Korrigerte mitt svar til 1 om propertyList etter å ha fikset en skrivefeil i OpenAPI-spekken der propertyList i ett av tilfellene var listet som "metadata" istedenfor sitt rette navn.

[joakibj]

@RagnarFatland-Avanade Takk! Ser ikke noe behov for søk / filter på sendersFileReference i første omgang for NAV sin del. Sikkert greit å holde muligheten åpen for andre klienter.

I slides fra åpen møte 2023-11-08 så ble webhooks for TransferCompleted / NewFileUploaded nevnt, ser ingen issues på dette repo relatert til det. Så kanskje ikke i første versjon? Kan være interessant for NAV sin del fremfor å polle etter filer/statuser. Vi ønsker å unngå at filer som blir sendt havner i en Failed fileStatus uten at vi oppdager det.

[erik-nygren]

Vil man for formidlingstjenesten også benytte "tjenesteregisteret" slik at mottaker kan sette opp hvordan (i hvilken kanal) den ønsker å motta informasjon? Ref første spørsmål ovenfor

[RagnarFatland-Avanade]

@joakibj

Er det planlagt noe GUI/selvbetjening slik at de som eier filene kan se status / feilmeldinger osv uten å ringe / lage support ticket hos Altinn?

Vi ser på å implementere GUI for både sender og mottaker i fremtiden, - mest sannsynlig som en del av felles arbeidsflate / Dialogporten. GUI for eiere av formidlingstjenestene for å utføre oppsett/konfigurasjon av nye og eksisterende formidlingstjenester vil ligge i Altinn Studio.

I slides fra åpen møte 2023-11-08 så ble webhooks for TransferCompleted / NewFileUploaded nevnt, ser ingen issues på dette repo relatert til det. Så kanskje ikke i første versjon?

Det er planlagt å benytte Altinn Events til å publisere disse , som da blant annet kan konsumeres via webhooks. Planen er å få det på plass ganske fort etter første release.

@erik-nygren

Hvordan det avgjøres om det går via dialogporten eller direkte fra Broker?

Vi har føringer om at Broker skal kunne fungere uavhengig av dialogporten som selvstendig produkt, men vi er i dialog med dem om hvordan vi tilrettelegger for hverandre.

Vil man for formidlingstjenesten også benytte "tjenesteregisteret" slik at mottaker kan sette opp hvordan (i hvilken kanal) den ønsker å motta informasjon? Ref første spørsmål ovenfor

Kan du utdype hva du mener med "tjenesteregisteret"? Løsningen vil bruke de nye Altinn 3 komponentene Ressurs Registeret og Ressurs Rettighets Registeret (RRR) for å styre tilganger (tilsvarer Tjenesteeier Styrt Rettighets Register / service rights registry / SRR fra Altinn 2), men det er kanskje ikke det du mener?

I første release vil det kun være 1 kanal, men tanken er å kunne tilby overføring over multiple kanaler, og at mottaker skal kunne benytte den kanal de selv vil uten at avsender nødvendigvis må forholde seg til det. Men det kommer naturligvis an på nøyaktig hvilke kanaler som ønskes implementert.

[erik-nygren]

Vi tenkte på Adresstjenesten / Service registry som benyttes for å slå opp kapabiliteter / ønsket kanal for mottaker: https://docs.digdir.no/docs/eFormidling/Utvikling/serviceregistry_api

Denne brukes i eFormidling allerede. Tilganger er altså noe annet.

[AnneLiseFurmyr]

I forlengelsen av kommentaren til @erik-nygren ovenfor - to spørsmål til innhold og kryptering av meldinger:

• planlegger dere å støtte forsendelse av dokumenter uten bruk av ASIC-containere og SBD/SBDH formatene? Det hadde vært mye enklere for en del av Skatteetatens bruksmønstre for tjenesten
• legges det opp til at vi kan benytte JWE-standarden og bruk av BCL ved behov for meldingskryptering?

[Ceredron]

I forlengelsen av kommentaren til @erik-nygren ovenfor - to spørsmål til innhold og kryptering av meldinger:

• planlegger dere å støtte forsendelse av dokumenter uten bruk av ASIC-containere og SBD/SBDH formatene? Det hadde vært mye enklere for en del av Skatteetatens bruksmønstre for tjenesten
• legges det opp til at vi kan benytte JWE-standarden og bruk av BCL ved behov for meldingskryptering? Hei!

• Ja, vi kommer ikke til å kreve bruk av ASIC-containere eller noen spesielle format. For oss er det bare filer og innholdet har ingenting å si for oss.
• Ja, Vi har fått implementert det denne uka. Vi bruker et maskinporten token for autentisering (JWE). Microsoft.BCL kan brukes for å generere JWT-grantet.

[erik-nygren]

Her mener vi altså om det er lagt opp til mulighet for meldingskryptering av innholdet, i så fall ønsker vi at man ser på "lettvektsløsninger" slik som JWE (JSON web encryption) for dette. Her vil jo Altinn bli en "mellommann" hvor informasjonen i utgangspunktet lagres ukryptert. I tidligere formidlingstjeneste oppfatter jeg at man dermed gjerne pekte på ASIC for å støtte kryptering av meldingen.

BCL (Business Certificate Locator) er Digdir-løsning for å slå opp offentlige sertifikater som kan benyttes for krypteringen.

(Maskinporten token er på JWT format, og altså ikke det vi sikter til her. Vi har allerede mange løsninger som bruker Maskinporten både som tilbydere og konsumenter).

[Ceredron]

Jeg ser at vi fortsatt har litt mye TBD i dokumentasjonen for det: https://docs.altinn.studio/broker/5.-altinn-3-broker-solution-architecture-managed-file-transfers/5.8-realization-of-capabilities-and-features/#at-rest-protection Den underliggende infrastrukturen vår i MVP er Azure Storage Account der vi tar i bruk den innebygde løsningen der for at-rest kryptering.

Kommer tilbake til dere om hvordan det fungerte i tidligere formidlingstjeneste med ASIC og hvordan vi forholder oss til BCL.

[RagnarFatland-Avanade]

@erik-nygren

I Altinn 2 formidlingstjeneste støtter man ikke ASIC grunnet at den er implementert med krav til ukrypterte zip-arkiv som payload, som måtte inneholde en "manifest.xml"-fil som ble oppdatert som en del av upload-proessen. Filene blir lagret på en sikret filserver. (Historikk fra en ikke-prodsatt SFTP-kanal, som har vist seg vanskelig å gå vekk fra grunnet av at mottakerne ble avhengig av denne funksjonen for å få tak i PropertyList.) I ny versjon vil vi derfor vi vekk fra å forholde oss til innhold/formatet for fil-payload så langt det er mulig (som @Ceredron nevnte), (samt at vi tilgjengeliggjør PropertyList via API for å fjerne behovet for manifest.xml).

Jeg må innrømme at jeg kan lite om JSON web encryption, og har bare lest om det i bruk for små meldinger, typisk for å kryptere JWT-tokens, så jeg er usikker på hvor kapabel den er for store datamengder. - Men del gjerne informasjon dersom dere kjenner til :)

Det vil i praksis være mulig for avsendere å kryptere filene de vil sende via oss på forhånd, og feks. angi Public Key i PropertyList. (- Private Key må da være utvekslet via en annen kanal).

Kan du peke meg til dokumentasjon for den nevnte BCL (Business Certificate Locator) ? Jeg slet med å finne det konkrete, mye falske positiver i mine søk.

[erik-nygren]

Vi har erfaring med bruk av JWE for større meldinger og i prinsippet kan man kryptere et hvilket som helst innhold, dette er bare en struktur for en slik "melding" i et kompakt format. Vi har brukt det som mekanisme for kryptering på meldingsnivå i DSOP kontroll / Accounts API (f.eks. https://data.norge.no/dataservices/8f56672d-2e4c-3ac1-b6d3-d7d7bc94b934).

Overraskende vanskelig å finne dokumentasjon for BCL, BCPene er jo CAene. Kalles muligens også CertPub.

[erikhag1]

Hei! Ang. BCL (Business Certificate Locator), så er dette noe vi tok inn i referansearkitektur for eMelding (basert på EU eDelivery og Peppol) ca. 2019, da med input fra avd. for anskaffelser i Difi. Nå forvaltes dette med DFØ som norsk Peppol-myndighet. Min forståelse er at BCL-komponenten var og er en god ide, men at den som et norsk initiativ ikke er dokumentert eller internasjonalt adoptert. La oss se an hvordan dette bør følges opp, men jeg er usikker på om Altinn Formidling er "riktig" adresse for dette.

[erik-nygren]

Helt enig at Altinn Formidling ikke direkte skal støtte dette, men det bør gå inn i det helhetlige konseptet dersom kryptering må meldingsnivå blir aktuelt. Og det kan det fort bli siden filene håndteres av "mellommann" altså dere. Mulig at kryptering at rest kan avhjelpe noe.

[erik-nygren]

Blir det implementert noe form for viruskontroll av innhold i Formidlingstjenesten?

[erik-nygren]

Og, når er api'ene klare for bruk i test? :)

[Ceredron]

Hei! Vi har implementert viruskontroll for overføring av filer opp til 2gb basert på Microsoft Defender.

Formidlingstjenesten ble nylig lagt ut i staging-miljøet (https://platform.tt02.altinn.no/), og vi jobber for å være klar for tidlig/begrenset pilot-testing 1. mars. Selve formidlingstjeneste API'et ligger an til å bli klart, men det er fortsatt noen uavklarte punkter mot den nye fellesløsningen for autorisering i DigDir som må landes.