Bokmål Nynorsk English
Du må oppgradere nettleseren din for å bruke Digipost. Les mer her.
Kom i gang API Batch Funksjonalitet Annet
Get started API Batch Functionality Misc.

Autentisering mot Digipost med OAuth 2.0

For å integrere med Digipost sitt privatperson-API må du bruke OAuth2. Merk at dette kun gjelder privat-API-et, ikke virksomhets-API-et.

Digipost-implementasjonen av OAuth er basert på The OAuth 2.0 Authorization Framework draft 31. OAuth-protokollen er designet for autorisering, men vi har utvidet protokollen for at den også skal kunne brukes til autentisering. Dette har vi gjort på samme måte som Facebook, og det er veldig likt den kommende «OpenID Connect»-standarden.

Før du kan starte med OAuth-integrasjonen, er det første du må gjøre å registrere applikasjonen din i Digipost. Les mer om dette her.

1. Hvordan be en Digipost-bruker om tilgang til data?

Applikasjonen må i en nettleser sende brukeren til:

https://www.digipost.no/post/api/oauth/authorize/new?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<state>&scope=<scope>

I denne URL-en må du sette inn:

Etter at brukeren har godkjent forspørselen, vil nettleseren sendes til URI-en angitt av redirect_uri med parameterne code og state.

  1. Din applikasjon skal da sjekke at state stemmer med det du sendte inn (forsøk på ny dersom den er feil)
  2. Benytt code som en autoriseringskode for å hente ut et access token. Autoriseringskoden (access token) du da får tilbake er gyldig i en kortere tidsperiode (angitt i responsen, pr. i dag 15 minutter).
  3. Du vil også få ut et refresh-token som kan benyttes til å hente ut et nytt access-token når dette utløper. Refresh-tokenet er gyldig helt til brukeren eventuelt velger å trekke tilbake tilgangen fra innstillinger i webgrensesnittet til Digipost.

2. Uthenting av access token

For å hente ut et access token, må applikasjon gjøre en POST-forespørsel mot:

https://www.digipost.no/post/api/oauth/accesstoken

Denne skal ha følgende headere:

POST /post/api/oauth/accesstoken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50aWQ6c2VjcmV0

Headeren Authorization er en standard HTTP Basic Authentication header der client id og secret er slått sammen med kolon mellom og deretter Base64-encodet. Som Content-Type og HTTP-verbet hinter om, skal vi også ha med et sett med parametere til dette kallet. Disse parameterne skal URL-encodes og slås sammen med & slik:

grant_type=code&code=<code>&redirect_uri=<redirect_uri>&nonce=<nonce>

Verdiene som skal settes inn over er:

Responsen til dette kallet vil være en json-string som ser slik ut:

{
    "access_token": "S8d79_zKHBzFOMQ0kHCwJ0o9ukynG0q29L7-Tc1_IrU",
    "refresh_token":"Abd89789KGAS78khjkasd-asdu_klasqw09jkasqwuz",
    "expires_in":180,
    "token_type":"bearer",
    "id_token":"WYOB0orIGIAn4LY8Xo7JxpXTQ5VX/oKZSiE/dnTum7I=.eyJhdWQiOiIzUVdwVW5FQ2NiYkEtQk..."
}

Her ser vi at første element er et access token. Dersom expires_in er høyere enn 0 sekunder, angir denne at tokenet har en begrenset levetid. Man vil da måtte bruke verdien fra refresh_token til å hente et nytt access token. Dersom det ikke finnes et refresh_token, vil man måtte be bruker om tilgang på ny for å få et nytt token, når access tokenet utløper.

Når man skal hente et nytt access token via et refresh token, gjøres det på samme måte som når man henter ut via autoriseringskode, men code byttes ut med refresh_token:

grant_type=refresh_token&refresh_token=<refresh_token>&scope=<scope>

Verdien for scope er frillig og benyttes dersom du ønsker et token med et lavere scope.

3. Bruk av id_token

Feltet id_token er utvidelsen som gjør det mulig å bruke OAuth 2.0 til autentisering. Verdien for id_token er forkortet i eksempelet over. Dette feltet inneholder en signert verdi med informasjon om den påloggede brukeren. Feltet er todelt og kan splittes på punktum. Første del er en signatur og andre del er selve tokenet. Signaturen er generert slik:

BASE64(HMACSHA256(client_secret, token_verdi))

Den kan verfiseres på samme måte. Med token_verdi menes verdien fra id_token etter punktum. Denne verdien er et BASE64-encodet JSON-objekt. Ved å BASE64-dekode vil man da få ut en JSON som ser slik ut:

{
    "aud":"<aud>",
    "exp":180,
    "iat":1349250680,
    "user_id":"<user_id>",
    "iss":"https://www.digipost.no/",
    "nonce":"<nonce>"
}

Verdiene man får ut her er:

Hensikten med id_token er å gjøre det mulig for en applikasjon å bruke Digipost som en login-mekanisme. For at dette skal fungere på en sikker måte må applikasjonen:

4. Bruk av access token

For å benytte access tokenet må man i kall til Digipost benytte headeren:

Authorization: Bearer S8d79_zKHBzFOMQ0kHCwJ0o9ukynG0q29L7-Tc1_IrU

Verdien etter Bearer er her verdien vi mottok som access token i punkt 3.

5. Feilsituasjoner

Mulige feilsituasjoner og forventet handling er dokumentert i OAuth 2-standarden.

5.1 Feil under godkjenning av token

Dersom feilen skyldes ugyldig client_id eller redirect_uri, vil brukeren se en feilmelding i Digipost.

Dersom feilen skyldes feil i andre parametere, eller dersom brukeren velger å ikke gi applikasjonen tilgang, vil Digipost omdirigere nettleseren tilbake til redirect_uri med URI-parametere m.m. som angitt i http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1.2.1.

5.2 Feil under uthenting av access token

Ved feil under uthenting av token vil responsen være som beskrevet i http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-5.2.

5.3 Ugyldig access token

Dersom brukeren på et senere tidspunkt fjerner applikasjonens tilgang fra sine innstillinger, eller man angir et ugyldig access token, vil Digipost returnere en HTTP-respons med status 403 Forbidden.

6. Sikkerhetskrav