Forespørsel-svar

1. Generisk forespørsel-svar

1.1. Om dette mønsteret

Generisk mønster for spørring og oppslag adresserer området Deling av data på forespørsel og omhandler tilgjengeliggjøring av data og oppslag i data, som sett fra henholdvis datatilbyder og datakonsument.

Mønsteret dekker både asynkrone og synkrone oppslag, og det tas ikke stilling til kommunikasjonsprotokoll. Spørring og oppslag kan gjøres både mot data med ulike grader av tilgangsbegrensninger og mot åpne data helt uten tilgangsstyring.

Mønsteret gir heller ingen begrensninger i hva slags informasjon det gjelder, om det er strukturerte eller ustrukturerte data, eller hva data skal brukes til. Tilbyder og konsument av data kan være på tvers av virksomheter eller innenfor samme virksomhet.

Eksempler på bruk:

  • Oppslag i et felles dataregister, f.eks. Folkeregisteret.

  • Oppslag av data hos en annen virksomhet .

  • Oppslag av data i egen virksomhet.

1.2. Kapabiliteter for deling av data på forespørsel

Modellen under viser hovedinndelingen i kapabiliteter en tilbyder og en konsument må ha for å dele data gjennom spørring og oppslag. Dette er av området som omhandler Deling av data på forespørsel.

Kapabiliteter
Figur 1. Kapabiliteter, deling av data på forespørsel

Tilbyder må kunne tilgjengeliggjøre data og dette er delt i to kapabiliteter:

  • Tilgjengeliggjøre data omhandler hvordan man registerer og setter opp tilganger.

  • Avgi data omhandler den operative delingen av data fra tilbyder.

Tilsvarende er det to detaljerte kapabiliteter tilknyttet konsument og det å innhente data:

  • Få tilgang til data består av prosesser for oppsett av tilgang.

  • Innhente data er det konsumenten må gjøre hver gang det gjøres et oppslag.

I tillegg kan begge parter ha kapabiliteten:

  • Delegering av rettigheter til databehandler må gjøres dersom en av partene benytter seg av en databehandler.

Tabell 1. Elementer i view for Kapabiliteter, forespørsel-svar
Element Beskrivelse

Datatilbyder

Tilbyder av data til andre aktører.

Datakonsument

Den som innhenter eller mottar data fra andre aktører.

Delegere rettigheter til databehandler

Evnen til å delegere rettigheter til databehandler som utfører oppgaver på vegne av behandlingsansvarlig.

Tilgjengeliggjøre data

Evnen til å gjøre data tilgjengelig for aktører utenfor egen virksomhet.

Få tilgang til data (konsument)

Evnen til å skaffe seg tilgang til tilbudte data fra annen aktør.

Avgi data

Evne til å avgi data på forespørsel. Kan omfatte tilgangsstyring.

Innhente data

Evnen til å innhente data fra en annen aktør.

2. eOppslag - konseptuell beskrivelse

2.1. Om dette mønsteret

eOppslag som arkitekturmønster beskriver synkrone API-kall mot en datatilbyder med tilgangsstyring ved bruk av sikkerhetsbilletter.

Her beskrives realiseringen av kapabilitetene i det generiske mønsteret for deling av data på forespørsel innenfor rammene av synkrone oppslag mot APIer og tilgangsstyring ved bruk av sikkerhetsbilletter.

Beskrivelsene er forsøkt å holdes generisk uten å peke til noen løsning og det vil dermed kunne være flere måter å realisere de ulike elementene på.

2.2. Klargjøring for deling av data på forespørsel

2.2.1. Tilgjengeliggjøre data

Tilgjengeliggjøring av API gjøres av tilbyder av data og er det tilbyder må gjennomføre for å gjøre et API synlig og tilgjengelig gjennom kataloger og søkeløsninger. Registrering av konsumenters rettigheter og tilganger inngår også som et prosessteg.

Dersom det er registrering av et åpent API, er det kun relevante prossessteg som utføres.

Bilde mangler
Figur 2. Tilgjengeliggjøre data
Tabell 2. Elementer i view for Tilgjengeliggjøre data
Element Beskrivelse

Datatilbyder

Tilbyder av data til andre aktører.

Tilgjengeliggjøre data

Evnen til å gjøre data tilgjengelig for aktører utenfor egen virksomhet.

Bruksavtale

Avtale om tilgang til og bruk av data. Dette kan for eksempel være en bilateralt utformet avtale, aksept av generelle bruksvilkår eller lisens for bruk av åpne data.

Tilgjengeliggjøre API

Prosessen med å tilby data gjennom et API til aktører utenfor egen virksomhet.

Registrere API

Prosess med å registere API i relevante tjenester, api-katalog, Maskinporten, Kapabilitetsoversikt

Inngå avtale om tilgang til data

Prosess for å inngå avtale om tilgang og bruk av data.

Tildele tilganger til API

Prosess for å registrere hvilke databrukere som skal få tilgang Sette policy, og grov tilgangsstyring gjennom maskinporten.

Registrere brukere av samtykke

Prosess for å registrere konsumenter som skal ha mulighet for å innhente samtykker som gir tilgang til en tjeneste.

Dette utføres kun om det er behov for samtykke for tilgang til dataene.

API-registreringstjeneste

Tjeneste for å registerer de API-ene man ønsker å tilby til konsumenter og egenskaper ved disse.

Registrering av API-brukere

Tjeneste for gjennom selvbetjening å registrere og vedlikeholde tilgangene konsumenter skal ha til API-er og scopes.

Registrere samtykkebasert tilgang

Tjeneste for å registerer konsumenter som kan innhente samtykke som gir grunnlag for utlevering fra datatilbyder.

2.2.2. Få tilgang til data

Få tilgang til API er det en konsument av data må gjøre for å få tilgang til data gjennom et API. Det omfatter å få kjennskap til aktuelt API, inngå avtale om bruk av data, samt å registrere den tekniske komponenten som skal utføre tjenestekallet. Dersom det dreier seg om tilgang til et åpent tilgjengelig API, kan enkelte delaktiviteter i prosessene hoppes over.

Bilde mangler
Figur 3. Få tilgang til data
Tabell 3. Elementer i view for Få tilgang til data
Element Beskrivelse

Datakonsument

Den som innhenter eller mottar data fra andre aktører.

Få tilgang til data (konsument)

Evnen til å skaffe seg tilgang til tilbudte data fra annen aktør.

Bruksavtale

Avtale om tilgang til og bruk av data. Dette kan for eksempel være en bilateralt utformet avtale, aksept av generelle bruksvilkår eller lisens for bruk av åpne data.

Få tilgang til API

Prosessen med å skaffe seg tilgang til tilbudte data fra annen aktør. Omfatte å finne API-er, inngå nødvendige avtaler og få tilganger.

Finn/få kjennskap til API

Prosessen med å finne eller få kjennskap til tilgjengelige API-er gjennom relevante kataloger og søkeløsninger.

Inngå avtale om tilgang til data

Prosess for å inngå avtale om tilgang og bruk av data.

Registreringstjeneste for API-brukere

Tjeneste for å registrere klienter som skal ha tilgang til et gitt API.

API-søk

Tjeneste for å søke etter og finne tilgjengelige API-er

Registrer klient med tildelt tilgang

Prosess for konsument å registerere (provisjonering av) den klienten som skal ha tilgang til API-et ved bruk av sikkerhetsbillett. Dette forutsetter at konsumenten har avtale om bruk av sikkerhetsbillettjenesten og at tilbyder har gitt konsumenten tilgang.

Dersom det er en leverandør som har blitt delegert rettigheter som databehandler på vegne av konsument er det leverandøren som registrer sin klient.

2.2.3. Delegere rettigheter til databehandler

Delegering av rettigheter til databehandler er det en konsument må gjøre for at en leverandør kan identifisere seg med sitt eget virksomhetssertifikat og opptre på vegne av konsumenten som er den som innehar behandlingsgrunnlaget for å innhente data.

Bilde mangler
Figur 4. Delegere rettigheter til databehandler
Tabell 4. Elementer i view for Delegere rettigheter til databehandler
Element Beskrivelse

Samhandlingsaktør

Samlebetegnelse på roller som inngår i en samhandlingsprosess og samhandler med en annen samhandlingsaktør. Kan være en tilbyder, konsument, avsender, mottaker, leverandør etc.

Delegere rettigheter til databehandler

Evnen til å delegere rettigheter til databehandler som utfører oppgaver på vegne av behandlingsansvarlig.

Tjenesteavtale

Avtale mellom leverandør og konsument som er grunnlaget for å kunne delegere rettigheter fra konsument til en leverandør

Delegering av rettigheter til databehandler (leverandør)

Prosessen med å delegere rettigheter til databehandler/leverandør.

Inngå avtale med leverandør

Prosessen med å inngå en avtale med leverandør. En slik avtale vil normalt være inngått tidligere og uavhengig av om man skal ta i bruk et nytt API. En tjenesteavtale med leverandør er en forutsetning for å kunne delegere en tilgang.

Registrere delegert tilgang

Prosessen med å delegere tilganger. I tilknytning til eOppslag vil formålet være å gi leverandør tilgang til å representere konsument overfor et API, men registreringen vil potensielt også kunne gjelde for andre områder.

Registering av representasjonsforhold

Tjeneste for å registrere et representasjonsforhold som gir leverandør mulighet til å opptre på vegne av konsument

2.3. Utveksling av data

2.3.1. Innhente data

Slå opp data gjennom et API er det en konsument må gjøre når det utføres et tjenestekall for å innhente data gjennom et API. Dersom det er et åpent API er det kun relevante prossessteg som utføres.

Bilde mangler
Figur 5. Innhente data
Tabell 5. Elementer i view for Innhente data
Element Beskrivelse

Datakonsument

Den som innhenter eller mottar data fra andre aktører.

Innhente data

Evnen til å innhente data fra en annen aktør.

Forespørsel om data

Forespørsel om data med parametetere i forespørselen, sikkerhetsbillett mv.

Slå opp data gjennom et API

Prosessen med å slå opp og hente data gjennom et API.

Innhent samtykke ved behov

Prosess for å innhente samtykke fra person eller virksomhet som grunnlag for å innhente data. Dette gjøres kun ved behov.

Hent teknisk endepunkt ved behov

Prosessen å slå opp den tekniske adressen til et API før spørring mot API-et. Gjøres kun dersom det er nødvendig.

Be om tilgangstoken

Prosessen med å benytte en sikkerhetsbillettjeneste for hente en sikkerhetsbillett som gir tilgang til et API. Dette forutsetter at alt er registert og satt opp riktig mot de aktuelle tjenestene.

Utfør tjenestekall

Prosessen med å benytte (gjøre et oppslag mot) et eksternt API.

Samtykkeregistererings-tjeneste

Tjeneste for å innhente samtykke fra den registrert som dataene gjelder. Dette kan være en person eller en virksomhet.

Adressetjeneste

Tjeneste som gir mulighet til å slå opp teknisk endepunkt

Tokentjeneste

Tjeneste som utsteder sikkerhetsbilletter. Sikkerhetsbillett utstedes basert på tildelte rettigheter og eventuelle representasjonsforhold.

Datautvekslings-tjeneste

Tjeneste for utveksling av data. Samme som data exchange service. Benyttes av avsender og mottaker for transport av meldinger.

2.3.2. Avgi data

Avgi forespurte data er det tilbyder av data må gjøre for å svare på en forespørsel. Prosessen kontrollere tilgang gjøres kun dersom det er enakk om å avgi data gjennom et sikret API.

Bilde mangler
Figur 6. Avgi data
Tabell 6. Elementer i view for Avgi data
Element Beskrivelse

Datatilbyder

Tilbyder av data til andre aktører.

Avgi data

Evne til å avgi data på forespørsel. Kan omfatte tilgangsstyring.

Forespørsel

Informasjon om det som forespørres.

Autentiseringsdata

Data som autentiserer konsument, f.eks. digitalt sertifikat eller sikkerhetsbillett.

Autorisasjonsdata

Data som autoriserer konsument, f.eks. påstander i en sikkerhetsbillett.

Svar på forespørsel

Informasjonen som avgis til konsument som svar på en forespørsel.

Avgi forespurte data gjennom API

Prosessen med å avgi data på forespørsel gjennom et egnet API.

Motta forespørsel om oppslag

Motta forespørsler fra API-konsument om å avgi data.

Autentisere konsument

Prosessen med å autentisere en kosnument.

Kontroller tilgang

Kontroll og håndheving av konsumentens rettigheter til å få forespurte data. I tillegg til "validering av sikkerhetsbillet", kan det være behov for kontroll mot virksomhetsinterne policies.

Avgi data

Prosessen med å gi svar på forespørselen.

Datautvekslings-tjeneste

Tjeneste for utveksling av data. Samme som data exchange service. Benyttes av avsender og mottaker for transport av meldinger.

Autentiseringstjeneste

Tjeneste som benyttes av tilbyder for å validere og kontrollere autentisiteten til et OAUTH2 token fra Maskinporten

Tilgangskontroll-tjeneste

Tjeneste for å sjekke rettigheter til data. Kan være eksterne eller interne tjenester. Eksempler på rettigheter kan komme av samtykker fra person eller virksomhet, eller rollebasert fra vergemål, familierelasjon el.

Datautvekslings-tjeneste

Tjeneste for utveksling av data. Samme som data exchange service. Benyttes av avsender og mottaker for transport av meldinger.

3. eOppslag - bruk av nasjonale fellesløsninger

: :imagepath: ../images/ :toc: left :sectnums: :toclevels: 5 :sectnumlevels: 7

3.1. Om dette mønsteret

Beskrivelsene her viser hvordan den konseptuelle arkitekturen for eOppslag kan realiseres med løsningskomponentene Maskinporten, API-katalogen og Altinn-autorisasjon. Disse fellesløsningene leverer de tjenestene som er beskrevet på forretningsnivå over.

eOppslag kan benyttes både for sikrede API-er og API-er som tilbyr åpent tilgjengelige data uten tilgangsbegrensninger.

Det er ikke hensikten å låse referansearkitekturen til spesifikke løsninger, da ulike sektorer og aktører kan ha behov som ikke passer med det som er beskrevet. For synkrone tjenestekall basert på REST og med tilgangsstyring ved hjelp av OAUTH2-tokens, vil det være god støtte i å benytte de foreslåtte løsningene.

Nederst i beskrivelsen av løsningsmønstre er det en overordnet beskrivelse av hvilke data som inngår i registrering i de ulike komponentene.

For å registrere API må man for i de respektive fellestjenestene ha rettigheter til dette på vegne av egen virksomhet. Dette tildeles iht. hvem som har rettigheter i enhetsregisteret og rettighetene må delegeres nedover i organisasjonen til den som skal gjennomføre registreringen. Dette foregår i Altinn.

3.2. Klargjøring for deling av data på forespørsel

3.2.1. Tilgjengeliggjøre data

For å tilby data gjennom et API sikret med fellestjenester må tilbyder inngå avtale for bruk av Maskinporten og Felles API-katalog. De respektive API-ene og hvem som skal ha hvilke rettighetene til disse må så registreres i løsningene.

Bilde mangler
Figur 7. Tilgjengeliggjøre data
Tabell 7. Elementer i view for Tilgjengeliggjøre data løsningsmønster
Element Beskrivelse

Datatilbyder

Tilbyder av data til andre aktører.

Tilgjengeliggjøre data

Evnen til å gjøre data tilgjengelig for aktører utenfor egen virksomhet.

Tilgjengeliggjøre API

Prosessen med å tilby data gjennom et API til aktører utenfor egen virksomhet.

Registrere API

Prosess med å registere API i relevante tjenester, api-katalog, Maskinporten, Kapabilitetsoversikt

Inngå avtale om tilgang til data

Prosess for å inngå avtale om tilgang og bruk av data.

Tildele tilganger til API

Prosess for å registrere hvilke databrukere som skal få tilgang Sette policy, og grov tilgangsstyring gjennom maskinporten.

Registrere brukere av samtykke

Prosess for å registrere konsumenter som skal ha mulighet for å innhente samtykker som gir tilgang til en tjeneste.

Dette utføres kun om det er behov for samtykke for tilgang til dataene.

Registrere Open API specification¨

Tjeneste i Felles API-katalogen for å registrere API. Bruk av tjenesten forutsetter at rettigheter til å gjøre dette på vegne av tilbyders virksomhet.

Selvbetjeningstjeneste for administrasjon av integrasjoner og APIer

Tjeneste "administrasjonssentre" vil ha rettigheter til å registrere på vegne av andre f.eks. API-katalogen

Registrering av API-brukere

Tjeneste for gjennom selvbetjening å registrere og vedlikeholde tilgangene konsumenter skal ha til API-er og scopes.

Registrere samtykkebasert tilgang

Tjeneste for å registerer konsumenter som kan innhente samtykke som gir grunnlag for utlevering fra datatilbyder.

Beskrivelse API

Dataobjekt som er en maskinlesbar beskrivelse av REST API-er iht. Open API Specification. Dette er formatet som benyttes for å registrere et API i felles API-katalog

Token-egenskaper

Egenskaper som f.eks. gyldighetstid ved tilgangstoken som er Maskinportens variant av sikkerhetsbillett.

OAUTH scopes

Dataobjekt som som kan beskrives som en ressurs-definisjon, og et token er som regel knyttet til ett eller flere scopes. Scopes benyttes til å styre tilganger til API-er og operasjoner, samt eventuelt hva slags responser man får fra API-er.

Tilganger konsument

Oversikt over hvilke API og OAUTH-scopes en virksomhet (representert ved organisasjonsnummer) skal ha tilgang til (utstedt token for).

Aktører som kan innhente samtykke for bruk av API

Oversikt over aktører som skal ha mulighet til å innhente samtykke som grunnlag for å få tilgang til data gjennom et API. URL til konsumenten det kan innhentes samtykke for må inngå i beskrivelsen.

Felles API-katalog

Del av Felles datakatalog som gir mulighet for å søke etter API-er og lese API-spesifikasjoner https://fellesdatakatalog.brreg.no/apis

Maskinporten

Maskinporten er en løsning for tilgangsstyring for virksomheter som utveksler data. Løsningen garanterer identiteten mellom virksomheter, og sørger for maskin-til-maskin autentisering

Altinn autorisasjon

Autorisasjonskomponenten i Altinn som gir muligheter til å delegere rettigheter til andre organisasjoner eller personer. Rettigheter til bruk av autorisasjonskomponenten baserer seg på registrerte roller i Enhetsregisteret. Altinn autorisasjon leverer også tjenester for å registrere og kontrollere samtykke gitt av person eller virksomhet.

3.2.2. Få tilgang til data

For å få tilgang til data gjennom et API sikret ved hjelp av nasjonale fellesløsninger, må konsumenten inngå avtale for bruk av Maskinporten og registrere den tekniske klienten som skal benytte løsningen.

Bilde mangler
Figur 8. Få tilgang til data
Tabell 8. Elementer i view for Få tilgang til data - løsningsmønster
Element Beskrivelse

Datakonsument

Den som innhenter eller mottar data fra andre aktører.

Få tilgang til data (konsument)

Evnen til å skaffe seg tilgang til tilbudte data fra annen aktør.

Få tilgang til API

Prosessen med å skaffe seg tilgang til tilbudte data fra annen aktør. Omfatte å finne API-er, inngå nødvendige avtaler og få tilganger.

Finn/få kjennskap til API

Prosessen med å finne eller få kjennskap til tilgjengelige API-er gjennom relevante kataloger og søkeløsninger.

Inngå avtale om tilgang til data

Prosess for å inngå avtale om tilgang og bruk av data.

Registrer klient med tildelt tilgang

Prosess for konsument å registerere (provisjonering av) den klienten som skal ha tilgang til API-et ved bruk av sikkerhetsbillett. Dette forutsetter at konsumenten har avtale om bruk av sikkerhetsbillettjenesten og at tilbyder har gitt konsumenten tilgang.

Dersom det er en leverandør som har blitt delegert rettigheter som databehandler på vegne av konsument er det leverandøren som registrer sin klient.

API-søk

Tjeneste for å søke etter og finne tilgjengelige API-er

Registreringstjeneste for API-brukere

Tjeneste for å registrere klienter som skal ha tilgang til et gitt API.

Beskrivelse API

Dataobjekt som er en maskinlesbar beskrivelse av REST API-er iht. Open API Specification. Dette er formatet som benyttes for å registrere et API i felles API-katalog

Felles API-katalog

Del av Felles datakatalog som gir mulighet for å søke etter API-er og lese API-spesifikasjoner https://fellesdatakatalog.brreg.no/apis

Maskinporten

Maskinporten er en løsning for tilgangsstyring for virksomheter som utveksler data. Løsningen garanterer identiteten mellom virksomheter, og sørger for maskin-til-maskin autentisering

3.2.2.1. Delegering av rettigheter til databehandler

Dersom konsumenten benytter en leverandør som skal opptre på konsumentens vegne, må dette forholdet registereres gjennom Altinn autorisasjon slik at det blir tilgjengelig for Maskinporten å kontrollere representasjonsforholdet.

Bilde mangler
Figur 9. Delegering av rettigheter til databehandler
Tabell 9. Elementer i view for Delegere rettigheter til databehandler - løsningsmønster
Element Beskrivelse

Samhandlingsaktør

Samlebetegnelse på roller som inngår i en samhandlingsprosess og samhandler med en annen samhandlingsaktør. Kan være en tilbyder, konsument, avsender, mottaker, leverandør etc.

Delegere rettigheter til databehandler

Evnen til å delegere rettigheter til databehandler som utfører oppgaver på vegne av behandlingsansvarlig.

Delegering av rettigheter til databehandler (leverandør)

Prosessen med å delegere rettigheter til databehandler/leverandør.

Inngå avtale med leverandør

Prosessen med å inngå en avtale med leverandør. En slik avtale vil normalt være inngått tidligere og uavhengig av om man skal ta i bruk et nytt API. En tjenesteavtale med leverandør er en forutsetning forutsetning for å kunne delegere en tilgang.

Registrere delegert tilgang

Prosessen med å delegere tilganger. I tilknytning til eOppslag vil formålet være å gi leverandør tilgang til å representere konsument overfor et API, men registreringen vil potensielt også kunne gjelde for andre områder.

Delegerbar ressurs

Dataobjekt som beskriver en ressurs, f.eks. et API, som det kan gis rettigheter til gjennom et representasjonsforhold.

Registering av representasjonsforhold

Tjeneste for å registrere et representasjonsforhold som gir leverandør mulighet til å opptre på vegne av konsument

Altinn autorisasjon

Autorisasjonskomponenten i Altinn som gir muligheter til å delegere rettigheter til andre organisasjoner eller personer. Rettigheter til bruk av autorisasjonskomponenten baserer seg på registrerte roller i Enhetsregisteret. Altinn autorisasjon leverer også tjenester for å registrere og kontrollere samtykke gitt av person eller virksomhet.

3.2.3. Informasjon som inngår i klargjøring av forespørsel

Figuren under viser hvilken informasjons som må registreres i de ulike komponentene som del av klargjøringen for å forespørre data fra et API.

Bilde mangler
Figur 10. Informasjon som inngår i klargjøring av forespørsel
Tabell 10. Elementer i view for Dataobjekter eOppslag
Element Beskrivelse

API-katalogen

API-katalogen er en del av Felles datakatalog som inneholder API-beskrivelser med endepunktsadresser og kobling til datasett.

Beskrivelse API

Dataobjekt som er en maskinlesbar beskrivelse av REST API-er iht. Open API Specification. Dette er formatet som benyttes for å registrere et API i felles API-katalog

Endepunkt (adresse)

Dataobjekt som representerer teknisk adresse til et API eller ressurs.

Altinn autorisasjon

Autorisasjonskomponenten i Altinn som gir muligheter til å delegere rettigheter til andre organisasjoner eller personer. Rettigheter til bruk av autorisasjonskomponenten baserer seg på registrerte roller i Enhetsregisteret. Altinn autorisasjon leverer også tjenester for å registrere og kontrollere samtykke gitt av person eller virksomhet.

Delegerbar ressurs

Dataobjekt som beskriver en ressurs, f.eks. et API, som det kan gis rettigheter til gjennom et representasjonsforhold.

Beskrivelse av aktør som kan innhente samtykke

Dataobjekt som beskriver en datakonsument som har rett til å innhente samtykke om å slå opp data. Viktig innholde er bl.a. URL

Tilganger konsument/representasjonsforhold

Dataobjekt som beskriver hvilke tilganger til ressurser en representant (leverandør) skal ha på vegne av konsument.

Maskinporten

Maskinporten er en løsning for tilgangsstyring for virksomheter som utveksler data. Løsningen garanterer identiteten mellom virksomheter, og sørger for maskin-til-maskin autentisering

OAUTH scopes

Dataobjekt som som kan beskrives som en ressurs-definisjon, og et token er som regel knyttet til ett eller flere scopes. Scopes benyttes til å styre tilganger til API-er og operasjoner, samt eventuelt hva slags responser man får fra API-er.

3.3. Utveksling av data

3.3.1. Innhente data

Når en konsumet skal slå opp data gjennom et API benyttes Maskinporten for å få utstedt en sikkerhetsbillett som legges ved tjenestekallet til tilbyders API. Maskinporten utsteder sikkerhetsbilletter som OAUTH2-tokens.

  1. Innhente data image::architecture-repository:eOppslag-solution-no:SBB_Innhente.png[alt="Bilde mangler", width=750,link=https://nasjonal-arkitektur.github.io/nab_modeller_html-hovedbibliotek/e7e6c527-26f4-461c-b4dd-651fcbe85c8d/views/8d72be4b-7e31-438d-9990-c2c3f38f551e.html]

Tabell 11. Elementer i view for Innhente data - løsningsmønster
Element Beskrivelse

Datakonsument

Den som innhenter eller mottar data fra andre aktører.

Innhente data

Evnen til å innhente data fra en annen aktør.

Slå opp data gjennom et API

Prosessen med lå opp og hente data gjennom et API.

Innhent samtykke ved behov

Prosess for å innhente samtykke fra person eller virksomhet som grunnlag for å innhente data. Dette gjøres kun ved behov.

Hent teknisk endepunkt ved behov

Prosessen å slå opp den tekniske adressen til et API før spørring mot API-et. Gjøres kun dersom det er nødvendig.

Be om tilgangstoken

Prosessen med å benytte en sikkerhetsbillettjeneste for hente en sikkerhetsbillett som gir tilgang til et API. Dette forutsetter at alt er registert og satt opp riktig mot de aktuelle tjenestene.

Utfør tjenestekall

Prosessen med å benytte (gjøre et oppslag mot) et eksternt API.

Samtykkeregistererings-tjeneste

Tjeneste for å innhente samtykke fra den registrert som dataene gjelder. Dette kan være en person eller en virksomhet.

Adressetjeneste

Tjeneste som gir mulighet til å slå opp teknisk endepunkt

Tokentjeneste

Tjeneste som utsteder sikkerhetsbilletter. Sikkerhetsbillett utstedes basert på tildelte rettigheter og eventuelle representasjonsforhold.

Oppslag representasjonsforhold

Tjeneste som benyttes av tokentjenesten for å kontrollere om det foreligger et delegert representasjonsforhold fra konsument til leverendør i autorisasjonstjenesten til Altinn.

Datautvekslingstjeneste

Tjeneste for utveksling av data. Samme som data exchange service. Benyttes av avsender og mottaker for transport av meldinger.

Endepunkt (adresse)

Teknisk adresse til et API eller ressurs

Virksomhetssertifikat

En virksomhets elektroniske ID. Benyttes for å autentisere virksomheten overfor tokentjenesten.

Tilganger konsument

Oversikt over hvilke API og OAUTH-scopes en virksomhet (representert ved organisasjonsnummer) skal ha tilgang til (utstedt token for).

Altinn autorisasjon

Autorisasjonskomponenten i Altinn som gir muligheter til å delegere rettigheter til andre organisasjoner eller personer. Rettigheter til bruk av autorisasjonskomponenten baserer seg på registrerte roller i Enhetsregisteret. Altinn autorisasjon leverer også tjenester for å registrere og kontrollere samtykke gitt av person eller virksomhet.

Felles API-katalog

Del av Felles datakatalog som gir mulighet for å søke etter API-er og lese API-spesifikasjoner https://fellesdatakatalog.brreg.no/apis

Maskinporten

Fellesløsning for API-sikring ved bruk av OAUTH2-tokens.

Altinn autorisasjon

Autorisasjonskomponenten i Altinn som gir muligheter til å delegere rettigheter til andre organisasjoner eller personer. Rettigheter til bruk av autorisasjonskomponenten baserer seg på registrerte roller i Enhetsregisteret. Altinn autorisasjon leverer også tjenester for å registrere og kontrollere samtykke gitt av person eller virksomhet.

3.3.2. Avgi data

Når tilbyder får en forspørsel om data som et API-kall og det ligger ved en sikkerhetsbillett benyttes valideringstjenesten til maskinporten for grov tilgangskontroll.

Bilde mangler
Figur 11. Avgi data
Tabell 12. Elementer i view for Avgi data - løsningsmønster
Element Beskrivelse

Datatilbyder

Tilbyder av data til andre aktører.

Avgi data

Evne til å avgi data på forespørsel. Kan omfatte tilgangsstyring.

Avgi forespurte data gjennom API

Prosessen med å avgi data på forespørsel gjennom et egnet API.

Motta forespørsel om oppslag

Motta forespørsler fra API-konsument om å avgi data.

Autentisere konsument

Prosessen med å autentisere en kosnument.

Kontroller tilgang

Kontroll og håndheving av konsumentens rettigheter til å få forespurte data. I tillegg til "validering av sikkerhetsbillet", kan det være behov for kontroll mot virksomhetsinterne policies.

Avgi data

Prosessen med å gi svar på forespørselen.

Datautvekslingstjeneste

Tjeneste for utveksling av data. Samme som data exchange service. Benyttes av avsender og mottaker for transport av meldinger.

Tokenvalideringstjeneste

Tjeneste som benyttes av tilbyder for å validere og kontrollere autentisiteten til et OAUTH2 token fra Maskinporten

Tilgangskontrolltjeneste

Tjeneste for å sjekke rettigheter til data. Kan være eksterne eller interne tjenester. Eksempler på rettigheter kan komme av samtykker fra person eller virksomhet, eller rollebasert fra vergemål, familierelasjon el.

Datautvekslingstjeneste

Tjeneste for utveksling av data. Samme som data exchange service. Benyttes av avsender og mottaker for transport av meldinger.

Maskinporten

Maskinporten er en løsning for tilgangsstyring for virksomheter som utveksler data. Løsningen garanterer identiteten mellom virksomheter, og sørger for maskin-til-maskin autentisering

Altinn autorisasjon

Autorisasjonskomponenten i Altinn som gir muligheter til å delegere rettigheter til andre organisasjoner eller personer. Rettigheter til bruk av autorisasjonskomponenten baserer seg på registrerte roller i Enhetsregisteret. Altinn autorisasjon leverer også tjenester for å registrere og kontrollere samtykke gitt av person eller virksomhet.

Egen autorisasjonskomponent

Komponent for å håndheve virksomhetens regler for tilgang. Også kalt policy enforcement point (PEP).