Zprostředkovatel webového ověřování

2025-06-10

Tento článek vysvětluje, jak připojit aplikaci univerzální platformy Windows (UPW) k online zprostředkovateli identity, který používá ověřovací protokoly, jako je OpenID nebo OAuth. Metoda AuthenticateAsync odešle žádost online zprostředkovateli identity a vrátí přístupový token, který popisuje prostředky zprostředkovatele, ke kterým má aplikace přístup.

Poznámka:

Pro kompletní a funkční ukázku kódu projděte na úložiště WebAuthenticationBroker na GitHubu a naklonujte ho.

Registrace aplikace u online poskytovatele

Aplikaci musíte zaregistrovat u zprostředkovatele online identity, ke kterému se chcete připojit. Zjistěte, jak zaregistrovat aplikaci od zprostředkovatele identity. Po registraci vám online poskytovatel obvykle poskytne ID nebo tajný klíč vaší aplikace.

Sestavit URI žádosti o ověření

Identifikátor URI požadavku se skládá z adresy, kde odešlete žádost o ověření vašemu online poskytovateli s dalšími požadovanými informacemi, jako je ID aplikace nebo tajný klíč, identifikátor URI přesměrování, do kterého se uživatel odešle po dokončení ověřování, a očekávaný typ odpovědi. Zjistěte od svého poskytovatele, jaké parametry jsou potřeba.

Identifikátor URI požadavku se odešle jako parametr requestUri metody AuthenticateAsync . Musí to být zabezpečená adresa (musí začínat https://)

Následující příklad ukazuje, jak sestavit identifikátor URI požadavku.

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);

Připojení k online poskytovateli

Zavoláte metodu AuthenticateAsync k připojení k poskytovateli online identity a k získání přístupového tokenu. Metoda používá identifikátor URI vytvořený v předchozím kroku jako parametr requestUri a identifikátor URI, na který chcete, aby byl uživatel přesměrován, jako parametr 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;
}

Výstraha

Kromě AuthenticateAsyncobsahuje Windows.Security.Authentication.Web obor názvů metodu AuthenticateAndContinue. Tuto metodu nevolejte. Je určená jenom pro aplikace určené jenom pro Windows Phone 8.1 a od Windows 10 je zastaralá.

Připojení pomocí jednotného přihlašování (SSO).

Ve výchozím nastavení zprostředkovatel webového ověřování neumožňuje trvalé uchovávání souborů cookie. Z tohoto důvodu, i když uživatel aplikace indikuje, že chce zůstat přihlášený (například zaškrtnutím políčka v přihlašovacím dialogovém okně poskytovatele), bude se muset přihlásit pokaždé, když chce získat přístup k prostředkům daného poskytovatele. Pokud se chcete přihlásit pomocí jednotného přihlašování, musí váš online zprostředkovatel identity povolit jednotné přihlašování pro zprostředkovatele webového ověřování a vaše aplikace musí volat přetížení AuthenticateAsync, které nepřebírají parametr zpětného volání. To umožní, aby se trvalé soubory cookie ukládaly zprostředkovatelem webového ověřování, takže budoucí volání ověřování stejnou aplikací nebudou vyžadovat opakované přihlášení uživatelem (uživatel se efektivně přihlásí, dokud nevyprší platnost přístupového tokenu).

Aby poskytovatel online mohl podporovat jednotné přihlášení, musí umožnit registraci identifikátoru URI pro přesměrování ve formátu ms-app://<appSID>, přičemž <appSID> je identifikátor SID vaší aplikace. Identifikátor SID vaší aplikace najdete na stránce pro vývojáře aplikace nebo voláním metody 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;
}

Odstraňování chyb

Existuje několik způsobů, jak řešit potíže s rozhraními API zprostředkovatele webového ověřování, včetně kontroly provozních protokolů a kontroly webových požadavků a odpovědí pomocí Fiddleru.

Provozní protokoly

Pomocí provozních protokolů můžete často určit, co nefunguje. Existuje vyhrazený kanál protokolu událostí Microsoft-Windows-WebAuth\Operational, který vývojářům webu umožňuje pochopit, jak se webové stránky zpracovávají zprostředkovatelem ověřování webu. Pokud ho chcete povolit, spusťte eventvwr.exe a povolte provozní protokol v části Aplikace a služby\Microsoft\Windows\WebAuth. Aplikace zprostředkovatele webového ověřování také připojuje ke stringu uživatelského agenta jedinečný řetězec, aby se identifikovala na webovém serveru. Řetězec je "MSAuthHost/1.0". Všimněte si, že číslo verze se může v budoucnu změnit, takže byste neměli záviset na daném čísle verze v kódu. Příklad celého řetězce uživatelského agenta a následných úplných kroků ladění je uvedený níže.

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

Povolte provozní protokoly.
Spusťte aplikaci společnosti Contoso pro sociální sítě.
Vygenerované položky protokolů lze použít k podrobnějšímu pochopení chování zprostředkovatele ověřování webu. V tomto případě můžou zahrnovat:
- Start navigace: Zaznamená, když se spustí AuthHost a obsahuje informace o adresách URL pro spuštění a ukončení.
- Dokončení navigace: Zaznamená dokončení načítání webové stránky.
- Metaznačka: Zaznamenává, kdy je detekována metaznačka včetně podrobností.
- Ukončení navigace: Navigace byla ukončena uživatelem.
- Chyba navigace: AuthHost narazí na navigační chybu na adrese URL, včetně HttpStatusCode.
- Konec navigace: Byla zjištěna koncová adresa URL.

Houslista

Webový ladicí program Fiddler lze použít s aplikacemi. Další informace najdete v dokumentaci Fiddler

Vzhledem k tomu, že AuthHost běží ve vlastním kontejneru aplikace, abyste získali možnost privátní sítě, musíte nastavit klíč registru: Editor registru Systému Windows verze 5.00.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Možnosti spuštění souboru obrázku\authhost.exe\EnablePrivateNetwork = 00000001

Pokud tento klíč registru nemáte, můžete ho vytvořit v příkazovém řádku s oprávněními správce.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Přidejte pravidlo pro AuthHost, protože to generuje odchozí provoz.

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-3480344935

Přidejte pravidlo brány firewall pro příchozí provoz do Fiddleru.

Sdílet prostřednictvím