Gestore di autenticazioni Web

Questo articolo illustra come connettere l'app piattaforma UWP (Universal Windows Platform) (UWP) a un provider di identità online che usa protocolli di autenticazione come OpenID o OAuth. Il metodo AuthenticateAsync invia una richiesta al provider di identità online e restituisce un token di accesso che descrive le risorse del provider a cui l'app ha accesso.

Registrare l'app con il provider online

Si deve registrare l'app con il provider di identità online a cui si vuole connettersi. È possibile scoprire come registrare l'app dal provider di identità. Dopo la registrazione, il provider online fornisce in genere un ID o una chiave privata per l'app.

Compilare l'URI della richiesta di autenticazione

L'URI della richiesta è costituito dall'indirizzo a cui si invia la richiesta di autenticazione al provider online aggiunto con altre informazioni necessarie, ad esempio un ID app o un segreto, un URI di reindirizzamento a cui l'utente viene inviato dopo il completamento dell'autenticazione e il tipo di risposta previsto. È possibile scoprire dal provider quali parametri sono necessari.

L'URI della richiesta viene inviato come parametro requestUri del metodo AuthenticateAsync. Deve essere un indirizzo sicuro (deve iniziare con https://)

Nell'esempio seguente viene illustrato come compilare l'URI della richiesta.

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

Connessione al provider online

Richiamare il metodo AuthenticateAsync per connettersi al provider di identità online e ottenere un token di accesso. Il metodo accetta l'URI costruito nel passaggio precedente come parametro requestUri e un URI a cui si vuole che l'utente venga reindirizzato come parametro 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;
}

Connessione con Single Sign-On (SSO).

Per impostazione predefinita, Il broker di autenticazione Web non consente la persistenza dei cookie. Per questo motivo, anche se l'utente dell'app indica che vuole rimanere connesso (ad esempio, selezionando una casella di controllo nella finestra di dialogo di accesso al provider), dovrà accedere ogni volta che vuole accedere alle risorse per tale provider. Per accedere con SSO, il provider di identità online deve avere abilitato l'accesso SSO per Il broker di autenticazione Web e l'app deve richiamare l'overload di AuthenticateAsync che non accetta un parametro callbackUri. In questo modo i cookie persistenti verranno archiviati dal gestore di autenticazione Web, in modo che le chiamate di autenticazione future dalla stessa app non richiedano l'accesso ripetuto da parte dell'utente (l'utente è effettivamente "connesso" fino alla scadenza del token di accesso).

Per supportare l'accesso SSO, il provider online deve consentire di registrare un URI di reindirizzamento nel formato ms-app://<appSID>, dove <appSID> è il SID per l'app. Il SID dell'app è disponibile dalla pagina per sviluppatori dell'app o richiamando il metodo 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;
}

Debug

Esistono diversi modi per risolvere i problemi relativi alle API del broker di autenticazione Web, tra cui la revisione dei log operativi e la revisione delle richieste Web e delle risposte tramite Fiddler.

Log operativi.

Spesso è possibile determinare cosa non funziona usando i registri operativi. È disponibile un canale dedicato del registro eventi Microsoft-Windows-WebAuth\Operational che consente agli sviluppatori di siti Web di comprendere come le pagine Web vengono elaborate dal broker di autenticazione Web. Per abilitarla, avviare eventvwr.exe e abilitare il registro operativo in Application and Services\Microsoft\Windows\WebAuth. Inoltre, il gestore di autenticazione Web aggiunge una stringa univoca alla stringa dell'agente utente per identificarsi nel server Web. La stringa è "MSAuthHost/1.0". Si noti che il numero di versione potrebbe cambiare in futuro, quindi non è consigliabile dipendere da tale numero di versione nel codice. Di seguito è riportato un esempio della stringa completa dell'agente utente, seguita dai passaggi di debug completi.

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

1. Abilitare i registri operativi.
2. Eseguire l'applicazione di social networking Contoso.
3. Le voci di registro generate possono essere usate per comprendere in maggiore dettaglio il comportamento del gestore di autenticazione Web. In questo caso, questi possono includere:
   • Avvio navigazione: registra l'avvio di AuthHost e contiene informazioni sugli URL di inizio e terminazione.
   • 
   • Navigazione completata: registra il completamento del caricamento di una pagina Web.
   • Meta Tag: registra quando viene rilevato un meta-tag, inclusi i dettagli.
   • Termina navigazione: navigazione terminata dall'utente.
   • Errore di navigazione: AuthHost rileva un errore di navigazione in un URL incluso HttpStatusCode.
   • Fine navigazione: viene rilevato l'URL di terminazione.

Fiddler

Il debugger Web Fiddler può essere usato con le app. Per altre informazioni, consultare Documentazione Fiddler.

1. Poiché AuthHost viene eseguito nel proprio contenitore di app, per offrire la funzionalità di rete privata è necessario impostare una chiave del Registro di sistema: Editor del Registro di sistema di Windows versione 5.00

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\Versione attuale\Opzioni di esecuzione del file immagine\authhost.exe\EnablePrivateNetwork = 00000001

   Se questa chiave del Registro di sistema non è disponibile, è possibile crearla in un prompt dei comandi con privilegi di amministratore.

   REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
   

2. Aggiungere una regola per AuthHost perché si tratta di ciò che genera il traffico in uscita.

   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
   

3. Aggiungere una regola del firewall per il traffico in ingresso a Fiddler.