OAuth 2, hur fungerar det?

Västtrafiks API:er använder sig av autentiseringsstandarden OAuth 2. Läs därför denna guide för att förstå hur din implementation skall autentisera sig på bästa sätt.

När du i utvecklarportalen skapat en applikation genereras automatiskt en klientidentifierare och en hemlighet. Med hjälp av dessa kan du skapa en accesstoken. Det är en accesstoken som du skall skicka med i dina anrop för att autentisera dig till ett API.

En accesstoken är en kortlivad autentiserings-token
Som längst är den giltig i 24 timmar. Efter denna tid måste du skaffa en ny accesstoken.

Applikationer och accesstokens

Betänk att det är din applikation som får rättigheter till ett API, inte ditt konto. Skapa därför olika applikationer för olika tillämpningar. Skulle någon av din applikations uppgifter hamna i orätta händer är det möjligt att ta bort din applikation för att förhindra vidare användning utan att det påverkar ditt konto i övrigt.

Det finns många färdiga bibliotek som implementerar hela OAuth2-standarden. Med största sannolikhet behöver du därför inte bygga någon egen hantering för att hantera accesstokens. Nedan visas dock stegen som ingår för full transparens och förklaring av standarden.

Västtrafik använder sig av OAuth2-standarden Client Credentials. Det betyder att du endast behöver uppge din applikations klientidentifierare och hemlighet för att få en kortlivad accesstoken.

Steg 1. Generera en accesstoken

Skicka ett POST-anrop till https://ext-api.vasttrafik.se/token med följande headers och payload


          POST https://ext-api.vasttrafik.se/token HTTP/1.1

          Content-Type: application/x-www-form-urlencoded
          Authorization: Basic Z0hoeUlVczF6UFh4VFZhWDhqVTI1R1NxbGE0YToyeTYzOU52NlpMcGQ1Q1BJTU5lNk44dW9JbWNh

          grant_type=client_credentials

I headern Authorization används din klientidentifierare och hemlighet base64-encodad base64(klientidentifierare:hemlighet). Detta är också vad som benämns som Autentiseringsnyckel i vyn för din applikation.

Autentiseringsnyckel
Z0hoeUlVczF6UFh4VFZhWDhqVTI1R1NxbGE0YToyeTYzOU52NlpMcGQ1Q1BJTU5lNk44dW9JbWNh

I payload på ditt anrop specificerar du grant_type=client_credentials.

Ovanstående anrop ger följande svar ifrån servern


          {
            "access_token": "eyJ4NXQiOiJaV05sT...",
            "scope": "default",
            "token_type": "Bearer",
            "expires_in": 86400
          }

Din accesstoken är en JSON Web Token (JWT) som innehåller information om din applikation och vilka API:er du prenumerar på.

En JWT är en base64-encodad JSON-struktur, så det går enkelt att utläsa vad för information som den innehåller. Du kan t.ex enkelt göra detta på jwt.io; men även i din egen kod, t.ex för att utläsa värdet av exp som säger när din token inte längre är giltig.

Du skall inte begära en ny token förrän tiden för nuvarande token gått ut

Om du behöver skapa flera tokens under samma tid skall de skapas med ett individuellt scope

grant_type=client_credentials&scope=device_{deviceId}

Steg 2. Använd din accesstoken

Använd din accesstoken i header Authorization: Bearer {accesstoken} i dina anrop


          GET https://ext-api.vasttrafik.se/pr/v2 HTTP/1.1

          Authorization: Bearer eyJ4NXQiOiJaV05sT...

Steg 3. Förnya din accesstoken

När en accesstoken gått ut kan en ny enkelt skapas genom att upprepa steg 1. Notera att du i anropet får tillbaka värdet expires_in för att se när token går ut. Dessutom innehåller din JWT-token värdet exp som specificerar exakt när accesstoken slutar vara giltig så att du alltid kan verifiera om du har en giltig token eller inte innan du ställer ett anrop.

Om du inte har en giltig accesstoken kommer du i dina anrop få HTTP status 401 tillbaka. Eftersom din JWT innehåller informationen om vilka API:er du prenumererar på behöver du begära en ny token om du prenumererar på ett nytt API.