Token di accesso in Microsoft Identity Platform

  • Articolo

I token di accesso consentono ai client di chiamare in modo sicuro le API Web protette. Le API Web usano token di accesso per eseguire l'autenticazione e l'autorizzazione.

In base alla specifica OAuth, i token di accesso sono stringhe opache senza un formato impostato. Alcuni provider di identità usano GUID e altri usano BLOB crittografati. Il formato del token di accesso può dipendere dalla configurazione dell'API che lo accetta.

Le API personalizzate registrate dagli sviluppatori in Microsoft Identity Platform possono scegliere tra due formati diversi di token JSON Web denominati v1.0 e v2.0. Le API sviluppate da Microsoft come Microsoft Graph o le API in Azure hanno altri formati di token proprietari. Questi formati proprietari che non possono essere convalidati potrebbero essere token crittografati, JWT o speciali simili a JWT.

Il contenuto del token è destinato solo all'API, il che significa che i token di accesso devono essere considerati stringhe opache. Solo a scopo di convalida e debug, gli sviluppatori possono decodificare JWT usando un sito come jwt.ms. I token ricevuti da un'API Microsoft potrebbero non essere sempre un token JWT che può essere decodificato.

I client devono usare i dati di risposta del token restituiti con il token di accesso per informazioni dettagliate sugli elementi al suo interno. Quando il client richiede un token di accesso, Microsoft Identity Platform restituisce anche alcuni metadati relativi al token di accesso per l'utilizzo dell'applicazione. Queste informazioni includono l'ora di scadenza del token di accesso e gli ambiti per cui è valido. Questi dati consentono all'applicazione di eseguire la memorizzazione intelligente nella cache dei token di accesso senza dover analizzare il token di accesso stesso.

Vedere le sezioni seguenti per informazioni su come un'API può convalidare e usare le attestazioni all'interno di un token di accesso.

Nota

Tutta la documentazione in questa pagina, tranne dove indicato, si applica solo ai token rilasciati per le API registrate. Non si applica ai token rilasciati per le API di proprietà Microsoft, né a tali token per convalidare il modo in cui Microsoft Identity Platform rilascia i token per un'API registrata.

Formati del token

In Microsoft Identity Platform sono disponibili due versioni dei token di accesso: v1.0 e v2.0. Queste versioni determinano le attestazioni presenti nel token e assicurarsi che un'API Web possa controllare il contenuto del token.

Per le API Web è selezionata una delle versioni seguenti come predefinita durante la registrazione:

  • v1.0 per le applicazioni solo Entra di Microsoft. L'esempio seguente mostra un token v1.0 (le chiavi vengono modificate e le informazioni personali vengono rimosse, impedendo la convalida dei token):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

  • v2.0 per le applicazioni che supportano gli account consumer. L'esempio seguente mostra un token v2.0 (le chiavi vengono modificate e le informazioni personali vengono rimosse, impedendo la convalida dei token):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Impostare la versione per le applicazioni specificando il valore appropriato per l'impostazione accessTokenAcceptedVersion nel manifesto dell'app. I valori di null e 1 generano token v1.0 e il valore dei 2 risultati nei token v2.0.

Proprietà del token

Una richiesta di token di accesso coinvolge due parti: il client, che richiede il token e la risorsa (API Web) che accetta il token. La risorsa destinata al token (destinatari) è definita nell'attestazione aud in un token. I client usano il token ma non devono comprendere o tentare di analizzarlo. Le risorse accettano il token.

Microsoft Identity Platform supporta l'emissione di qualsiasi versione del token da qualsiasi endpoint di versione. Ad esempio, quando il valore di accessTokenAcceptedVersion è 2, un client che chiama l'endpoint v1.0 per ottenere un token per tale risorsa riceve un token di accesso v2.0.

Le risorse possiedono sempre i propri token usando l'attestazione aud e sono le uniche applicazioni che possono modificare i dettagli del token.

Durata dei token

La durata predefinita di un token di accesso è variabile. Quando viene rilasciato, Microsoft Identity Platform assegna un valore casuale compreso tra 60 e 90 minuti (75 minuti in media) come durata predefinita di un token di accesso. La variazione migliora la resilienza del servizio distribuendo la domanda di token di accesso nel tempo, impedendo così picchi orari nel traffico verso Microsoft Entra ID.

I tenant che non usano l'accesso condizionale hanno una durata predefinita del token di accesso di due ore per i client, ad esempio Microsoft Teams e Microsoft 365.

Modificare la durata di un token di accesso per controllare la frequenza con cui l'applicazione client scade la sessione dell'applicazione e la frequenza con cui l'utente deve ripetere l'autenticazione (in modo invisibile all'utente o in modo interattivo). Per eseguire l'override della variazione di durata del token di accesso predefinita, usare Durata token configurabile (CTL).

Applicare la variazione di durata dei token predefinita alle organizzazioni in cui è abilitata la valutazione dell'accesso continuo .Apply default token lifetime variation to organizations that have Continuous Access Evaluation (CAE) enabled. Applicare la variazione di durata del token predefinita anche se le organizzazioni usano criteri CTL. La durata del token predefinita per la durata del token di lunga durata è compresa tra 20 e 28 ore. Quando il token di accesso scade, il client deve usare il token di aggiornamento per acquisire automaticamente un nuovo token di aggiornamento e un token di accesso.

Le organizzazioni che usano la frequenza di accesso condizionale (SIF) per applicare la frequenza con cui si verificano gli accessi non possono eseguire l'override della variazione di durata del token di accesso predefinito. Quando le organizzazioni usano SIF, il tempo tra le richieste di credenziali per un client è la durata del token compresa tra 60 e 90 minuti più l'intervallo di frequenza di accesso.

Ecco un esempio del funzionamento della variazione della durata dei token predefinita con la frequenza di accesso. Si supponga che un'organizzazione imposti la frequenza di accesso ogni ora. Quando il token ha una durata compresa tra 60 e 90 minuti a causa della variazione della durata del token, l'intervallo di accesso effettivo si verifica ovunque tra 1 ora e 2,5 ore.

Se un utente con un token con una durata di un'ora esegue un accesso interattivo a 59 minuti, non viene richiesto alcun prompt delle credenziali perché l'accesso è inferiore alla soglia SIF. Se un nuovo token ha una durata di 90 minuti, l'utente non visualizzerà una richiesta di credenziali per un'altra ora e mezza. Durante un tentativo di rinnovo invisibile all'utente, Microsoft Entra ID richiede una richiesta di credenziali perché la lunghezza totale della sessione ha superato l'impostazione della frequenza di accesso di 1 ora. In questo esempio, la differenza di tempo tra le richieste delle credenziali a causa dell'intervallo SIF e della variazione della durata del token sarebbe di 2,5 ore.

Convalidare i token

Non tutte le applicazioni devono convalidare i token. Solo in scenari specifici le applicazioni devono convalidare un token:

  • Le API Web devono convalidare i token di accesso inviati da un client. Devono accettare solo token contenenti uno degli URI AppId come aud attestazione.
  • Le app Web devono convalidare i token ID inviati usando il browser dell'utente nel flusso ibrido, prima di consentire l'accesso ai dati di un utente o stabilire una sessione.

Se nessuno degli scenari descritti in precedenza si applica, non è necessario convalidare il token. I client pubblici come applicazioni native, desktop o a pagina singola non traggono vantaggio dalla convalida dei token ID perché l'applicazione comunica direttamente con l'IDP in cui la protezione SSL garantisce che i token ID siano validi. Non devono convalidare i token di accesso, perché l'API Web deve convalidare, non il client.

Le API e le applicazioni Web devono convalidare solo i token con un'attestazione aud corrispondente all'applicazione. Altre risorse possono avere regole di convalida dei token personalizzate. Ad esempio, non è possibile convalidare i token per Microsoft Graph in base a queste regole a causa del formato proprietario. La convalida e l'accettazione di token destinati a un'altra risorsa è un esempio del problema confuso di deputy .

Se l'applicazione deve convalidare un token ID o un token di accesso, deve prima convalidare la firma del token e l'emittente rispetto ai valori nel documento di individuazione OpenID.

Il middleware Microsoft Entra include funzionalità predefinite per la convalida dei token di accesso, vedere esempi per trovarne uno nel linguaggio appropriato. Sono disponibili anche diverse librerie open source di terze parti per la convalida JWT. Per altre informazioni sulle librerie di autenticazione e sugli esempi di codice, vedere le librerie di autenticazione. Se l'app Web o l'API Web si trova in ASP.NET o ASP.NET Core, usare Microsoft.Identity.Web, che gestisce automaticamente la convalida.

Token v1.0 e v2.0

  • Quando l'app Web/API convalida un token v1.0 (ver attestazione ="1.0"), deve leggere il documento di metadati OpenID Connessione dall'endpoint v1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), anche se l'autorità configurata per l'API Web è un'autorità v2.0.
  • Quando l'app Web/API convalida un token v2.0 (ver attestazione ="2.0"), deve leggere il documento di metadati openID Connessione dall'endpoint v2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), anche se l'autorità configurata per l'API Web è un'autorità v1.0.

Gli esempi seguenti presuppongono che l'applicazione stia convalidando un token di accesso v2.0 e quindi facciano riferimento alle versioni v2.0 dei documenti e delle chiavi dei metadati OIDC. Rimuovere semplicemente "/v2.0" nell'URL se si convalidano i token v1.0.

Convalidare l'autorità emittente

OpenID Connessione Core indica "L'identificatore dell'autorità di certificazione [...] DEVE corrispondere esattamente al valore dell'attestazione iss (autorità emittente). Per le applicazioni che usano un endpoint di metadati specifico del tenant (ad esempio https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration o https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), questo è tutto ciò che è necessario.

Microsoft Entra ID ha una versione indipendente dal tenant del documento disponibile all'indirizzo https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Questo endpoint restituisce un valore https://login.microsoftonline.com/{tenantid}/v2.0dell'autorità di certificazione . Le applicazioni possono usare questo endpoint indipendente dal tenant per convalidare i token da ogni tenant con le modifiche seguenti:

  1. Anziché prevedere che l'attestazione dell'autorità emittente nel token corrisponda esattamente al valore dell'autorità emittente dai metadati, l'applicazione deve sostituire il {tenantid} valore nei metadati dell'autorità di certificazione con l'id tenant che è la destinazione della richiesta corrente e quindi controllare la corrispondenza esatta.

  2. L'applicazione deve usare la issuer proprietà restituita dall'endpoint delle chiavi per limitare l'ambito delle chiavi.

    • Le chiavi con un valore dell'autorità di certificazione come https://login.microsoftonline.com/{tenantid}/v2.0 possono essere usate con qualsiasi autorità emittente di token corrispondente.
    • Le chiavi con un valore dell'autorità di certificazione come https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 devono essere usate solo con corrispondenza esatta.

    L'endpoint della chiave indipendente dal tenant di Microsoft Entra (https://login.microsoftonline.com/common/discovery/v2.0/keys) restituisce un documento simile al seguente:

    {
  "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. Le applicazioni che usano un'attestazione tenantid () di Microsoft Entra cometid limite di attendibilità anziché l'attestazione dell'autorità emittente standard devono assicurarsi che l'attestazione id tenant sia un GUID e che l'autorità di certificazione e tenantid corrispondano.

L'uso di metadati indipendenti dal tenant è più efficiente per le applicazioni che accettano token da molti tenant.

Nota

Con i metadati indipendenti dal tenant di Microsoft Entra, le attestazioni devono essere interpretate all'interno del tenant, proprio come nel Connessione OpenID standard, le attestazioni vengono interpretate all'interno dell'autorità emittente. {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} Ovvero, e {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} descrivere utenti diversi, anche se sub è lo stesso, perché le attestazioni come sub vengono interpretate all'interno del contesto dell'autorità emittente/tenant.

convalidare la firma

Un token JWT contiene tre segmenti separati dal . carattere . Il primo segmento costituisce l'intestazione, il secondo è il corpo, il terzo la firma. Usare il segmento di firma per valutare l'autenticità del token.

Microsoft Entra ID rilascia i token firmati usando gli algoritmi di crittografia asimmetrica standard del settore, ad esempio RS256. L'intestazione del token JWT contiene informazioni sulla chiave e sul metodo di crittografia usati per firmare il token:

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

L'attestazione alg indica l'algoritmo usato per firmare il token, mentre l'attestazione kid indica la chiave pubblica specifica usata per convalidare il token.

In un determinato momento, Microsoft Entra ID può firmare un token ID usando una determinata coppia di chiavi pubblica-privata. Microsoft Entra ID ruota il possibile set di chiavi su base periodica, quindi scrivi l'applicazione per gestire automaticamente tali modifiche alla chiave. Una frequenza ragionevole per verificare la disponibilità di aggiornamenti delle chiavi pubbliche usate da Microsoft Entra ID è ogni 24 ore.

Acquisire i dati della chiave di firma necessari per convalidare la firma usando il documento di metadati OpenID Connessione disponibile in:

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

Suggerimento

Provare a eseguire questa operazione in un browser: URL

Le informazioni seguenti descrivono il documento di metadati:

  • Oggetto JSON che contiene diverse informazioni utili, ad esempio la posizione dei vari endpoint necessari per eseguire l'autenticazione openID Connessione.
  • Include un jwks_urioggetto , che fornisce la posizione del set di chiavi pubbliche che corrispondono alle chiavi private usate per firmare i token. Il token JWK (chiave Web JSON) disponibile in jwks_uri contiene tutte le informazioni sulla chiave pubblica in uso in un determinato momento. RFC 7517 descrive il formato JWK. L'applicazione può usare l'attestazione kid nell'intestazione JWT per selezionare la chiave pubblica, da questo documento, che corrisponde alla chiave privata usata per firmare un token specifico. Può quindi eseguire la convalida della firma usando la chiave pubblica corretta e l'algoritmo indicato.

Nota

Usare l'attestazione kid per convalidare il token. Anche se i token v1.0 contengono entrambe le x5t attestazioni e kid , i token v2.0 contengono solo l'attestazione kid .

L'operazione di convalida della firma non rientra nell'ambito di questo documento. Sono disponibili molte librerie open source per facilitare la convalida della firma, se necessario. Tuttavia, Microsoft Identity Platform dispone di un'estensione per la firma di token per gli standard, ovvero chiavi di firma personalizzate.

Se l'applicazione dispone di chiavi di firma personalizzate in seguito all'uso della funzionalità di mapping delle attestazioni, aggiungere un appid parametro di query contenente l'ID applicazione. Per la convalida, usare jwks_uri questa opzione che punta alle informazioni sulla chiave di firma dell'applicazione. Ad esempio, https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 contiene una l'indirizzo jwks_urihttps://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Convalidare l'autorità emittente

Le app Web che convalidano i token ID e le API Web che convalidano i token di accesso devono convalidare l'autorità di certificazione del token (iss attestazione) rispetto a:

  1. l'autorità emittente disponibile nel documento dei metadati openID connect associato alla configurazione dell'applicazione (autorità). Il documento di metadati da verificare dipende da:
    • versione del token
    • gli account supportati dall'applicazione.
  2. ID tenant (tid attestazione) del token,
  3. autorità di certificazione della chiave di firma.

Applicazioni a tenant singolo

OpenID Connessione Core indica "L'identificatore dell'autorità di certificazione [...] DEVE corrispondere esattamente al valore dell'attestazione iss (autorità emittente). Per le applicazioni che usano un endpoint di metadati specifico del tenant, ad esempio https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration o https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Le applicazioni a tenant singolo sono applicazioni che supportano:

  • Account in una directory organizzativa (solo example-tenant-id ): https://login.microsoftonline.com/{example-tenant-id}
  • Solo account Microsoft personali: https://login.microsoftonline.com/consumers (i consumer sono un nome alternativo per il tenant 9188040d-6c67-4c5b-b112-36a304b66dad)

Applicazioni multi-tenant

Microsoft Entra ID supporta anche applicazioni multi-tenant. Queste applicazioni supportano:

  • Account in qualsiasi directory organizzativa (qualsiasi directory di Microsoft Entra): https://login.microsoftonline.com/organizations
  • Account in qualsiasi directory organizzativa (qualsiasi directory Microsoft Entra) e account Microsoft personali (ad esempio, Skype, XBox): https://login.microsoftonline.com/common

Per queste applicazioni, Microsoft Entra ID espone rispettivamente le versioni indipendenti dal tenant del documento OIDC all'indirizzo https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration e https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration . Questi endpoint restituiscono un valore dell'autorità tenantidemittente, ovvero un modello parametrizzato da : https://login.microsoftonline.com/{tenantid}/v2.0. Le applicazioni possono usare questi endpoint indipendenti dal tenant per convalidare i token da ogni tenant con le clausole seguenti:

  • Convalidare l'autorità di certificazione della chiave di firma
  • Anziché prevedere che l'attestazione dell'autorità emittente nel token corrisponda esattamente al valore dell'autorità emittente dai metadati, l'applicazione deve sostituire il {tenantid} valore nei metadati dell'autorità di certificazione con l'ID tenant che è la destinazione della richiesta corrente e quindi verificare la corrispondenza esatta (tid attestazione del token).
  • Verificare che l'attestazione tid sia un GUID e che l'attestazione iss sia nel formato https://login.microsoftonline.com/{tid}/v2.0 in cui {tid} è l'attestazione esatta tid . Questa convalida collega il tenant all'autorità emittente e torna all'ambito della chiave di firma che crea una catena di attendibilità.
  • Usare tid l'attestazione quando individuano i dati associati all'oggetto dell'attestazione. In altre parole, l'attestazione tid deve far parte della chiave usata per accedere ai dati dell'utente.

Convalidare l'autorità di certificazione della chiave di firma

Le applicazioni che usano i metadati indipendenti dal tenant v2.0 devono convalidare l'autorità di certificazione della chiave di firma.

Documento chiavi e autorità di certificazione della chiave di firma

Come illustrato, nel documento di Connessione OpenID l'applicazione accede alle chiavi usate per firmare i token. Ottiene il documento delle chiavi corrispondente accedendo all'URL esposto nella proprietà jwks_uri del documento OpenId Connessione.

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

Il {example-tenant-id} valore può essere sostituito da un GUID, da un nome di dominio o da organizzazioni e consumer comuni

I keys documenti esposti da Azure AD v2.0 contengono, per ogni chiave, l'emittente che usa questa chiave di firma. Ad esempio, l'endpoint https://login.microsoftonline.com/common/discovery/v2.0/keys della chiave "comune" indipendente dal tenant restituisce un documento simile al seguente:

{
  "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"}
  ]
}

Convalida dell'autorità emittente della chiave di firma

L'applicazione deve usare la issuer proprietà del documento delle chiavi, associata alla chiave usata per firmare il token, per limitare l'ambito delle chiavi:

  • Le chiavi con un valore dell'autorità di certificazione con un GUID come https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 devono essere usate solo quando l'attestazione iss nel token corrisponde esattamente al valore.
  • Le chiavi con un valore di autorità di certificazione basato su modelli come https://login.microsoftonline.com/{tenantid}/v2.0 devono essere usate solo quando l'attestazione iss nel token corrisponde a questo valore dopo aver sostituito l'attestazione tid nel token per il {tenantid} segnaposto.

L'uso di metadati indipendenti dal tenant è più efficiente per le applicazioni che accettano token da molti tenant.

Nota

Con i metadati indipendenti dal tenant di Microsoft Entra, le attestazioni devono essere interpretate all'interno del tenant, proprio come nel Connessione OpenID standard, le attestazioni vengono interpretate all'interno dell'autorità emittente. {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} Ovvero, e {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} descrivere utenti diversi, anche se sub è lo stesso, perché le attestazioni come sub vengono interpretate all'interno del contesto dell'autorità emittente/tenant.

Riepilogo

Ecco alcuni pseudocode che ricapitolano come convalidare l'autorità emittente e firmare l'emittente della chiave:

  1. Recuperare le chiavi dall'URL dei metadati configurato
  2. Controllare il token se firmato con una delle chiavi pubblicate, in caso contrario, non riuscire
  3. Identificare la chiave nei metadati in base all'intestazione kid. Controllare la proprietà "issuer" associata alla chiave nel documento di metadati: 
    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;

Vedi anche

Passaggi successivi