Microsoft Entra ID - OAuth & OpenID Connect (OIDC)

📰 Blogserie Microsoft Entra ID – Identities

Microsoft Entra ID is een Identity Provider (IdP) met diverse soorten identities voor gecentraliseerde authenticatie en autorisatie in verschillende type tenants.

🗺️ Overzicht

Dit deel van de serie gaat in op de werking en configuratie van de moderne autorisatie- en authentiatieprotocollen OAuth en Open-ID Connect (OIDC). Wil je liever eerst een ander onderwerp lezen? Onderaan deze blog vind je het overzicht van alle artikelen in deze serie!

naar het serie overzicht

Inleiding OAuth & OIDC

OAuth staat voor Open Autorisatie. OAuth is een open standaard voor het delegeren van toegang. Dit protocol is ontwikkeld om een (web) applicatie toegang te geven tot een beperkte verzameling van resources, namens een gebruiker, voor een gelimiteerde hoeveelheid tijd, zonder dat de gebruiker zijn/haar gebruikersnaam en paswoord deelt met die applicatie. Hiervoor maakt OAuth gebruik van access tokens. Deze tijdelijke tokens specificeren welke data een applicatie namens een gebruiker kan benaderen of bewerken en voor hoe lang.

OAuth gaat primair over autorisatie en niet authenticatie. Wanneer je bijvoorbeeld als gebruiker via een applicatie e-mails wilt lezen uit je gmail account, gebruikt deze applicatie OAuth. Jij autoriseert die applicatie om namens jou e-mails te mogen lezen. Hiervoor gebruikt OAuth een ‘consent’ scherm. Dit scherm bevat informatie over welke gegevens de applicatie wil benaderen en waarvoor deze gegevens gebruikt zullen worden. Het doel van dit proces is om gebruikers bewust te maken van de toegang die men verleent en om de mogelijkheid te geven deze toegang goed te keuren of te weigeren. Dit helpt bij het beschermen van de privacy en veiligheid van gebruikersgegevens.

OIDC is een authenticatieprotocol dat bovenop OAuth 2.0 is gebouwd. Het voegt een identiteitslaag toe aan het autorisatieframework van OAuth 2.0. Dit betekent dat OAuth de toegang tot gegevens verleent en OIDC de identiteit van de gebruiker verifieert. Dit gebeurt met een id-token dat informatie bevat over de gebruiker, zoals hun unieke ID, naam en bijvoorbeeld e-mailadres.

OAuth/OIDC gebruiken veel termen die essentieel zijn om Entra ID App registraties en Entra ID Enterprise applications te begrijpen en op de juiste, veilige manier te configureren.

Onderstaand figuur en tabel geven een overzicht van OAuth/OIDC- en gerelateerde Entra ID termen.

OAuth/OIDC/Entra ID termen

OAuth/OIDC flows

OAuth gebruikt verschillende soorten ‘flows’. Een OAuth flow is een reeks stappen die een applicatie doorloopt om toegang te krijgen tot gebruikersgegevens via een autorisatieserver. Er zijn verschillende soorten OAuth flows, elk ontworpen voor specifieke scenario’s en applicatietypen.

De meest gebruikte flows zijn de ‘client credentials’, ‘hybrid’ en ‘authorization code grant’-flows.

client credentials flow

De ‘client credentials’ flow wordt gebruikt voor Clients die deamon-apps en -scripts vertegenwoordigen, zonder dat er enige gebruikersauthenticatie bij betrokken is. De hybrid flow is een mix van OAuth en OIDC.

hybrid flow

Bij een hybrid flow is de Client geconfigureerd om niet alleen een access token (OAuth) maar ook een id-token (OIDC) op te halen bij de autorisatie server. Wanneer een id-token wordt teruggestuurd naar de Client, weet de Client dat de gebruiker is geverifieerd. Id-tokens kunnen door de Client worden gebruikt en geïnterpreteerd om bijvoorbeeld bepaalde inhoud weer te geven op basis van de claims in een id-token. Acces tokens daarentegen hebben geen betekenis voor de Client. De Client stuurt het access token als een ‘bearer’ token naar de resource server om toegang te krijgen tot de resourceserver/api met de gedelegeerde machtigingen.

authorization code grant flow

Met een ‘authorization code grant flow’ wordt eerst een autorisatie code naar de Client gestuurd, die de Client vervolgens gebruikt om een access token te verkrijgen. Deze flow wordt nu met OAuth 2.1 ook afgedwongen voor Single Page Apps (SPA), Native en Mobile Apps. Hieronder volgt uitleg over deze flow, waarom je de implicit grant flow niet meer moet gebruiken, en wat de relatie is met Entra ID app registrations, enterprise app registrations, en service principals.

Authorization code grant flow (en hybrid flow)

Een gebruiker (resource owner) heeft data, bijvoorbeeld e-mails of foto’s op een resource server staan. De resource server maakt de data beschikbaar via een API. De data kan gelezen of bewerkt worden. Deze acties (permissies) op data worden scopes genoemd. Om deze data te beschermen en van permissies te voorzien wordt een authorization (AuthZ) server gebruikt.
Op deze AuthZ server bestaat een security principal (user account) die de resource owner vertegenwoordigt. De resource server vertrouwt de AuthZ server. Wanneer de AuthZ server ook authenticatie (AuthN) ondersteunt zoals bij Entra ID, wordt deze gezien als een Identity Provider (IdP).

De resource owner gebruikt een Client om zijn of haar data te benaderen via een user agent (browser, native- of mobile app). De Client kan een mobiele applicatie zijn (mobile app), een desktop applicatie (native client), een web-server (backend server draait het proces), of bijvoorbeeld een single page app (SPA, een javascript draaiend in de browser van de resource owner).
In plaats van de Client een username/password te geven delegeert de resource owner de benodigde actie (read, write) naar de Client om deze actie namens de resource owner uit te voeren. Daarvoor heeft de Client interactie nodig met de AuthZ server. De Client heeft een representatie van zichzelf op de AuthZ server (app registration). Deze representatie bestaat uit een Client ID en optioneel een secret of een certificaat.

De resource owner benadert/start de Client (A). De Client gebruikt de AuthZ server om een access token te verkrijgen en daarvoor redirect de Client de resource owner naar het authorization endpoint van de AuthZ server. Deze redirection bevat het Client ID, de lijst van benodigde scopes, en een redirection URI (B). Het authorization endpoint voor Entra ID single tenant applicaties is https://login.microsoftonline.com//oauth2/v2.0/authorize.

Wanneer de response_type parameter van het het autorisatie request (B) niet alleen “code” bevat maar ook “openid”, wordt behalve om een autorisatie code (welke later omgewisseld wordt voor een access token) ook om een id token gevraagd. Dit wordt de hybrid flow genoemd, waarbij het autorization endpoint dus niet alleen een ‘code’ terugstuurt nadat de gebruiker is geauthenticeerd, maar ook een id token. Wanneer de scope parameter ook “offline_access” bevat, wordt de ontvangen autorisatie code later niet alleen omgewisseld voor een access token maar ook een refresh token.

In geval van een web-server is de redirection URI het endpoint waar de web-server een response op wil hebben. In geval van een SPA is dit de URL van de bron van de SPA (bijvoorbeeld statische web pagina van een Azure storage account). Voor native- en mobile apps is dit:

• “https://login.microsoftonline.com/common/oauth2/nativeclient”, voor apps met embedded browsers
• “http://localhost” voor apps die systeem browsers gebruiken.

Wanneer de resource owner nog niet geauthenticeerd is zal de IdP de resource owner laten authenticeren. Vervolgens wordt de resource owner ‘geprompt’ voor ‘consent’. De resource owner geeft nu wel/geen toestemming aan de Client, om namens hem/haar, de resource te benaderen met de betreffende scope (bijvoorbeeld lezen) (C). Wanneer de resource owner toestemming geeft worden deze delegated permissies (consent) bewaard in het service principal object (Enterprise App) behorende bij de Client (app registration).

Na het toekennen van de consent permisssies stuurt de AuthZ Server een AUTHZ CODE naar de Client via de in de App Registration gedefinieerde redirect URI (D). In geval van een hybrid flow stuurt de AuthZ Server niet alleen een AUTHZ CODE maar ook een id token behorende bij de ingelogde gebruiker. Het beveiligen van de AUTHZ CODE uitwisseling tussen de Client en de AUTZ server is afhankelijk van het type Client. De volgende stap is ook afhankelijk van het type Client.

Na ontvangst van de AUTZ CODE door de Client zal deze, of via de user agent (in geval van een public client) of via een ‘back-channel’ (in geval van een confidential client) de AUTZ CODE, Client ID, secret (in geval van confidential client), en een code verifier (in geval van PKCE, zie Public Clients vs Confidential Clients ) naar het token endpoint van de AUTZ server sturen (E), in ruil voor een access token en optioneel een id- en refresh- token indien de client hier in het oorspronkelijke request (B) om gevraagd heeft. Het token endpoint voor een Entra ID single tenant applicatie is https://login.microsoftonline.com//oauth2/v2.0/token.

Entra ID genereert d.m.v. “permission grants” tussen het service principal van de Client en het service principal van de API, een acces token.

Een permission grant is een expliciete goedkeuring (“toestemming”) waarbij eén service principal (bijv. jouw eigen applicatie of een daemon/service), toegang krijgt tot een andere service principal (bijv. Microsoft Graph API, of een API die je zelf hebt geregistreerd), met een specifieke machtiging (bijv. User.Read.All, Mail.Send, of een custom scope zoals app.read). Entra ID ondertekend het access token met een cryptografische handtekening.

Nu kan de Client het acces token in de authorization header van het http request naar de API van de resource server sturen. De resource server valideert het aangeboden token en stuurt vervolgens als response de gevraagde data terug (F).

Hieronder volgt een demo voor het volgen van de hierboven beschreven stappen. Het voorbeeld maakt gebruik van de Authorization Code Flow met PKCE voor het verkrijgen van zowel het id token als access token.

Maak een SPA App registration aan waarmee een “code” verkregen kan worden welke “ingewisseld” wordt voor een id token en access token. Met het verkregen access token ga je vervolgens de Azure Storage API aanroepen om de inhoud van een Azure Storage Tabel te bekijken.

Ga naar de Entra ID admin portal en maak een App Registration aan:

Deze App Registration representeert de Client (SPA). Geef http://localhost als rederict URL mee.

Microsoft heeft standaard diverse APIs beschikbaar voor toegang tot diverse resources zoals bijvoorbeeld Azure Storage.

Voeg de scope (permissie) voor toegang tot de Azure Storage toe aan de zojuist aangemaakt App Registration:
Open de aangemaakt App Registation en selecteer “API permissions”. Selecteer “Add a permission” en selecteer “APIs my organization uses”. Selecteer Azure Storage:

en voeg deze permissie toe aan de App registration.

De Microsoft Graph User.Read permissie wordt tegenwoordig standaard aan elke App registration toegevoegd. Deze permissie is nodig om gebruikers te kunnen laten inloggen.

De applicatie (Client) moet nu een code aanvragen bij het ENTRA ID authorizaiton endpoint welke later ingewisseld kan worden voor een id, refresh en access token. Deze stap kun je uitvoeren in een browser. Pas het tenant id en client id aan en plak dan de volgende URI in een browser:

https://login.microsoftonline.com//oauth2/v2.0/authorize?
client_id=
&response_type=code
&redirect_uri=http://localhost
&response_mode=query
&scope=openid%20https://storage.azure.com/.default
&code_challenge=NzBhMDE2YjFjYjA1N2ViMWJkZGIyZGVhMGNhMzdjMjRjNzhjMTRhMGUxMDFiZjRlNjY5MzhjMGYwZDMzNWJlNgkk
&code_challenge_method=plain

Met scope openid wordt een id token gevraagd (OIDC) en https://storage.azure.com/.default geeft de benodigde permissie voor het access token aan (toegang tot Azure Storage).

Voor meer achtergrond informatie over de parameters zie: Microsoft identity platform and OAuth 2.0 authorization code flow

Na het invoeren van de URL wordt je gevraagd om in te loggen. Log in met een Entra ID account. Nu vraagt Entra ID om consent permissies. (Later volgt hier meer over.)

Selecteer “Accept”. Omdat de redirect URI http://localhost en response_mode query krijg je de code terug in de URL van de browser:

Kopieer de gehele URL naar een editor en verwijder het eerste stuk tekst voor 1…. en het laatste stuk tekst vanaf &session…

Nu houd je de code over die ingewisseld kan worden voor de benodigde tokens. Voor het inwisselen kun je postman gebruiken met een POST request naar het token endpoint van je Entra ID tenant: https://login.microsoftonline.com//oauth2/v2.0/token. Plak de verkregen code als waarde in het code veld:

Omdat de code_challenge_method op “plain” staat is de code_verifier hier gelijk aan de code_challenge. Normaliter gebruik je s256 (SHA256) als method.

Verstuur de code (send) voor het verkrijgen van het id, refresh en access token.

Open https://jwt.ms en plak het verkregen access token in de pagina. Hier zie je het verkregen access token:

Met dit token kan nu toegang tot de Azure Storage API verkregen worden.
Maak een storage account aan met bijvoorbeeld table storage:

Zorg ervoor dat de authentication method op Microsoft Entra user account staat, en dat de ingelogde gebruiker waarmee het accestoken verkregen is minimaal lees rechten heeft op het storage account.
Voeg een entity toe aan de tabel:

Met postman stuur je het access token als een bearer token naar het table storage endpoint.

Als resultaat zie je nu de inhoud van de tabel:

Client credential flow

Met de client credential flow kan een webservice (confidential client) zijn/haar ‘eigen’ credentials gebruiken in plaats van te handelen namens een gebruiker.

Deze flow wordt gebruikt om toegang tot web hosted resources te krijgen door de identiteit van een applicatie (Client) te gebruiken. Dit type flow wordt vaak gebruikt voor server-naar-server-interacties die op de achtergrond moeten worden uitgevoerd, zonder directe interactie met een gebruiker en wordt vaak aangeduid met termen als daemons of backend service. De benodigde identiteit voor zo’n daemon of backend service wordt door Microsoft een workload identity genoemd.

Bij de client credential flow worden application permission toegekend aan de applicatie zelf door een beheerder. Id tokens komen in deze flow niet voor omdat er geen (interactieve) gebruikersauthenticatie plaatsvindt. Refresh tokens komen in deze flow ook niet voor omdat het client-id en client secret gebruikt worden om direct een nieuw acces-token te verkrijgen.

De authentictatie van de Client kun je met een secret of X.509certificaat configureren. De certificaat optie is veiliger maar vergt ook meer configuratie en beheer.

Het volgende voorbeeld representeert een web applicatie die alle app registrations in je tenant uitleest zonder een ingelogde gebruiker.

Maak een Entra ID app registratie aan:

De Client heeft eigen credentials nodig voor authenticatie bij je Entra ID tenant. Geef de Client een secret:

Geeft de Client permissies om via MS Graph App Registrations uit te lezen:

Geef Admin consent permissies:

Haal met postman het access token op:

Lees de App Registrations uit met Postman. Plak het verkregen access token als bearer token in de http autorisatie header:

Implicit flow

Entra ID support de OAut 2.0 implicit grant flow zoals beschreven in de OAuth 2.0 specificatie. Met de implicit grant flow komen de access- en/of id-tokens (hybrid flow) direct van het autorisatie endpoint van de autorisatatie server i.p.v. het token endpoint.

Microsoft adviseert deze flow niet meer te gebruiken en in de OAuth 2.1 specificatie is deze flow ook geschrapt in verband met de minder veilige manier waarop de tokens verkregen worden.

I.p.v. het uitwisselen van een autorisatie code om een token te verkrijgen, krijg je het token namelijk direct van het autorisatie endpoint als fragmentdeel van de redirect URL: https://#token (mits het request is uitgevoerd met de “response_mode=fragment” parameter). Dus waar de autorisatie server (entra-id) de browser ook naartoe redirect, het token is op deze manier beschikbaar voor alle code draaiend in de browser. Denk hierbij aan een javascript draaiend in de browser met onbekende/niet vertrouwde libraries. Omdat het token de browser toestaat API calls en web request te maken namens een gebruiker is dit zeer gevaarlijk!

Om te voorkomen dat het token als fragmentdeel van de redirect meegestuurd wordt kan de parameter “response_mode=form_post” in het request gebruikt worden. Op deze manier wordt het token op een veiligere manier door een HTML form POST naar de redirect URI van de Client gestuurd. Bij een HTML POST worden de gegevens in de body van het HTTP request opgenomen, in plaats van in de URL zoals bij een GET request.

Toch blijft de implicit flow kwetsbaar omdat je zonder extra stap direct het access token krijgt van het autorization endpoint. Microsoft verplicht ook voor SPAs tegenwoordig gebruik te maken van de OAuth Authorization Code grant met Proof Key for Code Exchange (PKCE).

Veder dienen access tokens buiten bereik van JavaScripts in de browser opgeslagen te worden. Hiervoor kunnen ‘secure’ en ‘HttpOnly’ cookies gebruikt worden. Secure cookies worden alleen verzonden via een versleutelde HTTPS-verbinding. HttpOnly cookies kunnen niet worden benaderd door client-side scripts zoals JavaScript. Ze zijn alleen leesbaar door de webserver, wat bescherming biedt tegen aanvallen zoals cross-site scripting.

Wanneer je de Microsoft Authentication Library (MSAL) gebruikt, worden veel beveiligingsmaatregelen automatisch voor je geregeld. MSAL zorgt ervoor dat tokens veilig worden opgeslagen en verzonden, en het ondersteunt beveiligingsfuncties zoals de Secure en HttpOnly attributen voor cookies. Verder maakt MSAL tegenwoordig standaard gebruik van de authorization code flow met Proof Key for Code Exchange (PKCE) voor zowel de uitwisseling van id- als access tokens wat een veiliger alternatief is dan de implicit flow. Dit helpt om de veiligheid van je applicaties te waarborgen zonder dat je zelf veel extra configuratie hoeft te doen.

Public Clients vs Confidential Clients

OAuth onderscheidt twee verschillende type Clients, public en confidential.

Confidential Clients zijn applicaties die op een ‘eigen’ web server draaien, afgeschermt van de ‘buiten wereld’, en goed beveiligd. Op dit type Client is het veilig om een ‘secret’, bijvoorbeeld in de vorm van een certificaat, op te slaan, en dit vervolgens mee te sturen naar de AuthZ server ter controle.

Public Clients zijn applicaties die bijvoorbeeld draaien in de browser van een gebruiker (SPA), of applicaties op een mobiele telefoon of desktop van een gebruiker (mobile-, native- apps). Voor dit type apps is het niet veilig om secrets te gebruiken. Bij SPA wordt de source code volledig in de browser geladen en redelijk eenvoudig kunnen keys/codes/secrets achterhaald worden. Voor native- en mobile apps is dit al wat lastiger maar ook daarvoor zijn inmiddels diverse technieken bekend. Voor meer informatie zie: oauth-api-keys-arent-safe-in-mobile-apps.

Voor public clients mogen dus geen secrets gebruikt worden. De geboden oplossing wordt Proof Key for Code Exhange (PKCE) genoemd. De Client genereert een ‘code verifier’ voor een OAuth 2.0 authorisatie aanvraag (B). De Client maakt vervolgens een code challenge, door de code verifier te hashen met een algoritme zoals SHA-256. De Client stuurt een autorisatieverzoek naar de autorisatieserver, inclusief de code challenge. De AuthZ Server associeert een AUTHZ CODE met de code challange. Bij ontvangst van de AUTHZ CODE van de Client (stap E) verifieert de AUTZ Server de door de Client meegestuurde code verifier door deze te vergelijken met de code challenge die eerder werd ontvangen.

PKCE is oorspronkelijk ontworpen om de AUTZ CODE flow in mobile apps te beschermen, maar omdat het de mogelijkheid biedt om AUTZ CODE injectie te voorkomen wordt het tegenwoordig aanbevolen voor elk type OAUTH Client, zelfs voor web apps (confidential Clients) die Client authenticatie gebruiken (d.m.v. een secret of certificaat). Microsoft ENTRA ID verplicht tegenwoordig het gebruik van PKCE voor SPA met de autorization code grant flow!

Toch blijkt PKCE alleen, voor SPA applicaties gebruik makend van javascript, niet voldoende veilig. Browser gebaseerde applicaties zonder backend moeten alle securitymaatregelen voor token aanvragen, sessie-, token-management en token opslag, zelf uitvoeren. Dit leidt tot meer complexe JavaScripts, cross-browser incompatibiliteit en een hoger aanvalsrisico, omdat deze oplossing meer security gevoelige artifacts (zoals tokens) moet opslaan in JavaScript bereikbare locaties.

Daarom is het aan te bevelen voor JavaScript browser applicaties, acterend als een OAuth Client, altijd gebruik te maken van een backend. Dit patroon wordt een backend for frontend (BFF) applicatie architectuur genoemd. Hierbij zorgt de backend, als confidential Client, voor alle veilige protocolinteractie met de autorisatie server voor het verkrijgen van access tokens en optioneel refresh tokens. De backend proxied een request van de frontend naar de resource server, waarbij de backend het correcte access token toevoegt aan het request naar de resource server. Voor meer uitleg over deze applicatie architectuur zie: OAuth 2.0 for Browser-Based Applications.

Duende IdentityServer is een standaard-compliant OpenID Connect and OAuth 2.0 framework voor ASP.NET Core en biedt een Duende.BFF bibliotheek voor het implementeren van de BFF applicatie architectuur. De backend zorgt voor veilige protocol interactie met de autorisatie server en de JavaScript client authenticeert zich bij de backend gebruik makend van traditionele cookie authenticatie. Dit vereenvoudigt de JavaScript code aan de Client frontend kant, en verkleint het aanvalsgebied van de applicatie.

Tokens

Access tokens, id-tokens en refresh tokens

Access tokens worden, na authenticatie, uitgeven door een autorisatie server en geven tijdelijk toegang tot resources. Access tokens hebben een korte levensduur om de beveiliging te waarborgen.

Id tokens worden, na authenticatie van een gebruiker, uitgegeven door een IdP bijv. Entra ID. Bij ontvangst van een id token door een Client, weet de Client dat de betreffende gebruiker succesvol geauthentiseerd is. Informatie in een id token (claims) zoals bijv. naam, e-mail adres, woonplaats, maakt het voor Clients mogelijk om op basis van deze informatie te beslissen wat de gebruiker wel of niet te zien krijgt.

Met refresh tokens worden nieuwe access en id tokens verkregen zonder dat de gebruiker opnieuw hoeft in te loggen. Refresh tokens worden uitgegeven samen met access tokens en hebben een langere levensduur. Refresh tokens kunnen zelf geen toegang krijgen tot resources. Ze worden alleen gebruikt om nieuwe access tokens te verkrijgen. Bij elke keer dat een refresh token wordt gebruikt, wordt een nieuw refresh token uitgegeven, samen met een nieuw access token. Dit betekent dat een refresh token slechts één keer kan worden gebruikt, wat het risico op misbruik vermindert.

OAuth Token formaat

De OAuth specificatie dicteert geen formaat voor access tokens, maar applicaties en identity providers gebruiken ‘opaque’ (ondoorzichtig) tokens of Jason Web Tokens (JWT). Opaque tokens bestaan uit een string die alleen bij de AuthZ server bekend is. Het token wordt gekoppeld aan gebruikers informatie en de permissies van het token zijn alleen bekend bij de AuthZ server. Wanneer de resource server een opaque token van een Client ontvangt, stuurt de resource server een request naar de AuthZ server om het token te valideren en gekoppelde gebruikersinformatie op te halen. De AuthZ server stuurt een ‘token introspection’ resultaat terug, bestaande uit het wel of niet valide zijn van het opaque token en gekoppelde gebruikersinformatie. De resource server gebruikt dit om authorisatie beslissingen te nemen en toegang te verlenen aan de Client voor de gevraagde resource.

Omdat er een aantal nadelen kleven aan opaque tokens, zoals additionele netwerk communicatie, het onderhouden van een statefull session door de resource server en het ontbreken van een echte standaard hebben JWTs tegenwoordig vaak de voorkeur. Ook Microsoft Entra ID gebruikt JWTs voor OAuth access tokens, id-tokens en refresh tokens.

JWT is een open standaard (RFC 7519) die een compacte en zelf onderhoudende manier specifieert voor het veilig versturen van informatie tussen partijen als een JSON object. Het bevat informatie die een resource server kan ontleden en valideren. Een JWT wordt digitaal ondertekend met de private key van de autorisatie server (bijv. Entra ID).
Vanwege de relatieve kleine omvang kan een JWT middels een URL (POST parameter of in de HTTP header) verstuurd worden.

Entra ID access tokens

Een access token heeft geen betekenis voor een OAuth Client zelf maar de Client gebruikt dit token om toegang te krijgen tot een resource server/API. Een claim in een access token is een stuk informatie, over een gebruiker of applicatie, wat wordt verstrekt door Entra ID. Claims zijn feiten over het tokensubject, zoals de identiteit van de gebruiker en de machtigingen die de gebruiker heeft.

Een access token kan bijvoorbeeld de volgende claims bevatten:

• sub: De unieke identifier van de gebruiker (of Client) waar het token betrekking op heeft.
• aud: De beoogde ontvanger van het token (meestal de API die wordt aangeroepen).
• exp: De vervaltijd van het token.
• roles: De rollen die de gebruiker heeft binnen de applicatie, of die de Client (applicatie) zelf heeft.

Claims helpen de ontvangende service (zoals een API) om te bepalen of de gebruiker of applicatie de juiste rechten heeft om toegang te krijgen tot de gevraagde bronnen.

Voorbeeld van een access token gedecodeerd met https://jwt.ms:

Levensduur

De standaard levensduur van een uitgegeven Entra ID access token varieert tussen de 60 en 90 minuten. Deze variatie verbetert de ‘service resilience’ omdat access token aanvragen verspreid worden over de tijd, wat verkeerspieken naar Entra ID voorkomt.

De levensduur van access tokens en id tokens kan per applicatie aangepast worden met token lifetime policies, maar is in het algemeen niet aan te raden. Voor meer informatie zie Configurable token lifetimes – Microsoft identity platform.

De levensduur van refresh- en session tokens kan tegenwoordig niet meer worden aangepast. Deze functionaliteit is vervangen door de Conditional Access authentication session management functionaliteit, zie Configure adaptive session lifetime policies – Microsoft Entra ID.

Gedurende de levensduur van een access token kan dit token gebruikt worden, ook wanneer het user account disabled wordt of wanneer refresh tokens ingetrokken worden (Entra ID Admin Center, selecteer gebruike, selecteer “revoke session”). Dit vormt een risico en daarvoor is een industrie standaard “Open ID Continuous Access Evaluation Profile (CAEP)” ontwikkeld. Deze oplossing maakt het mogelijk onder bepaalde kritische gebeurtenissen (bijv. bij het disablen van een gebruiker) de Client, vrijwel onmiddellijk, een access token behorende bij die gebruiker, niet meer te laten respecteren. Microsoft heeft deze oplossing beschikbaar voor een bepekt aantal applicaties (Sharepoint Online, Exchange online, Teams). Voor meer informatie zie:
Continuous access evaluation in Microsoft Entra – Microsoft Entra ID

Validatie

Validatie van access tokens door een public Client is niet van toepassing omdat het access token geen betekenis heeft voor de Client. Web APIs/Servers dienen access tokens die vanuit een Client gestuurd worden te valideren. Een validatie is bijvoorbeeld het controleren of het token cryptografisch geldig ondertekend is door de issuer (Entra ID).
De public keys voor het verifiëren van de digitale handtekening zijn beschikbaar via het OpenID Connect discovery document.
(https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration). Dit document bevat de JSON Web Key Set (JWKS) uri die verwijst naar de locatie van de JSON Web Key Set welke de public keys bevat.

Een andere validatie is het controleren of het token de juiste audience claim heeft. Is het token bedoeld voor jouw API? Hiermee voorkom je dat iemand een geldig token voor een andere API probeert te gebruiken bij jouw endpoint. De audience claim van het access token moet bijvoorbeeld gelijk zijn aan een voor de API geconfigureerde Application ID URI:

Controleer ook de tijd gerelateerde claims:

• iat: issued at time
• nbf: not before time
• exp: expiration time

en afhankelijk van het autorisatiescenario, controleer de autorisatie gerelateerde claims:

• roles: Rollen toegekend aan de gebruiker of applicatie
• scopes: Lijst van permissies waarvoor de gebruiker (of een admin) de aanroepende Client applicatie consent heeft gegeven om namens hem/haar uit te voeren.

Voor de validatie van tokens is het raadzaam waar mogelijk standard libraries te gebruiken. Voor .NET zie bijvoorbeeld: https://auth0.com/blog/how-to-validate-jwt-dotnet/

Entra ID ID token

In tegenstelling tot access tokens, die bedoeld zijn voor autorisaties tot ‘acties’ in een resource server/API, zijn id tokens voornamelijk bedoeld voor een (frontend) Client/App om de identiteit van een gebruiker te bevestigen. ID tokens geven toegang tot een Client. Claims in een id token zijn niet bedoeld voor autorisaties maar kunnen bijvoorbeeld wel gebruikt worden voor UX-doeleinden van een applicatie.

Levensduur

De standaard levensduur van een id token is 1 uur. Deze kan aangepast worden maar dit is meestal niet wenselijk. Voor meer informatie zie Configurable token lifetimes – Microsoft identity platform.

Validatie

Tokens worden door Entra ID van een digitale handteking voorzien (d.m.v. private key). Een digitale handtekening verzekerd de integriteit van het token (wanneer het token na de digitaal ondertekend aangepast wordt klopt de digitale handtekening niet meer). De digitale handtekening garandeert ook de authenticiteit van het token. Met alleen de public key van de uitgever van het token kan de digitale handtekening geverifieerd worden.

De meningen voor het valideren van de digitale handtekening van id-tokens voor public Clients lopen uiteen. Microsoft stelt dat de sleutels voor validatie op dit type Client door kwaadwillige onderschept en aangepast kunnen worden en daarom deze validatie op dit soort Clients niet wenselijk is en de standaard TLS sessie bescherming garandeert dat de id tokens voor public Clients valide zijn.

Ook de IETF (Internet Engineering Task Force) geeft aan dat het bewaren van ‘secrets’ op public Clients niet veilig is en public Clients gevoelig zijn voor het ‘lekken’ van tokens. Om dit te mitigeren wordt aangeraden token afhandeling te verplaatsen naar een ‘vertrouwde’ backend.

De OIDC Core 1.0 specificatie geeft aan de volgende validaties uit te voeren voor een id token:

• Signature Is het token niet aangepast?
• Issuer (iss): Komt het token van jouw vertrouwde IdP?
• Audience (aud): Is het token voor jouw client/app uitgegeven?
• Expiratie (exp): Is het token nog niet verlopen?
• Issued At (iat) (optioneel): Controleer op geldige uitgiftetijd
• Nonce (optioneel): Komt de nonce overeen met die van het auth request? (tegen replay attacks)
• Subject: Voor wie het token aangemaakt?

Entra ID Refresh token

Refresh tokens worden gebruikt om een gebruikerssessie te verlengen zonder dat de gebruiker opnieuw hoeft te authentiseren. Met een refresh token krijgt de Client een nieuw access token voordat de levensduur van het eerder verkregen access token verstreken is. Refresh tokens zijn niet van toepassing voor workload identies.
Dit type identities heeft niets te maken met gebruikersauthenticatie en halen een nieuw access token op met de OAuth Client Credential Flow of (bij managed identities) via het IMDS endpoint (zie Entra ID Managed Identities).

Clients krijgen een refresh token wanneer ze in een OAuth Authorization CODE Flow Request als scope “offline_access” meegeven. Entra ID OAuth refresh tokens zijn versleuteld en kunnen niet gelezen worden met bijvoorbeeld https://jwt.ms.

Levensduur

De levensduur van Entra ID refresh tokens voor confidential Clients is 90 dagen.
Voor Public Clients (SPAs) is dit 24 uur. SPAs in Entra ID kunnen refresh tokens alleen gebruiken met de Autorization CODE Flow en PKCE. Refresh token maken gebruik van een ‘non-sliding window’. Stel na 20 uur gebruik je het eerst verkregen refresh token om een nieuw access token + refresh token te krijgen, dan is het nieuw verkregen refresh token nog maar 4 uur geldig. Na 24 uur vereist een SPA dus het opnieuw inloggen via een interactieve flow. Wanneer de gebruiker nog een actieve sessie (session cooky) heeft, merkt hij daar niks van, maar omdat browsers geen cookies meer toestaan in iframes, moet dit in een volledig browservenster gebeuren, anders werkt het niet.

Voor meer achtergrondinformatie zie: How to handle third-party cookie blocking in browsers – Microsoft identity platform.

Het aanpassen van de levensduur van refresh tokens in Entra ID is niet mogelijk. Wel kun je met een ENTRA ID Conditional Access Policy, de ‘sign-in frequency’ refresh tokens ongeldig maken na een bepaalde tijd zodat gebruikers geforceerd worden opnieuw in te loggen.

Validatie

Entra ID refresh tokens zijn encrypted en deze kun je dan ook niet valideren. Wel zijn refresh tokens interessant voor aanvallers. Het gebruik en opslaan van refresh tokens moet dan ook veilig gebeuren. Gebruik hiervoor libraries die het veilig omgaan met refresh tokens voor je regelen zoals bijvoorbeeld MSAL.js (v2 of hoger).

Entra ID Family of Refresh Tokens

Microsoft zou Microsoft niet zijn wanneer ze niet ook ‘eigen’ propriatary tokens gebruiken. Een daarvan is “Family of Refresh Tokens” behorende bij een “Family of Client Ids”, gebruikt voor in inloggen in meerdere Microsoft Office Applicaties. Er is weinig informatie te vinden maar in de volgende artikelen wordt hier op ingegaan:

– https://www.xintra.org/blog/tokens-in-entra-id-guide
– https://github.com/secureworks/family-of-client-ids-research

Entra ID Primary Refresh Token

Een meer bekend Microsoft proprietary token is het Primary Refresh Token gebruikt voor ‘seamless’ SSO tussen desktop applicaties en browser sessies. Dit type token zit gekoppeld aan een device. Meer hierover in “Device Identities”.

Permissions

Application permissions vs Delegated permissions

Zoals eerder benoemd is de structuur van access tokens niet gestandaardiseerd. Microsoft gebruikt delegated permission als OAuth Scopes en application permissions als roles.

Delegated permissions

Met delegated permissies kijgt de Client (Applicatie) permissies die de ingelogde gebruiker heeft. Bijvoorbeeld wanneer een delegated permissie “Mail.Read” wordt gegeven aan de App Registratie krijgt de Client alleen toegang tot de mails van de ingelogde gebruiker.

Entra ID delegated permissions zijn OAuth scopes toegekend aan een service principal behorend bij een Client. Voor het toekennen van deze delegated permissions moet een gebruiker consent geven of een beheerder admin consent namens alle gebruikers. Het is aan de applicatie (API/Resource Server) om deze delegated permissions (scope) uit het access token te halen en op de juiste manier te gebruiken. Voor het verkrijgen van een een access token met delegated permissies door een Client moet een gebruiker altijd eerst geauthentiseerd zijn. Dit betekent dat hiervoor een OAuth flow nodig is die eerst de gebruiker authentiseert zoals de Authorization code grant flow (en hybrid flow).

Om dit ter verduidelijken volgt hieronder een voorbeeld van een declaratiesysteem voor medewerkers. De medewerkers authentiseren zich bij de Entra ID workforce tenant

DeclaratieClient: een confidential Web Client die namens gebruikers declaraties kan aanmaken. De Client applicatie krijgt, nadat een gebruiker succesvol is geauthentiseerd en consent permissies heeft gegeven om namens hem/haar declaraties aan te mogen maken, een access token met delegated permissions (scope) declaratie.create.

De Client applicatie stuurt dit access token naar de declaratie API, welke dit token verifieert en de Client applicatie toegang geeft tot de declaratie data voor de betreffende medewerker.

App Registratie voor DeclaratieAPI
Maak een App Registratie aan voor de API met de naam DeclaratieAPI:

Maak jezelf Owner van de App Registration. (Dit maakt het makkelijker om in de volgende stap de API permissies toe te kunnen kunnen voegen aan de App Registration voor de Client.)
Open de App Registration en selecteer “Expose an API” en maak een global unieke Application ID URI aan:

App Registratie voor DeclaratieClient:
Maak een nieuwe App Registration aan voor de DeclaratieClient:

Selecteer API permissions en Add a permission. Selecteer vervolgens My APIs en DeclaratieAPI:

Selecteer Create.Declaraties en Add Permissions. Nu heb je de zojuist aangemaakt OAuth scope van je API toegevoegd aan je Client.

De Microsoft Graph User.Read permissie wordt standaard toegevoegd voor aan een App Registration en kan gebruikt worden door de Client om basis profiel informatie (naam, email, ..) van de ingelogde gebruiker te verkrijgen.

Omdat de nieuwe delegated permissies (scope) niet als low level permissies geconfigureerd zijn kan een standaard gebruiker geen consent permissies geven en moet dit door een administrator gedaan worden. Hierover volgt verderop meer uitleg.
Voor nu, geef admin consent:

Selecteer nu Certificates & secrets en maak een secret aan voor de DeclaratieClient App Registration. Een confidential client (Web App) vereist in Entra ID een certificaat of secret.

Kopieer de volgende URL in een private (incognito) browser en login met een standaard gebruikers account:

https://login.microsoftonline.com/f398b6ff-468c-41f0-aefe-78efa2d4998d/oauth2/v2.0/authorize?
client_id=30509e2d-df34-4994-bd4f-2ac36b882038
&response_type=code
&redirect_uri=http://localhost
&response_mode=query
&scope=api://wjvproapis/Declaratie.Create openid profile offline_access
&code_challenge=NzBhMDE2YjFjYjA1N2ViMWJkZGIyZGVhMGNhMzdjMjRjNzhjMTRhMGUxMDFiZjRlNjY5MzhjMGYwZDMzNWJlNgkk
&code_challenge_method=plain

Nu krijg je de code terug in je adresbalk:

Haal uit de response alles voor 1.AU en alles vanaf &session weg.
Maak een postman request met de volgende parameters:

Omdat in de scope van het autorisatie code request openid staat krijg je ook een id token terug. Omdat er ook offline_access in staat, krijg je ook een refresh_token terug.
Het access token bevat de delegated permissions (scope) in het token:

Veel applicaties gebruiken ‘eigen’ autorisatie registraties (database) met bijvoorbeeld groepen en of rollen om te bepalen wat een gebruiker in een applicatie mag.

Voor het uniek identificeren van een user account kun je de oid claim of sub claim uit het id token gebruiken. De sub claim is ‘pairwise’ oftewel uniek per applicatie. Deze identifier is gegenereerd gebaseerd op een combinatie van de gebruiker, de applicatie registratie en de tenant.

De oid claim is uniek per tenant, dus consistent over meerdere app registraties.

Om de oid claim in het id token te krijgen moet de scope parameter van het autorisatie code request ‘profile’ bevatten.

Entra ID biedt ook de mogelijkheid om rollen toe te kennen aan gebruikers en/of groepen en deze rol in het access token te plaatsen. De applicatie kan dan het accestoken gebruiken om te bepalen wat een ingelogde gebruiker voor rol heeft.

Voeg een role “Approver” toe aan de DeclaratieAPI:
Op de App Registration DeclaratieAPI en selecteer App roles. Selecteer create app role

Open de Enterprise Application DeclaratieAPI en selecteer Users and Groups
Selecteer Add User/Group en voeg de testuser toe.

Selecteer Assign
Herhaal de stappen om een access token te verkrijgen voor de gebruikte testuser.

In deze context zijn rollen meer bedoeld om te bepalen wat een gebruiker mag in een applicatie (RBAC). Rollen worden gecontroleerd in de applicatie code. Scopes definiëren wélke acties een client (bijv. een frontend) namens de gebruiker mag uitvoeren op een API.

Applicatie permissies

Wanneer een App Registration application permissies krijgt, zijn deze permissies onafhankelijk van een ingelogde gebruiker. De App zelf krijgt deze permissies. Dit wordt vaak gebruikt voor geautomatiseerde services (deamons) zonder tussenkomst van een gebruiker. In geval van bijvoorbeeld een “Mail.Read” application permission krijgt de App toegang tot alle mails van alle mailboxen. Omdat hier geen sprake is van een gebruiker die interactief inlogt zijn deze permissies alleen van toepassing met de OAuth Client Credential Flow.

Een API ‘exposed’ Application permissions door het toevoegen van een of meerder rollen aan de App Registration van de betreffende API. Vervolgens kun je die rol als Application Permission toevoegen aan je aan de App Registration (Client) van je deamon applicatie. Het is verstandig om voor App Registations delegated permissies en application permissies niet door elkaar te gebruiken. Dit om verduidelijkt je autorisatiemodel, biedt voordelen met het geven van consent, en voorkomt het toekennen van teveel permissies.

Doorgaand op het voorbeeld van het declaratie systeem waarbij een deamon App gemaakt wordt die bijvoorbeeld automatisch declaraties van niet meer bestaande medewerkers verwijdert:
Voeg de App Role “Declaraties.Remove” toe aan de App Registration van de Declaratie API:

Voeg API permissies toe aan een nieuwe App Registration voor je Deamon App:

En geef Admin Consent:

Na de admin consent van de applicatie permissie wordt in de enterprise app van de DeclaratieAPI automatisch het service principal van de Declaratie Deamon App toegevoegd bij Users en Groups:

Door het verwijderen van dit service principal haal je de admin consent gegeven aan de Client (Deamon App) weer weg.

Voer de Client Credential flow uit met postman. Let op de scope, Microsoft gebruikt altijd de scope </xxx>.default wanneer er geen expliciete OAuth Scope (delegated permissions) gebruikt worden!

Decodeer het access token met https://jwt.ms:

In het gedecodeerde access token zie je dat Application Permissions toegekend zijn als een rol claim in het access token.

Om na te gaan of een gebruiker nog bestaat in Entra ID moet de applicatie de oid claims van alle users kunnen lezen. Hiervoor is de applicatie permissie user.read.all (MS Graph) permissies nodig.

Voeg de User.Read.All permissie toe aan de DeclaratieDeamon app registration en geef admin consent.

Wanneer MS Graph permissies als application permissies toegevoegd worden aan een app registration krijgt het ms graph service principal, het service principal van de app registratie toegevoegd bij ‘users en groups.’
Zoek het service principal Microsoft Graph:

Open het service principal Microsoft Graph en selecteer Users and groups:

Vraag nu in Postman met de client credential flow om een access token met scope https://graph.microsoft.com/default.

Zoals eerder beschreven en hieruit af te leiden, genereert Entra ID d.m.v. “permission grants” tussen het service principal van de Client en het service principal van de API, een acces token.

Met het verkregen access token kan je nu controleren of een oid (bijv. uit de database van je declaratie applicatie) in de tenant nog bestaat:

Bij niet meer bestaan:

Bovenstaande voorbeelden laten zien dat delegated en applicatie permissies nogal verschillend zijn van elkaar. Ben je dus bewust wanneer je applicatie en/of delegated permissies configureert. In veel gevallen worden voor het gemak applicatie permissies geconfigureerd en worden deze door een beheerder toegewezen (admin consent). Hiermee geef je de applicatie zelf dus permissies zonder dat een gebruiker hoeft te zijn ingelogd en dit kan een serieus beveiligingsrisico zijn.

Consent

Delegated- en Application permissions moeten goedgekeurd worden (consent voor gegeven worden). Afhankelijk van je tenant configuratie kan voor een subset van delegated permissies de gebruiker zelf consent geven.

Dit zijn de in Entra ID geconfigureerde low-level permissies. Default zijn dat de volgende delegated permissies:

Deze lijst van low-level permissions kan een tenant administrator uitbreiden zodat gebruikers voor meer delegated permissies consent kunne geven.

Voor multi-tenant App Registrations en voor alle overige delegated permissies kunnen alleen administrators consent geven.

Hiervoor bestaan in Entra ID diverse administratieve rollen. De volgende rollen kunnen consent geven voor non low-level configureerde delegated permissies:
– Global Administrator
– Privileged Role Administrator
– Cloud Application Administrator

Deze consent geldt standaard voor alle gebruikers (tenant-wide). Administrators kunnen optioneel via de Microsoft Graph API consent geven voor specifieke delegated permissies voor specifieke gebruikers.

Bovengenoemde rollen kunnen ook voor Application Permissies consent geven. Cloud Application Administrators kunnen echter geen consent geven voor Microsoft Graph Application Permissies, daarvoor is de rol Global Administrator of Privileged Role Administrator vereist. Onderstaand overzicht toont een voorbeeld van toegekende delegated en application permissies met de Cloud Application Administrator rol.

In bovenstaande afbeelding zijn Microsoft Graph en OneNote Microsoft APIs en is wjvtestappreg een ‘eigen’ geconfigureerde API (exposed API van een App Registration), waarbij de ingelogde gebruiker met de rol Cloud Application Administrator wel consent kan geven voor de OneNote API application permissies maar niet voor de MS Graph API application permissies.

De consent voor permissies wordt opgeslagen in het Service Principal (Enterprise Application) van een App Registration.

Voor meer granualaire controle over deze consent permissies kun je app consent policies gebruiken. Voor meer informatie zie:
– Overview of permissions and consent in the Microsoft identity platform – Microsoft identity platform
– Configure how users consent to applications – Microsoft Entra ID

Het toekennen van consent aan delegated en applicatie permissies moet zorgvuldig gebeuren. Aanvallers kunnen OAuth permissies misbruiken en een regelmatig audit op deze permissies is geen overbodige luxe. Microsoft Defender for Cloud Apps kan hierbij helpen. Microsoft heeft ook een lijst samengesteld van veel misbruikte OAuth permissies in Entra ID: App consent grant investigation. Met bijvoorbeeld “Azure Data explorer” kun je een analyse uitvoeren op een export van OAuth permissies met consent. Zie voor meer informatie Auditing OAuth consent grants in Entra ID (Azure AD) | by Ravi Bakamwar.

📌 Conclusie

Ondanks dat OAuth en OIDC tegenwoordig veel gebruikt worden, ook met Entra ID, is de correcte configuratie en gebruik van Entra ID App Registrations en Enterprise applications bij veel engineers en developers nog een onbekend terrein.

Ook het goed onderhouden van service principals laat bij veel organsiaties te wensen over. Dit terwijl meer en meer services geautomatiseerd worden door het gebruik van CI/CD, pipelines en microservices architecturen.

Dit kan leiden tot risicovolle implementaties, zeker ook omdat kwaadwillende zich meer en meer richten op kwetsbaarheden in het gebruik van tokens en toegekende OAuth permissies. Kennis over OAuth en OIDC is dan ook een bittere noodzaak. Hopelijk heeft deze blog hieraan bijgedragen en kunnen, indien nodig, verbeteringen gepland en geïmplementeerd worden.