Kom i gang tjenesteeier
Tjenesteeier: en offentlig virksomhet som har inngått en avtale for å konfigurere og forvalte tjenester i Altinn, for eksempel en meldingstjeneste.
1. Registrer deg som tjenesteeier hos Altinn
For å sette opp en meldingstjeneste i Altinn Melding, må virksomheten din være registrert som en tjenesteeier hos Altinn. Se hvordan du går frem her: Kom i gang med Altinn.
Dette steget er kun nødvendig for nye virksomheter som ikke er etablert som en tjenesteeier i Altinn.
2. Opprett bruker i Altinn Studio
For å kunne opprette en ressurs (steg 3) må du ha en bruker i Altinn Studio. Brukeren din må så knyttes til din organisasjon. (Har du allerede en Altinn Studio bruker kan du gå til steg 3.) Hvis du er usikker på hvem som er administrator eller du ikke vet om organisasjonen din er satt opp i Altinn Studio kan du spørre Altinn Servicedesk om hjelp.
Se Opprette bruker i Altinn Studio for en detaljert veiledning.
3. Aktivere ressursadministrasjonen
For å kunne sende meldinger via Altinn Melding, må meldingen være tilknyttet en ressurs. Ressurser registreres via Altinn Studio og brukes til å definere tilgangsregler og tilgangslister, dette sikrer at bare autoriserte brukere kan utføre bestemte handlinger. Man aktiverer ressursadministrasjonen ved å opprette et spesifikt repo (repository) og en ressursgruppe for organisasjonen din. (Har du allerede aktivert ressursadministrasjon kan du gå til steg 4.)
Se Ressursadministrasjon for en detaljert veiledning.
4. Opprett en ressurs
- Logg inn på Altinn Studio og naviger til ressursdashboardet.
- Opprett ny ressurs, følg veiledningen og fyll inn nødvendig informasjon og detaljer om tjenesten: Se Ressursregister for en detaljert veiledning.
- Angi tilgangsregler for ressursen. Tilgangsregler for ressursen må konfigureres slik at de tillater følgende handlinger:
- “read” ment for at mottakere skal kunne åpne og lese en melding.
- “write” ment for at avsendere skal kunne sende en melding.
- “subscribe” for å registrere hendelsesabonnement i Altinn Events.
Her er en eksempelpolicy.
Merk at denne eksempelpolicyen angir en påkrevd brukerrolle “DAGL(daglig leder)” for brukeren som har tilgang til ressursen. Med en så åpen policy er det anbefalt å bruke Ressursrettighetsregister (gå til engelsk språk for å se dokumentasjon for RRR) for å gi tilgang til spesifikke organisasjoner. En bruker med denne tilgangen kan deretter delegere tilgangen til virksomhetsbrukeren/systembrukeren
TIPS: Verifiser konfigurasjonene dine ved hjelp av Postman-samlingen, og erstatt testtokenene med dine egne Altinn-token. (Se forespørselen “Logg inn i Maskinporten (Initialiser)” i Authenticator-mappen.)
5. Skaff Altinn API-nøkkel og tilgang til scopes
For å bruke Altinn Melding må man ha en abonnementsnøkkel. Teknisk sett er dette en API-nøkkel som må inkluderes i forespørselens Ocp-Apim-Subscription-Key
header for å verifisere at du har rett til å bruke Meldings API-et. Uten denne nøkkelen vil forespørselen din bli avvist.
For å kunne autentisere og sikre at du kan utføre operasjoner via meldings-APIet, må Altinn gi deg tilgang på de scopes du trenger. Dette sikrer at kun autoriserte klienter kan sende og motta filer, og opprettholder dermed sikkerheten i tjenesten. Følgende scopes brukes for å sende og/eller motta meldinger:
altinn:correspondence.write
altinn:correspondence.read
For å få Altinn API-nøkkel og scopes må du sende en forespørsel til: servicedesk@altinn.no Forespørselen må inneholde de scopes du trenger. Vær obs på at du kan trenge flere scopes for integrasjonen din enn bare altinn:correspondence.write/altinn:correspondence.read. Utfyllende liste over scopes finner du her: https://docs.altinn.studio/nb/api/authentication/digdirscopes/
6. Registrer Maskinporten-klient med nødvendige scopes
For å autentisere mot meldings-API-et, må du registrere Maskinporten-klienten(e) din med nødvendige scopes for om du skal sende og/eller motta meldinger: Scopene vedlikeholdes av Altinn og må være autorisert for de riktige API-operasjonene, og er derfor uavhengige av tilgangen satt av tjenesteeiere i steg 2 for den spesifikke meldingstjenesten.
Bruk Samarbeidsportalen for selvbetjent registrering. Følg den detaljerte guiden som er tilgjengelig der. Her er en detaljert guide.
Merk: Ressurspolicyen på ressursen din må ha tildelt de nødvendige scopene til organisasjonen som Maskinporten-klienten(e) din er registrert på.
7. Autentisering
For alle operasjoner må du autentisere deg ved hjelp av din Maskinporten-klient, og deretter hente et Altinn-token fra Altinn Autentisering.
8. Integrer mot meldings-API-et
Siden Altinn Melding er åpen kildekode har du tilgang til koden vår i vårt offentlige GitHub-repo og bygge en lokal Docker-instans for å teste mot.
Vi ønsker bidrag til løsningen velkommen.
Se Readme-filen på GitHub for en introduksjon til Altinn 3 Melding, og kan kjøre koden lokalt sammen med Docker.
Repoet inneholder også en Postman-samling med eksempler.
Swagger for meldings-APIet finner du her.
9. Sett opp hendelsesabonnementer
For å kunne motta varsler om endringer eller hendelser knyttet til dine meldingstjenester, må du sette opp et abonnement for den aktuelle tjenesten. Dette trinnet er spesielt viktig for deg som ønsker å få automatiserte varsler om hendelser fra meldingstjenesten. Hvis du ikke trenger varsler, kan du hoppe over dette trinnet. Se utviklerveiledningen for events for detaljerte instruksjoner om hvordan du setter opp abonnementet.