Service Broker d’authentification web
Cet article explique comment connecter votre application de Plateforme Universelle Windows (UWP) à un fournisseur d’identité en ligne qui utilise des protocoles d’authentification comme OpenID ou OAuth. La méthode AuthenticateAsync envoie une demande au fournisseur d’identité en ligne, puis obtient un jeton d’accès en retour qui décrit les ressources du fournisseur auxquelles l’application a accès.
Remarque
Pour un exemple de code complet et fonctionnel, clonez le dépôt WebAuthenticationBroker sur GitHub.
Enregistrez votre application auprès de votre fournisseur en ligne
Vous devez enregistrer votre application auprès du fournisseur d’identité en ligne auquel vous souhaitez vous connecter. Vous pouvez savoir comment enregistrer votre application auprès du fournisseur d’identité. Après l’enregistrement, le fournisseur en ligne vous donne généralement un identifiant ou une clé secrète pour votre application.
Construisez l’URI de la demande d’authentification
L’URI de la demande est composé de l’adresse où vous envoyez la demande d’authentification à votre fournisseur en ligne, suivi d’autres informations requises, telles qu’un ID ou une clé secrète d’application, un URI de redirection où l’utilisateur est envoyé après avoir terminé l’authentification, et le type de réponse attendu. Vous pouvez obtenir auprès de votre fournisseur les paramètres requis.
L’URI de la demande est envoyé en tant que paramètre requestUri de la méthode AuthenticateAsync. Il doit s’agir d’une adresse sécurisée (elle doit commencer par https://).
L’exemple suivant montre comment construire l’URI de la demande.
string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";
System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);
Connectez-vous au fournisseur en ligne
Vous appelez la méthode AuthenticateAsync pour vous connecter au fournisseur d’identité en ligne et obtenir un jeton d’accès. La méthode prend l’URI construit à l’étape précédente en tant que paramètre requestUri, et un URI vers lequel vous souhaitez rediriger l’utilisateur en tant que paramètre callbackUri.
string result;
try
{
var webAuthenticationResult =
await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync(
Windows.Security.Authentication.Web.WebAuthenticationOptions.None,
startURI,
endURI);
switch (webAuthenticationResult.ResponseStatus)
{
case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
// Successful authentication.
result = webAuthenticationResult.ResponseData.ToString();
break;
case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
// HTTP error.
result = webAuthenticationResult.ResponseErrorDetail.ToString();
break;
default:
// Other error.
result = webAuthenticationResult.ResponseData.ToString();
break;
}
}
catch (Exception ex)
{
// Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here.
result = ex.Message;
}
Avertissement
En plus de AuthenticateAsync, l’espace de noms Windows.Security.Authentication.Web contient une méthode AuthenticateAndContinue. N'appelez pas cette méthode. Elle est conçue pour les applications ciblant uniquement Windows Phone 8.1 et est obsolète à partir de Windows 10.
Connexion avec une authentification unique (SSO).
Par défaut, le courtier d’authentification Web ne permet pas à des cookies de persister. Pour cette raison, même si l’utilisateur de l’application indique qu’il souhaite rester connecté (par exemple, en sélectionnant une case à cocher dans la boîte de dialogue de connexion du fournisseur), il devra se connecter à chaque fois qu’il souhaite accéder aux ressources de ce fournisseur. Pour vous connecter avec SSO, votre fournisseur d’identité en ligne doit avoir activé le SSO pour le courtier d’authentification Web, et votre application doit appeler la surcharge de AuthenticateAsync qui ne prend pas de paramètre callbackUri. Cela permettra aux cookies persistants d’être stockés par le courtier d’authentification web, de sorte que les futurs appels d’authentification par la même application ne nécessiteront pas de nouvelle connexion de la part de l’utilisateur (l’utilisateur est effectivement « connecté » jusqu’à ce que le jeton d’accès expire).
Pour prendre en charge le SSO, le fournisseur en ligne doit vous permettre d’enregistrer un URI de redirection sous la forme ms-app://<appSID>, où <appSID> est le SID de votre application. Vous pouvez trouver le SID de votre application sur la page de développement de votre application, ou en appelant la méthode GetCurrentApplicationCallbackUri.
string result;
try
{
var webAuthenticationResult =
await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync(
Windows.Security.Authentication.Web.WebAuthenticationOptions.None,
startURI);
switch (webAuthenticationResult.ResponseStatus)
{
case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
// Successful authentication.
result = webAuthenticationResult.ResponseData.ToString();
break;
case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
// HTTP error.
result = webAuthenticationResult.ResponseErrorDetail.ToString();
break;
default:
// Other error.
result = webAuthenticationResult.ResponseData.ToString();
break;
}
}
catch (Exception ex)
{
// Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here.
result = ex.Message;
}
Débogage
Il existe plusieurs façons de dépanner les API du courtier d’authentification web, notamment en examinant les journaux opérationnels et en examinant les requêtes et réponses web à l’aide de Fiddler.
Journaux des opérations
Souvent, vous pouvez déterminer ce qui ne fonctionne pas en utilisant les journaux opérationnels. Il existe un canal de journal d’événements dédié Microsoft-Windows-WebAuth\Operational qui permet aux développeurs de sites Web de comprendre comment leurs pages Web sont traitées par le courtier d’authentification Web. Pour l’activer, lancez eventvwr.exe et activez le journal Opérationnel sous Application et services\Microsoft\Windows\WebAuth. De plus, le courtier d’authentification Web ajoute une chaîne unique à la chaîne d’agent utilisateur pour s’identifier sur le serveur web. La chaîne est « MSAuthHost/1.0 ». Notez que le numéro de version peut changer à l’avenir, donc vous ne devez pas dépendre de ce numéro de version dans votre code. Voici un exemple de la chaîne d’agent utilisateur complète, suivi de la procédure complète de débogage.
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)
- Activer les journaux opérationnels.
- Exécutez l’application sociale Contoso.
- Les entrées de journal générées peuvent être utilisées pour comprendre le comportement du courtier d’authentification Web en détail. Dans ce cas, elles peuvent inclure :
- Début de la navigation : Journalise le démarrage de l’AuthHost et contient des informations sur les URL de démarrage et de terminaison.
- Navigation terminée : Journalise l’achèvement du chargement d’une page web.
- Balise meta : Journalise lorsqu’une balise meta est rencontrée, y compris les détails.
- Terminer la navigation : Navigation terminée par l’utilisateur.
- Erreur de navigation : L’AuthHost rencontre une erreur de navigation à une URL incluant HttpStatusCode.
- Fin de la navigation : URL de terminaison rencontrée.
Fiddler
Le débogueur web Fiddler peut être utilisé avec les applications. Pour plus d’informations, veuillez consulter la documentation de Fiddler.
Puisque l’AuthHost s’exécute dans son propre conteneur d’application, pour lui donner la capacité de réseau privé, vous devez définir une clé de registre : Windows Registry Editor Version 5.00
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001
Si vous n’avez pas cette clé de registre, vous pouvez la créer dans une Invite de commandes avec des privilèges d’administrateur.
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /fAjoutez une règle pour l’AuthHost car c’est lui qui génère le trafic sortant.
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s List Loopback Exempted AppContainers [1] ----------------------------------------------------------------- Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe SID: S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349 [2] ----------------------------------------------------------------- Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe SID: S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544 [3] ----------------------------------------------------------------- Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe SID: S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935Ajoutez une règle de pare-feu pour le trafic entrant vers Fiddler.