Concepts CORS d’authentification native incorporée

Le partage de ressources entre origines (CORS) contrôle si le code du navigateur peut lire une réponse provenant d’une autre origine. Les applications monopages (SPA) avec authentification native intégrée et les sites web Bring Your Own UX (BYO UX) nécessitent un proxy ou une stratégie CORS en périphérie pour les appels inter-origines à l’API d’authentification native.

Les applications Android et iOS qui appellent l’API via des transports HTTP natifs n’ont pas besoin de CORS ou d’un proxy CORS. Ils appellent directement l’autorité de service configurée. Les exigences de cet article s’appliquent aux requêtes de navigateur, et non aux appels d’API natifs.

S’applique à : cercle vert avec un symbole de coche blanc qui indique que le contenu suivant s’applique aux locataires externes. Locataires externes (en savoir plus)

Approche d’authentification : Authentification native incorporée.

Important

L’API d’authentification native V2 est en préversion. L’API d’authentification native V1 reste généralement disponible. Consultez les conditions d’utilisation supplémentaires pour les préversions Microsoft Azure pour connaître les conditions légales qui s’appliquent aux fonctionnalités en préversion.

Pourquoi CORS s’applique au navigateur

Une application de navigateur et son point de terminaison d’authentification du locataire ont généralement des origines différentes. Pour les demandes d’origine croisée, le navigateur vérifie les en-têtes de réponse CORS du serveur avant d’exposer la réponse au code d’application.

Une origine inclut le schéma, l’hôte et le port. Le partage d’un domaine parent ne rend pas deux origines identiques.

Les requêtes JSON POST et les demandes de mise à jour PUT de mot de passe de l’API nécessitent une vérification préliminaire. Le navigateur envoie OPTIONS avec la méthode et les en-têtes demandés avant d’envoyer la demande d’authentification. Un en-tête tel que client-request-id déclenche également une requête preflight. Les requêtes OAuth encodées par formulaire font partie de la même intégration ; leurs méthodes et en-têtes déterminent si le preflight est requis.

Le code du navigateur reste soumis à CORS même lorsqu’il s’exécute dans une vue web incorporée. CORS régit l’accès aux réponses du navigateur ; l’authentification de l’appelant et la prévention des abus nécessitent des contrôles distincts.

Pourquoi un proxy est requis

Le service d’authentification natif gère OPTIONS avant d’analyser la demande d’API ou d’appeler son action relative aux informations d’identification. Elle retourne un HTTP 200vide. Lorsque la demande inclut Origin, le service publie les méthodes acceptées de l’action et fait écho aux en-têtes demandés dans Access-Control-Allow-Headers. Aucun indicateur de fonctionnalité preflight supplémentaire n’est nécessaire.

Le service ne fournit pas Access-Control-Allow-Credentials ni Access-Control-Allow-Origin. Votre proxy ou votre edge fournit la stratégie d’origine autorisée explicite. Il peut transférer la réponse preflight du service ou répondre localement à une requête preflight validée. Une page d’erreur HTML avec une réponse HTTP englobante 200 n’est pas une réponse préliminaire réussie.

Le proxy conserve les opérations d’API, les corps et l’état des transactions. Le transfert ou l’omission de l’en-tête en amont Origin est un choix d’implémentation, et non une exigence universelle pour le supprimer. Appliquez votre choix de manière cohérente et vérifiez l’autorisation, les opérations natives et l’échange de jetons ensemble.

Autorité de service et transport proxy

Les URL actuelles de l’API du service UX BYO et d’authentification native incorporée utilisent un domaine d’authentification personnalisé vérifié par le locataire et le GUID du locataire :

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

Par exemple, l’autorité de service peut être https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. Un préfixe de transport local peut plutôt être http://localhost:3001/api. Ces valeurs servent des objectifs différents :

Value Purpose
Autorité du service Identifie le service d’authentification du locataire. Configurez ce domaine personnalisé et ce GUID du locataire en tant qu’autorité en amont et validez les liens retournés par le service par rapport à celui-ci.
Préfixe de transport Identifie le proxy accessible par le navigateur. Il peut remplacer la partie autorité d’une demande d’API validée pour le transport, mais ne modifie pas l’autorité de service ou la transaction.

Avec ce préfixe local, un chemin de service /<tenant-GUID>/api/v2.0/signin/start est mappé vers /api/api/v2.0/signin/start. Le premier /api est le préfixe du proxy ; le second appartient au chemin d’accès au service. Les requêtes OAuth sont également mappées vers /api/oauth2/v2.0/authorize-challenge ou /api/oauth2/v2.0/token.

Ne configurez pas d’adresse ciamlogin.com en tant qu’autorité d’API de service de l’application. Le routage d’origine managée par la plateforme derrière un domaine personnalisé vérifié ne remplace pas cette exigence. Consultez Configurer l’autorité d’API.

Contrat de proxy

Configurez ces paramètres dans votre proxy inverse. Transférer directement les corps de l’API et les codes d’état du service.

Setting Configuration
Autorité en amont Définissez https://<tenant-verified-custom-domain>/<tenant-GUID> comme destination fixe. Pour une périphérie de domaine personnalisé, utilisez la configuration d’origine de service documentée de la plateforme.
Itinéraires Autorisez /api/v2.0/*, /oauth2/v2.0/authorize-challengeet /oauth2/v2.0/token sous le préfixe tenant-GUID.
Méthodes et pré-vérification Activer POST, password-update PUT, et OPTIONS. Gérez la requête preflight localement ou transférez-la au service. Approuvez uniquement les méthodes et les en-têtes configurés ; renvoyez Access-Control-Allow-Methods: POST, PUT.
Origine du navigateur Définissez Access-Control-Allow-Origin l’origine exacte de votre application, par https://app.contoso.comexemple . Retournez-la uniquement pour les demandes correspondantes Origin , y compris sur les réponses d’erreur.
En-têtes de requête autorisés Réglez Access-Control-Allow-Headers sur Content-Type, Accept, client-request-id. Pour les clients Microsoft Authentication Library (MSAL), autorisez x-client-skuégalement , , x-client-verx-client-os, x-client-cpux-client-current-telemetryet x-client-last-telemetry.
En-têtes de réponse exposés Réglez Access-Control-Expose-Headers sur Retry-After, client-request-id, x-ms-request-id, x-ms-clitelem.
Mise en cache Désactivez la mise en cache du proxy et du CDN. Ajouter Cache-Control: no-store à chaque réponse.
Redirections et échecs Désactivez les redirections en amont automatiques et supprimez les en-têtes de réponse Location . Retourne des erreurs de proxy explicites pour les échecs de connexion et les délais d’expiration.

La référence d’API définit les méthodes, les en-têtes, les corps de requête et les réponses spécifiques à l’opération.

Implémentations de proxy

Choisissez une implémentation qui correspond à votre environnement d’hébergement et répond au même contrat :

Le Kit de développement logiciel (SDK) customAuth.authApiProxyUrl JavaScript ne remappe pas de liens HAL absolus. Utilisez la stratégie CORS au niveau du point d’entrée du domaine personnalisé pour ces demandes du SDK. Les recettes locales et Functions montrent plutôt un transport personnalisé client qui valide et mappe les liens de service.

Le proxy local est lié à une interface de bouclage et n’est pas une recette d’hébergement partagée. Pour un proxy déployé, examinez également la capacité, le coût, les contrôles d’accès, la rétention des diagnostics et les procédures de récupération pour votre environnement.