Maskinporten uten client secret: slik setter du opp første API-klient

For et tilgangsstyrt API begynner oppsettet med at virksomheten får riktig scope, og at den som skal registrere klienten får fullmakt til selvbetjening. Opprett deretter en Maskinporten-integrasjon i Samarbeidsportalen og velg virksomhetssertifikat eller egen asymmetrisk nøkkel. Digdirs veiledning for API-konsumenter angir private_key_jwt som autentiseringsmetode og sier uttrykkelig at Maskinporten ikke godtar client secret.

Det er to forskjellige tilganger å få på plass: En person trenger rett til å administrere integrasjonen, mens virksomheten trenger rett til å bruke det aktuelle APIet. Når integrasjonen er registrert, bruker klienten tildelt client_id og en privat signeringsnøkkel til å lage en JWT grant. Den sendes til Maskinporten for å få et tilgangstoken som kan brukes mot APIet.

Avklar fullmakt og miljø

Bestem hvilken virksomhet som skal eie klienten før noen oppretter en bruker i Samarbeidsportalen. Virksomheten må være registrert for tjenesten og ha signert bruksvilkårene. Brukeren registreres med jobbadresse knyttet til virksomheten; i produksjon krever selvbetjeningen i tillegg innlogging og godkjenning fra en bemyndiget person. At en bruker kommer inn i portalen, betyr derfor ikke automatisk at vedkommende kan opprette integrasjoner.

Rettigheten «Selvbetjening av klienter i ID-porten/Maskinporten» gir adgang til å opprette, endre og slette klienter og integrasjoner i test og produksjon. En hovedadministrator gir den som skal registrere klienten fullmakt under Tilgangsstyring i Altinn, slik Digdirs fremgangsmåte for selvbetjening beskriver. Rettigheten «Selvbetjening av APIer i ID-porten/Maskinporten» gjelder administrasjon av scopes på tilbydersiden og erstatter ikke klientrettigheten.

Velg test eller produksjon bevisst. I Samarbeidsportalen går du via «Virksomhetens tjenester» og «Administrasjon av tjenester» til «Integrasjoner» i ønsket miljø. Kontroller også hvilken virksomhet portalen viser; brukere kan bli knyttet til virksomhet via e-postdomenet. Er «Ny integrasjon» utilgjengelig i produksjon, kontroller innloggingen og Altinn-fullmakten før du endrer klientens tekniske oppsett.

Få scope fra riktig API-tilbyder

Be API-tilbyderen om det eksakte scope-navnet og avklar hvilket organisasjonsnummer og hvilket miljø tilgangen gjelder. For tilgangsstyrte scopes må tilbyderen dele tilgang med virksomheten som skal konsumere APIet. Mangler scopet når du velger «Legg til scopes», kan tilbyderen ha gitt tilgang til feil virksomhet eller i et annet miljø. Å skrive scope-navnet inn i en JWT gir ikke virksomheten en tilgang den ikke har fått.

Avklar om APIet bruker direkte tildeling eller Altinn-delegering før klienten registreres. Skal en leverandør hente token på vegne av en kunde, må API-tilbyderen støtte slik delegering, og kunden må delegere riktig API-tilgang i Altinn. Delegerte scopes kan vises under «Scopes tilgjengelig for alle» når de legges på en leverandørklient. Noen APIer kan brukes av alle Maskinporten-konsumenter; slike scopes kan ikke forhåndsregistreres på klienten.

Opprett Maskinporten-integrasjonen

Velg «Ny integrasjon» i riktig miljø, sett tjenesten til «Maskinporten», legg til scopet og skriv en beskrivelse som identifiserer tjenesten. Lagre integrasjonen og ta vare på client_id som blir tildelt ved registrering. ID-en identifiserer klienten i den senere tokenforespørselen; organisasjonsnummer og client_id fyller ulike roller og skal ikke blandes.

Den tekniske konfigurasjonen bruker integration_type «Maskinporten», token_endpoint_auth_method «private_key_jwt» og grant_types «urn:ietf:params:oauth:grant-type:jwt-bearer». Det siste betyr at klienten ber om token med en signert JWT grant. Dersom du registrerer via selvbetjenings-APIet i stedet for portalen, trenger du en egen selvbetjeningsklient først; for en første integrasjon gir portalen et registreringsløp uten dette ekstra oppsettet.

Velg signeringsnøkkel

Et virksomhetssertifikat kan brukes når virksomheten allerede forvalter et egnet sertifikat og kan beskytte den private signeringsnøkkelen. I portalen registrerer du den offentlige signeringsdelen under «Virksomhetssertifikat»; ved eksport må signeringsnøkkelen velges. Et produksjonssertifikat kan ikke brukes i testmiljøet, så miljøvalget må også stemme med sertifikatet.

En egen asymmetrisk nøkkel er et valg når signeringen skal være knyttet til én integrasjon uten at virksomhetssertifikatet spres til flere systemer. Opprett nøkkelparet, behold den private nøkkelen hos klienten og konverter den offentlige nøkkelen til JWK før den legges inn under «Egne public nøkler». Kontroller at registreringen inneholder en kid-verdi som identifiserer nøkkelen; verdien må være unik i Maskinporten. Begge valgene krever at klienten kan signere JWT-en med den tilhørende private nøkkelen.

Kontroller JWT-en før første tokenkall

JWT-granten må ha aud satt til Maskinportens identifikator i det valgte miljøet, iss satt til tildelt client_id og scope satt til det APIet klienten skal bruke. Sett iat etter korrekt UTC-klokke og exp kort tid etter; Digdirs spesifikasjon for JWT grant anbefaler 120 sekunder og angir en gyldighetsperiode på høyst 180 sekunder. Bruk en ny jti for hver grant, siden samme JWT ikke kan brukes igjen.

I JWT-headeren må alg angi en støttet signeringsalgoritme. Bruk x5c for sertifikatkjeden, eller kid som peker på en nøkkel som allerede er registrert på klienten. Dersom leverandøren bruker Altinn-delegering, settes kundens organisasjonsnummer i consumer_org; Maskinporten kontrollerer da delegeringen mot Altinn. For et vanlig direkte kall lar du dette feltet være ute og holder forespørselen til scopet du trenger.

Send granten til tokenendepunktet som assertion sammen med grant_type «urn:ietf:params:oauth:grant-type:jwt-bearer». Før sending bør virksomhet og miljø, scope-tilgang, client_id, aud, signeringsnøkkel og eventuell delegering være avklart. Et utstedt tilgangstoken sendes videre til APIet slik API-tilbyderen beskriver, typisk i Authorization-headeren som Bearer-token. Ved avslag gir skillet mellom en ugyldig signatur og manglende scope-tilgang et konkret sted å begynne feilsøkingen.

Les også:

• Slik kjøper du SpaceX-aksjen fra Norge – ASK kan ikke brukes
• YouTube-testen velger seertid, ikke klikk: slik tester du miniatyrbilder