Toegangstokens in het Microsoft Identity Platform

  • Artikel

Met toegangstokens kunnen clients beveiligde web-API's veilig aanroepen. Web-API's gebruiken toegangstokens om verificatie en autorisatie uit te voeren.

Volgens de OAuth-specificatie zijn toegangstokens ondoorzichtige tekenreeksen zonder een ingestelde indeling. Sommige id-providers (IDP's) gebruiken GUID's en andere maken gebruik van versleutelde blobs. De indeling van het toegangstoken kan afhankelijk zijn van de configuratie van de API die het accepteert.

Aangepaste API's die zijn geregistreerd door ontwikkelaars op het Microsoft Identity Platform kunnen kiezen uit twee verschillende indelingen van JSON-webtokens (JWT's) die worden aangeroepen v1.0 en v2.0. Door Microsoft ontwikkelde API's, zoals Microsoft Graph of API's in Azure, hebben andere eigen tokenindelingen. Deze eigen indelingen die niet kunnen worden gevalideerd, kunnen versleutelde tokens, JWT's of speciale JWT-achtige zijn.

De inhoud van het token is alleen bedoeld voor de API, wat betekent dat toegangstokens moeten worden behandeld als ondoorzichtige tekenreeksen. Voor validatie- en foutopsporingsdoeleinden kunnen ontwikkelaars JWT's decoderen met behulp van een site zoals jwt.ms. Tokens die een Microsoft-API ontvangt, zijn mogelijk niet altijd een JWT die kan worden gedecodeerd.

Clients moeten de antwoordgegevens van het token gebruiken die worden geretourneerd met het toegangstoken voor meer informatie over wat erin staat. Wanneer de client een toegangstoken aanvraagt, retourneert het Microsoft Identity Platform ook enkele metagegevens over het toegangstoken voor het verbruik van de toepassing. Deze informatie omvat de verlooptijd van het toegangstoken en de bereiken waarvoor het geldig is. Met deze gegevens kan de toepassing intelligente caching van toegangstokens uitvoeren zonder dat het toegangstoken zelf hoeft te worden geparseerd.

Zie de volgende secties voor meer informatie over hoe een API de claims in een toegangstoken kan valideren en gebruiken.

Notitie

Alle documentatie op deze pagina, behalve waar vermeld, is alleen van toepassing op tokens die zijn uitgegeven voor geregistreerde API's. Het is niet van toepassing op tokens die zijn uitgegeven voor API's die eigendom zijn van Microsoft, en kunnen deze tokens ook niet worden gebruikt om te valideren hoe tokens voor het Microsoft Identity Platform tokens voor een geregistreerde API uitgeven.

Tokenindelingen

Er zijn twee versies van toegangstokens beschikbaar in het Microsoft Identity Platform: v1.0 en v2.0. Deze versies bepalen de claims die zich in het token bevinden en zorg ervoor dat een web-API de inhoud van het token kan beheren.

Web-API's hebben een van de volgende versies geselecteerd als standaard tijdens de registratie:

  • v1.0 voor Microsoft Entra-only toepassingen. In het volgende voorbeeld ziet u een v1.0-token (de sleutels worden gewijzigd en persoonlijke gegevens worden verwijderd, waardoor tokenvalidatie wordt voorkomen):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

  • v2.0 voor toepassingen die consumentenaccounts ondersteunen. In het volgende voorbeeld ziet u een v2.0-token (de sleutels worden gewijzigd en persoonlijke gegevens worden verwijderd, waardoor tokenvalidatie wordt voorkomen):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Stel de versie voor toepassingen in door de juiste waarde op te geven voor de accessTokenAcceptedVersion instelling in het app-manifest. De waarden van null en 1 het resultaat in v1.0-tokens en de waarde van 2 resultaten in v2.0-tokens.

Eigendom van token

Een toegangstokenaanvraag omvat twee partijen: de client, die het token aanvraagt en de resource (Web-API) die het token accepteert. De resource die het token voor (de doelgroep) is bedoeld, wordt gedefinieerd in de aud claim in een token. Clients gebruiken het token, maar moeten het niet begrijpen of proberen te parseren. Resources accepteren het token.

Het Microsoft Identity Platform biedt ondersteuning voor het uitgeven van een tokenversie vanaf elk versie-eindpunt. Wanneer de waarde accessTokenAcceptedVersion bijvoorbeeld is 2, ontvangt een client die het v1.0-eindpunt aanroept om een token voor die resource op te halen een v2.0-toegangstoken.

Resources zijn altijd eigenaar van hun tokens met behulp van de aud claim en zijn de enige toepassingen die hun tokengegevens kunnen wijzigen.

Levensduur van token

De standaard levensduur van een toegangstoken is variabel. Wanneer het Microsoft Identity Platform wordt uitgegeven, wordt een willekeurige waarde toegewezen tussen 60 en 90 minuten (gemiddeld 75 minuten) als de standaardlevensduur van een toegangstoken. De variatie verbetert de servicetolerantie door de vraag naar toegangstokens gedurende een tijd te spreiden, waardoor pieken in het verkeer naar Microsoft Entra ID per uur worden voorkomen.

Tenants die geen voorwaardelijke toegang gebruiken, hebben een standaardlevensduur van twee uur voor clients zoals Microsoft Teams en Microsoft 365.

Pas de levensduur van een toegangstoken aan om te bepalen hoe vaak de clienttoepassing de toepassingssessie verloopt en hoe vaak de gebruiker zich opnieuw moet verifiëren (op de achtergrond of interactief). Als u de standaardvariatie voor de levensduur van het toegangstoken wilt overschrijven, gebruikt u Configureerbare tokenlevensduur (CTL).

Standaardvariatie van tokenlevensduur toepassen op organisaties waarvoor CONTINUOUS Access Evaluation (CAE) is ingeschakeld. Standaardvariatie van tokenlevensduur toepassen, zelfs als de organisaties CTL-beleid gebruiken. De standaardtokenlevensduur voor de levensduur van tokens met een lange levensduur varieert van 20 tot 28 uur. Wanneer het toegangstoken verloopt, moet de client het vernieuwingstoken gebruiken om op de achtergrond een nieuw vernieuwingstoken en toegangstoken te verkrijgen.

Organisaties die gebruikmaken van de aanmeldingsfrequentie voor voorwaardelijke toegang (SIF) om af te dwingen hoe vaak aanmeldingen optreden, kunnen de standaardvariatie van de levensduur van het toegangstoken niet overschrijven. Wanneer organisaties SIF gebruiken, is de tijd tussen referentieprompts voor een client de levensduur van het token dat varieert van 60 tot 90 minuten plus het interval voor de aanmeldingsfrequentie.

Hier volgt een voorbeeld van hoe de standaardvariatie van de levensduur van tokens werkt met de aanmeldingsfrequentie. Stel dat een organisatie elke uur de aanmeldingsfrequentie instelt. Wanneer het token een levensduur heeft van 60 tot 90 minuten vanwege een variatie in de levensduur van tokens, vindt het werkelijke aanmeldingsinterval plaats tussen 1 uur en 2,5 uur.

Als een gebruiker met een token met een levensduur van één uur een interactieve aanmelding uitvoert op 59 minuten, is er geen referentieprompt omdat de aanmelding onder de drempelwaarde voor SIF ligt. Als een nieuw token een levensduur van 90 minuten heeft, ziet de gebruiker geen referentieprompt voor een ander uur en een half uur. Tijdens een stille verlengingspoging vereist Microsoft Entra ID een referentieprompt omdat de totale sessielengte de instelling voor de aanmeldingsfrequentie van 1 uur heeft overschreden. In dit voorbeeld is het tijdsverschil tussen referentieprompts vanwege het SIF-interval en de levensduur van tokens 2,5 uur.

Tokens valideren

Niet alle toepassingen moeten tokens valideren. Alleen in specifieke scenario's moeten toepassingen een token valideren:

  • Web-API's moeten toegangstokens valideren die naar hen zijn verzonden door een client. Ze mogen alleen tokens accepteren die een van hun AppId-URI's als claim aud bevatten.
  • Web-apps moeten id-tokens valideren die naar hen worden verzonden met behulp van de browser van de gebruiker in de hybride stroom, voordat toegang wordt geboden tot de gegevens van een gebruiker of het tot stand brengen van een sessie.

Als geen van de eerder beschreven scenario's van toepassing is, hoeft u het token niet te valideren. Openbare clients, zoals systeemeigen toepassingen, desktoptoepassingen of toepassingen met één pagina, profiteren niet van het valideren van id-tokens, omdat de toepassing rechtstreeks communiceert met de IDP waarbij SSL-beveiliging ervoor zorgt dat de id-tokens geldig zijn. Ze moeten de toegangstokens niet valideren, omdat ze voor de web-API zijn om te valideren, niet de client.

API's en webtoepassingen moeten alleen tokens valideren die een aud claim hebben die overeenkomt met de toepassing. Andere resources hebben mogelijk aangepaste tokenvalidatieregels. U kunt bijvoorbeeld geen tokens valideren voor Microsoft Graph op basis van deze regels vanwege hun eigen indeling. Het valideren en accepteren van tokens die zijn bedoeld voor een andere resource, is een voorbeeld van het verwarde probleem met deputy .

Als de toepassing een id-token of een toegangstoken moet valideren, moet eerst de handtekening van het token en de verlener worden gevalideerd op basis van de waarden in het OpenID-detectiedocument.

De Microsoft Entra-middleware heeft ingebouwde mogelijkheden voor het valideren van toegangstokens. Bekijk voorbeelden om er een te vinden in de juiste taal. Er zijn ook verschillende opensourcebibliotheken van derden beschikbaar voor JWT-validatie. Zie de verificatiebibliotheken voor meer informatie over verificatiebibliotheken en codevoorbeelden. Als uw web-app of web-API zich op ASP.NET of ASP.NET Core bevindt, gebruikt u Microsoft.Identity.Web, waarmee de validatie voor u wordt afgehandeld.

v1.0- en v2.0-tokens

  • Wanneer uw web-app/API een v1.0-token valideert (verclaim ="1.0"), moet het openID-Verbinding maken metagegevensdocument van het v1.0-eindpunt (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration) lezen, zelfs als de instantie die is geconfigureerd voor uw web-API een v2.0-instantie is.
  • Wanneer uw web-app/API een v2.0-token valideert (verclaim ="2.0"), moet het openID-Verbinding maken metagegevensdocument van het v2.0-eindpunt (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration) lezen, zelfs als de instantie die is geconfigureerd voor uw web-API een v1.0-instantie is.

De volgende voorbeelden veronderstellen dat uw toepassing een v2.0-toegangstoken valideert (en daarom verwijst naar de v2.0-versies van de documenten en sleutels voor metagegevens van OIDC). Verwijder de '/v2.0' in de URL als u v1.0-tokens valideert.

De verlener valideren

OpenID Verbinding maken Core zegt : "The Issuer Identifier [...] MOET exact overeenkomen met de waarde van de iss (verlener) Claim." Voor toepassingen die gebruikmaken van een tenantspecifiek metagegevenseindpunt (zoals https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration ofhttps://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), is dit alles wat nodig is.

Microsoft Entra ID heeft een tenantonafhankelijke versie van het document dat beschikbaar is op https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Dit eindpunt retourneert een verlenerwaarde https://login.microsoftonline.com/{tenantid}/v2.0. Toepassingen kunnen dit tenantonafhankelijke eindpunt gebruiken om tokens van elke tenant te valideren met de volgende wijzigingen:

  1. In plaats van te verwachten dat de verlenerclaim in het token exact overeenkomt met de waarde van de uitgever uit metagegevens, moet de toepassing de {tenantid} waarde in de metagegevens van de verlener vervangen door de tenantid die het doel van de huidige aanvraag is en controleer vervolgens de exacte overeenkomst.

  2. De toepassing moet de issuer eigenschap gebruiken die wordt geretourneerd vanuit het eindpunt van de sleutels om het bereik van sleutels te beperken.

    • Sleutels met een verlenerwaarde zoals https://login.microsoftonline.com/{tenantid}/v2.0 kunnen worden gebruikt met een overeenkomende tokenverlener.
    • Sleutels met een verlenerwaarde moeten https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 alleen worden gebruikt met exacte overeenkomst.

    Microsoft Entra tenantonafhankelijk sleuteleindpunt (https://login.microsoftonline.com/common/discovery/v2.0/keys) retourneert een document zoals:

    {
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

  3. Toepassingen die een Microsoft Entra-tenantid(tid)-claim gebruiken als een vertrouwensgrens in plaats van de standaard claim voor verleners, moeten ervoor zorgen dat de claim tenant-id een guid is en dat de verlener en tenantid overeenkomen.

Het gebruik van tenantonafhankelijke metagegevens is efficiënter voor toepassingen die tokens van veel tenants accepteren.

Notitie

Met tenantonafhankelijke metagegevens van Microsoft Entra moeten claims binnen de tenant worden geïnterpreteerd, net zoals bij standaard OpenID-Verbinding maken, worden claims binnen de verlener geïnterpreteerd. Dat wil zeggen, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} en {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} beschrijf verschillende gebruikers, ook al is het sub hetzelfde, omdat claims zoals sub worden geïnterpreteerd binnen de context van de verlener/tenant.

De handtekening valideren

Een JWT bevat drie segmenten, gescheiden door het . teken. Het eerste segment is de koptekst, de tweede is de hoofdtekst en het derde is de handtekening. Gebruik het handtekeningsegment om de echtheid van het token te evalueren.

Microsoft Entra ID-problemen met tokens die zijn ondertekend met behulp van de industriestandaard asymmetrische versleutelingsalgoritmen, zoals RS256. De header van de JWT bevat informatie over de sleutel en versleutelingsmethode die wordt gebruikt om het token te ondertekenen:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

De alg claim geeft het algoritme aan dat wordt gebruikt om het token te ondertekenen, terwijl de kid claim de specifieke openbare sleutel aangeeft die is gebruikt om het token te valideren.

Op een bepaald moment kan microsoft Entra-id een id-token ondertekenen met behulp van een bepaalde set openbare persoonlijke sleutelparen. Microsoft Entra ID roteert de mogelijke set sleutels periodiek, dus schrijf de toepassing om deze sleutelwijzigingen automatisch af te handelen. Een redelijke frequentie om te controleren op updates voor de openbare sleutels die door Microsoft Entra-id worden gebruikt, is elke 24 uur.

Haal de ondertekeningssleutelgegevens op die nodig zijn om de handtekening te valideren met behulp van het OpenID-Verbinding maken metagegevensdocument op:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Tip

Probeer dit in een browser: URL

In de volgende informatie wordt het metagegevensdocument beschreven:

  • Is een JSON-object dat verschillende nuttige informatie bevat, zoals de locatie van de verschillende eindpunten die nodig zijn voor het uitvoeren van OpenID-Verbinding maken-verificatie.
  • Bevat een jwks_uri, waarmee de locatie wordt opgegeven van de set openbare sleutels die overeenkomen met de persoonlijke sleutels die worden gebruikt voor het ondertekenen van tokens. De JSON-websleutel (JWK) in het jwks_uri bestand bevat alle informatie over de openbare sleutel die op dat moment in gebruik is. RFC 7517 beschrijft de JWK-indeling. De toepassing kan de kid claim in de JWT-header gebruiken om in dit document de openbare sleutel te selecteren, die overeenkomt met de persoonlijke sleutel die is gebruikt om een bepaald token te ondertekenen. Vervolgens kan de handtekeningvalidatie worden uitgevoerd met behulp van de juiste openbare sleutel en het aangegeven algoritme.

Notitie

Gebruik de kid claim om het token te valideren. Hoewel v1.0-tokens zowel de als de x5tkid claims bevatten, bevatten v2.0-tokens alleen de kid claim.

Het valideren van handtekeningen valt buiten het bereik van dit document. Er zijn veel opensourcebibliotheken beschikbaar om zo nodig te helpen bij het valideren van handtekeningen. Het Microsoft Identity Platform heeft echter één uitbreiding voor tokenondertekening voor de standaarden, die aangepaste ondertekeningssleutels zijn.

Als de toepassing aangepaste ondertekeningssleutels heeft als gevolg van het gebruik van de functie claimtoewijzing , voegt u een appid queryparameter toe die de toepassings-id bevat. Gebruik deze informatie voor validatie jwks_uri naar de informatie over de ondertekeningssleutel van de toepassing. Bijvoorbeeld: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 bevat een jwks_uri van https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

De verlener valideren

Web-apps die id-tokens valideren en web-API's die toegangstokens valideren, moeten de uitgever van het token (iss claim) valideren op:

  1. de verlener die beschikbaar is in het openID connect-metagegevensdocument dat is gekoppeld aan de toepassingsconfiguratie (instantie). Het document met metagegevens waarop moet worden gecontroleerd, is afhankelijk van:
    • de versie van het token
    • de accounts die door uw toepassing worden ondersteund.
  2. de tenant-id (tid claim) van het token,
  3. de uitgever van de ondertekeningssleutel.

Toepassingen met één tenant

OpenID Verbinding maken Core zegt : "The Issuer Identifier [...] MOET exact overeenkomen met de waarde van de iss claim (uitgever). Voor toepassingen die gebruikmaken van een tenantspecifiek metagegevenseindpunt, zoals https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration ofhttps://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Toepassingen met één tenant zijn toepassingen die ondersteuning bieden voor:

  • Accounts in één organisatiemap (alleen voorbeeld-tenant-id ): https://login.microsoftonline.com/{example-tenant-id}
  • Alleen persoonlijke Microsoft-accounts: https://login.microsoftonline.com/consumers (consumenten zijn een bijnaam voor de tenant 9188040d-6c67-4c5b-b112-36a304b66dad)

Toepassingen voor meerdere tenants

Microsoft Entra ID ondersteunt ook toepassingen met meerdere tenants. Deze toepassingen ondersteunen:

  • Accounts in elke organisatiemap (elke Microsoft Entra-directory): https://login.microsoftonline.com/organizations
  • Accounts in elke organisatiedirectory (elke Microsoft Entra-directory) en persoonlijke Microsoft-accounts (bijvoorbeeld Skype, XBox): https://login.microsoftonline.com/common

Voor deze toepassingen maakt Microsoft Entra ID tenantonafhankelijke versies van het OIDC-document beschikbaar op https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration en https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration respectievelijk. Deze eindpunten retourneren een verlenerwaarde, een sjabloon die is geparametriseerd door : tenantidhttps://login.microsoftonline.com/{tenantid}/v2.0. Toepassingen kunnen deze tenantonafhankelijke eindpunten gebruiken om tokens van elke tenant te valideren met de volgende bepalingen:

  • De verlener van ondertekeningssleutels valideren
  • In plaats van te verwachten dat de verlenerclaim in het token exact overeenkomt met de waarde van de uitgever uit metagegevens, moet de toepassing de {tenantid} waarde in de metagegevens van de uitgever vervangen door de tenant-id die het doel van de huidige aanvraag is en controleer vervolgens de exacte overeenkomst (tid claim van het token).
  • Controleer of de tid claim een GUID is en de iss claim van het formulier https://login.microsoftonline.com/{tid}/v2.0 is waar {tid} de exacte tid claim is. Deze validatie koppelt de tenant aan de verlener en weer aan het bereik van de ondertekeningssleutel die een vertrouwensketen creëert.
  • Gebruik tid claim wanneer ze gegevens vinden die zijn gekoppeld aan het onderwerp van de claim. Met andere woorden, de tid claim moet deel uitmaken van de sleutel die wordt gebruikt voor toegang tot de gegevens van de gebruiker.

De verlener van ondertekeningssleutels valideren

Toepassingen die gebruikmaken van de tenantonafhankelijke metagegevens van v2.0 moeten de uitgever van de ondertekeningssleutel valideren.

Document- en ondertekeningssleutelverlener van sleutels

Zoals besproken, opent uw toepassing in het document OpenID Verbinding maken de sleutels die worden gebruikt om de tokens te ondertekenen. Het bijbehorende sleutelsdocument wordt opgehaald door toegang te krijgen tot de URL die wordt weergegeven in de eigenschap jwks_uri van het OpenId Verbinding maken-document.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

De {example-tenant-id} waarde kan worden vervangen door een GUID, een domeinnaam of algemene organisaties en consumenten

De keys documenten die door Azure AD v2.0 worden weergegeven, bevatten voor elke sleutel de verlener die deze ondertekeningssleutel gebruikt. Het tenantonafhankelijke sleuteleindpunt https://login.microsoftonline.com/common/discovery/v2.0/keys retourneert bijvoorbeeld een document zoals:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Validatie van de verlener van ondertekeningssleutels

De toepassing moet de issuer eigenschap van het sleuteldocument gebruiken, gekoppeld aan de sleutel die wordt gebruikt om het token te ondertekenen, om het bereik van sleutels te beperken:

  • Sleutels met een verlenerwaarde met een GUID moeten https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 alleen worden gebruikt wanneer de iss claim in het token exact overeenkomt met de waarde.
  • Sleutels met een waarde voor een sjabloonuitgever moeten https://login.microsoftonline.com/{tenantid}/v2.0 alleen worden gebruikt wanneer de iss claim in het token overeenkomt met deze waarde nadat de tid claim in het token voor de {tenantid} tijdelijke aanduiding is vervangen.

Het gebruik van tenantonafhankelijke metagegevens is efficiënter voor toepassingen die tokens van veel tenants accepteren.

Notitie

Met tenantonafhankelijke metagegevens van Microsoft Entra moeten claims binnen de tenant worden geïnterpreteerd, net zoals bij standaard OpenID-Verbinding maken, worden claims binnen de verlener geïnterpreteerd. Dat wil zeggen, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} en {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} beschrijf verschillende gebruikers, ook al is het sub hetzelfde, omdat claims zoals sub worden geïnterpreteerd binnen de context van de verlener/tenant.

Samenvatting

Hier volgt een pseudocode waarin wordt uitgelegd hoe u de uitgever en de verlener van ondertekeningssleutels kunt valideren:

  1. Sleutels ophalen uit de geconfigureerde metagegevens-URL
  2. Controleer het token als het is ondertekend met een van de gepubliceerde sleutels, mislukt als dat niet het enige is
  3. Identificeer de sleutel in de metagegevens op basis van de kid-header. Controleer de eigenschap 'issuer' die is gekoppeld aan de sleutel in het metagegevensdocument: 
    var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Zie ook

Volgende stappen