Om oss
- Om oss
- » Digitala samarbeten
- » Börja använda 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. Våra steg för steg-guider förklarar hur flödet fungerar tillsammans med API-nycklar och 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 korrelations-id. Med hjälp av korrelations-id kan vi följa anropet i loggar och därmed felsöka lättare. Ett korrelations-id ska vara en max 36 tecken lång textsträng. Du skickar med värdet när du anropar 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ö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 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 (som körs på till exempel Windows, OSx eller Linux) för att kommunicera med programvaran.
Varje partner-API är knutet till ett eller flera specifika säkerhetsflöden och autentiseringsmetoder, du kan alltså inte välja fritt. Inom ACG-flödet finns det två olika autentiseringsmetoder:
- Autentisering med client ID, client secret och organisationslegitimation
- Autentisering med client ID, client secret och e-legitimation
Vad som gäller för respektive API kan du läsa om här:
För dig som använder client ID, client secret och organisationslegitimation
Steg 1. Autentisera organisationen och begär en auktorisationskod
Vid anropet behöver du använda en organisationslegitimation från Expisoft för att autentisera organisationen.
Autentiseringen mot Skatteverket börjar genom att användaren av programvaran klickar på en länk som leder till ett GET-anrop mot authorize-ändpunkten hos Skatteverkets auktorisationsserver. Se även under rubriken "Så här ska anropet se ut". Auktorisationsservern kontrollerar organisationslegitimationen och omdirigerar svaret till den redirect-URI som angetts i anropet.
Anropet ska innehålla: | |
|---|---|
OAuth2 client ID | En del av dina API-nycklar. |
State-parameter | 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). |
Scope | Välj det scope som står i API-beskrivningen på Utvecklarportalen. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så 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>
Testa att hämta auktorisationskod med curl
Du kan hämta en auktorisationskod med ett curl-anrop. På så sätt kan du kontrollera att anslutningen till API:et fungerar. Ersätt bara orden inom vinkelparenteserna med dina uppgifter:
# curl -c "cookies.txt" -L --request GET --cert <SÖKVÄG-TILL-ORGCERT>:<PINKOD-FÖR-ORGCERT> --cert-type P12 "<ÄNDPUNKT-FÖR-AUTHORIZE-ANROP>?client_id=<OAUTH2-CLIENT-ID>&response_type=code&state=1234567&redirect_uri=<DIN-REGISTRERADE-REDIRECT-URI>" -v
Svaret i exemplet ovan kommer att omdirigeras till den redirect-URI som du har angett, med auktorisationskoden som värde på query-parametern "code". Det är detta värde som plockas ut och används i nästa steg. För att få ett resultat med en tydligare utskrift kan du lägga till "2>&1 | grep "code=" sist i anropet ovan.
Förklaring av vinkelparenteserna:
- SÖKVÄG-TILL-ORGCERT: Sökväg till giltig organisationslegitimation
- PINKOD-FÖR-ORGCERT: Pinkoden till organisationslegitimationen.
- ÄNDPUNKT-FÖR-AUTHORIZE-ANROP: Adress till ändpunkt för authorize (anpassa för anrop till test- eller produktionsmiljö).
- DIN-REGISTRERADE-REDIRECT-URI: Den redirect som är registrerad som kopplad till API-nycklarna
Här under ser du hur anropet kan se ut i testmiljö. Observera att värden på parametrar för pinkod, client id och client secret är ofullständiga i exemplet.
# curl -c "cookies.txt" -L --request GET --cert ./bolagA/6489...f69.p12:8433...335 --cert-type P12 "https://orgoauth2.test.skatteverket.se/oauth2/v1/org/authorize?client_id=6dba...75a&response_type=code&state=1234567&redirect_uri=https://localhost/test" -v 2>&1 | grep "code="
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 identisk med den som skickades med i anropet till auktorisationsservern.
Tänk på att en auktorisationskod bara är giltig i fem minuter.
Exempel på omdirigering
<REDIRECT-URI>:?code=<AUKTORISATIONSKOD>&state=<STATE-PARAMETER>
Här är ett verkligt exempel på omdirigeringen:
https://localhost/test?code=9096c9acb71a97359deb1dc201b53907db2de1f31d67156eae3c1ff68c150507&state=1234567
Steg 3. Använd din auktorisationskod för att begära en access token
I nästa steg anropar programvaran auktorisationsservern (ändpunkten Token endpoint) med auktorisationskoden du just fått.
Anropet ska innehålla: | |
|---|---|
Auktorisationskod | Den du precis fått, används för att få en access token. |
OAuth2 client ID | En del av dina API-nycklar. Den är märkt med OAuth2. |
OAuth2 client secret | En del av dina API-nycklar. Den är märkt med OAuth2. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så ska anropet se ut
Ändpunkt för access token i testmiljö: POST https://orgoauth2.test.skatteverket.se/oauth2/v1/org/token
Ändpunkt för access token i testmiljö: POST https://orgoauth2.skatteverket.se/oauth2/v1/org/token
HTTP-header: Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Body: grant_type=authorization_code&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&redirect_uri=<REDIRECT-URI>&code=<AUKTORISATIONSKOD>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
Testa att hämta access token med curl
Du kan hämta en access token med ett curl-anrop. På så sätt kan du kontrollera att anslutningen till API:et fungerar. Ersätt orden inom vinkelparenteserna med dina uppgifter, samt den authorization code som hämtats i anropet ovan.
# curl --request POST --cert <SÖKVÄG-TILL-ORGCERT>:<PINKOD-FÖR-ORGCERT> --cert-type P12 <ÄNDPUNKT-FÖR-ACCESS-TOKEN> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=authorization_code&scope=foo&client_id=<OAUTH2-CLIENT-ID>&client_secret=<OAUTH2-CLIENT-SECRET>&code=<AUTHORIZATION-CODE-FRÅN-FÖREGÅENDE-ANROP>&state=1234567&redirect_uri=<DIN-REGISTRERADE-REDIRECT-URI>"
Förklaring av vinkelparenteserna:
- SÖKVÄG-TILL-ORGCERT: Sökväg till giltig organisationslegitimation
- PINKOD-FÖR-ORGCERT: Pinkoden till organisationslegitimationen.
- ÄNDPUNKT-FÖR-ACCESS-TOKEN: Adress till ändpunkt för att hämta token (anpassa för anrop till test- eller produktionsmiljö).
- DIN-REGISTRERADE-REDIRECT-URI: Den redirect som är registrerad som kopplad till API-nycklarna
Här under ser du hur anropet kan se ut i testmiljö. Observera att värden på parametrar för pinkod, client id och client secret är ofullständiga i exemplet.
# curl --request POST --cert ./bolagA/6489...f69.p12:8433...335 --cert-type P12 https://orgoauth2.test.skatteverket.se/oauth2/v1/org/token -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=authorization_code&scope=foo&client_id=6dba...75a&client_secret=6c9e...75a&code=6bfc...980&state=1234567&redirect_uri=https://localhost/test"
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 din access token. Svaret innehåller också det eller de scope du har begärt. Det är bra om du verifierar att det stämmer med anropet du skickade.
Exempelsvar
200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token":<ACCESS TOKEN>,
"expires_in":3600,
"token_type":"Bearer",
"scope":"<API SCOPE>"
}
Här är ett exempel med riktiga värden:
{
"access_token": "79ab042fc076a755b58cf649458efffad2868caeb2f978a3d1ec19b2405295a6",
"expires_in":3600,
"token_type":"Bearer",
"scope":"foo"
}
Du kan bara använda en access token under den tid som anges i svaret. Det är angett i sekunder på raden "expires in" i exemplet ovan. När tiden har gått ut måste du hämta en ny access token. Det är viktigt att du utnyttjar hela giltighetstiden och inte hämtar nya access tokens för varje anrop.
VIKTIGT! Tänk på att din access token är en värdehandling.
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. API:et kontrollerar vid varje anrop att uppgifterna i access token stämmer.
Anropet ska innehålla: | |
|---|---|
Access token | Den du precis fått. Tänk på att du bara kan använda samma access token under den tid som anges i svaret. |
APIgw client ID | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
APIgw client secret | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
Korrelations-id | Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelations-id. Ett korrelations-id ska vara en max 36 tecken lång textsträng. |
Så ska dina HTTP-headers se ut
Authorization: Bearer <Access token>
Client_Id: <APIgw Client ID>
Client_Secret: <APIgw Client secret>
skv_client_correlation_id: <Korrelations-id>
Här ser du bara de parametrar som är gemensamma för alla Skatteverkets API:er. För specifika API:er kan det krävas fler parametrar. Du hittar dem i tjänstebeskrivningen för respektive API. I tjänstebeskrivningen kan du också kontrollera parametern för korrelations-id, eftersom den finns i flera versioner.
VIKTIGT! Skicka endast med de header-parametrar som är angivna för respektive tjänst, annars kan anropet blockeras.
Här är ett exempel på hur HTTP-headers för anropet kan se ut. Observera att värden på parametrar för client id och client secret är ofullständiga i exemplet.
...
authorization: Bearer 79ab042fc076a755b58cf649458efffad2868caeb2f978a3d1ec19b2405295a6
client_id: b175a...g14c
client_secret: c0122...bcaed
skv_client_correlation_id: 5d93e201-ba43-40ff-ae52-c95d9f21d4e1
...
För dig som använder client ID, client secret och e-legitimation
Steg 1. Autentisera användaren och begär en auktorisationskod
Autentiseringen mot Skatteverket börjar genom att användaren av programvaran klickar på en länk som leder till ett GET-anrop mot authorize-ändpunkten hos Skatteverkets auktorisationsserver. Se även under rubriken "Så här ska anropet se ut".
Anropet ska innehålla: | |
|---|---|
OAuth2 client ID | En del av dina API-nycklar. |
State-parameter | 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). |
Scope | Välj det scope som står i API-beskrivningen på Utvecklarportalen. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid 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.
Observera att det inte går att testa detta flöde med hjälp av curl.
Steg 2. Ta emot auktorisationskoden
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 identisk med den som skickades med i anropet till auktorisationsservern.
Tänk på att en auktorisationskod bara är giltig i fem minuter.
Exempelsvar
Adressen som klienten omdirigerar till har format enligt nedan.
<REDIRECT-URI>:?code=<AUKTORISATIONSKOD>&state=<STATE-PARAMETER>
Ett verkligt exempel kan se ut så här:
https://localhost/my-redirect-uri?code=025bfd37f99c7caca886a12c17f87d33598d2ac7a3f2b031d16c6314b79e3cac&state=12345678901234567890123456789012345678901234567890123456789012345678901234567890YY
Steg 3. Använd din auktorisationskod för att begära en access token
I nästa steg anropar programvaran auktorisationsservern (ändpunkten Token endpoint) med auktorisationskoden du just fått.
Anropet ska innehålla: | |
|---|---|
Auktorisationskod | Den du precis fått, används för att få en access token. |
OAuth2 client ID | En del av dina API-nycklar. Den är märkt med OAuth2. |
OAuth2 client secret | En del av dina API-nycklar. Den är märkt med OAuth2. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så 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;charset=UTF-8
Body: grant_type=authorization_code&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&redirect_uri=<REDIRECT-URI>&code=<AUKTORISATIONSKOD>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
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 din access token. Svaret innehåller också det eller de scope du har begärt. Det är bra om du verifierar att det stämmer med anropet du skickade.
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>"
}
Här är ett exempel med riktiga värden:
{
"access_token": "96381c2d9d66464b427897347bc3aeaa8cd560246800dc60e673e417a0b43b18",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "foo",
"refresh_token": "08168e505b80fc7454f4ff2a1c74232cf7ff1d012b66c89eb529e6d96c9ca197"
}
Tänk på att du bara kan använda en access token under den tid som anges i svaret (expires in). Det är viktigt att du utnyttjar den här tiden och inte hämtar nya access tokens för varje anrop. När giltighetstiden gått ut kan du hämta en ny access token med hjälp av en refresh token.
Fördelen med refresh token är att slutanvändaren inte behöver legitimera sig igen när en ny access token hämtas. Du använder den genom att anropa auktorisationsservern och lägga till refresh token i anropet. Auktorisationsservern svarar då med en ny access token. Refresh token har en giltighetstid på 65 minuter. Det går att hämta maximalt 10 refresh tokens per användare under en pågående session
VIKTIGT! Tänk på att din access token är en värdehandling.
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. API:et kontrollerar vid varje anrop att uppgifterna i access token stämmer.
Anropet ska innehålla: | |
|---|---|
Access token | Den du precis fått. Tänk på att du bara kan använda samma access token under den tid som anges i svaret. |
APIgw client ID | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
APIgw client secret | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
Korrelations-id | Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelations-id. Ett korrelations-id ska vara en max 36 tecken lång textsträng. |
Så ska dina HTTP-headers se ut
Authorization: Bearer <Access token>
Client_Id: <APIgw Client ID>
Client_Secret: <APIgw Client secret>
skv_client_correlation_id: <Korrelations-id>
Här ser du bara de parametrar som är gemensamma för alla Skatteverkets API:er. För specifika API:er kan det krävas fler parametrar. Du hittar dem i tjänstebeskrivningen för respektive API. I tjänstebeskrivningen kan du också kontrollera parametern för korrelations-id, eftersom den finns i flera versioner.
VIKTIGT! Skicka endast med de header-parametrar som är angivna för respektive tjänst, annars kan anropet blockeras.
Här är ett exempel på hur HTTP-headers för anropet kan se ut. Observera att värden på parametrar för client id och client secret är ofullständiga i exemplet.
...
authorization: Bearer 79ab042fc076a755b58cf649458efffad2868caeb2f978a3d1ec19b2405295a6
client_id: b175a...g14c
client_secret: c0122...bcaed
skv_client_correlation_id: 5d93e201-ba43-40ff-ae52-c95d9f21d4e1
...
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
Delta på våra direktsända webbseminarier. Det är kostnadsfritt och du kan ställa frågor och få svar i en chatt.
Aktuellt
-
Nytt uppdrag att utreda AI-verkstad för offentlig sektor
Skatteverket och Försäkringskassan har fått ett nytt uppdrag från regeringen att...
-
Fel och brister inom skogs- och slaktnäringarna
Skatteverket har kontrollerat verksamheter inom skog och slakt. I omkring sex av...
-
Skatteverket leder nytt regeringsuppdrag
Skatteverket får ansvar för att samordna utvecklingen av digitala lösningar och ...
Tillsammans gör vi samhället möjligt