- Om oss
- » Digitala samarbeten
- » Utveckling av API:er och öppna data
- » Säkerhet och API:er
- » Authorization Code Grant (ACG)
Authorization Code Grant (ACG)
Authorization Code Grant är ett av de OAuth2-flöden som Skatteverket använder för att du ska få tillgång till våra API:er. Ta hjälp av steg för steg-guiderna för att veta hur flödet fungerar i kombination med antingen organisationslegitimation eller e-legitimation.
Bra att veta innan du börjar
Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelationsid. Ett korrelationsid ska vara i string-format i valfri längd men max 36 tecken långt. Du kommer behöva värdet när du ska anropa API:et.
Programvaran måste också generera så kallade state-parametrar. State-parametern är ett slumpmässigt värde som skickas mellan programvaran och auktorisationsservern för att för att förhindra så kallade CSRF-attacker (Cross-Site Request Forgery).
Så använder du flödet ACG
ACG-flödet används främst när den anropande programvaran är serverbaserad. I stora drag går det ut på att en organisation eller person autentiserar sig med hjälp av antingen organisationslegitimation eller e-legitimation mot Skatteverkets auktorisationsserver. Om det är en person som autentiserar sig med en e-legitimation behöver hen också lämna ett medgivande. När det är gjort får programvaran en auktorisationskod som den i sin tur växlar den mot en access token (ett slags behörighetsbiljett) i auktorisationsservern. Med hjälp av access token får användaren slutligen åtkomst till API:et.
Kommunikationen mellan programvaran och API:et ska alltid vara krypterad med https och användaren kan använda en webbläsare, mobilapp eller vanlig klientprogramvara (till exempel Windows, OSx eller Linux) för att kommunicera med programvaran.
För dig som använder API-nycklar och organisationslegitimation
Steg 1. Autentisera organisationen och begär en auktorisationskod
Användaren av din programvara (i det här fallet en organisation) börjar autentiseringen mot Skatteverket genom att till exempel klicka på en knapp någonstans i progamvaran. Detta triggar programvaran att starta en systemwebbläsare på klienten med en URL till auktorisationsservern. URL:en ska innehålla din OAuth2 Client ID (en del av dina API-nycklar), en state-parameter, API:ets scope och den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Om du registrerat flera redirect-URI:er väljer du ut en av dem. Tänk på att du alltid måste skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss.
Så här ska anropet se ut
Testmiljö: GET https://orgoauth2.test.skatteverket.se/oauth2/v1/org/authorize? client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<REDIRECT-URI>&scope=<API SCOPE>
Produktionsmiljö: GET https://orgoauth2.skatteverket.se/oauth2/v1/org/authorize? client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<REDIRECT-URI>&scope=<API SCOPE>
När auktorisationsservern tar emot anropet begär den först att programvaran autentiserar sig med ett organisationslegitimation enligt standarden TLS/SSL.
Steg 2. Ta emot en auktorisationskod
När autentiseringen är klar omdirigeras klienten till URI:n du angett i anropet och lägger samtidigt till en auktorisationskod som query-parameter tillsammans med state-parametern. Din programvara tar emot anropet på samma URI och kontrollerar att state-parametern är identiskt med det som skickades med i anropet till auktorisationsservern.
Exempelsvar
<REDIRECT-URI>:?code=<AUKTORISATIONSKOD>&state=<STATE-PARAMETER>
Steg 3. Använd din auktorisationskod för att begära en access token
I nästa steg anropar din programvaran auktorisationsservern (ändpunkten Token Endpoint) med auktorisationskoden du just fått. Anropet ska också innehålla dina API-nycklar som är märkta med "OAuth2" och en redirect-URI.
Så här ska anropet se ut
Testmiljö: POST https://orgoauth2.test.skatteverket.se/oauth2/v1/org/token
Produktionsmiljö: POST https://orgoauth2.skatteverket.se/oauth2/v1/org/token
HTTP-header: Content-Type: application/x-www-form-urlencoded
Body: grant_type=authorization_code&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&redirect_uri=<REDIRECT-URI>&code=<AUKTORISATIONSKOD>
Steg 4. Ta emot en access token
Efter att auktorisationsservern stämt av uppgifterna du skickade i anropet får du ett svar i form av en JSON-body. Bodyn innehåller bland annat access token och API:ets scope.
Exempelsvar
200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token": <ACCESS TOKEN>,
"expires_in": 3600,
"token_type": "Bearer",
"scope": <API SCOPE>
}
Tänk på att du bara kan använda en access token en timme, efter detta måste du hämta en ny. Det är samtidigt viktigt att du utnyttjar den här timmen och inte hämtar nya access tokens för varje anrop eftersom du bara kan hämta 200 access tokens per timme.
Steg 5. Anropa API:et
Nu när du har access token kan du anropa API:et. Du använder den som värde i en HTTP-header som du skickar med i anropet. Du ska också skicka med den andra delen av dina API-nycklar, de som är märkta med "APIgw" och ett korrelationsid som din programvara genererat. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope. Stämmer uppgifterna skickas anropet sedan vidare till API:et och du är redo att börja använda det.
Så här ska dina HTTP-headers se ut
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
För dig som använder API-nycklar och e-legitimation
Steg 1. Autentisera användaren och begär en auktorisationskod
Användaren av din programvara (i det här fallet en person) börjar autentiseringen mot Skatteverket genom att till exempel klicka på en knapp någonstans i progamvaran. Detta triggar programvaran att starta en systemwebbläsare på klienten med en URL till auktorisationsservern. URL:en ska innehålla din OAuth2 Client ID (en del av dina API-nycklar), en state-parameter, API:ets scope och den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Om du registrerat flera redirect-URI:er väljer du ut en av dem. Tänk på att du alltid måste skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss.
Så här ska anropet se ut
Testmiljö: GET https://peroauth2.test.skatteverket.se/oauth2/v1/per/authorize?client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<REDIRECT-URI>&scope=<API SCOPE>
Produktionsmiljö: GET https://peroauth2.skatteverket.se/oauth2/v1/per/authorize?client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<redirect_uri>&scope=<API SCOPE>
Auktorisationsservern skickar användaren vidare till Skatteverkets inloggningssidor där hen autentiserar sig med en godkänd e-legitimation. Efter inloggning dirigeras användaren till en sida där hen får godkänna att programvaran anropar API:et för användarens räkning.
Steg 2. Ta emot auktorisationskoden
Efter godkännandet omdirigeras klienten till URI:n du angett och lägger samtidigt till en auktorisationskod som query-parameter tillsammans med en state-parameter. Din programvara tar emot anropet på samma URI och kontrollerar att state-parametern är identiskt med det som skickades med i anropet till auktorisationsservern.
Exempelsvar
<REDIRECT-URI>:?code=<AUKTORISATIONSKOD>&state=<STATE-PARAMETER>
Tänk på att en auktorisationskod bara är giltig i fem minuter.
Steg 3. Använd din auktorisationskod för att begära en access token
I nästa steg anropar din programvaran auktorisationsservern (ändpunkten Token Endpoint) med auktorisationskoden du just fått. Anropet ska också innehålla dina API-nycklar som är märkta med "OAuth2" och en redirect-URI.
Så här ska anropet se ut
Testmiljö: POST https://peroauth2.test.skatteverket.se/oauth2/v1/per/token
Produktionsmiljö: POST https://peroauth2.skatteverket.se/oauth2/v1/per/token
HTTP-header: Content-Type: application/x-www-form-urlencoded
Body: grant_type=authorization_code&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&redirect_uri=<REDIRECT-URI>&code=<AUKTORISATIONSKOD>
Steg 4. Ta emot en access token
Efter att auktorisationsservern stämt av uppgifterna du skickade i anropet får du ett svar i form av en JSON-body. Bodyn innehåller bland annat access token och scopet som är kopplat till API:et.
Exempelsvar
200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token": <ACCESS TOKEN>,
"expires_in": 3600,
"token_type": "Bearer",
"scope": <API SCOPE>,
"refresh_token":"<REFRESH TOKEN>"
}
Du får också en refresh token som du kan använda vid ett tillfälle om du behöver hämta ut en ny access token för att giltighetstiden gått ut. Det gör du genom att anropa auktorisationsservern och lägga till refresh token i anropet. Auktorisationsservern svarar då med en ny access token.
Både access token och refresh token har en giltigtighetstid på en timme. Det går att hämta maximalt 12 refresh tokens per användare under tio timmar.
Steg 5. Anropa API:et
Nu när du har access token kan du anropa API:et. Du använder den som värde i en HTTP-header som du skickar med i anropet. Du ska också skicka med den andra delen av dina API-nycklar, de som är märkta med "APIgw" och ett korrelationsid som din programvara genererat. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope. Stämmer uppgifterna skickas anropet sedan vidare till API:et och du är redo att börja använda det.
Så här ska dina HTTP-headers se ut
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
Vi hjälper dig gärna vid frågor
Våra kunniga utvecklare på supporten hjälper dig gärna om du har frågor. Du kan även höra av dig till oss om du vill ha de gamla säkerhetsdokumenten som tidigare hittades på Utvecklarportalen i pdf-format.
Relaterat innehåll
Kontakta oss
Webbseminarier för företagare
Vill du lära dig mer om skatter och företagande? Ta då chansen och möt oss online på våra direktsända webbseminarier. Det är kostnadsfritt och du kan ställa frågor och få svar i en chatt.
Aktuellt
-
Sommarjobbare kan jämka för rätt skatt från början
Den som tjänar mindre än 20 431 kronor på ett sommarjobb och inte har andra inko...
-
Anstånd att lämna inkomstdeklaration till den 19 maj
En del användare har under måndagen haft svårt att logga in på Skatteverkets e-t...
-
Hinderspröva i tid för kommande bröllop
Den som planerar att gifta sig i sommar gör klokt i att ansöka om hindersprövnin...
Tillsammans gör vi samhället möjligt