Struttura e restrizioni dell'URI di reindirizzamento (URL di risposta)

Per accedere a un utente, l'applicazione deve inviare una richiesta di accesso all'endpoint di autorizzazione di Microsoft Entra, con un URI di reindirizzamento specificato come parametro. L'URI di reindirizzamento è una funzionalità di sicurezza fondamentale che garantisce che Microsoft Entra invii i codici di autorizzazione e i token di accesso solo al destinatario previsto. Questo articolo illustra le funzionalità e le restrizioni degli URI di reindirizzamento in Microsoft Identity Platform.

Che cos'è un URI di reindirizzamento?

Un URI di reindirizzamento o un URL di risposta è il percorso a cui il server di autenticazione di Microsoft Entra invia l'utente una volta eseguita l’autorizzazione e ottenuto un token di accesso. Per connettere un utente, l'applicazione deve inviare una richiesta di accesso con un URI di reindirizzamento specificato come parametro, poi, dopo l'accesso dell'utente, il server di autenticazione reindirizza l'utente e rilascia un token di accesso all'URI di reindirizzamento specificato nella richiesta di accesso.

Perché è necessario aggiungere uno/più URI di reindirizzamento a una registrazione dell'app?

Per motivi di sicurezza, il server di autenticazione Microsoft Entra non reindirizzerà gli utenti o invierà token a un URI che non viene aggiunto alla registrazione dell'app. I server di accesso di Microsoft Entra reindirizzano solo gli utenti e inviano token per reindirizzare gli URI aggiunti a una registrazione dell'app. Se l'URI di reindirizzamento specificato nella richiesta di accesso non corrisponde ad alcuno degli URI di reindirizzamento aggiunti nell'applicazione, verrà visualizzato un messaggio di errore, come ad esempio AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application.

Per altre informazioni sui codici di errore, vedere Codici errore di autenticazione e autorizzazione di Microsoft Entra.

È necessario aggiungere un URI di reindirizzamento a una registrazione dell'app?

L'aggiunta di un URI di reindirizzamento alla registrazione dell'app dipende dal protocollo di autorizzazione usato dall'applicazione. È necessario aggiungere gli URI di reindirizzamento appropriati alla registrazione dell'app se l'applicazione usa i protocolli di autorizzazione seguenti:

• Flusso del codice di autorizzazione OAuth 2.0
• Flusso delle credenziali client OAuth 2.0
• Flusso della concessione implicita OAuth 2.0
• OpenID Connect
• Protocollo SAML per Single Sign-On

Non è necessario aggiungere URI di reindirizzamento alla registrazione dell'app se l'applicazione usa i protocolli o le funzionalità di autorizzazione seguenti.

• Autenticazione nativa
• Flusso del codice del dispositivo OAuth 2.0
• Flusso On-Behalf-Of di OAuth 2.0
• Concessione delle credenziali di tipo password del proprietario delle risorse in OAuth 2.0
• Flusso di autenticazione integrata di Windows
• Provider di identità SAML 2.0 per l'accesso Single Sign-On

A quale piattaforma è necessario aggiungere gli URI di reindirizzamento?

Se l'applicazione che si sta creando contiene uno o più URI di reindirizzamento nella registrazione dell'app, sarà necessario abilitare una configurazione del flusso client pubblico. Le tabelle seguenti forniscono indicazioni sul tipo di URI di reindirizzamento da aggiungere o non dovrebbero essere aggiunte in base alla piattaforma in cui si sta compilando l'applicazione.

Configurazione dell'URI di reindirizzamento dell'applicazione Web

Configurazione dell'URI di reindirizzamento dell'applicazione per dispositivi mobili e desktop

Se si sta creando un'app iOS usando uno dei metodi seguenti, usare la piattaforma Applicazioni per dispositivi mobili e desktop per aggiungere un URI di reindirizzamento:

• App iOS che usano SDK legacy (ADAL)
• App iOS che usano SDK open source (AppAuth)
• Le app iOS che usano tecnologia multipiattaforma non sono supportate (Flutter)
• App iOS che implementano direttamente i protocolli OAuth
• App macOS che usano tecnologia multipiattaforma che non supportiamo (Electron)

Applicazioni che non richiedono un URI di reindirizzamento

Quali sono le restrizioni degli URI di reindirizzamento per le applicazioni Microsoft Entra?

Il modello di applicazione Microsoft Entra specifica le restrizioni seguenti per il reindirizzamento degli URI:

• Gli URI di reindirizzamento devono iniziare con lo schema https, con eccezioni per alcuni URI di reindirizzamento localhost.

• Gli URI di reindirizzamento fanno distinzione tra maiuscole e minuscole e devono corrispondere al caso del percorso URL dell'applicazione in esecuzione.

  Esempi:

  • Se l'applicazione include come parte del percorso .../abc/response-oidc, non specificare .../ABC/response-oidc nell'URL di reindirizzamento. Poiché il Web browser rileva la distinzione tra maiuscole e minuscole nei percorsi, è possibile che i cookie associati a .../abc/response-oidc vengano esclusi se reindirizzati all'URL .../ABC/response-oidc senza la corrispondenza tra maiuscole e minuscole.

• Gli URI di reindirizzamento non configurati con un segmento di percorso vengono restituiti con una barra finale ('/’) nella risposta. Questo vale solo quando la modalità di risposta è query o fragment.

  Esempi:

  • https://contoso.com viene restituito come https://contoso.com/
  • http://localhost:7071 viene restituito come http://localhost:7071/

• Gli URI di reindirizzamento che contengono un segmento di percorso non sono aggiunti con una barra finale nella risposta.

  Esempi:

  • https://contoso.com/abc viene restituito come https://contoso.com/abc
  • https://contoso.com/abc/response-oidc viene restituito come https://contoso.com/abc/response-oidc

• Gli URI di reindirizzamento non supportano caratteri speciali: ! $ ' ( ) , ;

• Gli URI di reindirizzamento non supportano i nomi di dominio internazionalizzati

Numero massimo di URI di reindirizzamento e lunghezza URI

Il numero massimo di URI di reindirizzamento non può essere generato per motivi di sicurezza. Se lo scenario richiede più URI di reindirizzamento rispetto al limite massimo consentito, prendere in considerazione l'approccio al parametro di stato seguente. La tabella seguente mostra il numero massimo di URI di reindirizzamento che è possibile aggiungere a una registrazione dell'app in Microsoft Identity Platform.

È possibile usare un massimo di 256 caratteri per ogni URI di reindirizzamento aggiunto a una registrazione di app.

URI di reindirizzamento negli oggetti applicazione e entità servizio

• Aggiungere sempre gli URI di reindirizzamento solo all'oggetto applicazione.
• Non aggiungere mai valori URI di reindirizzamento a un'entità servizio perché potrebbero essere rimossi quando l'oggetto entità servizio viene sincronizzato con l'oggetto applicazione. Ciò può verificarsi a causa di qualsiasi operazione di aggiornamento che attiva una sincronizzazione tra i due oggetti.

Supporto dei parametri di query negli URI di reindirizzamento

I parametri di query sono consentiti negli URI di reindirizzamento per le applicazioni che eseguono solo l’accesso degli utenti con account aziendali o dell'istituto di istruzione.

I parametri di query non sono consentiti negli URI di reindirizzamento per la registrazione di app configurate per l'accesso degli utenti con account Microsoft personali, ad esempio Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live o Microsoft 365.

Gruppo di destinatari per l'accesso alla registrazione dell'app	Supporta i parametri di query nell'URI di reindirizzamento
Account solo in questa directory dell'organizzazione (Solo Contoso - Tenant singolo)
Account in qualsiasi directory dell'organizzazione (qualsiasi directory Microsoft Entra - multi-tenant)
Account in qualsiasi directory organizzativa (qualsiasi directory di Microsoft Entra - Multitenant) e account Microsoft personali (ad esempio Skype e Xbox)
Solo account Microsoft personali

Schemi supportati

HTTPS: lo schema HTTPS (https://) è supportato per tutti gli URI di reindirizzamento basati su HTTP.

HTTP: lo schema HTTP (http://) è supportato solo per gli URI localhost e dovrebbe essere usato solo durante lo sviluppo e il test delle applicazioni locali attive.

Eccezioni localhost

Per RFC 8252 sezioni 8.3 e 7.3, gli URI di reindirizzamento "loopback" o "localhost" sono dotati di due considerazioni speciali:

1. Gli schemi URI http sono accettabili perché il reindirizzamento non lascia mai il dispositivo. Di conseguenza, entrambi questi URI sono accettabili:
   • http://localhost/myApp
   • https://localhost/myApp
2. A causa di intervalli di porte temporanei spesso richiesti dalle applicazioni native, il componente della porta (ad esempio, :5001 o :443) viene ignorato ai fini della corrispondenza di un URI di reindirizzamento. Di conseguenza, tutti questi URI sono considerati equivalenti:
   • http://localhost/MyApp
   • http://localhost:1234/MyApp
   • http://localhost:5000/MyApp
   • http://localhost:8080/MyApp

Dal punto di vista dello sviluppo, ciò significa alcuni aspetti:

• Non registrare più URI di reindirizzamento in cui è diversa solo la porta. Il server di accesso ne seleziona uno arbitrariamente e usa il comportamento associato a tale URI di reindirizzamento (ad esempio se si tratta di un reindirizzamento di tipo web-, native-, o spa-).

  Ciò è particolarmente importante quando si desidera usare flussi di autenticazione diversi nella stessa registrazione dell'applicazione, ad esempio sia la concessione del codice di autorizzazione che il flusso implicito. Per associare il comportamento di risposta corretto a ogni URI di reindirizzamento, il server di accesso deve essere in grado di distinguere tra gli URI di reindirizzamento e non può farlo quando solo la porta è diversa.

• Per registrare più URI di reindirizzamento in localhost per testare flussi diversi durante lo sviluppo, differenziarli usando il componente percorso dell'URI. Ad esempio, http://localhost/MyWebApp non corrisponde a http://localhost/MyNativeApp.

• L'indirizzo di loopback IPv6 ([::1]) non è attualmente supportato.

Preferire 127.0.0.1 rispetto a localhost

Per impedire l'interruzione dell'app a causa di firewall configurati in modo errato o di interfacce di rete rinominate, usare l'indirizzo di loopback dei valori letterali IP 127.0.0.1 nell'URI di reindirizzamento anziché localhost. Ad esempio: https://127.0.0.1.

Non è tuttavia possibile usare la casella di testo URI di reindirizzamento nel portale di Azure per aggiungere un URI di reindirizzamento basato su loopback che usa lo schema http:

Per aggiungere un URI di reindirizzamento che usa lo schema http con l'indirizzo di loopback 127.0.0.1, è attualmente necessario modificare l'attributo replyUrlsWithType nel manifesto dell'applicazione.

Restrizioni sui caratteri jolly negli URI di reindirizzamento

Gli URI con caratteri jolly come https://*.contoso.com possono sembrare pratici, ma dovrebbero essere evitati a causa di implicazioni per la sicurezza. In base alla specifica OAuth 2.0 (sezione 3.1.2 del documento RFC 6749), un URI di endpoint di reindirizzamento deve essere un URI assoluto. Di conseguenza, quando un URI con caratteri jolly configurato corrisponde a un URI di reindirizzamento, le stringhe di query e i frammenti nell'URI di reindirizzamento vengono rimossi.

Gli URI con caratteri jolly non sono attualmente supportati nelle registrazioni delle app configurate per accedere agli account Microsoft personali e agli account aziendali o dell'istituto di istruzione. Gli URI con caratteri jolly sono tuttavia consentiti per le app configurate per l'accesso solo agli account aziendali o dell'istituto di istruzione nel tenant di Microsoft Entra di un'organizzazione.

Per aggiungere URI di reindirizzamento con caratteri jolly alle registrazioni delle app che accedono agli account aziendali o dell'istituto di istruzione, usare l'editor del manifesto dell'applicazione in Registrazioni app nel portale di Azure. Anche se è possibile impostare un URI di reindirizzamento con un carattere jolly usando l'editor del manifesto, è fortemente consigliabile attenersi alla sezione 3.1.2 di RFC 6749. e usano solo URI assoluti.

Se lo scenario richiede più URI di reindirizzamento rispetto al limite massimo consentito, prendere in considerazione l'approccio al parametro di stato seguente, invece di aggiungere un URI di reindirizzamento con caratteri jolly.

Uso di un parametro di stato

Se sono presenti diversi sottodomini e lo scenario richiede che, al termine dell'autenticazione, gli utenti vengano reindirizzati alla stessa pagina da cui sono stati avviati, l'uso di un parametro di stato potrebbe essere utile.

In questo approccio:

1. Creare un URI di reindirizzamento "condiviso" per ogni applicazione per elaborare i token di sicurezza che si ricevono dall'endpoint di autorizzazione.
2. L'applicazione può inviare parametri specifici dell'applicazione (ad esempio, l'URL del sottodominio da cui l'utente ha iniziato o qualcosa di simile a informazioni di personalizzazione) nel parametro di stato. Quando si usa un parametro di stato, prestare attenzione alla protezione CSRF come specificato nella sezione 10.12 del documento RFC 6749.
3. I parametri specifici dell’applicazione includono tutte le informazioni necessarie all’applicazione per funzionare correttamente, vale a dire, creare lo stato dell'applicazione appropriato. L’endpoint di autorizzazione di Microsoft Entra esegue lo striping del codice HTML dal parametro di stato. È quindi necessario assicurarsi che non si stia passando contenuto HTML in questo parametro.
4. Quando Microsoft Entra ID invia una risposta all'URI di reindirizzamento "condiviso", invia di nuovo il parametro di stato all'applicazione.
5. L’applicazione può quindi usare il valore del parametro di stato per determinare a quale URL indirizzare l’utente. Assicurarsi di convalidare la protezione CSRF.

Passaggi successivi

Informazioni sul Manifesto dell'applicazione di Registrazioni app.