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.
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.
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.
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:
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.
Mulige feilsituasjoner og forventet handling er dokumentert i OAuth 2-standarden.
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.
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.
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.