Concetti di CORS per l'autenticazione nativa incorporata

Condivisione risorse tra le origini (CORS) controlla se il codice del browser può leggere una risposta da un'altra origine. Le applicazioni a pagina singola (SPA) con autenticazione nativa incorporata e i siti Web BRING Your Own UX (BYO UX) necessitano di un proxy o di un criterio CORS perimetrale per le chiamate tra le origini all'API di autenticazione nativa.

Le app Android e iOS che chiamano l'API tramite trasporti HTTP nativi non richiedono CORS o un proxy CORS. Chiamano direttamente l'autorità di servizio configurata. I requisiti in questo articolo si applicano alle richieste del browser, non alle chiamate API native.

Si applica a: cerchio verde con un simbolo di segno di spunta bianco che indica che il contenuto seguente si applica ai tenant esterni. Tenant esterni (altre informazioni)

Approccio di autenticazione: Autenticazione nativa incorporata.

Importante

L'API di autenticazione nativa V2 è disponibile in anteprima. L'API di autenticazione nativa V1 rimane generalmente disponibile. Vedere le Condizioni d'uso supplementari per le anteprime di Microsoft Azure per le condizioni legali applicabili alle funzionalità di anteprima.

Perché il browser CORS si applica

Un'app browser e il relativo endpoint di autenticazione tenant hanno in genere origini diverse. Per le richieste tra le origini, il browser controlla le intestazioni di risposta CORS del server prima di esporre la risposta al codice dell'applicazione.

Un'origine include lo schema, l'host e la porta. Condividere un dominio padre non rende uguali due origini.

Le richieste JSON POST e le richieste password-update PUT dell'API richiedono un controllo preliminare. Il browser invia OPTIONS con il metodo e le intestazioni richiesti prima di inviare la richiesta di autenticazione. Un'intestazione come client-request-id attiva anche una richiesta preflight. Le richieste OAuth con codifica form fanno parte della stessa integrazione; le intestazioni e il metodo determinano se è necessario eseguire la verifica preliminare.

Il codice del browser rimane soggetto a CORS anche quando viene eseguito in una visualizzazione Web incorporata. CORS regola l'accesso alle risposte del browser; L'autenticazione del chiamante e la prevenzione degli abusi richiedono controlli separati.

Perché è necessario un proxy

Il servizio di autenticazione nativo gestisce OPTIONS prima di analizzare la richiesta API o richiamare l'azione relativa alle credenziali. Restituisce un HTTP 200 vuoto. Quando la richiesta include Origin, il servizio annuncia i metodi accettati dell'azione e restituisce le intestazioni richieste in Access-Control-Allow-Headers. Non è necessario alcun flag di funzionalità preliminare aggiuntivo.

Il servizio non fornisce Access-Control-Allow-Origin o Access-Control-Allow-Credentials. Il proxy o il nodo edge fornisce i criteri espliciti di origine consentita. Può inoltrare la risposta preflight del servizio o rispondere localmente a una richiesta preflight convalidata. Una pagina di errore HTML con un HTTP esterno 200 non è una risposta preliminare riuscita.

Il proxy preserva le operazioni, i corpi e lo stato della transazione dell'API. L'inoltro o l'omissione dell'intestazione upstream Origin è una scelta di implementazione, non un requisito universale per rimuoverlo. Applicare la scelta in modo coerente e controllare l'autorizzazione, le operazioni native e lo scambio di token insieme.

Autorità del servizio e trasporto tramite proxy

Per le integrazioni del browser descritte in questo articolo, l'autenticazione nativa incorporata e gli URL dell'API del servizio BYO UX usano un dominio di autenticazione personalizzato verificato dal tenant e il GUID del tenant:

https://<tenant-verified-custom-domain>/<tenant-GUID>

Ad esempio, l'autorità di servizio potrebbe essere https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. Un prefisso di trasporto locale potrebbe essere http://localhost:3001/apiinvece . Questi valori servono a scopi diversi:

Value Purpose
Autorità del servizio Identifica il servizio di autenticazione del tenant. Configurare questo dominio personalizzato e il GUID del tenant come autorità upstream e convalidare i collegamenti restituiti dal servizio rispetto a essa.
Prefisso di trasporto Identifica il proxy rivolto al browser. Può sostituire la parte dell'autorità di una richiesta API convalidata per il trasporto, ma non modifica l'autorità di servizio o la transazione.

Con tale prefisso locale, un percorso del servizio di /<tenant-GUID>/api/v2.0/signin/start esegue il mapping a /api/api/v2.0/signin/start. Il primo /api è il prefisso proxy. Il secondo appartiene al percorso del servizio. Le richieste OAuth sono mappate in modo analogo a /api/oauth2/v2.0/authorize-challenge o /api/oauth2/v2.0/token.

Per queste integrazioni del browser, non configurare un indirizzo ciamlogin.com come autorità API del servizio dell'applicazione. Il routing dell'origine gestita dalla piattaforma dietro un dominio personalizzato verificato non sostituisce questo requisito. I client non browser che usano trasporti HTTP nativi non richiedono un dominio personalizzato. Vedere Configurare l'autorità API.

Contratto proxy

Configurare queste impostazioni nel proxy inverso. Inoltrare direttamente i corpi dell'API e i codici di stato del servizio.

Setting Configuration
Autorità a monte Impostare https://<tenant-verified-custom-domain>/<tenant-GUID> come destinazione fissa. Per un edge del dominio personalizzato, usare la configurazione documentata dell'origine del servizio della piattaforma.
Route Consentire /api/v2.0/*, /oauth2/v2.0/authorize-challenge e /oauth2/v2.0/token sotto il prefisso tenant-GUID.
Metodi e controlli preliminari Abilitare POST, password-update PUT e OPTIONS. Gestire la verifica preliminare in locale o inoltrarla al servizio. Approvare solo metodi e intestazioni configurati; restituisce Access-Control-Allow-Methods: POST, PUT.
Origine del browser Imposta Access-Control-Allow-Origin sull'origine esatta della tua app, ad esempio https://app.contoso.com. Restituisce solo per le richieste corrispondenti Origin , incluse le risposte agli errori.
Intestazioni di richiesta consentite Impostare Access-Control-Allow-Headers su Content-Type, Accept, client-request-id. Per i client Libreria di Autenticazione Microsoft (MSAL), consentire anche x-client-sku, x-client-ver, x-client-os, x-client-cpu, x-client-current-telemetry e x-client-last-telemetry.
Intestazioni di risposta esposte Impostare Access-Control-Expose-Headers su Retry-After, client-request-id, x-ms-request-id, x-ms-clitelem.
Memorizzazione nella cache Disabilitare la memorizzazione nella cache del proxy e della rete CDN. Aggiungere Cache-Control: no-store a ogni risposta.
Reindirizzamenti ed errori Disabilitare i reindirizzamenti upstream automatici e rimuovere le intestazioni di risposta Location . Restituisce errori di proxy espliciti per gli errori di connessione e i timeout.

Il riferimento API definisce i metodi, le intestazioni, i corpi delle richieste e le risposte specifici dell'operazione.

Implementazioni proxy

Scegli un'implementazione adatta all'ambiente di hosting e che rispetti lo stesso contratto:

L'customAuth.authApiProxyUrl dell'SDK JavaScript non rimappa i collegamenti HAL assoluti. Usare i criteri CORS nel perimetro del dominio personalizzato per tali richieste SDK. Le ricette locali e quelle di Functions mostrano invece un trasporto client personalizzato che convalida e mappa i collegamenti al servizio.

Il proxy locale viene associato a un'interfaccia di loopback e non è una ricetta di hosting condivisa. Per un proxy implementato, esaminare anche capacità, costi, controlli di accesso, conservazione dei dati diagnostici e procedure di ripristino per l'ambiente.