CORS-concepten voor ingebouwde systeemeigen authenticatie

CORS (Cross-Origin Resource Sharing) regelt of browsercode een reactie van een andere bron kan lezen. Toepassingen met één pagina (SPA's) met ingesloten native authentication en BYO UX-websites (Bring Your Own UX) hebben een PROXY- of edge CORS-beleid nodig voor cross-origin Native Authentication API-aanroepen.

Android- en iOS-apps die de API aanroepen via native HTTP-transporten hebben geen CORS of een CORS-proxy nodig. Ze roepen de geconfigureerde serviceautoriteit rechtstreeks aan. De vereisten in dit artikel zijn van toepassing op browserverzoeken, niet op die native API-aanroepen.

Van toepassing op: Groene cirkel met een wit vinkje dat aangeeft dat de volgende inhoud van toepassing is op externe tenants. Externe tenants (meer informatie)

Authenticatiemethode: Ingesloten systeemeigen authenticatie.

Important

De systeemeigen authenticatie-API V2 is in preview. De Native Authentication API V1 blijft algemeen beschikbaar. Zie de aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor juridische voorwaarden die van toepassing zijn op preview-functies.

Waarom CORS van de browser van toepassing is

Een browser-app en het eindpunt voor tenantverificatie hebben doorgaans verschillende oorsprongen. Voor cross-origin-aanvragen controleert de browser de CORS-antwoordheaders van de server voordat het antwoord beschikbaar wordt gesteld aan applicatiecode.

Een origin omvat het schema, de host en de poort. Het delen van een bovenliggend domein betekent niet dat twee origins hetzelfde zijn.

De JSON-aanvragen POST en aanvragen voor wachtwoordupdates PUT van de API vereisen een voorbereidende controle. De browser verzendt OPTIONS met de aangevraagde methode en headers voordat de authenticatieaanvraag wordt verzonden. Een header zoals client-request-id activeert ook preflight. Formulier-gecodeerde OAuth-aanvragen maken deel uit van dezelfde integratie; hun methode en headers bepalen of preflight vereist is.

Browsercode blijft onderhevig aan CORS, zelfs wanneer die wordt uitgevoerd in een ingesloten webweergave. CORS bepaalt toegang tot browserresponses; verificatie van bellers en misbruikpreventie vereisen afzonderlijke controles.

Waarom een proxy is vereist

De systeemeigen verificatieservice verwerkt OPTIONS voordat de API-aanvraag wordt geparseerd of de aanmeldingsgegevensactie wordt aangeroepen. Het retourneert een lege HTTP-200. Wanneer de aanvraag Origin bevat, kondigt de service de geaccepteerde methoden van de actie aan en echoot aangevraagde headers in Access-Control-Allow-Headers. Er is geen extra preflight-functievlag nodig.

De service levert Access-Control-Allow-Origin of Access-Control-Allow-Credentials niet. Uw proxy of edge-server levert het expliciete beleid voor toegestane oorsprong. Het kan het preflightantwoord van de service doorsturen of een gevalideerde preflight lokaal beantwoorden. Een HTML-foutpagina met een outer HTTP 200 is geen geslaagd preflight-antwoord.

De proxy behoudt de API-bewerkingen, bodies en de transactiestatus. Het doorsturen of weglaten van de upstream-header Origin is een implementatiekeuze, niet een universele vereiste om deze te verwijderen. Pas uw keuze consistent toe en controleer de autorisatie, systeemeigen bewerkingen en tokenuitwisseling samen.

Service-instantie en proxytransport

Current Embedded native authentication and BYO UX service API URL's use a tenant-verified custom authentication domain and the tenant GUID:

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

De serviceautorisatie-instantie kan bijvoorbeeld https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee zijn. Een lokaal transportvoorvoegsel kan in plaats daarvan http://localhost:3001/api zijn. Deze waarden dienen voor verschillende doeleinden:

Value Purpose
Serviceautoriteit Identificeert de authenticatieservice van de tenant. Configureer dit aangepaste domein en tenant-GUID als de upstream-authoriteit en valideer door de service geretourneerde koppelingen eraan.
Transportvoorvoegsel Identificeert de browsergerichte proxy. Het kan het autoriteitsgedeelte van een gevalideerde API-aanvraag voor transport vervangen, maar wijzigt de serviceautoriteit of transactie niet.

Met dat lokale voorvoegsel wordt een servicepad van /<tenant-GUID>/api/v2.0/signin/start toegewezen aan /api/api/v2.0/signin/start. De eerste /api is het proxyvoorvoegsel; de tweede behoort tot het servicepad. OAuth-aanvragen worden op dezelfde manier toegewezen aan /api/oauth2/v2.0/authorize-challenge of /api/oauth2/v2.0/token.

Configureer geen ciamlogin.com adres als de service-API-authoriteit van de toepassing. Door platform beheerde oorsprongsroutering achter een geverifieerd aangepast domein vervangt deze vereiste niet. Zie De API-instantie configureren.

Proxycontract

Configureer deze instellingen in uw omgekeerde proxy. Rechtstreeks API-instanties en servicestatuscodes doorsturen.

Setting Configuration
Upstream-instantie Stel https://<tenant-verified-custom-domain>/<tenant-GUID> in als de vaste bestemming. Voor een edge van een aangepast domein gebruikt u de gedocumenteerde configuratie van de service-origin van het platform.
Routes Toestaan /api/v2.0/*, /oauth2/v2.0/authorize-challengeen /oauth2/v2.0/token onder het tenant-GUID-voorvoegsel.
Methoden en voorbereidende stappen Inschakelen POST, wachtwoord bijwerken PUT, en OPTIONS. Preflight lokaal verwerken of doorsturen naar de service. Keur alleen geconfigureerde methoden en headers goed; retourneer Access-Control-Allow-Methods: POST, PUT.
Browserorigine Stel Access-Control-Allow-Origin in op de exacte origin van uw app, zoals https://app.contoso.com. Retourneer deze alleen voor overeenkomende Origin aanvragen, inclusief bij foutreacties.
Toegestane requestheaders Stel Access-Control-Allow-Headers in op Content-Type, Accept, client-request-id. Voor Microsoft Authentication Library (MSAL)-clients kunt u ook x-client-sku, x-client-ver, x-client-os, x-client-cpu, x-client-current-telemetry en x-client-last-telemetry toestaan.
Vrijgegeven antwoordheaders Stel Access-Control-Expose-Headers in op Retry-After, client-request-id, x-ms-request-id, x-ms-clitelem.
Opslaan in cache Proxy- en CDN-caching uitschakelen. Voeg Cache-Control: no-store toe aan elk antwoord.
Omleidingen en fouten Schakel automatische upstream-omleidingen uit en verwijder responseheaders Location. Retourneert expliciete proxyfouten voor verbindingsfouten en time-outs.

De API-verwijzing definieert de bewerkingsspecifieke methoden, headers, aanvraagbody’s en antwoorden.

Proxy-implementaties

Kies een implementatie die past bij uw hostingomgeving en voldoet aan hetzelfde contract:

De customAuth.authApiProxyUrl van de JavaScript SDK wijst absolute HAL-koppelingen niet opnieuw toe. Gebruik CORS-beleid aan de edge van het aangepaste domein voor deze SDK-aanvragen. In de lokale en Functions-recepten wordt in plaats daarvan een aangepast clienttransport weergegeven waarmee servicekoppelingen worden gevalideerd en toegewezen.

De lokale proxy bindt aan een loopback-interface en is geen recept voor gedeelde hosting. Voor een geïmplementeerde proxy controleert u ook de capaciteit, kosten, toegangsbeheer, retentie van diagnostische gegevens en herstelprocedures voor uw omgeving.