REST

Registrer ditt system og få API-nøkkel Dette gjøres litt ulikt avhengig om du representerer en tjenesteeier eller ikke. Er du tjenesteeier i Altinn? Tjenesteeiere er typisk offentlige etater som er en del av Altinn-samarbeidet. Da bestiller du tilgang fra tjenesteeier sitt dashboard på Altinn/digitalisering (krever innlogging). Her velger du “Support” » “Ny sak” » “Bestilling” » “Tilganger” » “REST API”. Har du ikke tilgang til dashboard kan du be om dette ved å sende en henvendelse til tjenesteeier@altinn. »

Last ned og installer Postman fra https://www.postman.com/downloads/. Man trenger en API-nøkkel som har lese-tilgang til Organization. Se API-nøkkel oversikt. Et virksomhetssertifikat. Kreves for leksjonene knyttet til Virksomhetssertifikat og Autentiserings-cookie. En virksomhetsbruker. Kreves for leksjonene knyttet til Altinn-exchange-token og Autentiserings-cookie. Se Virksomhetsbrukere Tilgang til Samarbedisportalen for Digitaliseringsdirektoratet. Kreves for leksjonene knyttet til Token-basert autentisering. »

Følgende informasjon er nødvendig for å lage klienten, og bør skaffes før man kan teste klienten mot Maskinporten og Altinn: Virksomhetssertifikat fra Buypass eller Commfides Klient ID fra Maskinporten API-nøkkel fra Altinn Innlest virksomhet og testbrukere i Altinns testmiljø Opprette virksomhetsbruker og gi den rettigheter Virksomhetssertifikat For at klienten skal kunne autentisere seg mot Maskinporten og Altinn må man ha installert et virksomhetssertifkat fra Buypass eller Commfides. Dette er digital sertifikater som bruker X. »

Denne leksjonen vil vise hvordan man lager en JWT (JSON Web Token) grant og bruker det til å hente et Maskinporten token. For overordnet beskrivelse refererer vi til Maskinportens guide for API-konsumenter. Koden under er skrevet i C# og .Net Core 3.1 og kan ses i sin helhet på Github. JWT grant oppsett JWT grantet består av to deler: Header - som beskriver hvordan hvordan JSON Web Tokenet er signert. Dette forutsetter at koden har tilgang til virksomhetssertifkatet. »

REST kallet for å bytte et Maskinporten token mot et Altinn (beriket) token ser slik ut: GET authentication/api/v1/exchange/maskinporten HTTP/1.1 Host: https://platform.tt02.altinn.no Bearer: eyJraWQiOiJjWmswME1rbTVIQzR ... aMrDO_g X-Altinn-EnterpriseUser-Authentication: <enkodet brukernavn:passord> Accept: application/json Her må man oppgi brukernavnet og passordet til virksomhetsbrukeren man opprettet. Merk at strengen har formatet brukernavn:passord og skal være Base64 enkodet. I det tilhørende .Net Core prosjektet er dette implementert slik: public async Task<string> GetAltinnExchangeToken(string maskinportenToken) { try { var basicAuthEncodedBytes = System. »

I denne leksjonen vil vi vise hvordan man henter en Reportee ID over REST hvis man har fødselsnummer og etternavnet til en person. Dette er IDen til personen som senere skal gis rettigheter til. Kodeeksemplene som brukes i denne leksjonen er hentet fra ReporteeHandler.cs og Reportee.cs. POST reportees/ReporteeConversion REST endepunket som skal brukes er POST reportees/ReporteeConversion. I tillegg til Altinn token så krever dette endepunktet API-nøkkel. HTTP requesten ser slik ut. »

Så langt i veiledningen har vi kun håndtert JSON modeller som System.Text.Json har hatt innebygd støtte for. Hypertext Appplication Language (HAL) brukes i Altinn 2s REST API for å inkludere lenker og lister av ressurser i responsene. Lenker er inkludert i _links og listen over ressurser er inkludert i _embedded. For å kunne håndtere listene med roller og rettigheter som autorisasjons APIet returnerer må vi beskrive HAL+JSON modellen og lage en tilpasset konverterer som kan serialisere lister av ressurser. »

Tilpasset HAL+JSON konverterer (eng: custom HAL+JSON converter) I denne leksjonen vil vi vise hvordan man lager en tilpasset konverterer for HAL+JSON for System.Text.Json. Detaljene vil være sterkt knyttet til System.Text.Json og vil ikke kunne brukes uten modifikasjoner mot andre JSON biblioteker. Vi har basert implementasjonen på Microsoft - How to write custom converters for JSON serialization (marshalling) in .NET og bruker factory pattern. JsonConverterFactory public class EmbeddedListConverter : JsonConverterFactory Tilpassede konverterere som bruker factory mønsteret må implementere to funksjoner: »

I denne leksjonen vi vi vise hvordan man kan hente delegerte rettigheter som er gitt til en person over REST. Koden vi viser i denne leksjonen kan ses i sin helhet i AuthorizationHandler.cs i det tilhørende C#/.Net prosjektet. GET authorization/Delegations REST kallet vi skal bruke for å hente alle rollene og rettighetene en person har for en organisasjon er GET {who}/authorization/Delegations/{receiverId}. {who} er aktøren som det gis tilgang til. Man kan bruke det forhåndsdefinerte argumentet my for å referere til samme aktør som har autentisert seg i REST kallet. »

Importere Altinn Collection og TT02 Environment Postman har to veldig nyttige konsepter, Collections og Environments, som vi skal bruke i denne introduksjonen. Collections er et strukturert oppsett av REST endepunkter, operasjoner, parametere og andre verdier som er definert av et API. Enviornments er verdier som brukes i REST forespørslene, men som ofte tilhører en spesifikk bruker eller et miljø. Man kan referere til en verdi i et Environment ved å bruke {{navn}}. »