Aggiornamenti importanti ai protocolli di autenticazione della versione 2.0Important Updates to the v2.0 Authentication Protocols

Nota per gli sviluppatori:Attention developers! nelle prossime due settimane verranno rilasciati alcuni aggiornamenti ai protocolli di autenticazione della versione 2.0 che potrebbero comportare modifiche di rilievo per le app scritte durante il periodo di anteprima.Over the next two weeks, we will be making a few updates to our v2.0 authentication protocols that may mean breaking changes for any apps you have written during our preview period.

Parti interessateWho does this affect?

Le app scritte per l'uso dell'endpoint di autenticazione convergente della versione 2.0,Any apps that have been written to use the v2.0 converged authentication endpoint,

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Altre informazioni sull'endpoint della versione 2.0 sono disponibili qui.More information on the v2.0 endpoint can be found here.

Se è stata compilata un'app con l'endpoint della versione 2.0 creando il codice direttamente nel protocollo della versione 2.0 e usando il middleware Web OAuth o OpenID Connect oppure usando altre librerie di terze parti per eseguire l'autenticazione, è necessario testare i progetti e apportare le eventuali modifiche necessarie.If you have built an app using the v2.0 endpoint by coding directly to the v2.0 protocol, using any of our OpenID Connect or OAuth web middlewares, or using other 3rd party libraries to perform authentication, you should be prepared to test your projects and make changes if necessary.

Parti non interessateWho doesn`t this affect?

Le app scritte in base all'endpoint di autenticazione di Azure AD di produzione,Any apps that have been written against the production Azure AD authentication endpoint,

https://login.microsoftonline.com/common/oauth2/authorize

Questo protocollo è fisso e non subirà modifiche.This protocol is set in stone and will not be experiencing any changes.

Se l'app usa solo la libreria ADAL per eseguire l'autenticazione, non è necessario apportare alcuna modifica.Furthermore, if your app only uses our ADAL library to perform authentication, you won`t have to change anything. ADAL protegge l'app dalle modifiche.ADAL has shielded your app from the changes.

Dettaglio delle modificheWhat are the changes?

Rimozione del valore x5t dalle intestazioni JWTRemoving the x5t value from JWT headers

L'endpoint della versione 2.0 fa ampio uso dei token JWT, che contengono una sezione dei parametri di intestazione con i relativi metadati sul token.The v2.0 endpoint uses JWT tokens extensively, which contain a header parameters section with relevant metadata about the token. Decodificando l'intestazione di uno dei JWT correnti, si otterrebbe un risultato simile al seguente:If you decode the header of one of our current JWTs, you would find something like:

{ 
    "type": "JWT",
    "alg": "RS256",
    "x5t": "MnC_VZcATfM5pOYiJHMba9goEKY",
    "kid": "MnC_VZcATfM5pOYiJHMba9goEKY"
}

Dove entrambe le proprietà "x5t" e "kid" identificano la chiave pubblica da usare per convalidare la firma del token, recuperata dall'endpoint dei metadati di OpenID Connect.Where both the "x5t" and "kid" properties identify the public key that should be used to validate the token`s signature, as retrieved from the OpenID Connect metadata endpoint.

La modifica consiste nella rimozione della proprietà "x5t".The change we are making here is to remove the "x5t" property. È possibile continuare a usare gli stessi meccanismi per la convalida dei token, ma per il recupero della chiave pubblica corretta è possibile basarsi unicamente sulla proprietà "kid", come specificato nel protocollo OpenID Connect.You may continue to use the same mechanisms to validate tokens, but should rely only on the "kid" property to retrieve the correct public key, as specified in the OpenID Connect protocol.

Importante

Assicurarsi che l'app non dipenda dall'esistenza del valore x5t.Your job: Make sure your app does not depend on the existence of the x5t value.

Rimozione di profile_infoRemoving profile_info

In precedenza, l'endpoint della versione 2.0 restituiva un oggetto JSON con codifica Base64 denominato profile_info nelle risposte dei token.Previously, the v2.0 endpoint has been returning a base64 encoded JSON object in token responses called profile_info. Quando si richiedeva un token di accesso dall'endpoint della versione 2.0 inviando una richiesta a:When requesting an access token from the v2.0 endpoint by sending a request to:

https://login.microsoftonline.com/common/oauth2/v2.0/token

La risposta era simile all'oggetto JSON seguente:The response would look like the following JSON object:

{ 
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https://outlook.office.com/mail.read",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
    "refresh_token": "OAAABAAAAiL9Kn2Z27UubvWFPbm0gL...",
    "profile_info": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
}

Il valore profile_info conteneva informazioni sull'utente che aveva eseguito l'accesso all'app, ad esempio il nome visualizzato, il nome, il cognome, l'indirizzo di posta elettronica, l'identificatore e così via.The profile_info value contained information about the user who signed into the app - their display name, first name, surname, email address, identifier, and so on. profile_info veniva usato principalmente per la memorizzazione nella cache dei token e ai fini della visualizzazione.Primarily, the profile_info was used for token caching and display purposes.

Il valore profile_info è stato rimosso e le informazioni vengono ora fornite agli sviluppatori in una posizione leggermente diversa.We are now removing the profile_info value – but don't worry, we are still providing this information to developers in a slightly different place. Invece di profile_info, l'endpoint della versione 2.0 restituisce ora un id_token in ogni risposta del token:Instead of profile_info, the v2.0 endpoint will now return an id_token in each token response:

{ 
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https://outlook.office.com/mail.read",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
    "refresh_token": "OAAABAAAAiL9Kn2Z27UubvWFPbm0gL...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
}

È possibile decodificare e analizzare l'id_token per recuperare le stesse informazioni fornite da profile_info.You may decode and parse the id_token to retrieve the same information that you received from profile_info. L'id_token è un token Web JSON (JWT) il cui contenuto è specificato da OpenID Connect.The id_token is a JSON Web Token (JWT), with contents as specified by OpenID Connect. Il codice per eseguire questa operazione dovrebbe essere molto simile. È sufficiente estrarre il segmento intermedio (il corpo) dell'id_token e decodificarlo con Base64 per accedere all'oggetto JSON al suo interno.The code for doing so should be very similar – you simply need to extract the middle segment (the body) of the id_token and base64 decode it to access the JSON object within.

Nelle prossime due settimane è consigliabile scrivere il codice dell'app in modo che le informazioni sull'utente vengano recuperate da id_token o profile_info, a seconda del valore presente.Over the next two weeks, you should code your app to retrieve the user information from either the id_token or profile_info; whichever is present. In questo modo, quando verrà apportata la modifica l'app potrà gestire senza problemi la transizione da profile_info a id_token, senza interruzioni.That way when the change is made, your app can seamlessly handle the transition from profile_info to id_token without interruption.

Importante

Assicurarsi che l'app non dipenda dall'esistenza del profile_info valore.Your job: Make sure your app does not depend on the existence of the profile_info value.

Rimozione di id_token_expires_inRemoving id_token_expires_in

Oltre a profile_info verrà rimosso anche il parametro id_token_expires_in dalle risposte.Similar to profile_info, we are also removing the id_token_expires_in parameter from responses. In precedenza, l'endpoint della versione 2.0 restituiva un valore per id_token_expires_in insieme a ogni risposta dell'id_token, ad esempio in una risposta di autorizzazione:Previously, the v2.0 endpoint would return a value for id_token_expires_in along with each id_token response, for instance in an authorize response:

https://myapp.com?id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...&id_token_expires_in=3599...

O in una risposta del token:Or in a token response:

{ 
    "token_type": "Bearer",
    "id_token_expires_in": 3599,
    "scope": "openid",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
    "refresh_token": "OAAABAAAAiL9Kn2Z27UubvWFPbm0gL...",
    "profile_info": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
}

Il valore id_token_expires_in indicava il numero di secondi di validità dell'id_token.The id_token_expires_in value would indicate the number of seconds the id_token would remain valid for. Il valore id_token_expires_in viene ora completamente rimosso.Now, we are removing the id_token_expires_in value completely. Al suo posto è possibile usare le attestazioni nbf e exp dello standard OpenID Connect per esaminare la validità di un id_token.Instead, you may use the OpenID Connect standard nbf and exp claims to examine the validity of an id_token. Per altre informazioni su queste attestazioni, vedere il riferimento al token della versione 2.0 .See the v2.0 token reference for more information on these claims.

Importante

Assicurarsi che l'app non dipenda dall'esistenza del id_token_expires_in valore.Your job: Make sure your app does not depend on the existence of the id_token_expires_in value.

Modifica delle attestazioni restituite da scope=openidChanging the claims returned by scope=openid

Questa sarà la modifica più significativa, che influirà su quasi tutte le app che usano l'endpoint della versione 2.0.This change will be the most significant – in fact, it will affect almost every app that uses the v2.0 endpoint. Molte applicazioni inviano richieste all'endpoint della versione 2.0 usando l'ambito openid, ad esempio:Many applications send requests to the v2.0 endpoint using the openid scope, like:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=...
&redirect_uri=...
&response_mode=form_post
&response_type=id_token
&scope=openid offline_access https://outlook.office.com/mail.read

Attualmente, quando l'utente concede l'autorizzazione per l'ambito openid, l'applicazione riceve molte informazioni sull'utente nell'id_token risultante.Today, when the user grants consent for the openid scope, your app receives a wealth of information about the user in the resulting id_token. Le attestazioni includono, ad esempio, il nome dell'utente, il nome utente preferito, l'indirizzo di posta elettronica, l'ID oggetto e altro ancora.These claims can include their name, preferred username, email address, object ID, and more.

In questo aggiornamento vengono modificate le informazioni a cui l'app ha accesso tramite l'ambito openid , per una maggiore conformità alle specifiche di OpenID Connect.In this update, we are changing the information that the openid scope affords your app access to, to better comform with the OpenID Connect specification. L'ambito openid consente all'app di far accedere l'utente e di ricevere un identificatore specifico dell'app per l'utente nell'attestazione sub dell'id_token.The openid scope will only allow your app to sign the user in, and receive an app-specific identifier for the user in the sub claim of the id_token. Le attestazioni in un id_token a cui è stato concesso solo l'ambito openid saranno prive di informazioni personali.The claims in an id_token with only the openid scope granted will be devoid of any personally identifiable information. Di seguito sono riportati alcuni esempi di attestazioni dell'id_token:Example id_token claims are:

{ 
    "aud": "580e250c-8f26-49d0-bee8-1c078add1609",
    "iss": "https://login.microsoftonline.com/b9410318-09af-49c2-b0c3-653adc1f376e/v2.0 ",
    "iat": 1449520283,
    "nbf": 1449520283,
    "exp": 1449524183,
    "nonce": "12345",
    "sub": "MF4f-ggWMEji12KynJUNQZphaUTvLcQug5jdF2nl01Q",
    "tid": "b9410318-09af-49c2-b0c3-653adc1f376e",
    "ver": "2.0",
}

Per ottenere informazioni personali sull'utente nell'app, questa dovrà richiedere autorizzazioni aggiuntive all'utente.If you want to obtain personally identifiable information (PII) about the user in your app, your app will need to request additional permissions from the user. Viene ora introdotto il supporto per due nuovi ambiti dalla specifica di OpenID Connect, email e profile, che consentono di eseguire questa operazione.We are introducing support for two new scopes from the OpenID Connect spec – the email and profile scopes – which allow you to do so.

  • L'ambito email è molto semplice: consente all'app di accedere all'indirizzo di posta elettronica primario dell'utente tramite l'attestazione email nell'id_token.The email scope is very straightforward – it allows your app access to the user's primary email address via the email claim in the id_token. Si noti che l'attestazione email non sarà sempre presente nell'id_token, ma verrà inclusa solo se disponibile nel profilo dell'utente.Note that the email claim will not always be present in id_tokens – it will only be included if available in the user's profile.
  • L'ambito profile concede all'app l'accesso a tutte le altre informazioni di base sull'utente, vale a dire il nome, il nome utente preferito, l'ID oggetto e così via.The profile scope affords your app access to all other basic information about the user – their name, preferred username, object ID, and so on.

Questo permette di creare il codice dell'app in modo che la divulgazione delle informazioni sia minima, chiedendo all'utente solo il set di informazioni necessario per il funzionamento dell'app.This allows you to code your app in a minimal-disclosure fashion – you can ask the user for just the set of information that your app requires to do its job. Se si vuole continuare a ottenere il set di informazioni utente completo attualmente ricevuto dall'app, è necessario includere tutti e tre gli ambiti nelle richieste di autorizzazione:If you want to continue getting the full set of user information that your app is currently receiving, you should include all three scopes in your authorization requests:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=...
&redirect_uri=...
&response_mode=form_post
&response_type=id_token
&scope=openid profile email offline_access https://outlook.office.com/mail.read

L'applicazione può iniziare immediatamente a inviare gli ambiti email e profile e, dopo averli accettati, l'endpoint della versione 2.0 inizia a richiedere agli utenti le autorizzazioni necessarie.Your app can begin sending the email and profile scopes immediately, and the v2.0 endpoint will accept these two scopes and begin requesting permissions from users as necessary. Tuttavia, la modifica all'interpretazione dell'ambito openid non sarà effettiva ancora per alcune settimane.However, the change in the interpretation of the openid scope will not take effect for a few weeks.

Importante

Aggiungere gli ambiti profile e email se l'app richiede informazioni sull'utente.Your job: Add the profile and email scopes if your app requires information about the user. Si noti che ADAL includerà entrambe le autorizzazioni nelle richieste per impostazione predefinita.Note that ADAL will include both of these permissions in requests by default.

Rimozione della barra finale dell'autorità di certificazioneRemoving the issuer trailing slash.

In precedenza, il valore dell'autorità di certificazione visualizzato nei token dall'endpoint della versione 2.0 aveva il formatoPreviously, the issuer value that appears in tokens from the v2.0 endpoint took the form

https://login.microsoftonline.com/{some-guid}/v2.0/

dove guid era l'ID tenant del tenant di Azure AD che aveva emesso il token.Where the guid was the tenantId of the Azure AD tenant which issued the token. Con queste modifiche, il valore dell'autorità di certificazione diventaWith these changes, the issuer value becomes

https://login.microsoftonline.com/{some-guid}/v2.0 

sia nei token che nel documento di individuazione di OpenID Connect.in both tokens and in the OpenID Connect discovery document.

Importante

Assicurarsi che l'app accetti il valore dell'autorità di certificazione con e senza una barra finale durante la convalida dell'autorità di certificazione.Your job: Make sure your app accepts the issuer value both with and without a trailing slash during issuer validation.

Perché cambiareWhy change?

La motivazione principale per l'introduzione di queste modifiche è la conformità alle specifiche dello standard OpenID Connect.The primary motivation for introducing these changes is to be compliant with the OpenID Connect standard specification. Con la conformità a OpenID Connect, Microsoft punta a ridurre al minimo le differenze tra l'integrazione con i servizi di identità Microsoft e con altri servizi di identità del settore.By being OpenID Connect compliant, we hope to minimize differences between integrating with Microsoft identity services and with other identity services in the industry. Gli sviluppatori devono avere la possibilità di usare le librerie di autenticazione open source preferite, senza doverle adattare alle differenze di Microsoft.We want to enable developers to use their favorite open source authentication libraries without having to alter the libraries to accommodate Microsoft differences.

Cosa fareWhat can you do?

A partire da oggi, è possibile iniziare ad apportare tutte le modifiche descritte sopra.As of today, you can begin making all of the changes described above. Nell'immediato:You should immediately:

  1. Rimuovere tutte le dipendenze dalx5t parametro di intestazione.Remove any dependencies on the x5t header parameter.
  2. Gestire correttamente la transizione da profile_info a id_token nelle risposte dei token.Gracefully handle the transition from profile_info to id_token in token responses.
  3. Rimuovere tutte le dipendenze dal parametro di risposta id_token_expires_in.Remove any dependencies on the id_token_expires_in response parameter.
  4. Aggiungere gli ambiti profile e email all'app se sono necessarie informazioni utente di base.Add the profile and email scopes to your app if your app needs basic user information.
  5. Accettare i valori dell'autorità di certificazione nei token con e senza una barra finale.Accept issuer values in tokens both with and without a trailing slash.

La documentazione relativa al protocollo della versione 2.0 è già stata aggiornata in base a queste modifiche e può essere usata come riferimento nell'aggiornamento del codice.Our v2.0 protocol documentation has already been updated to reflect these changes, so you may use it as reference in helping update your code.

Per qualsiasi domanda sull'ambito delle modifiche, è possibile contattare @AzureAD su Twitter.If you have any further questions on the scope of the changes, please feel free to reach out to us on Twitter at @AzureAD.

Frequenza delle modifiche ai protocolliHow often will protocol changes occur?

Non sono previste altre modifiche di rilievo ai protocolli di autenticazione.We do not foresee any further breaking changes to the authentication protocols. Microsoft sta unendo intenzionalmente queste modifiche in un unico rilascio per evitare la necessità di eseguire questo tipo di processo di aggiornamento nel prossimo futuro.We are intentionally bundling these changes into one release so that you won`t have to go through this type of update process again any time soon. Verranno naturalmente aggiunte altre funzionalità al servizio di autenticazione convergente della versione 2.0, ma non comporteranno modifiche di rilievo al codice esistente.Of course, we will continue to add features to the converged v2.0 authentication service that you can take advantage of, but those changes should be additive and not break existing code.

Microsoft ringrazia gli utenti per la disponibilità nel periodo di anteprima.Lastly, we would like to say thank you for trying things out during the preview period. Le informazioni e l'esperienza dei primi utenti sono state preziose e Microsoft si augura che continueranno a condividere idee e opinioni.The insights and experiences of our early adopters have been invaluable thus far, and we hope you`ll continue to share your opinions and ideas.

Buon lavoro.Happy coding!

Microsoft Identity DivisionThe Microsoft Identity Division