Beskriver hur du hämtar ut en Access Token för ett specifikt api med dina Client Credentials.
Det kompletta flödet finns beskrivet i OAuth2-specen, vi använder oss dock av extra parametrar som kan vara bra att känna till.
Flödet går i korthet till så här:
- Klienten (din applikation) skapar ett Request till Token-endpointen på Regionens OpenIdConnect-server där Klienten ber om en token för en specifik resurs (Api) och som Client Credential skickar applikationen med en Jwt som är signerad med Klientens hemlighet (privata nyckeln i det certifikat som registreats hos Regionen)
- Vid lyckad auktorisering ställs en Access Token ut.
- Klienten använder Access Token i alla Api-anrop till resursen tills dess att Access Token löper ut, då den Klienten på nytt hämtar en Access Token enligt steg 1.
Förberedelser för att hämta biljett
Kontrollera att du har all information tillgänglig:
- Du behöver ditt client_id som identifierar din applikation. Det har du fått från Regionen när du registrerade din applikation där.
- Du behöver veta Apiets resursid , tex: exempelapi.regionhalland.se.
- Du behöver veta vilka scopes du ska begära. Scopes namnges ofta med Apiets namn som prefix, t ex "exempelapi.Public", du kan begära fler scopes på samma gång för samma resursid.
För att bevisa att du är den Klient du utger dig för att vara, ska din begäran signeras med den privata nyckel som hör till det certifikat som registrerats i OpenIdConnect-server som tillhörandes din Klient. Se nedan för beskrivning.
Anrop till OpenIdConnect-servern för att begära ut en biljett (app-token)
För att begära ut en biljett ska du anropa token-endpointen med en POST.
Biljetten du får gäller sedan vanligtvis i en timme. Därefter måste du hämta ut en ny biljett. Den biljetten du fått MÅSTE du alltså cacha i din applikation så att du återanvänder biljetten för alla anrop under den timmen till Apiet. Du SKA INTE hämta ut en ny biljett per anrop.
Se exempel nedan för innehåll:
| POST https://logon.regionhalland.se/adfs/oauth2/token | ||
| Parameter | Exempelvärde | Beskrivning |
| grant_type | client_credentials | |
| resource | exempelapi.regionhalland.se | Apiets Id, återfinns i developer-portalen. |
| client_id | minklient.mindoman.se | Din Klients Id som du fått från Regionen |
| client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer | |
| client_assertion | En JWT som är signerad med ditt certifikat som är registrerat hos Regionen. Se nedan för innehåll | |
| scope | exempelapi.Public | En lista med scopes som du behöver för din applikation. Har du flera scopes separerar du dem med mellanslag |
Client Assertion
Som client_assertion ska du skicka med en Base64encoded signerad JWT med innehåll som nedan:
{
"alg":"RS256",
"kid":"UD4q3w5mjov9JKgEUXkAPr8CBPk", // Thumbprint av ditt certifikat OBS i format x5t
"x5t":"UD4q3w5mjov9JKgEUXkAPr8CBPk", // Det är en Base64Encodning av thumbprint-bytes
"typ":"JWT"
}
.
{
"sub":"minklient.mindoman.se", // Ditt client id
"jti":"5923d1df-7dea-4b12-9121-03efc609258d", // Nytt Guid för varje biljettförfrågan
"nbf":1554726286, // Denna JWT gäller från och med EPOCH-date
"exp":1554726586, // Denna JWT gäller till och med EPOCH-date
"iss":"minklient.mindoman.se", // Ditt client id
"aud":"https://openidconnectserver.endoman.se/tokenendpoint" // Url till Token-endpointen
}
.
base64encode(Signatur(jwt))
Du hittar mer information om hur detta går till i standarden JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants de flesta utvecklingsplattformar har färdiga komponenter som hanterar signeringen.
Token Response
Som svar från OpenIdConnect-server kommer du (om allt stämmer) få ett svar som ser ut ungefär så här:
{
"access_token":"xxxx....xxxxxx",
"token_type":"bearer",
"expires_in":3600,
"scope":"exempelapi.Public"
}
Med expires_in kan du räkna ut hur länge denna Accesstoken är giltig och i din Klient se till att hämta ut en ny Access Token med ett nytt anrop innan tiden löpt ut.
En mer utförlig dokumentation finner du på: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-scenarios-for-developers
Observera att anropet till Token Endpoint måste ske med TLS 1.2!